Forward

​
Forward Operations

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:

      1. Collect the PIN from the user.
      2. tokenize it using the /tokens endpoint 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.

  • 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

Request Example for 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"
      }
    ]
  }
}'

{
  "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.

Get forward request

​

Retrieve the details of a successfully forwarded API request.

The details can be retrieved for up to 14 days after the request was initiated.

Path Parameters
  • id
    Type: string Pattern: ^fwd_[A-Z0-9]{26}$
    required

    The unique identifier of the forward request.

Responses
  • application/json
  • 401

    Unauthorized

  • 404

    Forward request not found

  • 500

    Internal Server Error

Request Example for get/forward/{id}
Shell Curl
curl 'https://forward.checkout.com/forward/{id}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "request_id": "fwd_01HK153X00VZ1K15Z3HYC0QGPN",
  "reference": "ORD-5023-4E89",
  "entity_id": "ent_lp6h57qskk6ubewfk3pq4f2c2y",
  "destination_request": {
    "url": "https://example.com/payments",
    "method": "POST",
    "headers": {
      "Authorization": "***redacted***",
      "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}"
  },
  "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\"}}}"
  },
  "created_on": "2024-01-02T15:04:05+00:00"
}

Forward request retrieved successfully

Create secret

​

Create a new secret with a plaintext value.

Validation Rules:

  • name: 1-64 characters, alphanumeric + underscore
  • value: max 8KB
  • entity_id (optional): when provided, secret is scoped to this entity

Response: Returns metadata.

Body·
required
application/json

Request to create a secret with plaintext value

  • name
    Type: string
    min length:  
    1
    max length:  
    64    Pattern: ^[a-zA-Z0-9_]{1,64}$
    required

    Secret name.
    Format – 1-64 characters. Alphanumeric and underscore.

  • value
    Type: string
    max length:  
    8192
    required

    Plaintext secret value. Max 8KB.

  • entity_id
    Type: string

    Optional.When provided, the secret is scoped to this entity

Responses
  • application/json
  • 401

    Unauthorized

  • 409

    Conflict - secret with this name already exists

  • application/json
  • 500

    Internal Error

Request Example for post/secrets
curl https://forward.checkout.com/secrets \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "name": "secret_name",
  "value": "plaintext",
  "entity_id": "ent_12345"
}'

{
  "name": "secret_name",
  "created_at": "2025-10-14T00:00:00Z",
  "updated_at": "2025-10-14T00:00:00Z",
  "version": 1,
  "entity_id": "ent_123"
}

Secret created successfully.

List secrets

​

Returns metadata for secrets scoped for client_id.

Responses
  • application/json
  • 401

    Unauthorized

  • 500

    Internal Error

Request Example for get/secrets
Shell Curl
curl https://forward.checkout.com/secrets \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "data": [
    {
      "name": "secret_name_1",
      "created_at": "2025-10-14T00:00:00Z",
      "updated_at": "2025-10-14T00:00:00Z",
      "version": 1,
      "entity_id": "ent_123"
    },
    {
      "name": "secret_name_2",
      "created_at": "2025-10-14T01:00:00Z",
      "updated_at": "2025-10-14T01:00:00Z",
      "version": 2,
      "entity_id": "ent_456"
    },
    {
      "name": "secret_name_3",
      "created_at": "2025-10-14T02:00:00Z",
      "updated_at": "2025-10-14T02:00:00Z",
      "version": 3,
      "entity_id": "ent_789"
    }
  ]
}

List of secrets

Update secret

​

Update an existing secret. After updating, the version is automatically incremented.

Validation Rules:

  • Only value and entity_id can be updated
  • value: max 8KB

Response: Returns updated metadata with incremented version.

Path Parameters
  • name
    Type: string Pattern: ^[a-zA-Z0-9_]{1,64}$
    required

    Secret name.

Body·
required
application/json

Request to update an existing secret. At least one of value or entity_id must be provided.

  • entity_id
    Type: string

    Update the entity scope.

  • value
    Type: string
    max length:  
    8192

    New plaintext secret value. Max 8KB.

Responses
  • application/json
  • 401

    Unauthorized

  • 404

    Secret not found

  • application/json
  • 500

    Internal Error

Request Example for patch/secrets/{name}
curl 'https://forward.checkout.com/secrets/{name}' \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "entity_id": "ent_1234",
  "value": "NEW_VALUE_1"
}'

{
  "name": "secret_name_1",
  "created_at": "2025-10-14T00:00:00Z",
  "updated_at": "2025-10-14T12:00:00Z",
  "version": 2,
  "entity_id": "ent_123"
}

Secret updated successfully

Delete secret

​

Permanently delete a secret by name.

Path Parameters
  • name
    Type: string Pattern: ^[a-zA-Z0-9_]{1,64}$
    required

    Secret name.

Responses
  • 204

    Secret deleted successfully

  • 401

    Unauthorized

  • 404

    Secret not found

  • 500

    Internal Error

Request Example for delete/secrets/{name}
Shell Curl
curl 'https://forward.checkout.com/secrets/{name}' \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No Body

Secret deleted successfully