Forward an API request

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.

Body·

required

application/json

The request template to forward to the third-party endpoint.

Template values will be replaced before the request is forwarded.

source
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}}.
The payment instrument to enrich the forward request with.
type
Discriminator
Type: string
required

The payment source type.

id
Type: string Pattern: ^(src)_(\w{26})$
required

The unique identifier of the payment instrument.

cvv_token
Type: string Pattern: ^(tok)_(\w{26})$

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
Type: string Pattern: ^(tok)_(\w{26})$

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:

Collect the PIN from the user.

tokenize it using the /tokens endpoint setting type to pin.

Pass the resulting token value of the response in this field.

This token replaces the {{card_pin}} placeholder value in destination_request.body.
destination_request
Type: object ·
required

The parameters of the forward request.
reference
Type: string
max length:
80

The unique reference for the forward request.
processing_channel_id
Type: string Pattern: ^(pc)_(\w{26})$

The processing channel ID to associate the billing for the forward request with.
network_token
Type: object ·

Specifies if and how a network token should be used in the forward request.

Responses

application/json
401

Unauthorized
application/json
500

Internal Error

post/forward

curl https://forward.checkout.com/forward \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "source": {
    "id": "src_v5rgkf3gdtpuzjqesyxmyodnya",
    "type": "id"
  },
  "reference": "ORD-5023-4E89",
  "processing_channel_id": "pc_azsiyswl7bwe2ynjzujy7lcjca",
  "network_token": {
    "enabled": true,
    "request_cryptogram": false
  },
  "destination_request": {
    "url": "https://example.com/payments",
    "method": "POST",
    "headers": {
      "encrypted": "<JWE encrypted JSON object with string values>",
      "raw": {
        "Idempotency-Key": "xe4fad12367dfgrds",
        "Content-Type": "application/json"
      }
    },
    "body": "{\"amount\": 1000, \"currency\": \"USD\", \"reference\": \"some_reference\", \"source\": {\"type\": \"card\", \"number\": \"{{card_number}}\", \"expiry_month\": \"{{card_expiry_month}}\", \"expiry_year\": \"{{card_expiry_year_yyyy}}\", \"card_pin\": \"{{card_pin}}\", \"name\": \"Ali Farid\"}, \"payment_type\": \"Regular\", \"authorization_type\": \"Final\", \"capture\": true, \"processing_channel_id\": \"pc_xxxxxxxxxxx\", \"risk\": {\"enabled\": false}, \"merchant_initiated\": true}",
    "signature": {
      "type": "dlocal",
      "dlocal_parameters": {
        "secret_key": "9f439fe1a9f96e67b047d3c1a28c33a2e"
      }
    },
    "variables": [
      {
        "name": "card_data",
        "value": "{\"card_number\":\"{{card_number}}\",\"expiry\":\"{{card_expiry_month}}\"}"
      },
      {
        "name": "public_key",
        "value": "{\"kty\":\"RSA\",\"e\":\"AQAB\",\"use\":\"enc\",\"kid\":\"key-001\"}"
      }
    ],
    "query": [
      {
        "name": "api_key",
        "value": "1234567890"
      },
      {
        "name": "user_id",
        "value": "1234567890"
      }
    ]
  }
}'

Show Schema

{
  "request_id": "fwd_01HK153X00VZ1K15Z3HYC0QGPN",
  "destination_response": {
    "status": 201,
    "headers": {
      "Cko-Request-Id": [
        "5fa7ee8c-f82d-4440-a6dc-e8c859b03235"
      ],
      "Content-Type": [
        "application/json"
      ]
    },
    "body": "{\"id\": \"pay_mbabizu24mvu3mela5njyhpit4\", \"action_id\": \"act_mbabizu24mvu3mela5njyhpit4\", \"amount\": 6540, \"currency\": \"USD\", \"approved\": true, \"status\": \"Authorized\", \"auth_code\": \"770687\", \"response_code\": \"10000\", \"response_summary\": \"Approved\", \"_links\": {\"self\": {\"href\": \"https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4\"}, \"action\": {\"href\": \"https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions\"}, \"void\": {\"href\": \"https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids\"}, \"capture\": {\"href\": \"https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures\"}}}"
  },
  "source": {
    "id": "src_evls5rkafabudm3x6gejc4bbo4",
    "bin": "45434748",
    "last4": "9996",
    "fingerprint": "B086A9386241A0BDCBEFAFC1E4FD5C3DD04684AAD21A126CB426C05555AC86A9"
  }
}

The request was successfully forwarded.