--- title: "Forward an API request" method: POST path: "/forward" tags: ["Forward"] --- # Forward an API request `POST /forward` ## Request - Base URL: `https://forward.checkout.com` - URL: `https://forward.checkout.com/forward` - Auth: one of: - OAuth 2 - Client credentials - Token URL: `string` scopes: `forward` - API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) Forwards an API request to a third-party endpoint. For example, you can forward payment credentials you've stored in our Vault to a third-party payment processor. ## Request body - ForwardRequest: The request template to forward to the third-party endpoint. Template values will be replaced before the request is forwarded. - `source` union, required: The payment source to enrich the forward request with. You can provide placeholder values in `destination_request.body`. The request will be enriched with the respective payment credentials from the token or payment instrument you specified. For example, `{{card_number}}`. - object: The payment instrument to enrich the forward request with. - `type` string, required: The payment source type. - `id` string, required: The unique identifier of the payment instrument. - `cvv_token` string: The unique token for the card's security code. Checkout.com does not store a card's Card Verification Value (CVV) with its associated payment instrument. To pass a CVV with your forward request, use the Frames SDK for Android or iOS to collect and tokenize the CVV and pass the value in this field. The token will replace the placeholder `{{card_cvv}}` value in `destination_request.body`. - `pin_token` string: The unique token for the first 2 digits of the card's Personal Identification Number (PIN). Checkout.com does not store a card's PIN with its associated payment instrument. In specific regions, card holders must enter the first two digits of their 4-digit card PIN to confirm card ownership. To provide the first 2 digits of the PIN with your forward request: 1. Collect the PIN from the user. 2. tokenize it using the `/tokens` [endpoint](/#operation/requestAToken) setting `type` to `pin`. 3. Pass the resulting `token` value of the response in this field. This token replaces the `{{card_pin}}` placeholder value in `destination_request.body`. - object: The token to enrich the forward request with. - `type` string, required: The payment source type. - `token` string, required: The unique Checkout.com token. - `store_for_future_use` boolean: Specifies whether to store the tokenized credentials as a payment instrument and return its identifier in the response. - `reference` string: The unique reference for the forward request. - `processing_channel_id` string: The processing channel ID to associate the billing for the forward request with. - `network_token` ForwardRequestNetworkToken: Specifies if and how a network token should be used in the forward request. - `enabled` boolean: Specifies whether to use a network token. - `request_cryptogram` boolean: Specifies whether to generate a cryptogram. For example, for customer-initiated transactions (CITs). If you set `network_token.enabled` to `true`, you must provide this field. - `destination_request` ForwardDestinationRequest, required: The details of the request to forward. - `url` string, required: The URL to forward the request to. - `method` 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'OPTIONS' | 'TRACE' | 'PATCH', required: The HTTP method to use for the forward request. - `headers` ForwardBodyHeadersRequest, required: The request headers to include in the forward request. - `encrypted` string: The encrypted headers to include in the forward request, as a JSON object with string values encrypted with JSON Web Encryption (JWE). - `raw` object, required: The raw headers to include in the forward request. You can use the `{{metadata.KEY}}` placeholder in header values to insert a value from the `metadata` stored with the token or payment instrument. Metadata values inserted into headers may be stored unmasked in the forward request log returned by the [Get forward request](#operation/getForwardRequest) endpoint. Some sensitive headers, such as `Authorization`, are redacted, and `encrypted` headers are not logged in plain text, but other header values are logged as sent. - `body` string, required: The HTTP message body to include in the forward request. If you provide `source.id` or `source.token`, you can specify placeholder values in the body. The request will be enriched with the respective payment details from the token or payment instrument you specified. For example, `{{card_number}}`. To insert a value from the `metadata` stored with the token or payment instrument, use the `{{metadata.KEY}}` placeholder. For keys that are not valid identifiers, use `{{metadata["KEY"]}}`. Keys are case-sensitive. If the key does not exist, the placeholder is replaced with an empty string and the request is still forwarded. You can use metadata placeholders in `body`, `headers.raw`, and in `variables` values that are used in the body or headers. They are not supported in `url`, `query`, or `signature`. In those fields, the placeholder is replaced with an empty string and no error is returned. Metadata values are inserted exactly as stored, without escaping. Ensure a value cannot break the syntax of your body template. For example, a `"` character inside a JSON string. - `signature` union: Optional configuration to add a signature to the forwarded HTTP request. - object - `type` string, required: The identifier of the supported signature generation method or a specific third-party service. - `dlocal_parameters` object, required: The parameters required to generate an HMAC signature for the dLocal API. See their [documentation](https://docs.dlocal.com/reference/payins-security) for details. This method requires you to provide the `X-Login` header value in the destination request headers. When used, the Forward API appends the `X-Date` and `Authorization` headers to the outgoing HTTP request before forwarding. - `secret_key` string, required: The secret key used to generate the request signature. This is part of the dLocal API credentials. - object - `type` string, required: The identifier of the supported signature generation method or a specific third-party service. - `mastercard_parameters` object, required: The parameters required to generate an OAuth 1.0a authentication and request signature header for the Mastercard APIs. For more information, see [Mastercard documentation](https://developer.mastercard.com/platform/documentation/authentication/using-oauth-1a-to-access-mastercard-apis/). When used, the Forward API appends the `Authorization` header to the outgoing HTTP request before forwarding. - `consumer_key` string, required: An identifier of the client application. Part of the Mastercard APIs credentials. - `signing_key` string, required: A 2048-bit private RSA key used to generate request signatures and confirming ownership of the consumer key. Part of the Mastercard APIs credentials. - object - `type` string, required: The identifier of the supported signature generation method or a specific third-party service. - `visa_parameters` object, required: The parameters required to generate an HMAC-based request signature for the Visa APIs. For more information, see [Visa documentation](https://developer.visa.com/pages/working-with-visa-apis/x-pay-token). This method requires you to provide the `apikey` query parameter value in the destination request. When used, the Forward API appends the `X-PAY-TOKEN` header to the outgoing HTTP request before forwarding. - `shared_secret` string, required: The secret key used to generate the request signature; part of the Visa API credentials. - `remove_resource_path_prefix` string: Some Visa APIs require a prefix to be removed from the resource path used to calculate the signature.
By default, only the leading slash is removed.

For more information, see [Visa documentation](https://developer.visa.com/pages/working-with-visa-apis/x-pay-token). - `variables` object[]: The variables used in the forward request body. You can provide placeholder values in `destination_request.variables.value`. The request will be enriched with the payment credentials from the token or payment instrument you specified. For example, `{{card_number}}`. To reference variables, use `{{variable_name}}`. You cannot name a variable `secret` or `jwe_encrypt`, in any casing. If you do, the request is rejected with the `destination_request_variables_name_reserved` error code. Do not name a variable `metadata`, as it overrides the `{{metadata.KEY}}` placeholders in the request. - `name` string: The variable name. - `value` string: The variable value. - `query` object[]: The query parameters used in the forward request. These values are added to the destination URL as query parameters. - `name` string: The query parameter name. - `value` string: The query parameter value. ## Response `200` The request was successfully forwarded. - ForwardResponse: The response to the forward request. - `request_id` string, required: The unique identifier for the forward request. - `destination_response` ForwardBodyResponse: The response returned by the third-party endpoint the forward request was sent to. - `status` number, required: The HTTP status code of the destination response. - `headers` object, required: The destination response's HTTP headers. - `body` string, required: The destination response's HTTP message body. - `source` object: The metadata of the forwarded card credentials. - `id` string: The identifier of the payment instrument with the forwarded card credentials. When `source.type` is `"token"`, only returned if the `source.store_for_future_use` is true. - `bin` string, required: The card issuer's Bank Identification Number (BIN) - `last4` string, required: The last four digits of the card number - `fingerprint` string, required: Uniquely identifies this particular card. You can use this to compare cards across customers. ## Other responses - `401`: Unauthorized - `422`: Invalid data was sent. - `500`: Internal Error --- [API](https://skmtc.dev/checkout/apis/checkout-com-api-reference.md) - [All operations](https://skmtc.dev/checkout/apis/checkout-com-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/checkout/apis/checkout-com-api-reference/revisions/0f1abdb1c3e9?raw)