--- title: "Create a Forwarding Request" method: POST path: "/forwarding/requests" tags: ["Forwarding"] --- # Create a Forwarding Request `POST /forwarding/requests` ## Request - Base URL: `https://api.justifi.ai/v1` - URL: `https://api.justifi.ai/v1/forwarding/requests` - Auth: none declared. Required headers: `Idempotency-Key`, `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) 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](https://docs.justifi.tech/api-spec#tag/Forwarding/operation/GetForwardingRequest) or listen for the [`forwarding_request.completed` and `forwarding_request.failed` events](https://docs.justifi.tech/api-spec#tag/Events/operation/forwardingRequestEvent) 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](mailto:customer_success@justifi.tech) 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.* ## Headers - `Idempotency-Key` string, uuid, required - `Authorization` string, required ## Request body - object - `payment_method` string, required: the id of the card payment method whose details are substituted into the request body - `url` string, required: the destination to send the request to. Must match an allow-listed destination exactly - `forwarding_request` object, required: the request to send to the destination - `body` object, required: the request body the destination expects, as a JSON object. Use `{{card_number}}`, `{{card_expiry_month}}`, `{{card_expiry_year}}` and `{{cardholder_name}}` where card details belong; each tag must be the entire value of its field. JustiFi encodes the body in the format the destination expects - `headers` object: headers to relay to the destination, including the credentials it requires. Values must be strings. JustiFi stores none of its own credentials for the destination and adds only `Content-Type`, and only when you leave it out ## Response `201` The forwarding request was accepted and queued. Nothing has been sent to the destination yet, so `status` is `pending` and `response` is `null`. - object - `id` string, uuid: the object id, also found in the data object - `type` string: the object type, or array of objects - `data` object: the attributes for the object - `id` string: unique id of the forwarding request - `account_id` string, nullable: the sub account that owns the payment method the request was created from - `payment_method_id` string, nullable: the payment method whose card details are substituted into the request body - `url` string: the allow-listed destination the request is sent to - `http_method` 'POST': the HTTP method used to reach the destination, determined by the destination itself - `provider` 'stripe': the destination provider, determined by the destination itself - `status` 'pending' | 'processing' | 'completed' | 'failed': `pending` — accepted and queued, nothing has been sent yet; `processing` — the request is being sent and the outcome is not known yet; `completed` — the destination answered, see `data.response.status_code` for the outcome; `failed` — the destination could not be reached, see `failure_reason`. - `failure_reason` 'timeout' | 'connection_error' | 'internal_error', nullable: why the destination could not be reached, `null` unless `status` is `failed`. `timeout` — the destination did not answer in time; `connection_error` — the connection or TLS handshake failed; `internal_error` — JustiFi failed to send the request. - `replacements` string[]: the card tags JustiFi found in the request body and substituted before sending - `request` object: what was sent to the destination, masked - `body` object, nullable: the request body as it was sent, with card details masked. The card number renders as its last four digits; the expiration date and cardholder name render in the clear. - `headers` object: the headers as they were sent, with every value replaced by `[FILTERED]`. Header names are kept so you can confirm what was relayed; values are never stored in readable form. - `response` object, nullable: the destination's response, `null` until the destination has answered - `id` string: unique id of the forwarding response - `status_code` integer: the HTTP status code the destination answered with - `body` unknown - `headers` unknown - `response_time_ms` integer, nullable: how long the destination took to answer, in milliseconds - `attempted_at` string, date-time, nullable: when JustiFi started sending the request (in UTC), `null` while the request is still queued - `created_at` string, date-time - `updated_at` string, date-time - `page_info` unknown ## Other responses - `400`: The request was rejected. Nothing was created and nothing was sent. - `404`: No payment method with that id exists. --- [API](https://skmtc.dev/justifi/apis/justifi-api-documentation.md) - [All operations](https://skmtc.dev/justifi/apis/justifi-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/justifi/apis/justifi-api-documentation/revisions/dd9f3fed7e46?raw)