JUjustifi
Forwarding

Create a Forwarding Request

Send a request to an allow-listed destination with card details filled in from a payment method JustiFi already holds.

You describe the request the destination expects, and write {{card_number}}, {{card_expiry_month}}, {{card_expiry_year}} or {{cardholder_name}} wherever card details belong. JustiFi substitutes them at send time.

A tag must be the entire value of its field. A tag inside a longer string ("num:{{card_number}}"), an unknown tag ({{card_expiry}}) and {{card_cvc}}, which JustiFi does not store, are all rejected with invalid_parameter.

This endpoint responds before anything leaves JustiFi. The forwarding request is created with status pending and a null response. Poll Get a Forwarding Request or listen for the forwarding_request.completed and forwarding_request.failed events for the outcome.

Destinations are allow-listed by JustiFi and matched exactly — no trailing slash, casing or query normalization is applied. Contact JustiFi Customer Success to have a destination added.

Only card payment methods can be forwarded. Bank accounts and card-present payment methods are rejected with payment_method_type_not_supported, and digital wallet cards with digital_wallet_not_supported.

Note: no Sub-Account header is needed. The account is inferred from the payment method.

post/forwarding/requests

Request

Headers

Idempotency-Keystring uuid required

a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests

Authorizationstring required

the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)

Request body

payment_methodstring required

the id of the card payment method whose details are substituted into the request body

urlstring required

the destination to send the request to. Must match an allow-listed destination exactly

Example request

{
  "payment_method": "pm_123xyz",
  "url": "https://api.stripe.com/v1/payment_methods"
}

Response

The forwarding request was accepted and queued. Nothing has been sent to the destination yet, so status is pending and response is null.

idstring uuid

the object id, also found in the data object

typestring

the object type, or array of objects

page_infounknown

Example response

{
  "id": "prefix_xyz (same as id of data object)",
  "type": "forwarding_request",
  "data": {
    "id": "fwd_123xyz",
    "account_id": "acc_123xyz",
    "payment_method_id": "pm_123xyz",
    "url": "https://api.stripe.com/v1/payment_methods",
    "http_method": "POST",
    "provider": "stripe",
    "status": "completed",
    "failure_reason": "timeout",
    "replacements": [
      "card_number",
      "card_expiry_month",
      "card_expiry_year",
      "cardholder_name"
    ],
    "request": {
      "body": {
        "type": "card",
        "card": {
          "number": "4242",
          "exp_month": 5,
          "exp_year": 2042
        },
        "billing_details": {
          "name": "Lindsay Whalen"
        }
      },
      "headers": {
        "Authorization": "[FILTERED]",
        "Content-Type": "[FILTERED]"
      }
    },
    "response": {
      "id": "fwdr_123xyz",
      "status_code": 200,
      "body": {
        "id": "pm_1QabcStripeExample",
        "object": "payment_method",
        "card": {
          "last4": "4242"
        }
      },
      "headers": {
        "content-type": "application/json",
        "request-id": "req_stripe_123"
      },
      "response_time_ms": 512
    },
    "attempted_at": "2024-01-01T12:00:01Z",
    "created_at": "2024-01-01T12:00:00Z",
    "updated_at": "2024-01-01T12:00:02Z"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.