Checkout.com API logo

Forward

Forward an API request

Beta

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.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
Request Body schema: application/json
required
required
object (ForwardRequestSource)

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}}.

required
object

The parameters of the forward request.

reference
string <= 80 characters

The unique reference for the forward request.

processing_channel_id
string^(pc)_(\w{26})$

The processing channel ID to associate the billing for the forward request with.

object (ForwardRequestNetworkToken)

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

Responses
200

The request was successfully forwarded.

401

Unauthorized

422

Invalid data was sent.

500

Internal Error

post/forward
Request samples
application/json
{
  • "source": {
    },
  • "reference": "ORD-5023-4E89",
  • "processing_channel_id": "pc_azsiyswl7bwe2ynjzujy7lcjca",
  • "network_token": {
    },
  • "destination_request": {
    }
}
Response samples
application/json
{
  • "request_id": "fwd_01HK153X00VZ1K15Z3HYC0QGPN",
  • "destination_response": {
    },
  • "source": {
    }
}

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.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
path Parameters
id
required
string^fwd_[A-Z0-9]{26}$

The unique identifier of the forward request.

Responses
200

Forward request retrieved successfully

401

Unauthorized

404

Forward request not found

500

Internal Server Error

get/forward/{id}
Request samples 
Response samples 
application/json
{
  • "request_id": "fwd_01HK153X00VZ1K15Z3HYC0QGPN",
  • "reference": "ORD-5023-4E89",
  • "entity_id": "ent_lp6h57qskk6ubewfk3pq4f2c2y",
  • "destination_request": {
    },
  • "destination_response": {
    },
  • "created_on": "2024-01-02T15:04:05+00:00"
}
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.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
Request Body schema: application/json
required
name
required
string  [ 1 .. 64 ] characters ^[a-zA-Z0-9_]{1,64}$
Secret name. 

Format – 1-64 characters. Alphanumeric and underscore.


 
value
required
string  <= 8192 characters 
Plaintext secret value. Max 8KB.


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


 
Responses 
201
Secret created successfully.


401
Unauthorized


409
Conflict - secret with this name already exists


422
Invalid data was sent


500
Internal Error


post/forward/secrets
Request samples 
application/json
{
  • "name": "secret_name",
  • "value": "plaintext",
  • "entity_id": "ent_12345"
}
Response samples 
application/json
{
  • "name": "secret_name",
  • "created_at": "2025-10-14T00:00:00Z",
  • "updated_at": "2025-10-14T00:00:00Z",
  • "version": 1,
  • "entity_id": "ent_123"
}
List secrets
Returns metadata for secrets scoped for client_id.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Responses 
200
List of secrets


401
Unauthorized


500
Internal Error


get/forward/secrets
Request samples 
Response samples 
application/json
{
  • "data": [
    ]
}
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.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
name
required
string^[a-zA-Z0-9_]{1,64}$
Secret name.


 
Request Body schema: application/json
required
entity_id
string
Update the entity scope.


 
value
string  <= 8192 characters 
New plaintext secret value. Max 8KB.


 
Responses 
200
Secret updated successfully


401
Unauthorized


404
Secret not found


422
Invalid data was sent


500
Internal Error


patch/forward/secrets/{name}
Request samples 
application/json
{
  • "entity_id": "ent_1234",
  • "value": "NEW_VALUE_1"
}
Response samples 
application/json
{
  • "name": "secret_name_1",
  • "created_at": "2025-10-14T00:00:00Z",
  • "updated_at": "2025-10-14T12:00:00Z",
  • "version": 2,
  • "entity_id": "ent_123"
}
Delete secret
Permanently delete a secret by name.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
name
required
string^[a-zA-Z0-9_]{1,64}$
Secret name.


 
Responses 
204
Secret deleted successfully


401
Unauthorized


404
Secret not found


500
Internal Error


delete/forward/secrets/{name}
Request samples 
➔ Next to Standalone