",
"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"
}
]
}
```
The details of the request to forward.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|url|string|true|none|The URL to forward the request to.|
|method|string|true|none|The HTTP method to use for the forward request.|
|headers|[ForwardBodyHeadersRequest](#schemaforwardbodyheadersrequest)|true|none|The HTTP headers to include in the forward request.|
|body|string|true|none|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}}`.|
|signature|[ForwardRequestSignature](#schemaforwardrequestsignature)|false|none|Optional configuration to add a signature to the forwarded HTTP request.|
|variables|[object]|false|none|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}}`.|
|» name|string|false|none|The variable name.|
|» value|string|false|none|The variable value.|
|query|[object]|false|none|The query parameters used in the forward request. These values are added to the destination URL as query parameters.|
|» name|string|false|none|The query parameter name.|
|» value|string|false|none|The query parameter value.|
#### Enumerated Values
|Property|Value|
|---|---|
|method|GET|
|method|HEAD|
|method|POST|
|method|PUT|
|method|DELETE|
|method|OPTIONS|
|method|TRACE|
|method|PATCH|
ForwardRequestNetworkToken
```json
{
"enabled": true,
"request_cryptogram": false
}
```
Specifies if and how a network token should be used in the forward request.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|enabled|boolean|false|none|Specifies whether to use a network token.|
|request_cryptogram|boolean|false|none|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.|
ForwardRequestSignature
```json
{
"type": "dlocal",
"dlocal_parameters": {
"secret_key": "9f439fe1a9f96e67b047d3c1a28c33a2e"
}
}
```
Optional configuration to add a signature to the forwarded HTTP request.
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[ForwardRequestSignatureDLocal](#schemaforwardrequestsignaturedlocal)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[ForwardRequestSignatureMastercard](#schemaforwardrequestsignaturemastercard)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[ForwardRequestSignatureVisa](#schemaforwardrequestsignaturevisa)|false|none|none|
ForwardRequestSignatureDLocal
```json
{
"type": "dlocal",
"dlocal_parameters": {
"secret_key": "string"
}
}
```
dlocal
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The identifier of the supported signature generation method or a specific third-party service.|
|dlocal_parameters|object|true|none|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|true|none|The secret key used to generate the request signature. This is part of the dLocal API credentials.|
ForwardRequestSignatureMastercard
```json
{
"type": "mastercard",
"mastercard_parameters": {
"consumer_key": "string",
"signing_key": "string"
}
}
```
mastercard
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The identifier of the supported signature generation method or a specific third-party service.|
|mastercard_parameters|object|true|none|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|true|none|An identifier of the client application. Part of the Mastercard APIs credentials.|
|» signing_key|string|true|none|A 2048-bit private RSA key used to generate request signatures and confirming ownership of the consumer key. Part of the Mastercard APIs credentials.|
ForwardRequestSignatureVisa
```json
{
"type": "visa",
"visa_parameters": {
"shared_secret": "string",
"remove_resource_path_prefix": "/"
}
}
```
visa
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The identifier of the supported signature generation method or a specific third-party service.|
|visa_parameters|object|true|none|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|true|none|The secret key used to generate the request signature; part of the Visa API credentials.|
|» remove_resource_path_prefix|string|false|none|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).|
ForwardRequestSource
```json
{
"id": "src_v5rgkf3gdtpuzjqesyxmyodnya",
"type": "id"
}
```
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}}`.
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[ForwardRequestIdSource](#schemaforwardrequestidsource)|false|none|The payment instrument to enrich the forward request with.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[ForwardRequestTokenSource](#schemaforwardrequesttokensource)|false|none|The token to enrich the forward request with.|
ForwardValidationError
```json
{
"request_id": "fwd_01HK153X00VZ1K15Z3HYC0QGPN",
"error_type": "request_invalid",
"error_codes": [
"processing_channel_id_required"
],
"errors": {
"processing_channel_id": [
"The processing_channel_id field is required"
]
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|request_id|string|true|none|none|
|error_type|string|true|none|none|
|error_codes|[string]|true|none|none|
|errors|object|false|none|none|
|» **additionalProperties**|[string]|false|none|The field's error messages.|
GetForwardRequestDestinationRequest
```json
{
"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}"
}
```
The details of the request to forward.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|url|string|true|none|The URL of the forward request.|
|method|string|true|none|The HTTP method of the forward request.|
|headers|object|true|none|The HTTP headers of the forward request.
Encrypted and sensitive header values are redacted.|
|» **additionalProperties**|string|false|none|The header value.|
|body|string|true|none|The HTTP message body of the forward request.
This is the original value used to initiate the request, with placeholder value text included. For example, `{{card_number}}` is not replaced with an actual card number.|
GetForwardRequestDestinationResponse
```json
{
"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\"}}}"
}
```
The response returned by the third-party endpoint the forward request was sent to.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|status|number|true|none|The HTTP status code returned with the destination response.|
|headers|object|true|none|The destination response's HTTP headers.|
|» **additionalProperties**|[string]|false|none|The header values.|
|body|string|true|none|The destination response's HTTP message body.|
ForwardRequestIdSource
```json
{
"type": "id",
"id": "src_wmlfc3zyhqzehihu7giusaaawu",
"cvv_token": "tok_wnw2grxl4hbufp7q55tw2pb2t4",
"pin_token": "tok_wnw2grxl4hbufp7q55tw2pb2t4"
}
```
id
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
|id|string|true|none|The unique identifier of the payment instrument.|
|cvv_token|string|false|none|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|false|none|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`.|
ForwardRequestTokenSource
```json
{
"type": "token",
"token": "tok_ubfj2q76miwundwlk72vxt2i7q",
"store_for_future_use": false
}
```
token
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
|token|string|true|none|The unique Checkout.com token.|
|store_for_future_use|boolean|false|none|Specifies whether to store the tokenized credentials as a payment instrument and return its identifier in the response.|
CreateSecretPlaintextRequest
```json
{
"name": "secret_name",
"value": "my_secret_value",
"entity_id": "ent_svrxgarj6qru5pzx4m4movyney"
}
```
Request to create a secret with plaintext value
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|true|none|Secret name.
Format – 1-64 characters. Alphanumeric and underscore.|
|value|string|true|none|Plaintext secret value. Max 8KB.|
|entity_id|string|false|none|Optional.When provided, the secret is scoped to this entity|
SecretResponse
```json
{
"name": "secret_name",
"created_at": "2025-10-14T00:00:00Z",
"updated_at": "2025-10-14T00:00:00Z",
"version": 1,
"entity_id": "ent_123"
}
```
Secret response metadata. The secret value is never returned in responses.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|true|none|Secret name (1-64 characters, alphanumeric and underscore)|
|created_at|string(date-time)|true|none|Timestamp when the secret was created.|
|updated_at|string(date-time)|true|none|Timestamp when the secret was last updated.|
|version|integer|true|none|Version number.|
|entity_id|string|false|none|Entity ID if the secret is scoped to a specific entity.|
UpdateSecretRequest
```json
{
"entity_id": "ent_kf3pqe272lqevcpx5xtlndgcii",
"value": "NEW_VALUE_1"
}
```
Request to update an existing secret. At least one of `value` or `entity_id` must be provided.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|entity_id|string|false|none|Update the entity scope.|
|value|string|false|none|New plaintext secret value. Max 8KB.|
GooglePayDomainListResponse
```json
{
"domains": [
"example.com"
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|domains|[string]|true|none|The list of domains registered for the entity.|
GooglePayEnrollmentRequest
```json
{
"entity_id": "ent_uzm3uxtssvmuxnyrfdffcyjxeu",
"email_address": "test@gmail.com",
"accept_terms_of_service": true
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|entity_id|string|true|none|The unique identifier of the entity to enroll.|
|email_address|string|true|none|The email address of the user accepting the Google terms of service.|
|accept_terms_of_service|boolean|true|none|Indicates acceptance of the Google terms of service. Must be true to proceed with enrollment.|
GooglePayEnrollmentResponse
```json
{
"merchant_id": "01234567890123456789",
"tos_accepted_time": "2014-10-02T15:01:23Z",
"state": "ACTIVE"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|merchant_id|string|false|none|The Google Pay merchant ID associated with the entity.|
|tos_accepted_time|string(date-time)|true|none|An ISO 8601 timestamp of when the [Google terms of service](https://payments.developers.google.com/terms/sellertos) were accepted.|
|state|string|true|none|The current enrollment state of the entity.|
#### Enumerated Values
|Property|Value|
|---|---|
|state|ACTIVE|
|state|INACTIVE|
GooglePayEnrollmentStateResponse
```json
{
"state": "ACTIVE"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|state|string|true|none|The current enrollment state of the entity.|
#### Enumerated Values
|Property|Value|
|---|---|
|state|ACTIVE|
|state|INACTIVE|
GooglePayErrorResponse
```json
{
"error_codes": [
"string"
],
"error_type": "invalid_request",
"request_id": "string"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|error_codes|[string]|false|none|none|
|error_type|string|false|none|none|
|request_id|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|error_type|invalid_request|
GooglePayRegisterDomainRequest
```json
{
"web_domain": "some.example.com"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|web_domain|string(hostname)|true|none|The web domain to register for an actively enrolled entity.|
GetHostedPaymentsResponse
```json
{
"id": "hpp_xGQBg0AXl3cM",
"status": "Payment Pending",
"payment_id": "pay_88cb4e671m1da22e9bbbyx",
"amount": 100,
"currency": "GBP",
"reference": "ORD-123A",
"description": "Payment for Gold Necklace",
"customer": {
"email": "brucewayne@email.com",
"name": "Bruce Wayne"
},
"billing": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"products": [
{
"reference": "string",
"url": "https://example.com/products/gold-necklace",
"name": "Gold Necklace",
"quantity": 1,
"price": 1000
}
],
"metadata": {},
"success_url": "https://example.com/success",
"cancel_url": "https://example.com/cancel",
"failure_url": "https://example.com/failure",
"amount_allocations": [
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4",
"amount": 1000,
"reference": "ORD-5023-4E89",
"commission": {
"amount": 1000,
"percentage": 1.125
}
}
],
"_links": {
"self": {
"href": "https://{prefix}.api.sandbox.checkout.com/hosted-payments/hpp_xGQBg0AXl3cM"
},
"redirect": {
"href": "https://pay.sandbox.checkout.com/page/hpp_xGQBg0AXl3cM"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[HostedPaymentId](#schemahostedpaymentid)|true|none|The unique identifier for a Hosted Payments Page.|
|status|string|true|none|The status of the Hosted Payments Page:
- `Payment Pending`: The Hosted Payments Page can accept a payment from the customer. A payment may have been attempted by the customer but not completed successfully.
- `Payment Received`: A payment has been received successfully using this Hosted Payments Page.
- `Expired`: The Hosted Payments Page has expired and can no longer be accessed.|
|payment_id|string|false|none|Unique identifier for an in progress or completed payment for this Payment Link.|
|amount|integer|true|none|The original payment amount.|
|currency|string|true|none|The three-letter ISO currency code of the payment.
|
|reference|string|false|none|Your reference for the payment.|
|description|string|false|none|A description of the payment.|
|customer|object|false|none|The customer's details.|
|» email|string(email)|false|none|The email address for the customer.|
|» name|string|false|none|The customer's name.|
|billing|object|true|none|The billing details.|
|» address|[Address](#schemaaddress)|true|none|The billing address.|
|» phone|[PhoneNumber](#schemaphonenumber)|false|none|The customer's phone number.|
|products|[PaymentInterfacesProducts](#schemapaymentinterfacesproducts)|false|none|Contains details about the products in the order.|
|metadata|object|false|none|Any additional information stored at the point of creation.|
|success_url|string(uri)|true|none|The provided URL your customer will be redirected to upon a successful payment.|
|cancel_url|string(uri)|true|none|The provided URL your customer will be redirected to if the payment is cancelled.|
|failure_url|string(uri)|true|none|The provided URL your customer will be redirected to upon a failed payment.|
|amount_allocations|[AmountAllocations](#schemaamountallocations)|false|none|The sub-entities that the payment is being processed on behalf of|
|_links|[GetHostedPaymentsResponseLinks](#schemagethostedpaymentsresponselinks)|true|none|The links related to the Hosted Payments Page.|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[GetHostedPaymentsResponseStatusPaymentPending](#schemagethostedpaymentsresponsestatuspaymentpending)|false|none|A Hosted Payments Page that can accept a payment from a customer.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[GetHostedPaymentsResponseStatusPaymentReceived](#schemagethostedpaymentsresponsestatuspaymentreceived)|false|none|A Hosted Payments Page that has received a payment|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[GetHostedPaymentsResponseStatusExpired](#schemagethostedpaymentsresponsestatusexpired)|false|none|An expired Hosted Payments Page.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Payment Pending|
|status|Payment Received|
|status|Expired|
GetHostedPaymentsResponseLinks
```json
{
"self": {
"href": "https://{prefix}.api.sandbox.checkout.com/hosted-payments/hpp_xGQBg0AXl3cM"
},
"redirect": {
"href": "https://pay.sandbox.checkout.com/page/hpp_xGQBg0AXl3cM"
}
}
```
The links related to the Hosted Payments Page.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|self|[Link](#schemalink)|true|none|The URI of the Hosted Payments Page details.|
|redirect|[Link](#schemalink)|true|none|The link to visit the Hosted Payments Page.|
|payment|[Link](#schemalink)|false|none|The URI of the in progress or completed payment for this Hosted Payments Page.|
|payment_actions|[Link](#schemalink)|false|none|The URI of the actions associated with the in progress or completed payment for this Hosted Payments Page.|
GetHostedPaymentsResponseStatusExpired
```json
{
"id": "hpp_xGQBg0AXl3cM",
"status": "Expired",
"payment_id": "pay_88cb4e671m1da22e9bbbyx",
"amount": 100,
"currency": "GBP",
"reference": "ORD-123A",
"description": "Payment for Gold Necklace",
"customer": {
"email": "brucewayne@email.com",
"name": "Bruce Wayne"
},
"billing": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"products": [
{
"reference": "string",
"url": "https://example.com/products/gold-necklace",
"name": "Gold Necklace",
"quantity": 1,
"price": 1000
}
],
"metadata": {},
"success_url": "https://example.com/success",
"cancel_url": "https://example.com/cancel",
"failure_url": "https://example.com/failure",
"amount_allocations": [
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4",
"amount": 1000,
"reference": "ORD-5023-4E89",
"commission": {
"amount": 1000,
"percentage": 1.125
}
}
],
"_links": {
"self": {
"href": "https://{prefix}.api.sandbox.checkout.com/hosted-payments/hpp_xGQBg0AXl3cM"
},
"redirect": {
"href": "https://pay.sandbox.checkout.com/page/hpp_xGQBg0AXl3cM"
}
}
}
```
Expired
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[HostedPaymentId](#schemahostedpaymentid)|true|none|The unique identifier for a Hosted Payments Page.|
|status|string|true|none|The status of the Hosted Payments Page:
- `Payment Pending`: The Hosted Payments Page can accept a payment from the customer. A payment may have been attempted by the customer but not completed successfully.
- `Payment Received`: A payment has been received successfully using this Hosted Payments Page.
- `Expired`: The Hosted Payments Page has expired and can no longer be accessed.|
|payment_id|string|false|none|Unique identifier for an in progress or completed payment for this Payment Link.|
|amount|integer|true|none|The original payment amount.|
|currency|string|true|none|The three-letter ISO currency code of the payment.
|
|reference|string|false|none|Your reference for the payment.|
|description|string|false|none|A description of the payment.|
|customer|object|false|none|The customer's details.|
|» email|string(email)|false|none|The email address for the customer.|
|» name|string|false|none|The customer's name.|
|billing|object|true|none|The billing details.|
|» address|[Address](#schemaaddress)|true|none|The billing address.|
|» phone|[PhoneNumber](#schemaphonenumber)|false|none|The customer's phone number.|
|products|[PaymentInterfacesProducts](#schemapaymentinterfacesproducts)|false|none|Contains details about the products in the order.|
|metadata|object|false|none|Any additional information stored at the point of creation.|
|success_url|string(uri)|true|none|The provided URL your customer will be redirected to upon a successful payment.|
|cancel_url|string(uri)|true|none|The provided URL your customer will be redirected to if the payment is cancelled.|
|failure_url|string(uri)|true|none|The provided URL your customer will be redirected to upon a failed payment.|
|amount_allocations|[AmountAllocations](#schemaamountallocations)|false|none|The sub-entities that the payment is being processed on behalf of|
|_links|[GetHostedPaymentsResponseLinks](#schemagethostedpaymentsresponselinks)|true|none|The links related to the Hosted Payments Page.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Expired|
GetHostedPaymentsResponseStatusPaymentPending
```json
{
"id": "hpp_xGQBg0AXl3cM",
"status": "Payment Pending",
"payment_id": "pay_88cb4e671m1da22e9bbbyx",
"amount": 100,
"currency": "GBP",
"reference": "ORD-123A",
"description": "Payment for Gold Necklace",
"customer": {
"email": "brucewayne@email.com",
"name": "Bruce Wayne"
},
"billing": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"products": [
{
"reference": "string",
"url": "https://example.com/products/gold-necklace",
"name": "Gold Necklace",
"quantity": 1,
"price": 1000
}
],
"metadata": {},
"success_url": "https://example.com/success",
"cancel_url": "https://example.com/cancel",
"failure_url": "https://example.com/failure",
"amount_allocations": [
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4",
"amount": 1000,
"reference": "ORD-5023-4E89",
"commission": {
"amount": 1000,
"percentage": 1.125
}
}
],
"_links": {
"self": {
"href": "https://{prefix}.api.sandbox.checkout.com/hosted-payments/hpp_xGQBg0AXl3cM"
},
"redirect": {
"href": "https://pay.sandbox.checkout.com/page/hpp_xGQBg0AXl3cM"
}
}
}
```
Payment Pending
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[HostedPaymentId](#schemahostedpaymentid)|true|none|The unique identifier for a Hosted Payments Page.|
|status|string|true|none|The status of the Hosted Payments Page:
- `Payment Pending`: The Hosted Payments Page can accept a payment from the customer. A payment may have been attempted by the customer but not completed successfully.
- `Payment Received`: A payment has been received successfully using this Hosted Payments Page.
- `Expired`: The Hosted Payments Page has expired and can no longer be accessed.|
|payment_id|string|false|none|Unique identifier for an in progress or completed payment for this Payment Link.|
|amount|integer|true|none|The original payment amount.|
|currency|string|true|none|The three-letter ISO currency code of the payment.
|
|reference|string|false|none|Your reference for the payment.|
|description|string|false|none|A description of the payment.|
|customer|object|false|none|The customer's details.|
|» email|string(email)|false|none|The email address for the customer.|
|» name|string|false|none|The customer's name.|
|billing|object|true|none|The billing details.|
|» address|[Address](#schemaaddress)|true|none|The billing address.|
|» phone|[PhoneNumber](#schemaphonenumber)|false|none|The customer's phone number.|
|products|[PaymentInterfacesProducts](#schemapaymentinterfacesproducts)|false|none|Contains details about the products in the order.|
|metadata|object|false|none|Any additional information stored at the point of creation.|
|success_url|string(uri)|true|none|The provided URL your customer will be redirected to upon a successful payment.|
|cancel_url|string(uri)|true|none|The provided URL your customer will be redirected to if the payment is cancelled.|
|failure_url|string(uri)|true|none|The provided URL your customer will be redirected to upon a failed payment.|
|amount_allocations|[AmountAllocations](#schemaamountallocations)|false|none|The sub-entities that the payment is being processed on behalf of|
|_links|[GetHostedPaymentsResponseLinks](#schemagethostedpaymentsresponselinks)|true|none|The links related to the Hosted Payments Page.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Payment Pending|
GetHostedPaymentsResponseStatusPaymentReceived
```json
{
"id": "hpp_xGQBg0AXl3cM",
"status": "Payment Received",
"payment_id": "pay_88cb4e671m1da22e9bbbyx",
"amount": 100,
"currency": "GBP",
"reference": "ORD-123A",
"description": "Payment for Gold Necklace",
"customer": {
"email": "brucewayne@email.com",
"name": "Bruce Wayne"
},
"billing": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"products": [
{
"reference": "string",
"url": "https://example.com/products/gold-necklace",
"name": "Gold Necklace",
"quantity": 1,
"price": 1000
}
],
"metadata": {},
"success_url": "https://example.com/success",
"cancel_url": "https://example.com/cancel",
"failure_url": "https://example.com/failure",
"amount_allocations": [
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4",
"amount": 1000,
"reference": "ORD-5023-4E89",
"commission": {
"amount": 1000,
"percentage": 1.125
}
}
],
"_links": {
"self": {
"href": "https://{prefix}.api.sandbox.checkout.com/hosted-payments/hpp_xGQBg0AXl3cM"
},
"redirect": {
"href": "https://pay.sandbox.checkout.com/page/hpp_xGQBg0AXl3cM"
}
}
}
```
Payment Received
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[HostedPaymentId](#schemahostedpaymentid)|true|none|The unique identifier for a Hosted Payments Page.|
|status|string|true|none|The status of the Hosted Payments Page:
- `Payment Pending`: The Hosted Payments Page can accept a payment from the customer. A payment may have been attempted by the customer but not completed successfully.
- `Payment Received`: A payment has been received successfully using this Hosted Payments Page.
- `Expired`: The Hosted Payments Page has expired and can no longer be accessed.|
|payment_id|string|true|none|Unique identifier for an in progress or completed payment for this Payment Link.|
|amount|integer|true|none|The original payment amount.|
|currency|string|true|none|The three-letter ISO currency code of the payment.
|
|reference|string|false|none|Your reference for the payment.|
|description|string|false|none|A description of the payment.|
|customer|object|false|none|The customer's details.|
|» email|string(email)|false|none|The email address for the customer.|
|» name|string|false|none|The customer's name.|
|billing|object|true|none|The billing details.|
|» address|[Address](#schemaaddress)|true|none|The billing address.|
|» phone|[PhoneNumber](#schemaphonenumber)|false|none|The customer's phone number.|
|products|[PaymentInterfacesProducts](#schemapaymentinterfacesproducts)|false|none|Contains details about the products in the order.|
|metadata|object|false|none|Any additional information stored at the point of creation.|
|success_url|string(uri)|true|none|The provided URL your customer will be redirected to upon a successful payment.|
|cancel_url|string(uri)|true|none|The provided URL your customer will be redirected to if the payment is cancelled.|
|failure_url|string(uri)|true|none|The provided URL your customer will be redirected to upon a failed payment.|
|amount_allocations|[AmountAllocations](#schemaamountallocations)|false|none|The sub-entities that the payment is being processed on behalf of|
|_links|[GetHostedPaymentsResponseLinks](#schemagethostedpaymentsresponselinks)|true|none|The links related to the Hosted Payments Page.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Payment Received|
HostedPaymentId
```json
"stringstringstri"
```
The unique identifier for a Hosted Payments Page.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The unique identifier for a Hosted Payments Page.|
HostedPaymentsRequest
```json
{
"amount": 1000,
"currency": "GBP",
"payment_type": "Regular",
"authorization_type": "Estimated",
"payment_plan": {
"amount_variability": "Variable",
"days_between_payments": 28,
"total_number_of_payments": 5,
"current_payment_number": 3,
"expiry": "20251031",
"name": "Subscription 1234",
"start_date": "20260507",
"amount": 1234
},
"payment_ip": "90.197.169.245",
"billing_descriptor": {
"name": "string",
"city": "string",
"reference": "string"
},
"reference": "ORD-123A",
"description": "Payment for Gold Necklace",
"display_name": "The Jewelry Shop",
"processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
"amount_allocations": [
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4",
"amount": 1000,
"reference": "ORD-5023-4E89",
"commission": {
"amount": 1000,
"percentage": 1.125
}
}
],
"customer": {
"email": "ali.farid@example.com",
"name": "Ali Farid",
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"summary": {
"registration_date": "2023-05-01",
"first_transaction_date": "2023-07-01",
"last_payment_date": "2023-08-01",
"total_order_count": 15,
"last_payment_amount": 500,
"is_premium_customer": true,
"is_returning_customer": true,
"lifetime_value": 500
}
},
"shipping": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"billing": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"recipient": {
"dob": "1985-05-15",
"account_number": "5555554444",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"first_name": "Jia",
"last_name": "Tsang"
},
"processing": {
"aft": true,
"discount_amount": 0,
"shipping_amount": 300,
"tax_amount": 3000,
"invoice_id": "string",
"brand_name": "string",
"locale": "en-US",
"partner_customer_risk_data": {
"key": "string",
"value": "string"
},
"custom_payment_method_ids": [
"string"
],
"airline_data": [
{
"ticket": {
"number": "045-21351455613",
"issue_date": "2023-05-20",
"issuing_carrier_code": "AI",
"travel_package_indicator": "B",
"travel_agency_name": "World Tours",
"travel_agency_code": "01"
},
"passenger": [
{
"first_name": "John",
"last_name": "White",
"date_of_birth": "1990-05-26",
"address": {
"country": "US"
}
}
],
"flight_leg_details": [
{
"flight_number": "101",
"carrier_code": "BA",
"class_of_travelling": "J",
"departure_airport": "LHR",
"departure_date": "2023-06-19",
"departure_time": "15:30",
"arrival_airport": "LAX",
"stop_over_code": "x",
"fare_basis_code": "SPRSVR"
}
]
}
],
"accommodation_data": [
{
"name": "The Sea View Hotel",
"booking_reference": "HOTEL123",
"check_in_date": "2023-06-20",
"check_out_date": "2023-06-23",
"address": {
"address_line1": "123 Beach Road",
"zip": "10001"
},
"state": "FL",
"country": "USA",
"city": "Los Angeles",
"number_of_rooms": 2,
"guests": [
{
"first_name": "Jane",
"last_name": "Doe",
"date_of_birth": "1985-07-14"
}
],
"room": [
{
"rate": "70",
"number_of_nights_at_room_rate": "3"
}
]
}
],
"order_id": "123456789",
"surcharge_amount": 200,
"duty_amount": 0,
"shipping_tax_amount": 100,
"affiliate_id": "string",
"affiliate_url": "www.mycrypto.com",
"purchase_country": "string",
"merchant_initiated_reason": "Delayed_charge",
"campaign_id": 0,
"original_order_amount": 10,
"receipt_id": "10",
"merchant_callback_url": "string",
"line_of_business": "Flights",
"pan_preference": "fpan",
"provision_network_token": true,
"reconciliation_id": "4123495123",
"aggregator": {
"sub_merchant_id": "9cf70789ba90123",
"aggregator_id_visa": "10012345",
"aggregator_id_mc": "00000123456"
}
},
"allow_payment_methods": [
"card",
"applepay",
"googlepay"
],
"disabled_payment_methods": [
"eps",
"ideal",
"knet"
],
"products": [
{
"reference": "string",
"url": "https://example.com/products/gold-necklace",
"name": "Gold Necklace",
"quantity": 1,
"price": 1000
}
],
"risk": {
"enabled": false
},
"customer_retry": {
"max_attempts": 2
},
"sender": {},
"success_url": "https://example.com/payments/success",
"cancel_url": "https://example.com/payments/cancel",
"failure_url": "https://example.com/payments/failure",
"metadata": {},
"locale": "ar",
"3ds": {
"enabled": false,
"attempt_n3d": false,
"challenge_indicator": "no_preference",
"allow_upgrade": true,
"exemption": "low_value"
},
"capture": true,
"capture_on": "2019-08-24T14:15:22Z",
"instruction": {
"purpose": "donations"
},
"payment_method_configuration": {
"applepay": {
"account_holder": {},
"store_payment_details": "disabled"
},
"card": {
"store_payment_details": "disabled",
"account_holder": {}
},
"googlepay": {
"account_holder": {},
"store_payment_details": "disabled"
},
"stored_card": {
"customer_id": "string",
"instrument_ids": [
"string"
],
"default_instrument_id": "string"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|amount|integer|false|none|The payment amount. The exact format depends on the currency|
|currency|string|true|none|The three-letter ISO currency code of the payment|
|payment_type|string|false|none|This must be specified for card payments where the cardholder is not present (i.e., recurring or mail order / telephone order)|
|authorization_type|string|false|none|The authorization type.|
|payment_plan|[PaymentSessionPaymentPlanRecurring](#schemapaymentsessionpaymentplanrecurring)|false|none|The information to process a recurring payment request. To be used when the payment_type is Recurring.|
|payment_ip|[IPAddress](#schemaipaddress)|false|none|The Customers IP address. Only IPv4 and IPv6 addresses are accepted.|
|billing_descriptor|object|false|none|An optional description that is displayed on the customer's statement identifying a purchase|
|» name|string|true|none|A dynamic description of the change|
|» city|string|true|none|The city from which the charge originated|
|» reference|string|false|none|The reference shown on the statement. Required for payouts to bank accounts.|
|reference|[PaymentInterfacesReference](#schemapaymentinterfacesreference)|false|none|A reference you can use to identify the payment. For example, an order number.
- For Amex payments, this must be at most 30 characters.
- For Benefit payments, the reference must be a unique alphanumeric value.
- For iDEAL payments, the reference is required and must be an alphanumeric value with a 35-character limit.|
|description|string|false|none|A description of the payment|
|display_name|string|false|none|The merchant name to display to customers on the checkout page.|
|processing_channel_id|string|false|none|The processing channel to be used for the payment|
|amount_allocations|[AmountAllocations](#schemaamountallocations)|false|none|The sub-entities that the payment is being processed on behalf of|
|customer|object|false|none|The customer's details|
|» email|string(email)|false|none|The customer's email address.|
|» name|string|false|none|The customer's name.
This will only set the name for new customers.|
|» phone|[PaymentInterfacesPhoneNumber](#schemapaymentinterfacesphonenumber)|false|none|The customer's phone number.|
|» summary|[PaymentInterfacesCustomerSummary](#schemapaymentinterfacescustomersummary)|false|none|Summary of the customer's transaction history.
Used for risk assessment when `source.type` is `Tamara`|
|shipping|object|false|none|The address any products are being sent to.|
|» address|[Address](#schemaaddress)|true|none|The customer's address to ship to.|
|» phone|[PhoneNumber](#schemaphonenumber)|false|none|The customer's phone number|
|billing|object|true|none|The billing details|
|» address|[Address](#schemaaddress)|true|none|The billing address|
|» phone|[PhoneNumber](#schemaphonenumber)|false|none|The customer's phone number. This will override the phone number specified during tokenization|
|recipient|[PaymentInterfacesRecipient](#schemapaymentinterfacesrecipient)|false|none|Information about the recipient of the payment's funds. Applies to Account Funding Transactions, and VISA or Mastercard domestic UK transactions processed by financial institutions.|
|processing|[PaymentInterfacesProcessing](#schemapaymentinterfacesprocessing)|false|none|Use the processing object to influence or override the data sent during card processing|
|allow_payment_methods|[PaymentInterfacesPaymentMethodEnum](#schemapaymentinterfacespaymentmethodenum)|false|none|Specifies which payment method options to present to the customer.
The values in this field override any equivalent values in `disabled_payment_methods`.
Some payment methods have additional field requirements. See the documentation for more information.|
|disabled_payment_methods|[PaymentInterfacesPaymentMethods](#schemapaymentinterfacespaymentmethods)|false|none|Specifies which payment method options to not present to the customer.
If you specify the same payment method in this field and in `allow_payment_methods`, the `disabled_payment_methods` value will be overridden.
Any payment method options not explicitly specified in this field will be presented to the customer by default.|
|products|[PaymentInterfacesProducts](#schemapaymentinterfacesproducts)|false|none|Contains details about the products in the order.|
|risk|object|false|none|Configures the risk assessment performed during payment processing.|
|» enabled|boolean|true|none|Specifies whether to perform a risk assessment.|
|customer_retry|object|false|none|Configures the parameters for customer retries.
A customer retry is a payment attempt performed by the customer on the checkout page. This differs from [authorization request retries](https://api-reference.checkout.com/#operation/requestAPaymentOrPayout!path=0/retry&t=request) performed in the back end by Checkout.com.|
|» max_attempts|integer|false|none|The maximum number of customer retry attempts, excluding the initial payment attempt.|
|sender|[PaymentInterfacesSender](#schemapaymentinterfacessender)|false|none|The sender of the payment.|
|success_url|string(uri)|true|none|For redirect payment methods, this overrides the default success redirect URL configured on your account|
|cancel_url|string(uri)|true|none|The URL to which the customer should be directed if they cancel the payment|
|failure_url|string(uri)|true|none|For redirect payment methods, this overrides the default failure redirect URL configured on your account|
|metadata|object|false|none|Allows you to store additional information about the transaction. This object only allows one level of depth, so cannot accept non-primitive data types such as objects or arrays.|
|locale|string|false|none|Creates a translated version of the page in the specified language|
|3ds|object|false|none|Information required for 3D Secure payments|
|» enabled|boolean|false|none|Whether to process this payment as a 3D Secure payment|
|» attempt_n3d|boolean|false|none|Applies only when `3ds.enabled` is set to `true`. Set to `true` to attempt the payment without 3DS when the issuer, card, or network doesn’t support 3DS.|
|» challenge_indicator|string|false|none|Indicates the preference for whether or not a 3DS challenge should be performed. The customer’s bank has the final say on whether or not the customer receives the challenge.|
|» allow_upgrade|boolean|false|none|Whether to process this payment as 3D Secure if the authorization was soft declined because 3DS authentication is required.|
|» exemption|string|false|none|Specifies an exemption reason so that the payment is not processed using 3D Secure authentication. Learn more about exemptions in our SCA compliance guide.|
|capture|boolean|false|none|Whether to capture the payment (if applicable).|
|capture_on|[Timestamp](#schematimestamp)|false|none|A timestamp (ISO 8601 code) that determines when the payment should be captured.
Providing this field will automatically set `capture` to true.|
|instruction|object|false|none|Details about the payment instruction.|
|» purpose|[Purpose](#schemapurpose)|false|none|The purpose of the payment.
This field might be required for AFT transactions depending on the card's `issuer_country`. To view a card's `issuer_country`, [retrieve the card's metadata](https://api-reference.checkout.com/#operation/requestCardMetadata!c=200&path=issuer_country&t=response).
See the [AFT documentation page](https://www.checkout.com/docs/payments/manage-payments/perform-an-account-funding-transaction) for more details.|
|payment_method_configuration|object|false|none|Configuration options for specific payment methods.|
|» applepay|object|false|none|Configuration options specific to Apple Pay payments.|
|»» account_holder|object|false|none|The account holder's details.|
|»» store_payment_details|[PaymentInterfacesStorePaymentDetails](#schemapaymentinterfacesstorepaymentdetails)|false|none|Specifies whether you intend to store the cardholder's payment details.
If you set this field to `enabled`, you must:
- have obtained consent from the cardholder to store their payment details
- provide a customer ID or email address in the request
If the request's `payment_type` is set to one of the following values, you do not need to provide this field:
- `Installment`
- `Recurring`
- `Unscheduled`|
|» card|object|false|none|Configuration options specific to card payments.|
|»» store_payment_details|string|false|none|Specifies whether you intend to store the cardholder's payment details.
If you set this field to `enabled` or `collect_consent`, you must:
- Have obtained consent from the cardholder to store their payment details
- Provide `customer.id` or `customer.email` in the request
You do not need to provide this field if `payment_type` is set to one of the following values:
- `Installment`
- `Recurring`
- `Unscheduled`|
|»» account_holder|object|false|none|The account holder's details.|
|» googlepay|object|false|none|Configuration options specific to Google Pay payments.|
|»» account_holder|object|false|none|The account holder's details.|
|»» store_payment_details|[PaymentInterfacesStorePaymentDetails](#schemapaymentinterfacesstorepaymentdetails)|false|none|Specifies whether you intend to store the cardholder's payment details.
If you set this field to `enabled`, you must:
- have obtained consent from the cardholder to store their payment details
- provide a customer ID or email address in the request
If the request's `payment_type` is set to one of the following values, you do not need to provide this field:
- `Installment`
- `Recurring`
- `Unscheduled`|
|» stored_card|object|false|none|Configuration options specific to stored card payments.|
|»» customer_id|string|false|none|The unique identifier for an existing [customer](https://api-reference.checkout.com/#tag/Customers). Enables the stored card payment method if the associated customer has one or more payment instruments stored.
This value takes precedence over `payment_method_configuration.stored_card.instrument_ids` when determining the stored cards to present to the customer.|
|»» instrument_ids|[string]|false|none|The unique identifiers for card Instruments. Enables stored card payment method if any one of them exists.
The first valid payment instrument in the list will be presented to the customer as the default option. Alternatively, you can explicitly specify a default payment instrument by providing its ID in the `payment_method_configuration.stored_card.default_instrument_id` field.|
|»» default_instrument_id|string|false|none|The unique identifier for the payment instrument to present to the customer as the default option.|
#### Enumerated Values
|Property|Value|
|---|---|
|payment_type|Regular|
|payment_type|Recurring|
|authorization_type|Final|
|authorization_type|Estimated|
|locale|ar|
|locale|da-DK|
|locale|de-DE|
|locale|el|
|locale|en-GB|
|locale|es-ES|
|locale|fi-FI|
|locale|fil-PH|
|locale|fr-FR|
|locale|hi-IN|
|locale|id-ID|
|locale|it-IT|
|locale|ja-JP|
|locale|ms-MY|
|locale|nb-NO|
|locale|nl-NL|
|locale|pt-PT|
|locale|sv-SE|
|locale|th-TH|
|locale|vi-VN|
|locale|zh-CN|
|locale|zh-HK|
|locale|zh-TW|
|challenge_indicator|no_preference|
|challenge_indicator|no_challenge_requested|
|challenge_indicator|challenge_requested|
|challenge_indicator|challenge_requested_mandate|
|exemption|low_value|
|exemption|secure_corporate_payment|
|exemption|trusted_listing|
|exemption|transaction_risk_assessment|
|exemption|3ds_outage|
|exemption|sca_delegation|
|exemption|out_of_sca_scope|
|exemption|other|
|exemption|low_risk_program|
|exemption|recurring_operation|
|store_payment_details|disabled|
|store_payment_details|enabled|
|store_payment_details|collect_consent|
HostedPaymentsResponse
```json
{
"id": "hpp_xGQBg0AXl3cM",
"reference": "ORD-123A",
"_links": {
"self": {
"href": "https://{prefix}.api.sandbox.checkout.com/hosted-payments/hpp_xGQBg0AXl3cM"
},
"redirect": {
"href": "https://pay.sandbox.checkout.com/page/hpp_xGQBg0AXl3cM"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[HostedPaymentId](#schemahostedpaymentid)|true|none|The unique identifier for a Hosted Payments Page.|
|reference|string|false|none|A reference you can later use to identify this payment, such as an order number.|
|warnings|[object]|false|none|Related to the `allow_payment_methods` object in the request. Included in the response if an alternative payment method is passed through, but no card schemes are configured against the account.|
|» code|string|false|none|The reason for the warning|
|» description|string|false|none|The description of the warning code|
|» value|string|false|none|Payment method for which the warning applies|
|_links|object|true|read-only|The links related to the hosted payment.|
|» self|[Link](#schemalink)|false|none|none|
|» redirect|[Link](#schemalink)|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|value|card|
|value|sofort|
|value|ideal|
|value|knet|
|value|bancontact|
|value|eps|
|value|p24|
|value|multibanco|
PaymentInterfacesCustomerSummary
```json
{
"registration_date": "2023-05-01",
"first_transaction_date": "2023-07-01",
"last_payment_date": "2023-08-01",
"total_order_count": 15,
"last_payment_amount": 500,
"is_premium_customer": true,
"is_returning_customer": true,
"lifetime_value": 500
}
```
Summary of the customer's transaction history.
Used for risk assessment when `source.type` is `Tamara`
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|registration_date|string(date)|false|none|The date the customer registered.|
|first_transaction_date|string(date)|false|none|The date of the customer's first transaction.|
|last_payment_date|string(date)|false|none|The date of the customer's last payment.|
|total_order_count|integer|false|none|The total number of orders made by the customer.|
|last_payment_amount|number(float)|false|none|The amount of the customer's last payment.|
|is_premium_customer|boolean|false|none|Specifies whether the customer is a premium customer.|
|is_returning_customer|boolean|false|none|Specifies whether the customer is a returning customer.|
|lifetime_value|number(float)|false|none|The customer's lifetime value. This is the total monetary amount that the customer has ordered, in their local currency, excluding the following:
- canceled orders
- rejected payments
- refunded payments
- Tamara payments
The lifetime value is an indicator of how valuable the relationship with the customer is to your company.|
PaymentInterfacesPanPreference
```json
"fpan"
```
Specifies the preferred type of Primary Account Number (PAN) for the payment:
* DPAN: Uses the Checkout.com Network Token.
* FPAN: Uses the full card number.
**Note**: This only works when `source.type` is any of:
- `cards`
- `instruments`
- `tokens`
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|Specifies the preferred type of Primary Account Number (PAN) for the payment:
* DPAN: Uses the Checkout.com Network Token.
* FPAN: Uses the full card number.
**Note**: This only works when `source.type` is any of:
- `cards`
- `instruments`
- `tokens`|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|fpan|
|*anonymous*|dpan|
PaymentInterfacesPaymentMethod
```json
"alipay_cn"
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentInterfacesPaymentMethodEnum](#schemapaymentinterfacespaymentmethodenum)|false|none|none|
PaymentInterfacesPaymentMethodEnum
```json
"alipay_cn"
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|alipay_cn|
|*anonymous*|alipay_hk|
|*anonymous*|alma|
|*anonymous*|applepay|
|*anonymous*|bancontact|
|*anonymous*|benefit|
|*anonymous*|bizum|
|*anonymous*|card|
|*anonymous*|dana|
|*anonymous*|eps|
|*anonymous*|gcash|
|*anonymous*|googlepay|
|*anonymous*|ideal|
|*anonymous*|kakaopay|
|*anonymous*|klarna|
|*anonymous*|knet|
|*anonymous*|mbway|
|*anonymous*|mobilepay|
|*anonymous*|multibanco|
|*anonymous*|octopus|
|*anonymous*|p24|
|*anonymous*|paynow|
|*anonymous*|paypal|
|*anonymous*|plaid|
|*anonymous*|qpay|
|*anonymous*|sepa|
|*anonymous*|stcpay|
|*anonymous*|stored_card|
|*anonymous*|tabby|
|*anonymous*|tamara|
|*anonymous*|tng|
|*anonymous*|truemoney|
|*anonymous*|twint|
|*anonymous*|vipps|
|*anonymous*|wechatpay|
PaymentInterfacesPaymentMethods
```json
[
"alipay_cn"
]
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[[PaymentInterfacesPaymentMethodEnum](#schemapaymentinterfacespaymentmethodenum)]|false|none|none|
PaymentInterfacesPhoneNumber
```json
{
"country_code": "+1",
"number": "415 555 2671"
}
```
A phone number
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|country_code|string|false|none|The international country calling code.|
|number|string|false|none|The phone number.|
PaymentInterfacesProcessing
```json
{
"aft": true,
"discount_amount": 0,
"shipping_amount": 300,
"tax_amount": 3000,
"invoice_id": "string",
"brand_name": "string",
"locale": "en-US",
"partner_customer_risk_data": {
"key": "string",
"value": "string"
},
"custom_payment_method_ids": [
"string"
],
"airline_data": [
{
"ticket": {
"number": "045-21351455613",
"issue_date": "2023-05-20",
"issuing_carrier_code": "AI",
"travel_package_indicator": "B",
"travel_agency_name": "World Tours",
"travel_agency_code": "01"
},
"passenger": [
{
"first_name": "John",
"last_name": "White",
"date_of_birth": "1990-05-26",
"address": {
"country": "US"
}
}
],
"flight_leg_details": [
{
"flight_number": "101",
"carrier_code": "BA",
"class_of_travelling": "J",
"departure_airport": "LHR",
"departure_date": "2023-06-19",
"departure_time": "15:30",
"arrival_airport": "LAX",
"stop_over_code": "x",
"fare_basis_code": "SPRSVR"
}
]
}
],
"accommodation_data": [
{
"name": "The Sea View Hotel",
"booking_reference": "HOTEL123",
"check_in_date": "2023-06-20",
"check_out_date": "2023-06-23",
"address": {
"address_line1": "123 Beach Road",
"zip": "10001"
},
"state": "FL",
"country": "USA",
"city": "Los Angeles",
"number_of_rooms": 2,
"guests": [
{
"first_name": "Jane",
"last_name": "Doe",
"date_of_birth": "1985-07-14"
}
],
"room": [
{
"rate": "70",
"number_of_nights_at_room_rate": "3"
}
]
}
],
"order_id": "123456789",
"surcharge_amount": 200,
"duty_amount": 0,
"shipping_tax_amount": 100,
"affiliate_id": "string",
"affiliate_url": "www.mycrypto.com",
"purchase_country": "string",
"merchant_initiated_reason": "Delayed_charge",
"campaign_id": 0,
"original_order_amount": 10,
"receipt_id": "10",
"merchant_callback_url": "string",
"line_of_business": "Flights",
"pan_preference": "fpan",
"provision_network_token": true,
"reconciliation_id": "4123495123",
"aggregator": {
"sub_merchant_id": "9cf70789ba90123",
"aggregator_id_visa": "10012345",
"aggregator_id_mc": "00000123456"
}
}
```
Use the processing object to influence or override the data sent during card processing
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|aft|boolean|false|none|Indicates whether the payment is an [Account Funding Transaction](https://www.checkout.com/docs/payments/manage-payments/account-funding-transactions)|
|discount_amount|number|false|none|The discount amount applied to the transaction by the merchant.|
|shipping_amount|number|false|none|The total freight or shipping and handling charges for the transaction.|
|tax_amount|number|false|none|The customer's value-added tax registration number.|
|invoice_id|string|false|none|Invoice ID number.|
|brand_name|string|false|none|The label that overrides the business name in the PayPal account on the PayPal pages.|
|locale|string|false|none|The language and region of the customer in ISO 639-2 language code; value consists of language-country.|
|partner_customer_risk_data|object|false|none|An array of key-and-value pairs with merchant-specific data for the transaction.|
|» key|string|false|none|The key for the pair.|
|» value|string|false|none|The value for the pair.|
|custom_payment_method_ids|[string]|false|none|Promo codes - An array that can be used to define which of the configured payment options within a payment category (pay_later, pay_over_time, etc.) should be shown for this purchase.|
|airline_data|[PaymentInterfacesProcessingAirlineData](#schemapaymentinterfacesprocessingairlinedata)|false|none|Contains information about the airline ticket and flights booked by the customer.|
|accommodation_data|[PaymentInterfacesProcessingAccommodationData](#schemapaymentinterfacesprocessingaccommodationdata)|false|none|Contains information about the accommodation booked by the customer.|
|order_id|string|false|none|The number provided by the cardholder. Purchase order or invoice number may be used.|
|surcharge_amount|integer(int64)|false|none|Surcharge amount applied to the transaction in minor units by the merchant.|
|duty_amount|number|false|none|The total charges for any import/export duty included in the transaction.|
|shipping_tax_amount|number|false|none|The tax amount of the freight or shipping and handling charges for the transaction.|
|affiliate_id|string|false|none|The unique identifier for Visa-registered ramp providers.
Must only contain alphanumeric characters.
If you're a Visa-registered ramp provider operating with affiliates, this field is required.|
|affiliate_url|string|false|none|The affiliate URL.
If you're a Visa-registered ramp provider operating with affiliates, this field is required.|
|purchase_country|string|false|none|The purchase country of the customer. ISO 3166 alpha-2 purchase country.|
|merchant_initiated_reason|string|false|none|Indicates the reason for a merchant-initiated payment request.|
|campaign_id|integer|false|none|Unique number of the campaign this payment will be running in. Only required for Afterpay campaign invoices.|
|original_order_amount|number|false|none|The payment for a merchant's order may be split, and the original order price indicates the transaction amount of the entire order.|
|receipt_id|string|false|none|Merchant receipt ID.|
|merchant_callback_url|string|false|none|A URL which you can use to notify the customer that the order has been created.|
|line_of_business|string|false|none|Beta
The line of business that the payment is associated with.|
|pan_preference|[PaymentInterfacesPanPreference](#schemapaymentinterfacespanpreference)|false|none|Specifies the preferred type of Primary Account Number (PAN) for the payment:
* DPAN: Uses the Checkout.com Network Token.
* FPAN: Uses the full card number.
**Note**: This only works when `source.type` is any of:
- `cards`
- `instruments`
- `tokens`|
|provision_network_token|[PaymentInterfacesProvisionNetworkToken](#schemapaymentinterfacesprovisionnetworktoken)|false|none|Indicates whether to provision a network token for the payment.|
|reconciliation_id|string|false|none|Transaction identifier used to track a payment request|
|aggregator|[PaymentInterfacesProcessingAggregator](#schemapaymentinterfacesprocessingaggregator)|false|none|Contains information about the payment aggregator.|
#### Enumerated Values
|Property|Value|
|---|---|
|merchant_initiated_reason|Delayed_charge|
|merchant_initiated_reason|Resubmission|
|merchant_initiated_reason|No_show|
|merchant_initiated_reason|Reauthorization|
PaymentInterfacesProcessingAccommodationData
```json
[
{
"name": "The Sea View Hotel",
"booking_reference": "HOTEL123",
"check_in_date": "2023-06-20",
"check_out_date": "2023-06-23",
"address": {
"address_line1": "123 Beach Road",
"zip": "10001"
},
"state": "FL",
"country": "USA",
"city": "Los Angeles",
"number_of_rooms": 2,
"guests": [
{
"first_name": "Jane",
"last_name": "Doe",
"date_of_birth": "1985-07-14"
}
],
"room": [
{
"rate": "70",
"number_of_nights_at_room_rate": "3"
}
]
}
]
```
Contains information about the accommodation booked by the customer.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|Accommodation Data|object|false|none|none|
|» name|string|false|none|For lodging, contains the lodging name that appears on the storefront/customer receipts. For cruise, contains the ship name booked for the cruise.|
|» booking_reference|string|false|none|A unique identifier for the booking.|
|» check_in_date|string(date)|false|none|For lodging, contains the actual or scheduled date the guest checked-in. For cruise, contains the cruise departure date also known as sail date.|
|» check_out_date|string(date)|false|none|For lodging, contains the actual or scheduled date the guest checked-out. For cruise, contains the cruise return date also known as sail end date.|
|» address|object|false|none|The address details of the accommodation.|
|»» address_line1|string|false|none|The first line of the address.|
|»» zip|string|false|none|The postal code for the address.|
|» state|string|false|none|The state or province of the address country (ISO 3166-2 code of up to two alphanumeric characters).|
|» country|string|false|none|The ISO country code of the address.|
|» city|string|false|none|The address city.|
|» number_of_rooms|integer|false|none|The total number of rooms booked for the accommodation.|
|» guests|[object]|false|none|Contains information about the guests staying at the accommodation.|
|»» first_name|string|false|none|The first name of the guest.|
|»» last_name|string|false|none|The last name of the guest.|
|»» date_of_birth|string(date)|false|none|The date of birth of the guest.|
|» room|[object]|false|none|Contains information about the rooms booked by the customer.|
|»» rate|string|false|none|For lodging, contains the nightly rate for one room. For cruise, contains the total cost of the cruise.|
|»» number_of_nights_at_room_rate|string|false|none|For lodging, contains the number of nights charged at the rate provided in the rate field. For cruise, contains the length of the cruise in days.|
PaymentInterfacesProcessingAggregator
```json
{
"sub_merchant_id": "9cf70789ba90123",
"aggregator_id_visa": "10012345",
"aggregator_id_mc": "00000123456"
}
```
Aggregator
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|sub_merchant_id|string|false|none|ID that you assigned to the sub-entity.|
|aggregator_id_visa|string|false|none|Visa identifier of the payment aggregator.|
|aggregator_id_mc|string|false|none|Mastercard identifier of the payment aggregator.|
PaymentInterfacesProcessingAirlineData
```json
[
{
"ticket": {
"number": "045-21351455613",
"issue_date": "2023-05-20",
"issuing_carrier_code": "AI",
"travel_package_indicator": "B",
"travel_agency_name": "World Tours",
"travel_agency_code": "01"
},
"passenger": [
{
"first_name": "John",
"last_name": "White",
"date_of_birth": "1990-05-26",
"address": {
"country": "US"
}
}
],
"flight_leg_details": [
{
"flight_number": "101",
"carrier_code": "BA",
"class_of_travelling": "J",
"departure_airport": "LHR",
"departure_date": "2023-06-19",
"departure_time": "15:30",
"arrival_airport": "LAX",
"stop_over_code": "x",
"fare_basis_code": "SPRSVR"
}
]
}
]
```
Contains information about the airline ticket and flights booked by the customer.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|Airline Data|object|false|none|none|
|» ticket|object|false|none|Contains information about the airline ticket.|
|»» number|string|false|none|The ticket's unique identifier.|
|»» issue_date|string(date)|false|none|Date the airline ticket was issued.|
|»» issuing_carrier_code|string|false|none|Carrier code of the ticket issuer.|
|»» travel_package_indicator|string|false|none|C = Car rental reservation, A = Airline flight reservation, B = Both car rental and airline flight reservations included, N = Unknown.|
|»» travel_agency_name|string|false|none|The name of the travel agency.|
|»» travel_agency_code|string|false|none|The unique identifier from IATA or ARC for the travel agency that issues the ticket.|
|» passenger|any|false|none|Contains information about the passenger(s) on the flight. PayPal requires a single object.|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»» *anonymous*|[[PaymentInterfacesProcessingAirlinePassengerData](#schemapaymentinterfacesprocessingairlinepassengerdata)]|false|none|Array of passengers on the flight.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»» *anonymous*|[PaymentInterfacesProcessingAirlinePassengerData](#schemapaymentinterfacesprocessingairlinepassengerdata)|false|none|Contains information about a passenger on the flight.|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» flight_leg_details|[object]|false|none|Contains information about the flight leg(s) booked by the customer.|
|»» flight_number|string|false|none|The flight identifier.|
|»» carrier_code|string|false|none|The IATA 2-letter accounting code (PAX) that identifies the carrier. This field is required if the airline data includes leg details.|
|»» class_of_travelling|string|false|none|A one-letter travel class identifier. The following are common: F = First class, J = Business class, Y = Economy class, W = Premium economy.|
|»» departure_airport|string|false|none|The IATA three-letter airport code of the departure airport. This field is required if the airline data includes leg details.|
|»» departure_date|string(date)|false|none|The date of the scheduled take off.|
|»» departure_time|string|false|none|The time of the scheduled take off.|
|»» arrival_airport|string|false|none|The IATA 3-letter airport code of the destination airport. This field is required if the airline data includes leg details.|
|»» stop_over_code|string|false|none|A one-letter code that indicates whether the passenger is entitled to make a stopover. Can be a space, O if the passenger is entitled to make a stopover, or X if they are not.|
|»» fare_basis_code|string|false|none|The fare basis code, alphanumeric.|
PaymentInterfacesProcessingAirlinePassengerData
```json
{
"first_name": "John",
"last_name": "White",
"date_of_birth": "1990-05-26",
"address": {
"country": "US"
}
}
```
Single-Object Passenger Data
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|first_name|string|false|none|The passenger's first name.|
|last_name|string|false|none|The passenger's last name.|
|date_of_birth|string(date)|false|none|The passenger's date of birth.|
|address|object|false|none|Contains information about the passenger's address.|
|» country|string|false|none|The two-letter ISO country code of the passenger's country residence.|
PaymentInterfacesProcessingBase
```json
{
"pan_preference": "fpan",
"provision_network_token": true
}
```
Use the processing object to influence or override the data sent during card processing
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|pan_preference|[PaymentInterfacesPanPreference](#schemapaymentinterfacespanpreference)|false|none|Specifies the preferred type of Primary Account Number (PAN) for the payment:
* DPAN: Uses the Checkout.com Network Token.
* FPAN: Uses the full card number.
**Note**: This only works when `source.type` is any of:
- `cards`
- `instruments`
- `tokens`|
|provision_network_token|[PaymentInterfacesProvisionNetworkToken](#schemapaymentinterfacesprovisionnetworktoken)|false|none|Indicates whether to provision a network token for the payment.|
PaymentInterfacesProducts
```json
[
{
"reference": "string",
"url": "https://example.com/products/gold-necklace",
"name": "Gold Necklace",
"quantity": 1,
"price": 1000
}
]
```
Contains details about the products in the order.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|false|none|The item reference or product stock keeping unit (SKU).|
|url|string|false|none|Link to the line item's product page.|
|name|string|true|none|The descriptive name of the line item.|
|quantity|integer|true|none|The number of line items.|
|price|integer|true|none|The price per item in minor units, including tax but excluding discounts. The exact format depends on the currency. See Calculating the amount.|
PaymentInterfacesProvisionNetworkToken
```json
true
```
Indicates whether to provision a network token for the payment.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|boolean|false|none|Indicates whether to provision a network token for the payment.|
PaymentInterfacesRecipient
```json
{
"dob": "1985-05-15",
"account_number": "5555554444",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"first_name": "Jia",
"last_name": "Tsang"
}
```
Information about the recipient of the payment's funds. Applies to Account Funding Transactions, and VISA or Mastercard domestic UK transactions processed by financial institutions.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|dob|string(date)|false|none|The recipient's date of birth, in the format `YYYY-MM-DD`.|
|account_number|string|false|none|An identifier related to the primary recipient's account. For example, an IBAN, an internal account number, a phone number, or the first six and last four digits of the PAN.|
|address|[Address](#schemaaddress)|false|none|The recipient's address.|
|first_name|string|false|none|The recipient's first name.|
|last_name|string|false|none|The recipient's last name.|
PaymentInterfacesReference
```json
"ORD-123A"
```
A reference you can use to identify the payment. For example, an order number.
- For Amex payments, this must be at most 30 characters.
- For Benefit payments, the reference must be a unique alphanumeric value.
- For iDEAL payments, the reference is required and must be an alphanumeric value with a 35-character limit.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|A reference you can use to identify the payment. For example, an order number.
- For Amex payments, this must be at most 30 characters.
- For Benefit payments, the reference must be a unique alphanumeric value.
- For iDEAL payments, the reference is required and must be an alphanumeric value with a 35-character limit.|
PaymentInterfacesSender
```json
{}
```
The sender type. If set to `instrument`, the sender information (name and address) will be retrieved from the payment instrument.
### Properties
*None*
01_PaymentInterfacesIndividualSender
```json
{
"type": "individual",
"reference": "8285282045818",
"first_name": "John",
"last_name": "Jones",
"dob": "1985-05-15",
"date_of_birth": "1985-05-15",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"identification": {
"type": "driving_licence",
"number": "1234",
"issuing_country": "GT"
}
}
```
individual
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of sender|
|reference|string|false|none|The sender's reference for the payout|
|first_name|string|true|none|The sender's first name|
|last_name|string|true|none|The sender's last name|
|dob|string(date)|false|none|This field is deprecated. Use `date_of_birth` instead.
The sender's date of birth, in the format `yyyy-mm-dd`.|
|date_of_birth|string(date)|false|none|The sender's date of birth, in the format `yyyy-mm-dd`.|
|address|[Address](#schemaaddress)|false|none|The sender's address|
|identification|object|false|none|none|
|» type|string|false|none|The type of identification used to identify the sender|
|» number|string|false|none|The identification number|
|» issuing_country|string|false|none|The two-letter ISO country code of the country that issued the identification|
#### Enumerated Values
|Property|Value|
|---|---|
|type|individual|
|type|passport|
|type|driving_licence|
|type|national_id|
02_PaymentInterfacesCorporateSender
```json
{
"type": "corporate",
"reference": "8285282045818",
"company_name": "string",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
}
```
corporate
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of sender|
|reference|string|false|none|The sender's reference for the payout|
|company_name|string|true|none|The corporate sender's company name.|
|address|[Address](#schemaaddress)|false|none|The sender's registered corporate address.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|corporate|
03_PaymentInterfacesInstrumentSender
```json
{
"type": "instrument",
"reference": "8285282045818"
}
```
instrument
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of sender|
|reference|string|false|none|The sender's reference for the payout|
#### Enumerated Values
|Property|Value|
|---|---|
|type|instrument|
IddvAttemptAsset
```json
{
"type": "document_front_image",
"_links": {
"asset_url": {
"href": "http://example.com"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of asset.|
|_links|object|true|none|none|
|» asset_url|[IdvHalLink](#schemaidvhallink)|true|none|The URL to the applicant profile resource.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|document_front_image|
|type|document_back_image|
IddvAttemptAssets
```json
{
"total_count": 0,
"skip": 0,
"limit": 0,
"data": [
{
"type": "document_front_image",
"_links": {
"asset_url": {
"href": "http://example.com"
}
}
}
],
"_links": {
"self": {
"href": "http://example.com"
},
"next": {
"href": "http://example.com"
},
"previous": {
"href": "http://example.com"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|total_count|integer|true|none|The total number of assets.|
|skip|integer|true|none|The number of assets you want to skip.
Example – There are 10 assets. If you provide `6`, the first six assets are skipped.|
|limit|integer|true|none|The maximum number of assets you want returned.
Example – There are 10 assets. If you set `limit` to `5`, but skip the first six, four assets are returned.|
|data|[[IddvAttemptAsset](#schemaiddvattemptasset)]|true|none|The list of assets for the current page.|
|_links|any|true|read-only|The details of links to the previous, current, and next resources.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[IdvSelfLink](#schemaidvselflink)|false|none|The details of links related to the resource.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[IdvNextLink](#schemaidvnextlink)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[IdvPreviousLink](#schemaidvpreviouslink)|false|none|none|
IddvAttemptId
```json
"datp_tkoi5db4hryu5cei5vwoabraio"
```
The unique identifier for the ID document verification attempt.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|read-only|The unique identifier for the ID document verification attempt.|
IddvAttemptRequest
```json
{
"document_front": "string",
"document_back": "string"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|document_front|string(binary)|true|none|The image of the front of the document to upload.|
|document_back|string(binary)|false|none|The image of the back of the document to upload.|
IddvAttemptResponse
```json
{
"id": "datp_tkoi5db4hryu5cei5vwoabraio",
"status": "checks_in_progress",
"response_codes": [
{
"code": 10000,
"summary": "document_front_not_captured"
}
],
"_links": {
"self": {
"href": "http://example.com"
}
},
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IddvAttemptId](#schemaiddvattemptid)|true|none|The unique identifier for the ID document verification attempt.|
|status|[IddvAttemptStates](#schemaiddvattemptstates)|true|none|The [status](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Attempt_statuses) of the ID document verification attempt.|
|response_codes|[[IdvResponseCode](#schemaidvresponsecode)]|true|read-only|One or more [response codes](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Response_codes) that provide more information about the status.|
|_links|[IdvSelfLink](#schemaidvselflink)|true|none|The details of links related to the resource.|
IddvAttemptResponseList
```json
{
"total_count": 0,
"skip": 0,
"limit": 0,
"data": [
{
"id": "datp_tkoi5db4hryu5cei5vwoabraio",
"status": "checks_in_progress",
"response_codes": [
{
"code": 10000,
"summary": "document_front_not_captured"
}
],
"_links": {
"self": {
"href": "http://example.com"
}
},
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z"
}
],
"_links": {
"self": {
"href": "http://example.com"
},
"next": {
"href": "http://example.com"
},
"previous": {
"href": "http://example.com"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|total_count|integer|true|none|The total number of attempts.|
|skip|integer|true|none|The number of attempts you want to skip, to help you view the relevant attempt.
Example – There are 10 attempts. If you provide `6`, the first six attempts are skipped.|
|limit|integer|true|none|The maximum number of attempts you want returned.
Example – There are 10 attempts. If you set `limit` to `5`, but skip the first six, four attempts are returned.|
|data|[[IddvAttemptResponse](#schemaiddvattemptresponse)]|true|none|The details of the attempt.|
|_links|any|true|read-only|The details of links to the previous, current, and next resources.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[IdvSelfLink](#schemaidvselflink)|false|none|The details of links related to the resource.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[IdvNextLink](#schemaidvnextlink)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[IdvPreviousLink](#schemaidvpreviouslink)|false|none|none|
IddvAttemptStates
```json
"checks_in_progress"
```
The [status](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Attempt_statuses) of the ID document verification attempt.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The [status](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Attempt_statuses) of the ID document verification attempt.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|checks_in_progress|
|*anonymous*|checks_inconclusive|
|*anonymous*|completed|
|*anonymous*|quality_checks_aborted|
|*anonymous*|quality_checks_in_progress|
|*anonymous*|terminated|
IddvIdDocumentVerification
```json
{
"id": "iddv_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"declared_data": {
"name": "Hannah Bret",
"birth_date": "1994-10-15"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IddvIdDocumentVerificationId](#schemaiddviddocumentverificationid)|true|read-only|The ID document verification's unique identifier.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[DatedObject](#schemadatedobject)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[IddvIdDocumentVerificationBase](#schemaiddviddocumentverificationbase)|false|none|none|
IddvIdDocumentVerificationBase
```json
{
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"declared_data": {
"name": "Hannah Bret",
"birth_date": "1994-10-15"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|applicant_id|[ApplicantId](#schemaapplicantid)|true|none|The applicant's unique identifier.|
|user_journey_id|[IdvUserJourneyId](#schemaidvuserjourneyid)|true|none|Your configuration ID.|
|declared_data|[IdvDeclaredData](#schemaidvdeclareddata)|false|none|The personal details provided by the applicant.|
IddvIdDocumentVerificationCreateBase
```json
{
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"status": "created",
"declared_data": {
"name": "Hannah Bret",
"birth_date": "1994-10-15"
},
"document": {
"full_name": "string",
"first_names": "string",
"last_name": "string",
"last_name_at_birth": "string",
"birth_date": "2019-08-24",
"birth_place": "string",
"nationality": "US",
"gender": "M",
"personal_number": "string",
"tax_identification_number": "string",
"document_type": "Driving licence",
"document_issuing_country": "US",
"document_number": "string",
"document_expiry_date": "2019-08-24",
"document_issue_date": "2019-08-24",
"document_issue_place": "string",
"document_mrz": "string",
"address": "123 Main Street, London, SW1A 1AA",
"permit_obtaining_date": "2019-08-24",
"permit_expiry_date": "2019-08-24",
"permit_type_detailed": "string",
"permit_type_remarks": "string",
"front_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4",
"back_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4",
"signature_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
},
"response_codes": [
{
"code": 10000,
"summary": "document_front_not_captured"
}
],
"_links": {
"self": {
"href": "http://example.com"
},
"applicant": {
"href": "http://example.com"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|applicant_id|[ApplicantId](#schemaapplicantid)|true|none|The applicant's unique identifier.|
|user_journey_id|[IdvUserJourneyId](#schemaidvuserjourneyid)|false|none|Your configuration ID.|
|status|[IddvVerificationStatuses](#schemaiddvverificationstatuses)|true|none|The ID document [verification status](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Check_statuses).|
|declared_data|[IdvDeclaredData](#schemaidvdeclareddata)|false|none|The personal details provided by the applicant.|
|document|[IdvDocument](#schemaidvdocument)|false|none|The applicant's identity document details.|
|response_codes|[IdvResponseCodes](#schemaidvresponsecodes)|true|none|One or more [response codes](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Response_codes) that provide more information about the status.|
|_links|[IdvIdentityVerificationLinks](#schemaidvidentityverificationlinks)|true|none|The details of links related to the resource.|
IddvIdDocumentVerificationId
```json
"iddv_tkoi5db4hryu5cei5vwoabr7we"
```
The ID document verification's unique identifier.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|read-only|The ID document verification's unique identifier.|
IddvIdDocumentVerificationOutput
```json
{
"id": "iddv_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"status": "created",
"declared_data": {
"name": "Hannah Bret",
"birth_date": "1994-10-15"
},
"document": {
"full_name": "string",
"first_names": "string",
"last_name": "string",
"last_name_at_birth": "string",
"birth_date": "2019-08-24",
"birth_place": "string",
"nationality": "US",
"gender": "M",
"personal_number": "string",
"tax_identification_number": "string",
"document_type": "Driving licence",
"document_issuing_country": "US",
"document_number": "string",
"document_expiry_date": "2019-08-24",
"document_issue_date": "2019-08-24",
"document_issue_place": "string",
"document_mrz": "string",
"address": "123 Main Street, London, SW1A 1AA",
"permit_obtaining_date": "2019-08-24",
"permit_expiry_date": "2019-08-24",
"permit_type_detailed": "string",
"permit_type_remarks": "string",
"front_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4",
"back_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4",
"signature_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
},
"response_codes": [
{
"code": 10000,
"summary": "document_front_not_captured"
}
],
"_links": {
"self": {
"href": "http://example.com"
},
"applicant": {
"href": "http://example.com"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IddvIdDocumentVerificationId](#schemaiddviddocumentverificationid)|true|none|The ID document verification's unique identifier.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[DatedObject](#schemadatedobject)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[IddvIdDocumentVerificationCreateBase](#schemaiddviddocumentverificationcreatebase)|false|none|none|
IddvVerificationStatuses
```json
"created"
```
The ID document [verification status](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Check_statuses).
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The ID document [verification status](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Check_statuses).|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|created|
|*anonymous*|quality_checks_in_progress|
|*anonymous*|checks_in_progress|
|*anonymous*|approved|
|*anonymous*|declined|
|*anonymous*|retry_required|
|*anonymous*|inconclusive|
IdvActiveLink
```json
{
"verification_url": {
"href": "http://example.com"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|verification_url|[IdvHalLink](#schemaidvhallink)|true|none|The attempt URL.|
IdvAddress
```json
{
"address_line1": "123 Main Street",
"address_line2": "Apt 4B",
"city": "London",
"state": "Greater London",
"zip": "SW1A 1AA",
"country": "GB"
}
```
The applicant's address.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|address_line1|string|false|none|The first line of the address.|
|address_line2|string|false|none|The second line of the address.|
|city|string|false|none|The city or town.|
|state|string|false|none|The state, county, or province.|
|zip|string|false|none|The postal or ZIP code.|
|country|string|false|none|The two-letter ISO country code of the address.|
IdvApplicant
```json
{
"id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"external_applicant_id": "ext_osdfdfdb4hryu5cei5vwoabrk5k",
"email": "hannah.bret@example.com",
"external_applicant_name": "Hannah Bret",
"_links": {
"self": {
"href": "http://example.com"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[ApplicantId](#schemaapplicantid)|true|read-only|The applicant's unique identifier.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[DatedObject](#schemadatedobject)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[IdvBaseApplicant](#schemaidvbaseapplicant)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[IdvApplicantLinks](#schemaidvapplicantlinks)|false|none|none|
IdvApplicantLink
```json
{
"applicant": {
"href": "http://example.com"
}
}
```
The URL to the applicant's profile.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|applicant|[IdvHalLink](#schemaidvhallink)|true|none|The URL to the applicant profile resource.|
IdvApplicantLinks
```json
{
"_links": {
"self": {
"href": "http://example.com"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|_links|[IdvSelfLink](#schemaidvselflink)|true|read-only|The details of links related to the resource.|
```json
{
"ip_address": "123:456:789:00",
"number_of_sessions": 3,
"user_agent": "Mozilla/5.0 (Linux; Android 8.0.0; SM-G960F Build/R16NW) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.84 Mobile Safari/537.36",
"initial_device": "desktop",
"selected_documents": [
{
"country": "US",
"document_type": "Driving licence"
}
]
}
```
ApplicantSessionInformation
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|ip_address|string|false|none|The applicant's IP address during the attempt.|
|number_of_sessions|integer|false|read-only|The number of sessions the applicant opened during the attempt.|
|user_agent|string|false|read-only|The user agent of the browser the applicant used during the attempt.|
|initial_device|[IdvInitialDevices](#schemaidvinitialdevices)|false|none|The type of device the applicant used to start the attempt.|
|selected_documents|[[IdvSelectedDocument](#schemaidvselecteddocument)]|false|read-only|The documents the applicant selected in order.|
IdvAttemptAsset
```json
{
"type": "face_image",
"_links": {
"asset_url": {
"href": "http://example.com"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of asset.|
|_links|object|true|none|none|
|» asset_url|[IdvHalLink](#schemaidvhallink)|true|none|The URL to the applicant profile resource.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|face_image|
|type|face_video|
|type|document_front_image|
|type|document_back_image|
|type|document_front_video|
|type|document_back_video|
|type|document_signature_image|
|type|secondary_document_front_image|
|type|secondary_document_back_image|
|type|secondary_document_front_video|
|type|secondary_document_back_video|
|type|secondary_document_signature_image|
IdvAttemptAssets
```json
{
"total_count": 0,
"skip": 0,
"limit": 0,
"data": [
{
"type": "face_image",
"_links": {
"asset_url": {
"href": "http://example.com"
}
}
}
],
"_links": {
"self": {
"href": "http://example.com"
},
"next": {
"href": "http://example.com"
},
"previous": {
"href": "http://example.com"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|total_count|integer|true|none|The total number of assets.|
|skip|integer|true|none|The number of assets you want to skip.
Example – There are 10 assets. If you provide `6`, the first six assets are skipped.|
|limit|integer|true|none|The maximum number of assets you want returned.
Example – There are 10 assets. If you set `limit` to `5`, but skip the first six, four assets are returned.|
|data|[[IdvAttemptAsset](#schemaidvattemptasset)]|true|none|The list of assets for the current page.|
|_links|any|true|read-only|The details of links to the previous, current, and next resources.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[IdvSelfLink](#schemaidvselflink)|false|none|The details of links related to the resource.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[IdvNextLink](#schemaidvnextlink)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[IdvPreviousLink](#schemaidvpreviouslink)|false|none|none|
IdvAttemptId
```json
"iatp_tkoi5db4hryu5cei5vwoabraio"
```
The unique identifier for the attempt.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|read-only|The unique identifier for the attempt.|
IdvAttemptLinks
```json
{
"self": {
"href": "http://example.com"
},
"verification_url": {
"href": "http://example.com"
}
}
```
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[IdvSelfLink](#schemaidvselflink)|false|none|The details of links related to the resource.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[IdvActiveLink](#schemaidvactivelink)|false|none|none|
IdvAttemptRequest
```json
{
"redirect_url": "http://example.com",
"phone_number": {
"country_code": "+33",
"number": "5555550102"
},
"client_information": {
"pre_selected_residence_country": "FR",
"pre_selected_document_issuing_country": "FR",
"pre_selected_document_type": "Driving licence",
"pre_selected_language": "en-US"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|redirect_url|string(uri)|true|none|The URL to redirect the applicant to after the attempt.|
|phone_number|[IdvPhoneNumber](#schemaidvphonenumber)|false|none|The applicant's mobile phone number, if sharing the attempt URL via SMS.|
|client_information|[IdvClientInformation](#schemaidvclientinformation)|false|none|The applicant's details.|
IdvAttemptResponse
```json
{
"id": "iatp_tkoi5db4hryu5cei5vwoabraio",
"redirect_url": "string",
"status": "capture_aborted",
"response_codes": [
{
"code": 10000,
"summary": "document_front_not_captured"
}
],
"phone_number": {
"country_code": "+33",
"number": "5555550102"
},
"client_information": {
"pre_selected_residence_country": "FR",
"pre_selected_document_issuing_country": "FR",
"pre_selected_document_type": "Driving licence",
"pre_selected_language": "en-US"
},
"applicant_session_information": {
"ip_address": "123:456:789:00",
"number_of_sessions": 3,
"user_agent": "Mozilla/5.0 (Linux; Android 8.0.0; SM-G960F Build/R16NW) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.84 Mobile Safari/537.36",
"initial_device": "desktop",
"selected_documents": [
{
"country": "US",
"document_type": "Driving licence"
}
]
},
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IdvAttemptId](#schemaidvattemptid)|true|none|The unique identifier for the attempt.|
|redirect_url|string|true|none|The URL to redirect the applicant to after the attempt.|
|status|[IdvAttemptStatuses](#schemaidvattemptstatuses)|true|none|The [attempt status](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Attempt_statuses).|
|response_codes|[[IdvResponseCode](#schemaidvresponsecode)]|true|read-only|One or more [response codes](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Response_codes) that provide more information about the status.|
|phone_number|[IdvPhoneNumber](#schemaidvphonenumber)|false|none|The applicant's mobile phone number, if sharing the attempt URL via SMS.|
|client_information|[IdvClientInformation](#schemaidvclientinformation)|false|none|The applicant's details.|
|applicant_session_information|[IdvApplicantSessionInformation](#schemaidvapplicantsessioninformation)|true|none|The details of the attempt.|
IdvAttemptResponseList
```json
{
"total_count": 0,
"skip": 0,
"limit": 0,
"data": [
{
"id": "iatp_tkoi5db4hryu5cei5vwoabraio",
"redirect_url": "string",
"status": "capture_aborted",
"response_codes": [
{
"code": 10000,
"summary": "document_front_not_captured"
}
],
"phone_number": {
"country_code": "+33",
"number": "5555550102"
},
"client_information": {
"pre_selected_residence_country": "FR",
"pre_selected_document_issuing_country": "FR",
"pre_selected_document_type": "Driving licence",
"pre_selected_language": "en-US"
},
"applicant_session_information": {
"ip_address": "123:456:789:00",
"number_of_sessions": 3,
"user_agent": "Mozilla/5.0 (Linux; Android 8.0.0; SM-G960F Build/R16NW) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.84 Mobile Safari/537.36",
"initial_device": "desktop",
"selected_documents": [
{
"country": "US",
"document_type": "Driving licence"
}
]
},
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z"
}
],
"_links": {
"self": {
"href": "http://example.com"
},
"next": {
"href": "http://example.com"
},
"previous": {
"href": "http://example.com"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|total_count|integer|true|none|The total number of attempts.|
|skip|integer|true|none|The number of attempts you want to skip, to help you view the relevant attempt.
Example – There are 10 attempts. If you provide `6`, the first six attempts are skipped.|
|limit|integer|true|none|The maximum number of attempts you want returned.
Example – There are 10 attempts. If you set `limit` to `5`, but skip the first six, four attempts are returned.|
|data|[[IdvAttemptResponse](#schemaidvattemptresponse)]|true|none|The details of the attempt.|
|_links|any|true|read-only|The details of links to the previous, current, and next resources.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[IdvSelfLink](#schemaidvselflink)|false|none|The details of links related to the resource.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[IdvNextLink](#schemaidvnextlink)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[IdvPreviousLink](#schemaidvpreviouslink)|false|none|none|
IdvAttemptStatuses
```json
"capture_aborted"
```
The [attempt status](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Attempt_statuses).
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|read-only|The [attempt status](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Attempt_statuses).|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|capture_aborted|
|*anonymous*|capture_in_progress|
|*anonymous*|checks_inconclusive|
|*anonymous*|checks_in_progress|
|*anonymous*|completed|
|*anonymous*|expired|
|*anonymous*|pending_redirection|
|*anonymous*|capture_refused|
|*anonymous*|terminated|
IdvBaseApplicant
```json
{
"external_applicant_id": "ext_osdfdfdb4hryu5cei5vwoabrk5k",
"email": "hannah.bret@example.com",
"external_applicant_name": "Hannah Bret"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|external_applicant_id|string|false|none|Your reference for the applicant.|
|email|string(email)|false|none|The applicant's email address.|
|external_applicant_name|string|false|none|The applicant's full name.|
IdvCertification
```json
{
"type": "diatf",
"data": {
"gpg45_profile": "M1A",
"level_of_confidence": "medium",
"right_to_work": "GRANTED"
}
}
```
The details of a certification associated with the identity verification.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|false|none|The certification type.|
|data|[IdvDiatfCertificationData](#schemaidvdiatfcertificationdata)|false|none|The certification data. The properties returned depend on the certification `type`.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|diatf|
IdvCertifications
```json
[
{
"type": "diatf",
"data": {
"gpg45_profile": "M1A",
"level_of_confidence": "medium",
"right_to_work": "GRANTED"
}
}
]
```
The certifications associated with the identity verification.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[[IdvCertification](#schemaidvcertification)]|false|read-only|The certifications associated with the identity verification.|
```json
{
"pre_selected_residence_country": "FR",
"pre_selected_document_issuing_country": "FR",
"pre_selected_document_type": "Driving licence",
"pre_selected_language": "en-US"
}
```
ClientInformation
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|pre_selected_residence_country|string|false|none|The applicant's residence country.
Standard – [ISO alpha-2 country code](/developer-resources/codes/country-codes)
Example – `FR`|
|pre_selected_document_issuing_country|string|false|none|The country that issued the applicant's identity document.
Standard – [ISO alpha-2 country code](/developer-resources/codes/country-codes)
Example – `FR`|
|pre_selected_document_type|[IdvDocumentTypes](#schemaidvdocumenttypes)|false|none|The type of identity document the applicant uses for the attempt.|
|pre_selected_language|string(IETF BCP 47 language tag)|false|none|The language you want to use for the user interface.
Format – IETF BCP 47 language tag|
IdvCountryCode
```json
"US"
```
The applicant's nationality.
Standard – [ISO alpha-2 country code](https://www.checkout.com/docs/developer-resources/testing/codes/country-codes)
Example – `FR`
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string(ISO 3166-1 alpha-2)|false|none|The applicant's nationality.
Standard – [ISO alpha-2 country code](https://www.checkout.com/docs/developer-resources/testing/codes/country-codes)
Example – `FR`|
IdvDeclaredData
```json
{
"name": "Hannah Bret",
"birth_date": "1994-10-15"
}
```
The personal details provided by the applicant.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|true|none|The applicant's name.|
|birth_date|string(date)|false|none|The applicant's birth date.
Format – `YYYY-MM-DD`|
IdvDiatfCertificationData
```json
{
"gpg45_profile": "M1A",
"level_of_confidence": "medium",
"right_to_work": "GRANTED"
}
```
The certification data returned for the `diatf` certification type.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|gpg45_profile|string|false|none|The GPG 45 identity profile the verification meets.|
|level_of_confidence|string|false|none|The level of confidence in the verified identity.|
|right_to_work|string|false|none|The outcome of the applicant's right to work check.|
#### Enumerated Values
|Property|Value|
|---|---|
|gpg45_profile|M1A|
|gpg45_profile|M1C|
|gpg45_profile|H1A|
|level_of_confidence|medium|
|level_of_confidence|high|
IdvDocument
```json
{
"full_name": "string",
"first_names": "string",
"last_name": "string",
"last_name_at_birth": "string",
"birth_date": "2019-08-24",
"birth_place": "string",
"nationality": "US",
"gender": "M",
"personal_number": "string",
"tax_identification_number": "string",
"document_type": "Driving licence",
"document_issuing_country": "US",
"document_number": "string",
"document_expiry_date": "2019-08-24",
"document_issue_date": "2019-08-24",
"document_issue_place": "string",
"document_mrz": "string",
"address": "123 Main Street, London, SW1A 1AA",
"permit_obtaining_date": "2019-08-24",
"permit_expiry_date": "2019-08-24",
"permit_type_detailed": "string",
"permit_type_remarks": "string",
"front_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4",
"back_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4",
"signature_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
}
```
The applicant's identity document details.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[IdvIdentity](#schemaidvidentity)|false|none|The details of the applicant's verified identity.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» personal_number|string|false|none|The applicant's personal number. This depends on the document type.|
|» tax_identification_number|string|false|none|The tax identification number (TIN) extracted from the document.|
|» document_type|[IdvDocumentTypes](#schemaidvdocumenttypes)|false|none|The type of identity document.|
|» document_issuing_country|[IdvCountryCode](#schemaidvcountrycode)|false|none|The applicant's nationality.
Standard – [ISO alpha-2 country code](https://www.checkout.com/docs/developer-resources/testing/codes/country-codes)
Example – `FR`|
|» document_number|string|false|none|The document number extracted from the document.|
|» document_expiry_date|string(date)|false|none|The document expiry date extracted from the document.|
|» document_issue_date|string(date)|false|none|The document issue date extracted from the document.|
|» document_issue_place|string|false|none|The document's place of issue extracted from the document.|
|» document_mrz|string|false|none|The machine-readable zone (MRZ) data extracted from the document.|
|» address|string|false|none|The address extracted from the document.|
|» permit_obtaining_date|string(date)|false|none|The date the residence permit was obtained, extracted from the document.|
|» permit_expiry_date|string(date)|false|none|The residence permit expiry date extracted from the document.|
|» permit_type_detailed|string|false|none|The detailed residence permit type extracted from the document.|
|» permit_type_remarks|string|false|none|The residence permit remarks extracted from the document.|
|» front_image_signed_url|[IdvPreSignedUrl](#schemaidvpresignedurl)|false|none|The pre-signed URL to the captured image of the document.|
|» back_image_signed_url|[IdvPreSignedUrl](#schemaidvpresignedurl)|false|none|The pre-signed URL to the captured image of the document.|
|» signature_image_signed_url|[IdvPreSignedUrl](#schemaidvpresignedurl)|false|none|The pre-signed URL to the captured image of the document.|
IdvDocumentList
```json
[
{
"full_name": "string",
"first_names": "string",
"last_name": "string",
"last_name_at_birth": "string",
"birth_date": "2019-08-24",
"birth_place": "string",
"nationality": "US",
"gender": "M",
"personal_number": "string",
"tax_identification_number": "string",
"document_type": "Driving licence",
"document_issuing_country": "US",
"document_number": "string",
"document_expiry_date": "2019-08-24",
"document_issue_date": "2019-08-24",
"document_issue_place": "string",
"document_mrz": "string",
"address": "123 Main Street, London, SW1A 1AA",
"permit_obtaining_date": "2019-08-24",
"permit_expiry_date": "2019-08-24",
"permit_type_detailed": "string",
"permit_type_remarks": "string",
"front_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4",
"back_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4",
"signature_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
}
]
```
The details of the applicant's identity documents.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[[IdvDocument](#schemaidvdocument)]|false|read-only|The details of the applicant's identity documents.|
IdvDocumentTypes
```json
"Driving licence"
```
The type of identity document.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The type of identity document.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|Driving licence|
|*anonymous*|ID|
|*anonymous*|Other|
|*anonymous*|Passport|
|*anonymous*|Residence Permit|
|*anonymous*|Travel Document|
|*anonymous*|Visa|
IdvDomesticPhoneNumber
```json
"5555550102"
```
The applicant's mobile number, without the country code.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The applicant's mobile number, without the country code.|
IdvFace
```json
{
"image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
}
```
The details of the image of the applicant's face extracted from the video.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|image_signed_url|[IdvPreSignedUrl](#schemaidvpresignedurl)|true|none|The URL to the face image.|
IdvGender
```json
"M"
```
The applicant's gender.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The applicant's gender.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|M|
|*anonymous*|F|
IdvHalLink
```json
{
"href": "http://example.com"
}
```
The URL to the applicant profile resource.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|href|string(uri)|true|none|none|
IdvIdentity
```json
{
"full_name": "string",
"first_names": "string",
"last_name": "string",
"last_name_at_birth": "string",
"birth_date": "2019-08-24",
"birth_place": "string",
"nationality": "US",
"gender": "M"
}
```
The details of the applicant's verified identity.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|full_name|string|true|read-only|The applicant's full name.|
|first_names|string|false|read-only|The applicant's first names.|
|last_name|string|false|read-only|The applicant's last name.|
|last_name_at_birth|string|false|read-only|The applicant's last name at birth.|
|birth_date|string(date)|true|read-only|The applicant's birth date.
Format `YYYY-MM-DD`|
|birth_place|string|false|read-only|The applicant's birth place.|
|nationality|[IdvCountryCode](#schemaidvcountrycode)|false|none|The applicant's nationality.
Standard – [ISO alpha-2 country code](https://www.checkout.com/docs/developer-resources/testing/codes/country-codes)
Example – `FR`|
|gender|[IdvGender](#schemaidvgender)|false|none|The applicant's gender.|
IdvIdentityDeclaredData
```json
{
"name": "Hannah Bret",
"birth_date": "1994-10-15",
"phone_number": {
"country_code": "+33",
"number": "5555550102"
},
"email": "hannah.bret@example.com",
"address": {
"address_line1": "123 Main Street",
"address_line2": "Apt 4B",
"city": "London",
"state": "Greater London",
"zip": "SW1A 1AA",
"country": "GB"
}
}
```
The personal details provided by the applicant.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[IdvDeclaredData](#schemaidvdeclareddata)|false|none|The personal details provided by the applicant.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» phone_number|[IdvPhoneNumber](#schemaidvphonenumber)|false|none|The applicant's mobile phone number, if sharing the attempt URL via SMS.|
|» email|string(email)¦null|false|none|The applicant's email address.|
|» address|[IdvAddress](#schemaidvaddress)|false|none|The applicant's address.|
IdvIdentityVerification
```json
{
"id": "idv_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"status": "approved",
"response_codes": [
{
"code": 10000,
"summary": "document_front_not_captured"
}
],
"risk_labels": [
"multiple_faces_detected"
],
"verified_identity": {
"full_name": "string",
"first_names": "string",
"last_name": "string",
"last_name_at_birth": "string",
"birth_date": "2019-08-24",
"birth_place": "string",
"nationality": "US",
"gender": "M"
},
"certifications": [
{
"type": "diatf",
"data": {
"gpg45_profile": "M1A",
"level_of_confidence": "medium",
"right_to_work": "GRANTED"
}
}
],
"verification_policy_version": "string",
"declared_data": {
"name": "Hannah Bret",
"birth_date": "1994-10-15",
"phone_number": {
"country_code": "+33",
"number": "5555550102"
},
"email": "hannah.bret@example.com",
"address": {
"address_line1": "123 Main Street",
"address_line2": "Apt 4B",
"city": "London",
"state": "Greater London",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"documents": [
{
"full_name": "string",
"first_names": "string",
"last_name": "string",
"last_name_at_birth": "string",
"birth_date": "2019-08-24",
"birth_place": "string",
"nationality": "US",
"gender": "M",
"personal_number": "string",
"tax_identification_number": "string",
"document_type": "Driving licence",
"document_issuing_country": "US",
"document_number": "string",
"document_expiry_date": "2019-08-24",
"document_issue_date": "2019-08-24",
"document_issue_place": "string",
"document_mrz": "string",
"address": "123 Main Street, London, SW1A 1AA",
"permit_obtaining_date": "2019-08-24",
"permit_expiry_date": "2019-08-24",
"permit_type_detailed": "string",
"permit_type_remarks": "string",
"front_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4",
"back_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4",
"signature_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
}
],
"face": {
"image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
},
"_links": {
"self": {
"href": "http://example.com"
},
"applicant": {
"href": "http://example.com"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IdvIdentityVerificationId](#schemaidvidentityverificationid)|true|read-only|The identity verification's unique identifier.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[DatedObject](#schemadatedobject)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[IdvIdentityVerificationBase](#schemaidvidentityverificationbase)|false|none|none|
IdvIdentityVerificationBase
```json
{
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"status": "approved",
"response_codes": [
{
"code": 10000,
"summary": "document_front_not_captured"
}
],
"risk_labels": [
"multiple_faces_detected"
],
"verified_identity": {
"full_name": "string",
"first_names": "string",
"last_name": "string",
"last_name_at_birth": "string",
"birth_date": "2019-08-24",
"birth_place": "string",
"nationality": "US",
"gender": "M"
},
"certifications": [
{
"type": "diatf",
"data": {
"gpg45_profile": "M1A",
"level_of_confidence": "medium",
"right_to_work": "GRANTED"
}
}
],
"verification_policy_version": "string",
"declared_data": {
"name": "Hannah Bret",
"birth_date": "1994-10-15",
"phone_number": {
"country_code": "+33",
"number": "5555550102"
},
"email": "hannah.bret@example.com",
"address": {
"address_line1": "123 Main Street",
"address_line2": "Apt 4B",
"city": "London",
"state": "Greater London",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"documents": [
{
"full_name": "string",
"first_names": "string",
"last_name": "string",
"last_name_at_birth": "string",
"birth_date": "2019-08-24",
"birth_place": "string",
"nationality": "US",
"gender": "M",
"personal_number": "string",
"tax_identification_number": "string",
"document_type": "Driving licence",
"document_issuing_country": "US",
"document_number": "string",
"document_expiry_date": "2019-08-24",
"document_issue_date": "2019-08-24",
"document_issue_place": "string",
"document_mrz": "string",
"address": "123 Main Street, London, SW1A 1AA",
"permit_obtaining_date": "2019-08-24",
"permit_expiry_date": "2019-08-24",
"permit_type_detailed": "string",
"permit_type_remarks": "string",
"front_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4",
"back_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4",
"signature_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
}
],
"face": {
"image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
},
"_links": {
"self": {
"href": "http://example.com"
},
"applicant": {
"href": "http://example.com"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|applicant_id|[ApplicantId](#schemaapplicantid)|true|none|The applicant's unique identifier.|
|user_journey_id|[IdvUserJourneyId](#schemaidvuserjourneyid)|false|none|Your configuration ID.|
|status|[IdvVerificationStatuses](#schemaidvverificationstatuses)|true|read-only|The [verification status](https://www.checkout.com/docs/developer-resources/codes/identities-codes).|
|response_codes|[IdvResponseCodes](#schemaidvresponsecodes)|true|none|One or more [response codes](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Response_codes) that provide more information about the status.|
|risk_labels|[IdvRiskLabels](#schemaidvrisklabels)|true|none|One or more codes that provide more information about risks associated with the verification.|
|verified_identity|[IdvVerifiedIdentity](#schemaidvverifiedidentity)|false|none|The details of the applicant's verified identity.|
|certifications|[IdvCertifications](#schemaidvcertifications)|false|none|The certifications associated with the identity verification.|
|verification_policy_version|string|false|read-only|The version of the verification policy applied. Only returned for certified verifications.|
|declared_data|[IdvIdentityDeclaredData](#schemaidvidentitydeclareddata)|true|none|The personal details provided by the applicant.|
|documents|[IdvDocumentList](#schemaidvdocumentlist)|false|none|The details of the applicant's identity documents.|
|face|[IdvFace](#schemaidvface)|false|read-only|The details of the image of the applicant's face extracted from the video.|
|_links|[IdvIdentityVerificationLinks](#schemaidvidentityverificationlinks)|true|read-only|The details of links related to the resource.|
IdvIdentityVerificationCreateBase
```json
{
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"status": "approved",
"declared_data": {
"name": "Hannah Bret",
"birth_date": "1994-10-15",
"phone_number": {
"country_code": "+33",
"number": "5555550102"
},
"email": "hannah.bret@example.com",
"address": {
"address_line1": "123 Main Street",
"address_line2": "Apt 4B",
"city": "London",
"state": "Greater London",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"documents": [
{
"full_name": "string",
"first_names": "string",
"last_name": "string",
"last_name_at_birth": "string",
"birth_date": "2019-08-24",
"birth_place": "string",
"nationality": "US",
"gender": "M",
"personal_number": "string",
"tax_identification_number": "string",
"document_type": "Driving licence",
"document_issuing_country": "US",
"document_number": "string",
"document_expiry_date": "2019-08-24",
"document_issue_date": "2019-08-24",
"document_issue_place": "string",
"document_mrz": "string",
"address": "123 Main Street, London, SW1A 1AA",
"permit_obtaining_date": "2019-08-24",
"permit_expiry_date": "2019-08-24",
"permit_type_detailed": "string",
"permit_type_remarks": "string",
"front_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4",
"back_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4",
"signature_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
}
],
"face": {
"image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
},
"response_codes": [
{
"code": 10000,
"summary": "document_front_not_captured"
}
],
"risk_labels": [
"multiple_faces_detected"
],
"verified_identity": {
"full_name": "string",
"first_names": "string",
"last_name": "string",
"last_name_at_birth": "string",
"birth_date": "2019-08-24",
"birth_place": "string",
"nationality": "US",
"gender": "M"
},
"certifications": [
{
"type": "diatf",
"data": {
"gpg45_profile": "M1A",
"level_of_confidence": "medium",
"right_to_work": "GRANTED"
}
}
],
"verification_policy_version": "string",
"_links": {
"self": {
"href": "http://example.com"
},
"applicant": {
"href": "http://example.com"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|applicant_id|[ApplicantId](#schemaapplicantid)|true|none|The applicant's unique identifier.|
|user_journey_id|[IdvUserJourneyId](#schemaidvuserjourneyid)|false|none|Your configuration ID.|
|status|[IdvVerificationStatuses](#schemaidvverificationstatuses)|true|none|The [verification status](https://www.checkout.com/docs/developer-resources/codes/identities-codes).|
|declared_data|[IdvIdentityDeclaredData](#schemaidvidentitydeclareddata)|true|none|The personal details provided by the applicant.|
|documents|[IdvDocumentList](#schemaidvdocumentlist)|false|none|The details of the applicant's identity documents.|
|face|[IdvFace](#schemaidvface)|false|read-only|The details of the image of the applicant's face extracted from the video.|
|response_codes|[IdvResponseCodes](#schemaidvresponsecodes)|true|none|One or more [response codes](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Response_codes) that provide more information about the status.|
|risk_labels|[IdvRiskLabels](#schemaidvrisklabels)|true|none|One or more codes that provide more information about risks associated with the verification.|
|verified_identity|[IdvVerifiedIdentity](#schemaidvverifiedidentity)|false|none|The details of the applicant's verified identity.|
|certifications|[IdvCertifications](#schemaidvcertifications)|false|none|The certifications associated with the identity verification.|
|verification_policy_version|string|false|read-only|The version of the verification policy applied. Only returned for certified verifications.|
|_links|[IdvIdentityVerificationLinks](#schemaidvidentityverificationlinks)|true|none|The details of links related to the resource.|
IdvIdentityVerificationError
```json
{
"error_type": "unprocessable_entity",
"error_codes": [
"string"
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|error_type|string|true|none|The type of error.|
|error_codes|[string]|true|none|The error codes.|
#### Enumerated Values
|Property|Value|
|---|---|
|error_type|unprocessable_entity|
|error_type|request_invalid|
IdvIdentityVerificationHelper
```json
{
"id": "idv_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"status": "approved",
"response_codes": [
{
"code": 10000,
"summary": "document_front_not_captured"
}
],
"risk_labels": [
"multiple_faces_detected"
],
"verified_identity": {
"full_name": "string",
"first_names": "string",
"last_name": "string",
"last_name_at_birth": "string",
"birth_date": "2019-08-24",
"birth_place": "string",
"nationality": "US",
"gender": "M"
},
"certifications": [
{
"type": "diatf",
"data": {
"gpg45_profile": "M1A",
"level_of_confidence": "medium",
"right_to_work": "GRANTED"
}
}
],
"verification_policy_version": "string",
"declared_data": {
"name": "Hannah Bret",
"birth_date": "1994-10-15",
"phone_number": {
"country_code": "+33",
"number": "5555550102"
},
"email": "hannah.bret@example.com",
"address": {
"address_line1": "123 Main Street",
"address_line2": "Apt 4B",
"city": "London",
"state": "Greater London",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"documents": [
{
"full_name": "string",
"first_names": "string",
"last_name": "string",
"last_name_at_birth": "string",
"birth_date": "2019-08-24",
"birth_place": "string",
"nationality": "US",
"gender": "M",
"personal_number": "string",
"tax_identification_number": "string",
"document_type": "Driving licence",
"document_issuing_country": "US",
"document_number": "string",
"document_expiry_date": "2019-08-24",
"document_issue_date": "2019-08-24",
"document_issue_place": "string",
"document_mrz": "string",
"address": "123 Main Street, London, SW1A 1AA",
"permit_obtaining_date": "2019-08-24",
"permit_expiry_date": "2019-08-24",
"permit_type_detailed": "string",
"permit_type_remarks": "string",
"front_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4",
"back_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4",
"signature_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
}
],
"face": {
"image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
},
"redirect_url": "http://example.com",
"_links": {
"self": {
"href": "http://example.com"
},
"verification_url": {
"href": "http://example.com"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IdvIdentityVerificationId](#schemaidvidentityverificationid)|true|read-only|The identity verification's unique identifier.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[DatedObject](#schemadatedobject)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[IdvIdentityVerificationHelperBase](#schemaidvidentityverificationhelperbase)|false|none|none|
IdvIdentityVerificationHelperBase
```json
{
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"status": "approved",
"response_codes": [
{
"code": 10000,
"summary": "document_front_not_captured"
}
],
"risk_labels": [
"multiple_faces_detected"
],
"verified_identity": {
"full_name": "string",
"first_names": "string",
"last_name": "string",
"last_name_at_birth": "string",
"birth_date": "2019-08-24",
"birth_place": "string",
"nationality": "US",
"gender": "M"
},
"certifications": [
{
"type": "diatf",
"data": {
"gpg45_profile": "M1A",
"level_of_confidence": "medium",
"right_to_work": "GRANTED"
}
}
],
"verification_policy_version": "string",
"declared_data": {
"name": "Hannah Bret",
"birth_date": "1994-10-15",
"phone_number": {
"country_code": "+33",
"number": "5555550102"
},
"email": "hannah.bret@example.com",
"address": {
"address_line1": "123 Main Street",
"address_line2": "Apt 4B",
"city": "London",
"state": "Greater London",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"documents": [
{
"full_name": "string",
"first_names": "string",
"last_name": "string",
"last_name_at_birth": "string",
"birth_date": "2019-08-24",
"birth_place": "string",
"nationality": "US",
"gender": "M",
"personal_number": "string",
"tax_identification_number": "string",
"document_type": "Driving licence",
"document_issuing_country": "US",
"document_number": "string",
"document_expiry_date": "2019-08-24",
"document_issue_date": "2019-08-24",
"document_issue_place": "string",
"document_mrz": "string",
"address": "123 Main Street, London, SW1A 1AA",
"permit_obtaining_date": "2019-08-24",
"permit_expiry_date": "2019-08-24",
"permit_type_detailed": "string",
"permit_type_remarks": "string",
"front_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4",
"back_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4",
"signature_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
}
],
"face": {
"image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
},
"redirect_url": "http://example.com",
"_links": {
"self": {
"href": "http://example.com"
},
"verification_url": {
"href": "http://example.com"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|user_journey_id|[IdvUserJourneyId](#schemaidvuserjourneyid)|false|none|Your configuration ID.|
|applicant_id|[ApplicantId](#schemaapplicantid)|false|none|The applicant's unique identifier.|
|status|[IdvVerificationStatuses](#schemaidvverificationstatuses)|true|read-only|The [verification status](https://www.checkout.com/docs/developer-resources/codes/identities-codes).|
|response_codes|[IdvResponseCodes](#schemaidvresponsecodes)|true|none|One or more [response codes](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Response_codes) that provide more information about the status.|
|risk_labels|[IdvRiskLabels](#schemaidvrisklabels)|true|none|One or more codes that provide more information about risks associated with the verification.|
|verified_identity|[IdvIdentity](#schemaidvidentity)|false|read-only|The details of the applicant's verified identity.|
|certifications|[IdvCertifications](#schemaidvcertifications)|false|none|The certifications associated with the identity verification.|
|verification_policy_version|string|false|read-only|The version of the verification policy applied. Only returned for certified verifications.|
|declared_data|[IdvIdentityDeclaredData](#schemaidvidentitydeclareddata)|true|none|The personal details provided by the applicant.|
|documents|[IdvDocumentList](#schemaidvdocumentlist)|false|none|The details of the applicant's identity documents.|
|face|[IdvFace](#schemaidvface)|false|read-only|The details of the image of the applicant's face extracted from the video.|
|redirect_url|string(uri)|true|none|The URL to redirect the applicant to after the attempt.|
|_links|[IdvIdentityVerificationHelperLinks](#schemaidvidentityverificationhelperlinks)|true|read-only|The details of links related to the resource.|
IdvIdentityVerificationHelperLinks
```json
{
"self": {
"href": "http://example.com"
},
"verification_url": {
"href": "http://example.com"
}
}
```
The details of links related to the resource.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[IdvSelfLink](#schemaidvselflink)|false|none|The details of links related to the resource.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[IdvActiveLink](#schemaidvactivelink)|false|none|none|
IdvIdentityVerificationId
```json
"idv_tkoi5db4hryu5cei5vwoabr7we"
```
The identity verification's unique identifier.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|read-only|The identity verification's unique identifier.|
IdvIdentityVerificationLinks
```json
{
"self": {
"href": "http://example.com"
},
"applicant": {
"href": "http://example.com"
}
}
```
The details of links related to the resource.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[IdvSelfLink](#schemaidvselflink)|false|none|The details of links related to the resource.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[IdvApplicantLink](#schemaidvapplicantlink)|false|none|The URL to the applicant's profile.|
IdvIdentityVerificationOutput
```json
{
"id": "idv_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"status": "approved",
"declared_data": {
"name": "Hannah Bret",
"birth_date": "1994-10-15",
"phone_number": {
"country_code": "+33",
"number": "5555550102"
},
"email": "hannah.bret@example.com",
"address": {
"address_line1": "123 Main Street",
"address_line2": "Apt 4B",
"city": "London",
"state": "Greater London",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"documents": [
{
"full_name": "string",
"first_names": "string",
"last_name": "string",
"last_name_at_birth": "string",
"birth_date": "2019-08-24",
"birth_place": "string",
"nationality": "US",
"gender": "M",
"personal_number": "string",
"tax_identification_number": "string",
"document_type": "Driving licence",
"document_issuing_country": "US",
"document_number": "string",
"document_expiry_date": "2019-08-24",
"document_issue_date": "2019-08-24",
"document_issue_place": "string",
"document_mrz": "string",
"address": "123 Main Street, London, SW1A 1AA",
"permit_obtaining_date": "2019-08-24",
"permit_expiry_date": "2019-08-24",
"permit_type_detailed": "string",
"permit_type_remarks": "string",
"front_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4",
"back_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4",
"signature_image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
}
],
"face": {
"image_signed_url": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
},
"response_codes": [
{
"code": 10000,
"summary": "document_front_not_captured"
}
],
"risk_labels": [
"multiple_faces_detected"
],
"verified_identity": {
"full_name": "string",
"first_names": "string",
"last_name": "string",
"last_name_at_birth": "string",
"birth_date": "2019-08-24",
"birth_place": "string",
"nationality": "US",
"gender": "M"
},
"certifications": [
{
"type": "diatf",
"data": {
"gpg45_profile": "M1A",
"level_of_confidence": "medium",
"right_to_work": "GRANTED"
}
}
],
"verification_policy_version": "string",
"_links": {
"self": {
"href": "http://example.com"
},
"applicant": {
"href": "http://example.com"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IdvIdentityVerificationId](#schemaidvidentityverificationid)|true|none|The identity verification's unique identifier.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[DatedObject](#schemadatedobject)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[IdvIdentityVerificationCreateBase](#schemaidvidentityverificationcreatebase)|false|none|none|
IdvInitialDevices
```json
"desktop"
```
The type of device the applicant used to start the attempt.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|read-only|The type of device the applicant used to start the attempt.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|desktop|
|*anonymous*|mobile|
IdvNextLink
```json
{
"next": {
"href": "http://example.com"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|next|[IdvHalLink](#schemaidvhallink)|true|none|The URL to the applicant profile resource.|
IdvPdf
```json
{
"pdf_report": "https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|pdf_report|[IdvPreSignedUrl](#schemaidvpresignedurl)|true|none|The pre-signed URL to the PDF report.|
IdvPhoneNumber
```json
{
"country_code": "+33",
"number": "5555550102"
}
```
The applicant's mobile phone number, if sharing the attempt URL via SMS.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|country_code|[IdvPhonePrefix](#schemaidvphoneprefix)|true|none|The international [phone country code](https://www.checkout.com/docs/resources/codes/country-codes).|
|number|[IdvDomesticPhoneNumber](#schemaidvdomesticphonenumber)|true|none|The applicant's mobile number, without the country code.|
IdvPhonePrefix
```json
"+33"
```
The international [phone country code](https://www.checkout.com/docs/resources/codes/country-codes).
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The international [phone country code](https://www.checkout.com/docs/resources/codes/country-codes).|
IdvPreSignedUrl
```json
"https://storage-b.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
```
The pre-signed URL to the captured image of the document.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string(uri)|false|none|The pre-signed URL to the captured image of the document.|
IdvPreviousLink
```json
{
"previous": {
"href": "http://example.com"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|previous|[IdvHalLink](#schemaidvhallink)|true|none|The URL to the applicant profile resource.|
IdvResponseCode
```json
{
"code": 10000,
"summary": "document_front_not_captured"
}
```
The [response code](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Response_codes) that provides more information about the identity verification status.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|code|[IdvResponseCodeCode](#schemaidvresponsecodecode)|true|none|The [response code](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Response_codes).|
|summary|[IdvResponseCodeSummary](#schemaidvresponsecodesummary)|true|none|The description of the [response code](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Response_codes).|
IdvResponseCodeCode
```json
10000
```
The [response code](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Response_codes).
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|integer|false|read-only|The [response code](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Response_codes).|
IdvResponseCodes
```json
[
{
"code": 10000,
"summary": "document_front_not_captured"
}
]
```
One or more [response codes](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Response_codes) that provide more information about the status.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[[IdvResponseCode](#schemaidvresponsecode)]|false|read-only|One or more [response codes](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Response_codes) that provide more information about the status.|
IdvResponseCodeSummary
```json
"document_front_not_captured"
```
The description of the [response code](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Response_codes).
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|read-only|The description of the [response code](https://www.checkout.com/docs/developer-resources/codes/identities-codes#Response_codes).|
IdvRiskLabel
```json
"multiple_faces_detected"
```
A code that provides more information about a risk associated with the verification.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|read-only|A code that provides more information about a risk associated with the verification.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|multiple_faces_detected|
|*anonymous*|mcc_not_confident|
|*anonymous*|risky_document_format|
IdvRiskLabels
```json
[
"multiple_faces_detected"
]
```
One or more codes that provide more information about risks associated with the verification.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[[IdvRiskLabel](#schemaidvrisklabel)]|false|read-only|One or more codes that provide more information about risks associated with the verification.|
IdvSelectedDocument
```json
{
"country": "US",
"document_type": "Driving licence"
}
```
The details of the document the applicant selected.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|country|[IdvCountryCode](#schemaidvcountrycode)|false|none|The applicant's nationality.
Standard – [ISO alpha-2 country code](https://www.checkout.com/docs/developer-resources/testing/codes/country-codes)
Example – `FR`|
|document_type|[IdvDocumentTypes](#schemaidvdocumenttypes)|false|none|The type of identity document.|
IdvSelfLink
```json
{
"self": {
"href": "http://example.com"
}
}
```
The details of links related to the resource.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|self|[IdvHalLink](#schemaidvhallink)|true|none|The URL to the resource.|
IdvUserJourneyId
```json
"usj_tkoi5db4hryu5cei5vwoabr7we"
```
Your configuration ID.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|read-only|Your configuration ID.|
IdvVerificationStatuses
```json
"approved"
```
The [verification status](https://www.checkout.com/docs/developer-resources/codes/identities-codes).
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|read-only|The [verification status](https://www.checkout.com/docs/developer-resources/codes/identities-codes).|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|approved|
|*anonymous*|capture_in_progress|
|*anonymous*|checks_in_progress|
|*anonymous*|created|
|*anonymous*|declined|
|*anonymous*|inconclusive|
|*anonymous*|pending|
|*anonymous*|refused|
|*anonymous*|retry_required|
IdvVerifiedIdentity
```json
{
"full_name": "string",
"first_names": "string",
"last_name": "string",
"last_name_at_birth": "string",
"birth_date": "2019-08-24",
"birth_place": "string",
"nationality": "US",
"gender": "M"
}
```
The details of the applicant's verified identity.
### Properties
*None*
AccountHolder
```json
{
"type": "individual",
"first_name": "John",
"last_name": "Smith",
"tax_id": "123456",
"date_of_birth": "1986-01-01",
"country_of_birth": "GB",
"residential_status": "resident",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"identification": {
"type": "SSN",
"issuing_country": "string",
"number": "string"
}
}
```
The bank account holder details. Having accurate and complete data improves payout performance (increases success rate and the prevents delays).
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[01_PayoutRequestIndividualAccountHolder](#schema01_payoutrequestindividualaccountholder)|false|none|Store a previously tokenized instrument|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[03_PayoutRequestGovernmentAccountHolder](#schema03_payoutrequestgovernmentaccountholder)|false|none|Store a previously tokenized instrument|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[02_PayoutRequestCorporateAccountHolder](#schema02_payoutrequestcorporateaccountholder)|false|none|Store a previously tokenized instrument|
AccountHolderAch
```json
{
"type": "individual",
"first_name": "John",
"last_name": "Smith",
"company_name": "Test company",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"date_of_birth": "string",
"identification": {
"type": "SSN",
"issuing_country": "string",
"number": "string"
}
}
```
The account holder details
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of account holder|
|first_name|string|true|none|The first name of the account holder|
|last_name|string|true|none|The last name of the account holder|
|company_name|string|false|none|The legal name of a registered company that holds the account|
|billing_address|[Address](#schemaaddress)|false|none|The account holder's billing address.|
|date_of_birth|string|false|none|The account holder's date of birth.|
|identification|object|false|none|The account holder's government document identification. For example, the social security number (SSN).|
|» type|string|false|none|The document type|
|» issuing_country|string|false|none|The country where the document was issued|
|» number|string|false|none|The document number|
#### Enumerated Values
|Property|Value|
|---|---|
|type|individual|
|type|corporate|
|type|government|
AccountHolderEps
```json
{
"first_name": "John",
"last_name": "Smith"
}
```
The account holder details
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|first_name|string|true|none|The first name of the account holder|
|last_name|string|true|none|The last name of the account holder|
AccountHolderIdentification
```json
{
"type": "passport",
"number": "09876",
"issuing_country": "US"
}
```
Bank account holder's proof of identification
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|false|none|The type of identification used to identify the account holder|
|number|string|false|none|The identification number|
|issuing_country|string|false|none|The two-letter ISO country code of the country that issued the identification|
#### Enumerated Values
|Property|Value|
|---|---|
|type|passport|
|type|driving_licence|
|type|national_id|
|type|company_registration|
|type|tax_id|
AccountHolderResponse
```json
{
"first_name": "Hannah",
"last_name": "Bret",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
}
```
The account holder details
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|first_name|string|false|none|The account holder's first name.|
|last_name|string|false|none|The account holder's last name.|
|billing_address|[Address](#schemaaddress)|false|none|The account holder's billing address.|
|phone|[PhoneNumber](#schemaphonenumber)|false|none|The account holder's phone number.|
BankDetails
```json
{
"name": "Lloyds TSB",
"branch": "Bournemouth",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
}
```
Details of the bank
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|false|none|The bank's name|
|branch|string|false|none|The bank branch's name|
|address|[Address](#schemaaddress)|false|none|The bank's contact address|
NetworkToken
```json
{
"id": "nt_y3oqhf46pyzuxjbcn2giaqnb44",
"state": "active"
}
```
Network token details
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|true|none|The network token's unique identifier.|
|state|string|false|none|The token status|
#### Enumerated Values
|Property|Value|
|---|---|
|state|active|
|state|suspended|
|state|inactive|
ProvisionNetworkToken
```json
{
"provision": true
}
```
Provision network token details
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|provision|boolean|false|none|Indicates whether a network token should be provisioned or not. If you do not pass the provision field, the default value will be set as false.|
RetrieveInstrumentCustomerResponse
```json
{
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "brucewayne@gmail.com",
"name": "Bruce Wayne",
"default": true
}
```
Stored customer details
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|true|none|The customer's unique identifier. This can be passed as a source when making a payment.|
|email|string|false|none|The customer's email address|
|name|string|false|none|The customer's name|
|default|boolean|false|none|This will be true if this instrument is set as the default for the customer|
StoreAccountHolderTokenRequest
```json
{
"first_name": "John",
"last_name": "Smith",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
}
```
The account holder details
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|first_name|string|false|none|The first name of the account holder|
|last_name|string|false|none|The last name of the account holder|
|billing_address|[Address](#schemaaddress)|false|none|The billing address of the account holder|
|phone|[PhoneNumber](#schemaphonenumber)|false|none|The phone number of the account holder|
UpdateCardAccountHolder
```json
{
"first_name": "John",
"last_name": "Smith",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
}
```
The account holder details
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|first_name|string|false|none|The first name of the account holder|
|last_name|string|false|none|The last name of the account holder|
|billing_address|[Address](#schemaaddress)|false|none|The billing address of the account holder|
|phone|[PhoneNumber](#schemaphonenumber)|false|none|The phone number of the account holder|
RetrieveAchInstrumentResponse
```json
{
"type": "ach",
"id": "src_wmlfc3zyhqzehihu7giusaaawu",
"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
"created_on": "2021-01-01T00:00:00Z",
"modified_on": "2021-01-01T00:00:00Z",
"vault_id": "vid_wmlfc3zyhqzehihu7giusaaawu",
"instrument_data": {
"account_type": "savings",
"account_number": "4099999992",
"bank_code": "211370545",
"currency": "USD",
"country": "US"
},
"account_holder": {
"first_name": "John",
"last_name": "Smith",
"company_name": "Smith Enterprises",
"type": "individual"
},
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "brucewayne@gmail.com",
"name": "Bruce Wayne",
"default": true
}
}
```
ach
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The underlying instrument type|
|id|string|true|none|The unique identifier of the payment source or destination that can be used later for payments|
|fingerprint|string|true|none|A token that can uniquely identify this instrument across all customers.|
|created_on|string(date-time)|true|none|The date and time the instrument was created.|
|modified_on|string(date-time)|true|none|The date and time the instrument was last modified.|
|vault_id|string|true|none|The Vault ID currently attached to the instrument.|
|instrument_data|object|true|none|The details of the bank account|
|» account_type|string|true|none|The type of Direct Debit account|
|» account_number|string|true|none|The account number of the Direct Debit account|
|» bank_code|string|true|none|The bank code of the Direct Debit account|
|» currency|string|true|none|The currency of the account|
|» country|string|true|none|The country of the account|
|account_holder|object|true|none|The account holder details|
|» first_name|string|true|none|First name. Required for individual account holder type|
|» last_name|string|true|none|Last name. Required for individual account holder type|
|» company_name|string|true|none|Company name. Required for corporate account holder type|
|» type|string|true|none|Account holder type|
|customer|[RetrieveInstrumentCustomerResponse](#schemaretrieveinstrumentcustomerresponse)|false|none|Stored customer details|
#### Enumerated Values
|Property|Value|
|---|---|
|account_type|savings|
|account_type|checking|
|type|individual|
|type|corporate|
RetrieveBacsInstrumentResponse
```json
{
"type": "bacs",
"id": "src_wmlfc3zyhqzehihu7giusaaawu",
"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
"created_on": "2021-01-01T00:00:00Z",
"vault_id": "vid_wmlfc3zyhqzehihu7giusaaawu",
"modified_on": "2021-01-01T00:00:00Z",
"account": {
"client_id": "cli_memowvltf7aulpb3poehtiffei",
"processing_channel_id": "pc_jcs4ufa6hrgepcrvhic4bfspay"
},
"validations": [
{}
],
"instrument_data": {
"account_number": "86753246",
"bank_code": "040004",
"country": "GB",
"currency": "GBP",
"payment_type": "Recurring",
"allow_partial_match": true,
"status": "INVALID",
"match_status": "no match",
"description": "The name did not match with the account owner.",
"mandate_id": "6PZ6KFI3KW3UFHAM3J"
},
"account_holder": {
"first_name": "Hannah",
"last_name": "Bret",
"company_name": "string",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"zip": "SW1A 1AA",
"country": "GB"
},
"type": "corporate"
},
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "brucewayne@gmail.com",
"name": "Bruce Wayne",
"default": true
}
}
```
bacs
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The underlying instrument type|
|id|string|true|none|The unique identifier of the payment source or destination that can be used later for payments|
|fingerprint|string|true|none|A token that can uniquely identify this instrument across all customers.|
|created_on|string(date-time)|true|none|The date and time the instrument was created.|
|vault_id|string|true|none|The Vault ID currently attached to the instrument.|
|modified_on|string(date-time)|false|none|The date and time the instrument was last modified.|
|account|object|false|none|The account configuration for the instrument.|
|» client_id|string|false|none|The ID of the client associated with the instrument.|
|» processing_channel_id|string|false|none|The ID of the processing channel associated with the instrument.|
|validations|[object]|false|none|The list of validations performed on the instrument.|
|instrument_data|object|false|none|The details of the Bacs Direct Debit account.|
|» account_number|string|true|none|The account number of the Bacs Direct Debit account.|
|» bank_code|string|true|none|The sort code of the Bacs Direct Debit account.|
|» country|string|true|none|The country of the account, as an ISO 3166-1 alpha-2 code.|
|» currency|string|true|none|The currency of the account.|
|» payment_type|string|true|none|The type of payment.|
|» allow_partial_match|boolean|false|none|Whether vault accepted a partial match when looking up the Bacs instrument for the supplied account details.|
|» status|string|false|none|The validation status of the account.|
|» match_status|string|false|none|The result of matching the account holder name against the account owner.|
|» description|string|false|none|A human-readable description of the validation result.|
|» mandate_id|string|false|none|The identifier of the Bacs Direct Debit mandate.|
|account_holder|object|false|none|The account holder's details.|
|» first_name|string|true|none|The first name of the account holder.|
|» last_name|string|true|none|The last name of the account holder.|
|» company_name|string|false|none|The legal name of a registered company that holds the account.|
|» billing_address|object|true|none|The billing address of the account holder.|
|»» address_line1|string|false|none|The first line of the address.|
|»» address_line2|string|false|none|The second line of the address.|
|»» city|string|false|none|The address city.|
|»» zip|string|false|none|The address ZIP or postal code.|
|»» country|string|true|none|The address country.|
|» type|string|false|none|The type of account holder.|
|customer|[RetrieveInstrumentCustomerResponse](#schemaretrieveinstrumentcustomerresponse)|false|none|Stored customer details|
#### Enumerated Values
|Property|Value|
|---|---|
|payment_type|Recurring|
|payment_type|Regular|
|type|individual|
|type|corporate|
RetrieveBankAccountInstrumentResponse
```json
{
"type": "string",
"id": "src_wmlfc3zyhqzehihu7giusaaawu",
"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
"account_type": "savings",
"account_number": "13654567455",
"bank_code": "123-456",
"branch_code": "6443",
"iban": "HU93116000060000000012345676",
"bban": "3704 0044 0532 0130 00",
"swift_bic": "37040044",
"currency": "GBP",
"country": "GB",
"account_holder": {
"type": "individual",
"first_name": "John",
"last_name": "Smith",
"tax_id": "123456",
"date_of_birth": "1986-01-01",
"country_of_birth": "GB",
"residential_status": "resident",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"identification": {
"type": "SSN",
"issuing_country": "string",
"number": "string"
}
},
"bank": {
"name": "Lloyds TSB",
"branch": "Bournemouth",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "brucewayne@gmail.com",
"name": "Bruce Wayne",
"default": true
}
}
```
bank_account
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of instrument|
|id|string|true|none|The unique identifier of the payment source or destination that can be used later for payments|
|fingerprint|string|true|none|A token that can uniquely identify this instrument across all customers|
|account_type|string|false|none|The type of account|
|account_number|string|false|none|Number (which can contain letters) that identifies the account|
|bank_code|string|false|none|Code that identifies the bank|
|branch_code|string|false|none|Code that identifies the bank branch|
|iban|string|false|none|Internationally agreed standard for identifying bank account|
|bban|string|false|none|The combination of bank code and/or branch code and account number|
|swift_bic|string|false|none|8 or 11 character code which identifies the bank or bank branch|
|currency|string|true|none|The three-letter ISO currency code of the account's currency|
|country|string|true|none|The two-letter ISO country code of where the account is based|
|account_holder|[AccountHolder](#schemaaccountholder)|false|none|The bank account holder details. Having accurate and complete data improves payout performance (increases success rate and the prevents delays).|
|bank|[BankDetails](#schemabankdetails)|false|none|Details of the bank|
|customer|[RetrieveInstrumentCustomerResponse](#schemaretrieveinstrumentcustomerresponse)|false|none|Stored customer details|
#### Enumerated Values
|Property|Value|
|---|---|
|account_type|savings|
|account_type|current|
|account_type|cash|
RetrieveCardInstrumentResponse
```json
{
"type": "card",
"id": "src_wmlfc3zyhqzehihu7giusaaawu",
"encrypted_card_number": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz...",
"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
"expiry_month": 6,
"expiry_year": 2025,
"name": "John Test",
"scheme": "VISA",
"scheme_local": "cartes_bancaires",
"last4": "9996",
"bin": "454347",
"card_type": "CREDIT",
"card_category": "CONSUMER",
"issuer": "GOTHAM STATE BANK",
"issuer_country": "US",
"product_id": "F",
"product_type": "CLASSIC",
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "brucewayne@gmail.com",
"name": "Bruce Wayne",
"default": true
},
"account_holder": {
"first_name": "John",
"last_name": "Smith",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"network_token": {
"id": "nt_y3oqhf46pyzuxjbcn2giaqnb44",
"state": "active"
},
"card_wallet_type": "googlepay",
"regulated_indicator": true
}
```
card
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The underlying instrument type|
|id|string|true|none|The unique identifier of the payment source or destination that can be used later for payments|
|encrypted_card_number|string|false|none|The JWE-encrypted full card number. This is only present if your level of PCI compliance is SAQ-D.|
|fingerprint|string|true|none|A token that can uniquely identify this instrument across all customers|
|expiry_month|integer|true|none|The expiry month|
|expiry_year|integer|true|none|The expiry year|
|name|string|false|none|The name of the cardholder|
|scheme|string|false|none|The card scheme|
|scheme_local|string|false|none|The local co-branded card scheme|
|last4|string|true|none|The last four digits of the card number|
|bin|string|false|none|The card issuer's bank identification number (BIN)|
|card_type|string|false|none|The card type|
|card_category|string|false|none|The card category|
|issuer|string|false|none|The name of the card issuer|
|issuer_country|string|false|none|The card issuer's country (two-letter ISO code)|
|product_id|string|false|none|The issuer/card scheme product identifier|
|product_type|string|false|none|The issuer/card scheme product type|
|customer|[RetrieveInstrumentCustomerResponse](#schemaretrieveinstrumentcustomerresponse)|false|none|Stored customer details|
|account_holder|object|false|none|The account holder details|
|» first_name|string|false|none|The first name of the account holder|
|» last_name|string|false|none|The last name of the account holder|
|» billing_address|[Address](#schemaaddress)|false|none|The billing address of the account holder|
|» phone|[PhoneNumber](#schemaphonenumber)|false|none|The phone number of the account holder|
|network_token|[NetworkToken](#schemanetworktoken)|false|none|Network token details|
|card_wallet_type|string|false|none|The type of digital wallet used for the card.|
|regulated_indicator|boolean|true|none|Indicates whether the instrument is regulated debit.|
#### Enumerated Values
|Property|Value|
|---|---|
|scheme_local|cartes_bancaires|
|card_type|CREDIT|
|card_type|DEBIT|
|card_type|PREPAID|
|card_type|CHARGE|
|card_category|CONSUMER|
|card_category|COMMERCIAL|
|card_wallet_type|googlepay|
|card_wallet_type|applepay|
RetrieveInstrumentResponse
```json
{
"type": "string",
"id": "src_wmlfc3zyhqzehihu7giusaaawu",
"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
"account_type": "savings",
"account_number": "13654567455",
"bank_code": "123-456",
"branch_code": "6443",
"iban": "HU93116000060000000012345676",
"bban": "3704 0044 0532 0130 00",
"swift_bic": "37040044",
"currency": "GBP",
"country": "GB",
"account_holder": {
"type": "individual",
"first_name": "John",
"last_name": "Smith",
"tax_id": "123456",
"date_of_birth": "1986-01-01",
"country_of_birth": "GB",
"residential_status": "resident",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"identification": {
"type": "SSN",
"issuing_country": "string",
"number": "string"
}
},
"bank": {
"name": "Lloyds TSB",
"branch": "Bournemouth",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "brucewayne@gmail.com",
"name": "Bruce Wayne",
"default": true
}
}
```
The response for type of instrument stored
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The underlying instrument type|
|id|string|true|none|The unique identifier of the payment source or destination that can be used later for payments|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[RetrieveBankAccountInstrumentResponse](#schemaretrievebankaccountinstrumentresponse)|false|none|Bank account details|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[RetrieveCardInstrumentResponse](#schemaretrievecardinstrumentresponse)|false|none|card instrument response|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[RetrieveSepaInstrumentResponse](#schemaretrievesepainstrumentresponse)|false|none|SEPA instrument response|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[RetrieveAchInstrumentResponse](#schemaretrieveachinstrumentresponse)|false|none|ach instrument response|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[RetrieveBacsInstrumentResponse](#schemaretrievebacsinstrumentresponse)|false|none|Bacs Direct Debit instrument response|
RetrieveSepaInstrumentResponse
```json
{
"type": "sepa",
"id": "src_wmlfc3zyhqzehihu7giusaaawu",
"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
"created_on": "2021-01-01T00:00:00Z",
"modified_on": "2021-01-01T00:00:00Z",
"vault_id": "vid_wmlfc3zyhqzehihu7giusaaawu",
"instrument_data": {
"type": "B2B",
"account_number": "FR2810096000509685512959O86",
"country": "GB",
"currency": "GBP",
"payment_type": "recurring",
"mandate_id": "1234567890",
"date_of_signature": "2021-01-01"
},
"account_holder": {
"first_name": "Hannah",
"last_name": "Bret",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"zip": "SW1A 1AA",
"country": "GB"
},
"company_name": "string",
"type": "corporate"
},
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "brucewayne@gmail.com",
"name": "Bruce Wayne",
"default": true
}
}
```
sepa
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The underlying instrument type|
|id|string|true|none|The unique identifier of the payment source or destination that can be used later for payments|
|fingerprint|string|true|none|A token that can uniquely identify this instrument across all customers.|
|created_on|string(date-time)|true|none|The date and time the instrument was created.|
|modified_on|string(date-time)|true|none|The date and time the instrument was last modified.|
|vault_id|string|true|none|The Vault ID currently attached to the instrument.|
|instrument_data|object|false|none|The details of the SEPA mandate.|
|» type|string|false|none|The type of mandate.|
|» account_number|string|true|none|The International Bank Account Number (IBAN) of the account.|
|» country|string|true|none|The country of the account.|
|» currency|string|true|none|The currency of the account.|
|» payment_type|string|true|none|The type of payment.|
|» mandate_id|string|true|none|The mandate ID.
If this value was not provided when the instrument was created, it may take up to five seconds for the generated mandate ID to be available.|
|» date_of_signature|string(date)|true|none|The date the mandate was signed.
If `mandate_id` was not provided when the instrument was created, it may take up to five seconds for the generated date of signature to be available.|
|account_holder|object|false|none|The account holder's details.|
|» first_name|string|true|none|The first name of the account holder.|
|» last_name|string|true|none|The last name of the account holder.|
|» billing_address|object|true|none|The billing address of the account holder.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|string|true|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» zip|string|true|none|The address ZIP or postal code.|
|»» country|string|true|none|The address country.|
|» company_name|string|false|none|The legal name of a registered company that holds the account.|
|» type|string|false|none|The type of account holder.|
|customer|[RetrieveInstrumentCustomerResponse](#schemaretrieveinstrumentcustomerresponse)|false|none|Stored customer details|
#### Enumerated Values
|Property|Value|
|---|---|
|type|Core|
|type|B2B|
|payment_type|recurring|
|payment_type|regular|
|type|individual|
|type|corporate|
StoreAchInstrumentRequest
```json
{
"type": "ach",
"instrument_data": {
"account_type": "savings",
"account_number": "4099999992",
"bank_code": "211370545",
"currency": "USD",
"country": "US"
},
"account_holder": {
"first_name": "John",
"last_name": "Smith",
"company_name": "Smith Enterprises",
"type": "individual"
},
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "brucewayne@gmail.com",
"name": "Bruce Wayne",
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"default": true
}
}
```
ach
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|false|none|The type of instrument. `ach` payment instruments.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[StoreInstrumentRequestType](#schemastoreinstrumentrequesttype)|false|none|Ordered list of store instrument request types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|instrument_data|object|true|none|The details of the bank account|
|» account_type|string|true|none|The type of Direct Debit account|
|» account_number|string|true|none|The account number of the Direct Debit account|
|» bank_code|string|true|none|The bank code of the Direct Debit account|
|» currency|string|true|none|The currency of the account|
|» country|string|true|none|The country of the account|
|account_holder|object|true|none|The account holder details|
|» first_name|string|true|none|First name. Required for individual account holder type|
|» last_name|string|true|none|Last name. Required for individual account holder type|
|» company_name|string|true|none|Company name. Required for corporate account holder type|
|» type|string|true|none|Account holder type|
|customer|[StoreCustomerInstrumentRequest](#schemastorecustomerinstrumentrequest)|false|none|The customer's details|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|ach|
|account_type|savings|
|account_type|checking|
|type|individual|
|type|corporate|
StoreAchInstrumentResponse
```json
{
"type": "ach",
"id": "src_wmlfc3zyhqzehihu7giusaaawu",
"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q"
}
```
ach
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of instrument|
|id|string|true|none|The unique identifier of the payment source or destination that can be used later for payments|
|fingerprint|string|true|none|A token that can uniquely identify this instrument across all customers|
#### Enumerated Values
|Property|Value|
|---|---|
|type|ach|
StoreBacsInstrumentRequest
```json
{
"type": "bacs",
"account": {
"processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq"
},
"instrument_data": {
"account_number": "86753246",
"bank_code": "040004",
"country": "GB",
"currency": "GBP",
"payment_type": "Recurring",
"allow_partial_match": false
},
"account_holder": {
"first_name": "John",
"last_name": "Smith",
"billing_address": {
"address_line1": "Cloverfield St.",
"address_line2": "23A",
"city": "London",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "brucewayne@gmail.com",
"name": "Bruce Wayne",
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"default": true
}
}
```
bacs
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The type of instrument. `bacs` payment instruments.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[StoreInstrumentRequestType](#schemastoreinstrumentrequesttype)|false|none|Ordered list of store instrument request types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|account|object|true|none|The account configuration for the instrument.|
|» processing_channel_id|string|true|none|The ID of the processing channel to associate with the instrument.|
|instrument_data|object|true|none|The details of the Bacs Direct Debit account.|
|» account_number|string|true|none|The account number of the Bacs Direct Debit account.|
|» bank_code|string|true|none|The sort code of the Bacs Direct Debit account.|
|» country|string|true|none|The country of the account, as an ISO 3166-1 alpha-2 code.|
|» currency|string|true|none|The currency of the account.|
|» payment_type|string|true|none|The type of payment. `Recurring` or `Regular`.|
|» allow_partial_match|boolean|false|none|Indicates whether the Bacs instrument is created when account validation returns a partial match. When `true`, the instrument is created on a partial match; when `false`, instrument creation fails on a partial match.|
|account_holder|object|true|none|The account holder details|
|» first_name|string|true|none|The first name of the account holder|
|» last_name|string|true|none|The last name of the account holder|
|» billing_address|object|true|none|The billing address of the account holder|
|»» address_line1|string|false|none|The first line of the address.|
|»» address_line2|string|false|none|The street number. If no number, pass "w/n".|
|»» city|string|false|none|The address city.|
|»» zip|string|false|none|The address zip/postal code.|
|»» country|string|true|none|The two-letter ISO country code of the address.|
|customer|[StoreCustomerInstrumentRequest](#schemastorecustomerinstrumentrequest)|false|none|The customer's details|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|bacs|
|payment_type|Recurring|
|payment_type|Regular|
StoreBacsInstrumentResponse
```json
{
"type": "bacs",
"id": "src_wmlfc3zyhqzehihu7giusaaawu",
"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q"
}
```
bacs
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of instrument|
|id|string|true|none|The unique identifier of the payment source or destination that can be used later for payments|
|fingerprint|string|true|none|A token that can uniquely identify this instrument across all customers|
#### Enumerated Values
|Property|Value|
|---|---|
|type|bacs|
StoreBankAccountInstrumentRequest
```json
{
"type": "bank_account",
"account_type": "savings",
"account_number": "13654567455",
"bank_code": "123-456",
"branch_code": "6443",
"iban": "HU93116000060000000012345676",
"bban": "3704 0044 0532 0130 00",
"swift_bic": "37040044",
"currency": "GBP",
"country": "GB",
"processing_channel_id": "pc_u2l6xz5joigedmk7g5vxzt7rqy",
"account_holder": {
"type": "individual",
"first_name": "John",
"last_name": "Smith",
"tax_id": "123456",
"date_of_birth": "1986-01-01",
"country_of_birth": "GB",
"residential_status": "resident",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"identification": {
"type": "SSN",
"issuing_country": "string",
"number": "string"
}
},
"bank": {
"name": "Lloyds TSB",
"branch": "Bournemouth",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "brucewayne@gmail.com",
"name": "Bruce Wayne",
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"default": true
}
}
```
bank_account
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|false|none|The type of instrument. `bank_account` payment instruments only support payouts.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[StoreInstrumentRequestType](#schemastoreinstrumentrequesttype)|false|none|Ordered list of store instrument request types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|account_type|string|false|none|The type of account|
|account_number|string|false|none|Number (which can contain letters) that identifies the account|
|bank_code|string|false|none|Code that identifies the bank|
|branch_code|string|false|none|Code that identifies the bank branch|
|iban|string|false|none|Internationally agreed standard for identifying bank account|
|bban|string|false|none|The combination of bank code and/or branch code and account number|
|swift_bic|string|false|none|8 or 11 character code which identifies the bank or bank branch|
|currency|string|true|none|The three-letter ISO currency code of the account's currency|
|country|string|true|none|The two-letter ISO country code of where the account is based|
|processing_channel_id|string|false|none|The ID of the primary processing channel this instrument is intended to be used for|
|account_holder|[AccountHolder](#schemaaccountholder)|false|none|The bank account holder details. Having accurate and complete data improves payout performance (increases success rate and the prevents delays).|
|bank|[BankDetails](#schemabankdetails)|false|none|Details of the bank|
|customer|[StoreCustomerInstrumentRequest](#schemastorecustomerinstrumentrequest)|false|none|The customer's details|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|bank_account|
|account_type|savings|
|account_type|current|
|account_type|cash|
StoreBankAccountInstrumentResponse
```json
{
"type": "bank_account",
"id": "src_wmlfc3zyhqzehihu7giusaaawu",
"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "johnsmith@example.com",
"name": "John Smith",
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"summary": {
"registration_date": "2023-05-01",
"first_transaction_date": "2023-07-01",
"last_payment_date": "2023-08-01",
"total_order_count": 15,
"last_payment_amount": 500,
"is_premium_customer": true,
"is_returning_customer": true,
"lifetime_value": 500
}
},
"bank": {
"name": "Lloyds TSB",
"branch": "Bournemouth",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"swift_bic": "37040044",
"account_number": "13654567455",
"bank_code": "123-456",
"iban": "HU93116000060000000012345676"
}
```
bank_account
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of instrument|
|id|string|true|none|The unique identifier of the payment source or destination that can be used later for payments|
|fingerprint|string|true|none|A token that can uniquely identify this instrument across all customers|
|customer|[CustomerResponse](#schemacustomerresponse)|false|none|Stored customer details|
|bank|[BankDetails](#schemabankdetails)|false|none|Details of the bank|
|swift_bic|string|false|none|8 or 11 character code which identifies the bank or bank branch|
|account_number|string|false|none|Number (which can contain letters) that identifies the account|
|bank_code|string|false|none|Code that identifies the bank|
|iban|string|false|none|Internationally agreed standard for identifying bank account|
#### Enumerated Values
|Property|Value|
|---|---|
|type|bank_account|
StoreCardInstrumentRequest
```json
{
"type": "card",
"number": "4242424242424242",
"expiry_month": 5,
"expiry_year": 2025,
"name": "Mr. J Smith",
"account_holder": {
"first_name": "John",
"last_name": "Smith",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "brucewayne@gmail.com",
"name": "Bruce Wayne",
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"default": true
},
"entity_id": "ent_wxglze3wwywujg4nna5fb7ldli",
"processing_channel_id": "pc_u2l6xz5joigedmk7g5vxzt7rqy",
"network_token": {
"provision": true
}
}
```
card
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|false|none|The type of instrument.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[StoreInstrumentRequestType](#schemastoreinstrumentrequesttype)|false|none|Ordered list of store instrument request types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|number|string(pan)|true|none|The card number.|
|expiry_month|integer(int32)|true|none|The card's expiration month.|
|expiry_year|integer(int32)|true|none|The card's expiration year.|
|name|string|false|none|The cardholder's name.|
|account_holder|[StoreAccountHolderTokenRequest](#schemastoreaccountholdertokenrequest)|false|none|The account holder details|
|customer|[StoreCustomerInstrumentRequest](#schemastorecustomerinstrumentrequest)|false|none|The customer's details|
|entity_id|string|false|none|The client entity, used for billing purposes.
If you do not provide an `entity_id`, you must provide a `processing_channel_id` instead.|
|processing_channel_id|string|false|none|The processing channel, used for billing purposes.
If you do not provide a `processing_channel_id`, you must provide an `entity_id` instead.|
|network_token|[ProvisionNetworkToken](#schemaprovisionnetworktoken)|false|none|Provision network token details|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|card|
StoreCustomerInstrumentRequest
```json
{
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "brucewayne@gmail.com",
"name": "Bruce Wayne",
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"default": true
}
```
The customer's details
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The identifier of an existing customer|
|email|string(email)|false|none|An optional email address to associate with the customer|
|name|string|false|none|The customer's name. This will only set the name for *new* customers.|
|phone|[PhoneNumber](#schemaphonenumber)|false|none|The customer's phone number. This will only set the phone number for *new* customers.|
|default|boolean|false|none|If true, this instrument will become the default for the customer. If a *new* customer is created as a result of this request, the instrument will automatically be the default.|
StoreInstrumentRequest
```json
{
"type": "bank_account",
"account_type": "savings",
"account_number": "13654567455",
"bank_code": "123-456",
"branch_code": "6443",
"iban": "HU93116000060000000012345676",
"bban": "3704 0044 0532 0130 00",
"swift_bic": "37040044",
"currency": "GBP",
"country": "GB",
"processing_channel_id": "pc_u2l6xz5joigedmk7g5vxzt7rqy",
"account_holder": {
"type": "individual",
"first_name": "John",
"last_name": "Smith",
"tax_id": "123456",
"date_of_birth": "1986-01-01",
"country_of_birth": "GB",
"residential_status": "resident",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"identification": {
"type": "SSN",
"issuing_country": "string",
"number": "string"
}
},
"bank": {
"name": "Lloyds TSB",
"branch": "Bournemouth",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "brucewayne@gmail.com",
"name": "Bruce Wayne",
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"default": true
}
}
```
The type of instrument to be stored
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[StoreBankAccountInstrumentRequest](#schemastorebankaccountinstrumentrequest)|false|none|Store bank account details|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[StoreCardInstrumentRequest](#schemastorecardinstrumentrequest)|false|none|Details of the token to store.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[StoreTokenInstrumentRequest](#schemastoretokeninstrumentrequest)|false|none|Store token details|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[StoreSepaInstrumentRequest](#schemastoresepainstrumentrequest)|false|none|Store bank account details|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[StoreAchInstrumentRequest](#schemastoreachinstrumentrequest)|false|none|Store bank account details|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[StoreBacsInstrumentRequest](#schemastorebacsinstrumentrequest)|false|none|Store Bacs Direct Debit account details|
StoreInstrumentRequestType
```json
"bacs"
```
Ordered list of store instrument request types used for discriminators
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|Ordered list of store instrument request types used for discriminators|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|bacs|
|*anonymous*|bank_account|
|*anonymous*|card|
|*anonymous*|token|
|*anonymous*|sepa|
|*anonymous*|ach|
StoreInstrumentResponse
```json
{
"type": "bank_account",
"id": "src_wmlfc3zyhqzehihu7giusaaawu",
"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "johnsmith@example.com",
"name": "John Smith",
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"summary": {
"registration_date": "2023-05-01",
"first_transaction_date": "2023-07-01",
"last_payment_date": "2023-08-01",
"total_order_count": 15,
"last_payment_amount": 500,
"is_premium_customer": true,
"is_returning_customer": true,
"lifetime_value": 500
}
},
"bank": {
"name": "Lloyds TSB",
"branch": "Bournemouth",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"swift_bic": "37040044",
"account_number": "13654567455",
"bank_code": "123-456",
"iban": "HU93116000060000000012345676"
}
```
The response for type of instrument stored
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of instrument|
|id|string|true|none|The unique identifier of the payment source or destination that can be used later for payments|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[StoreBankAccountInstrumentResponse](#schemastorebankaccountinstrumentresponse)|false|none|Store bank account instrument response|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[StoreTokenInstrumentResponse](#schemastoretokeninstrumentresponse)|false|none|card instrument response|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[StoreSepaInstrumentResponse](#schemastoresepainstrumentresponse)|false|none|Store bank account instrument response|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[StoreAchInstrumentResponse](#schemastoreachinstrumentresponse)|false|none|Store bank account instrument response|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[StoreBacsInstrumentResponse](#schemastorebacsinstrumentresponse)|false|none|Store Bacs Direct Debit account instrument response|
StoreSepaInstrumentRequest
```json
{
"type": "sepa",
"instrument_data": {
"type": "B2B",
"account_number": "FR2810096000509685512959O86",
"country": "GB",
"currency": "GBP",
"payment_type": "recurring",
"mandate_id": "1234567890",
"date_of_signature": "2020-01-01"
},
"account_holder": {
"first_name": "John",
"last_name": "Smith",
"billing_address": {
"address_line1": "Cloverfield St.",
"address_line2": "23A",
"city": "London",
"zip": "SW1A 1AA",
"country": "GB"
},
"company_name": "string",
"type": "corporate"
},
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "brucewayne@gmail.com",
"name": "Bruce Wayne",
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"default": true
}
}
```
sepa
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|false|none|The type of instrument. `sepa` payment instruments.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[StoreInstrumentRequestType](#schemastoreinstrumentrequesttype)|false|none|Ordered list of store instrument request types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|instrument_data|object|true|none|The details of the mandate|
|» type|string|false|none|The type of mandate.|
|» account_number|string|true|none|The International Bank Account Number (IBAN) of the account.|
|» country|string|true|none|The country of the account.|
|» currency|string|true|none|The currency of the account.|
|» payment_type|string|true|none|The type of payment. `recurring` or `regular`.|
|» mandate_id|string|false|none|The mandate ID. If a mandate ID is not provided, a new, random mandate ID will be generated.|
|» date_of_signature|string(date)|false|none|The date on which the mandate was signed, in the format 'yyyy-MM-dd'.
Required if `mandate_id` is provided.
Ignored and set as the current date if `mandate_id` is not provided.|
|account_holder|object|true|none|The account holder details|
|» first_name|string|true|none|The first name of the account holder|
|» last_name|string|true|none|The last name of the account holder|
|» billing_address|object|true|none|The billing address of the account holder|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|string|true|none|The street number. If no number, pass "w/n".|
|»» city|string|true|none|The address city.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string|true|none|The two-letter ISO country code of the address.|
|» company_name|string|false|none|The legal name of a registered company that holds the account.|
|» type|string|false|none|The type of account holder.|
|customer|[StoreCustomerInstrumentRequest](#schemastorecustomerinstrumentrequest)|false|none|The customer's details|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|sepa|
|type|Core|
|type|B2B|
|payment_type|recurring|
|payment_type|regular|
|type|individual|
|type|corporate|
StoreSepaInstrumentResponse
```json
{
"type": "sepa",
"id": "src_wmlfc3zyhqzehihu7giusaaawu",
"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q"
}
```
sepa
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of instrument|
|id|string|true|none|The unique identifier of the payment source or destination that can be used later for payments|
|fingerprint|string|true|none|A token that can uniquely identify this instrument across all customers|
#### Enumerated Values
|Property|Value|
|---|---|
|type|sepa|
StoreTokenInstrumentRequest
```json
{
"type": "token",
"token": "tok_asoto22g2fsu7prwomy12sgfsa",
"account_holder": {
"first_name": "John",
"last_name": "Smith",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "brucewayne@gmail.com",
"name": "Bruce Wayne",
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"default": true
}
}
```
token
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The type of instrument|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[StoreInstrumentRequestType](#schemastoreinstrumentrequesttype)|false|none|Ordered list of store instrument request types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|token|string|true|none|The Checkout.com token|
|account_holder|[StoreAccountHolderTokenRequest](#schemastoreaccountholdertokenrequest)|false|none|The account holder details|
|customer|[StoreCustomerInstrumentRequest](#schemastorecustomerinstrumentrequest)|false|none|The customer's details|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|token|
StoreTokenInstrumentResponse
```json
{
"type": "card",
"id": "src_wmlfc3zyhqzehihu7giusaaawu",
"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
"expiry_month": 6,
"expiry_year": 2025,
"scheme": "VISA",
"scheme_local": "cartes_bancaires",
"last4": "9996",
"bin": "454347",
"card_type": "CREDIT",
"card_category": "CONSUMER",
"issuer": "GOTHAM STATE BANK",
"issuer_country": "US",
"product_id": "F",
"product_type": "CLASSIC",
"account_holder": {
"first_name": "Hannah",
"last_name": "Bret",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "johnsmith@example.com",
"name": "John Smith",
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"summary": {
"registration_date": "2023-05-01",
"first_transaction_date": "2023-07-01",
"last_payment_date": "2023-08-01",
"total_order_count": 15,
"last_payment_amount": 500,
"is_premium_customer": true,
"is_returning_customer": true,
"lifetime_value": 500
}
},
"network_token": {
"id": "nt_y3oqhf46pyzuxjbcn2giaqnb44",
"state": "active"
}
}
```
card
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of instrument|
|id|string|true|none|The unique identifier of the payment source or destination that can be used later for payments|
|fingerprint|string|true|none|A token that can uniquely identify this instrument across all customers|
|expiry_month|integer|true|none|The expiry month|
|expiry_year|integer|true|none|The expiry year|
|scheme|string|false|none|The card scheme|
|scheme_local|string|false|none|The local co-branded card scheme|
|last4|string|true|none|The last four digits of the card number|
|bin|string|true|none|The card issuer's bank identification number (BIN)|
|card_type|string|false|none|The card type|
|card_category|string|false|none|The card category|
|issuer|string|false|none|The name of the card issuer|
|issuer_country|string|false|none|The card issuer's country (two-letter ISO code)|
|product_id|string|false|none|The issuer/card scheme product identifier|
|product_type|string|false|none|The issuer/card scheme product type|
|account_holder|[AccountHolderResponse](#schemaaccountholderresponse)|false|none|The account holder details|
|customer|[CustomerResponse](#schemacustomerresponse)|false|none|Stored customer details|
|network_token|[NetworkToken](#schemanetworktoken)|false|none|Network token details|
#### Enumerated Values
|Property|Value|
|---|---|
|type|card|
|scheme_local|cartes_bancaires|
|card_type|CREDIT|
|card_type|DEBIT|
|card_type|PREPAID|
|card_type|CHARGE|
|card_category|CONSUMER|
|card_category|COMMERCIAL|
UpdateAchInstrumentRequest
```json
{
"type": "string",
"instrument_data": {
"account_type": "savings",
"account_number": "4099999992",
"bank_code": "211370545",
"currency": "USD",
"country": "US"
},
"account_holder": {
"first_name": "John",
"last_name": "Smith",
"company_name": "Smith Enterprises",
"type": "individual"
}
}
```
ach
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|false|none|The type of instrument. `ach` payment instruments.|
|instrument_data|object|false|none|The details of the bank account|
|» account_type|string|false|none|The type of Direct Debit account|
|» account_number|string|false|none|The account number of the Direct Debit account|
|» bank_code|string|false|none|The bank code of the Direct Debit account|
|» currency|string|false|none|The currency of the account|
|» country|string|false|none|The country of the account|
|account_holder|object|false|none|The account holder details|
|» first_name|string|true|none|First name. Required for individual account holder type|
|» last_name|string|true|none|Last name. Required for individual account holder type|
|» company_name|string|true|none|Company name. Required for corporate account holder type|
|» type|string|true|none|Account holder type|
#### Enumerated Values
|Property|Value|
|---|---|
|account_type|savings|
|account_type|checking|
|type|individual|
|type|corporate|
UpdateAchInstrumentResponse
```json
{
"type": "ach",
"id": "src_wmlfc3zyhqzehihu7giusaaawu",
"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q"
}
```
ach
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The underlying instrument type. For instruments created from Checkout.com tokens, this will reflect the type of instrument that was tokenized.|
|id|string|true|none|The unique identifier of the payment source or destination that can be used later for payments|
|fingerprint|string|true|none|A token that can uniquely identify this instrument across all customers|
#### Enumerated Values
|Property|Value|
|---|---|
|type|ach|
UpdateBacsInstrumentRequest
```json
{
"type": "string",
"instrument_data": {
"account_number": "86753246",
"bank_code": "040004",
"country": "GB",
"currency": "GBP",
"payment_type": "Recurring",
"allow_partial_match": true
},
"account_holder": {
"first_name": "John",
"last_name": "Smith",
"company_name": "string",
"billing_address": {
"address_line1": "Cloverfield St.",
"address_line2": "23A",
"city": "London",
"zip": "SW1A 1AA",
"country": "GB"
},
"type": "corporate"
}
}
```
bacs
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|false|none|The type of instrument. `bacs` payment instruments.|
|instrument_data|object|false|none|The details of the Bacs Direct Debit account.|
|» account_number|string|false|none|The account number of the Bacs Direct Debit account.|
|» bank_code|string|false|none|The sort code of the Bacs Direct Debit account.|
|» country|string|false|none|The country of the account, as an ISO 3166-1 alpha-2 code.|
|» currency|string|false|none|The currency of the account.|
|» payment_type|string|false|none|The type of payment. `Recurring` or `Regular`.|
|» allow_partial_match|boolean|false|none|Whether vault accepted a partial match when looking up the Bacs instrument for the supplied account details.|
|account_holder|object|false|none|The account holder details|
|» first_name|string|false|none|The first name of the account holder|
|» last_name|string|false|none|The last name of the account holder|
|» company_name|string|false|none|The legal name of a registered company that holds the account.|
|» billing_address|object|false|none|The billing address of the account holder|
|»» address_line1|string|false|none|The first line of the address.|
|»» address_line2|string|false|none|The street number. If no number, pass "w/n".|
|»» city|string|false|none|The address city.|
|»» zip|string|false|none|The address zip/postal code.|
|»» country|string|false|none|The two-letter ISO country code of the address.|
|» type|string|false|none|The type of account holder.|
#### Enumerated Values
|Property|Value|
|---|---|
|payment_type|Recurring|
|payment_type|Regular|
|type|individual|
|type|corporate|
UpdateBacsInstrumentResponse
```json
{
"type": "bacs",
"id": "src_wmlfc3zyhqzehihu7giusaaawu",
"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q"
}
```
bacs
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The underlying instrument type. For instruments created from Checkout.com tokens, this will reflect the type of instrument that was tokenized.|
|id|string|true|none|The unique identifier of the payment source or destination that can be used later for payments|
|fingerprint|string|true|none|A token that can uniquely identify this instrument across all customers|
#### Enumerated Values
|Property|Value|
|---|---|
|type|bacs|
UpdateBankInstrumentRequest
```json
{
"type": "string",
"account_type": "savings",
"account_number": "13654567455",
"bank_code": "123-456",
"branch_code": "6443",
"iban": "HU93116000060000000012345676",
"bban": "3704 0044 0532 0130 00",
"swift_bic": "37040044",
"currency": "GBP",
"country": "GB",
"processing_channel_id": "pc_u2l6xz5joigedmk7g5vxzt7rqy",
"account_holder": {
"type": "individual",
"first_name": "John",
"last_name": "Smith",
"tax_id": "123456",
"date_of_birth": "1986-01-01",
"country_of_birth": "GB",
"residential_status": "resident",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"identification": {
"type": "SSN",
"issuing_country": "string",
"number": "string"
}
},
"bank": {
"name": "Lloyds TSB",
"branch": "Bournemouth",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"default": true
}
}
```
bank_account
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|false|none|The type of instrument. `bank_account` payment instruments.|
|account_type|string|false|none|The type of account|
|account_number|string|false|none|Number (which can contain letters) that identifies the account|
|bank_code|string|false|none|Code that identifies the bank|
|branch_code|string|false|none|Code that identifies the bank branch|
|iban|string|false|none|Internationally agreed standard for identifying bank account|
|bban|string|false|none|The combination of bank code and/or branch code and account number|
|swift_bic|string|false|none|8 or 11 character code which identifies the bank or bank branch|
|currency|string|false|none|The three-letter ISO currency code of the account's currency|
|country|string|false|none|The two-letter ISO country code of where the account is based|
|processing_channel_id|string|false|none|The ID of the primary processing channel this instrument is intended to be used for|
|account_holder|[AccountHolder](#schemaaccountholder)|false|none|The bank account holder details. Having accurate and complete data improves payout performance (increases success rate and the prevents delays).|
|bank|[BankDetails](#schemabankdetails)|false|none|Details of the bank|
|customer|[UpdateCustomerRequest](#schemaupdatecustomerrequest)|false|none|The customer's details|
#### Enumerated Values
|Property|Value|
|---|---|
|account_type|savings|
|account_type|current|
|account_type|cash|
UpdateBankInstrumentResponse
```json
{
"type": "bank_account",
"fingerprint": "smoua2sbuqhupeofwbe77n5nsm"
}
```
bank_account
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of instrument|
|fingerprint|string|true|none|A token that can uniquely identify this instrument across all customers|
#### Enumerated Values
|Property|Value|
|---|---|
|type|bank_account|
UpdateCardInstrumentRequest
```json
{
"type": "string",
"expiry_month": 6,
"expiry_year": 2025,
"name": "Mr. J Smith",
"account_holder": {
"first_name": "John",
"last_name": "Smith",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"default": true
}
}
```
card
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|false|none|The type of instrument. `card` payment instruments.|
|expiry_month|integer|false|none|The expiry month of the card|
|expiry_year|integer|false|none|The expiry year of the card|
|name|string|false|none|Name of the cardholder|
|account_holder|[UpdateCardAccountHolder](#schemaupdatecardaccountholder)|false|none|The account holder details|
|customer|[UpdateCustomerRequest](#schemaupdatecustomerrequest)|false|none|The customer's details|
UpdateCardInstrumentResponse
```json
{
"type": "card",
"fingerprint": "smoua2sbuqhupeofwbe77n5nsm"
}
```
card
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of instrument|
|fingerprint|string|true|none|A token that can uniquely identify this instrument across all customers|
#### Enumerated Values
|Property|Value|
|---|---|
|type|card|
UpdateInstrumentRequest
```json
{
"type": "string",
"expiry_month": 6,
"expiry_year": 2025,
"name": "Mr. J Smith",
"account_holder": {
"first_name": "John",
"last_name": "Smith",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"default": true
}
}
```
The type of instrument to be updated
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[UpdateCardInstrumentRequest](#schemaupdatecardinstrumentrequest)|false|none|Update bank account details|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[UpdateBankInstrumentRequest](#schemaupdatebankinstrumentrequest)|false|none|Update bank account details|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[UpdateSepaInstrumentRequest](#schemaupdatesepainstrumentrequest)|false|none|Update bank account details|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[UpdateAchInstrumentRequest](#schemaupdateachinstrumentrequest)|false|none|Update bank account details|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[UpdateBacsInstrumentRequest](#schemaupdatebacsinstrumentrequest)|false|none|Update Bacs Direct Debit account details|
UpdateInstrumentResponse
```json
{
"type": "card",
"fingerprint": "smoua2sbuqhupeofwbe77n5nsm"
}
```
The response for type of instrument stored
### Properties
oneOf - discriminator: UpdateCardInstrumentResponse.type
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[UpdateCardInstrumentResponse](#schemaupdatecardinstrumentresponse)|false|none|The response for type of instrument stored|
xor - discriminator: UpdateBankInstrumentResponse.type
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[UpdateBankInstrumentResponse](#schemaupdatebankinstrumentresponse)|false|none|The response for type of instrument stored|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[UpdateSepaInstrumentResponse](#schemaupdatesepainstrumentresponse)|false|none|Update bank account instrument response|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[UpdateAchInstrumentResponse](#schemaupdateachinstrumentresponse)|false|none|Update bank account instrument response|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[UpdateBacsInstrumentResponse](#schemaupdatebacsinstrumentresponse)|false|none|Update Bacs Direct Debit account instrument response|
UpdateSepaInstrumentRequest
```json
{
"type": "string",
"instrument_data": {
"type": "B2B",
"account_number": "FR2810096000509685512959O86",
"country": "GB",
"currency": "GBP",
"payment_type": "recurring",
"mandate_id": "1234567890",
"date_of_signature": "2020-01-01"
},
"account_holder": {
"first_name": "John",
"last_name": "Smith",
"billing_address": {
"address_line1": "Cloverfield St.",
"address_line2": "23A",
"city": "London",
"zip": "SW1A 1AA",
"country": "GB"
},
"company_name": "string",
"type": "corporate"
}
}
```
sepa
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|false|none|The type of instrument. `sepa` payment instruments.|
|instrument_data|object|false|none|The details of the mandate|
|» type|string|false|none|The type of mandate.|
|» account_number|string|true|none|The International Bank Account Number (IBAN) of the account.|
|» country|string|true|none|The country of the account.|
|» currency|string|true|none|The currency of the account.|
|» payment_type|string|true|none|The type of payment. `recurring` or `regular`.|
|» mandate_id|string|false|none|The mandate ID. If a mandate ID is not provided, a new, random mandate ID will be generated.|
|» date_of_signature|string(date)|false|none|The date on which the mandate was signed, in the format 'yyyy-MM-dd'.
Required if `mandate_id` is provided.
Ignored and set as the current date if `mandate_id` is not provided.|
|account_holder|object|false|none|The account holder details|
|» first_name|string|true|none|The first name of the account holder|
|» last_name|string|true|none|The last name of the account holder|
|» billing_address|object|true|none|The billing address of the account holder|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|string|true|none|The street number. If no number, pass "w/n".|
|»» city|string|true|none|The address city.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string|true|none|The two-letter ISO country code of the address.|
|» company_name|string|false|none|The legal name of a registered company that holds the account.|
|» type|string|false|none|The type of account holder.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|Core|
|type|B2B|
|payment_type|recurring|
|payment_type|regular|
|type|individual|
|type|corporate|
UpdateSepaInstrumentResponse
```json
{
"type": "sepa",
"id": "src_wmlfc3zyhqzehihu7giusaaawu",
"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q"
}
```
sepa
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The underlying instrument type. For instruments created from Checkout.com tokens, this will reflect the type of instrument that was tokenized.|
|id|string|true|none|The unique identifier of the payment source or destination that can be used later for payments|
|fingerprint|string|true|none|A token that can uniquely identify this instrument across all customers|
#### Enumerated Values
|Property|Value|
|---|---|
|type|sepa|
IPAddress
```json
"90.197.169.245"
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string(ipv4)|false|none|none|
add-cardholder-request
```json
{
"type": "individual",
"reference": "X-123456-N11",
"entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"first_name": "John",
"middle_name": "Fitzgerald",
"last_name": "Kennedy",
"email": "john.kennedy@myemaildomain.com",
"phone_number": {
"country_code": "+1",
"number": "415 555 2671"
},
"date_of_birth": "1985-05-15",
"billing_address": {
"address_line1": "Checkout.com",
"address_line2": "90 Tottenham Court Road",
"city": "London",
"state": "London",
"zip": "W1T 4TJ",
"country": "GB"
},
"residency_address": {
"address_line1": "Checkout.com",
"address_line2": "90 Tottenham Court Road",
"city": "London",
"state": "London",
"zip": "W1T 4TJ",
"country": "GB"
}
}
```
The cardholder to create.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of cardholder to create.|
|reference|[IssuingReference](#schemaissuingreference)|false|none|Your reference.|
|entity_id|[IssuingEntityId](#schemaissuingentityid)|true|none|The entity's unique identifier.|
add-cardholder-response
```json
{
"id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
"client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
"entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"type": "individual",
"status": "active",
"reference": "X-123456-N11",
"created_date": "2019-08-24T14:15:22Z",
"last_modified_date": "2019-09-10T10:11:12Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cardholders/crh_d3ozhf43pcq2xbldn2g45qnb44",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"cards": {
"href": "https://{prefix}.api.checkout.com/issuing/cards",
"actions": [
"POST"
],
"types": [
"application/json"
]
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingCardholderId](#schemaissuingcardholderid)|true|none|The cardholder's unique identifier.|
|client_id|[IssuingClientId](#schemaissuingclientid)|true|none|The client's unique identifier.|
|entity_id|[IssuingEntityId](#schemaissuingentityid)|true|none|The entity's unique identifier.|
|type|string|true|none|The cardholder's type.|
|status|string|true|none|The cardholder's status, after creation.|
|reference|[IssuingReference](#schemaissuingreference)|false|none|Your reference.|
|created_date|string(date-time)|false|none|none|
|last_modified_date|string(date-time)|false|none|none|
|_links|[IssuingCardholderLinks](#schemaissuingcardholderlinks)|true|none|The links related to the current cardholder.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|individual|
|status|active|
|status|pending|
|status|restricted|
|status|requirements_due|
|status|inactive|
|status|rejected|
add-individual-cardholder-request
```json
{
"type": "individual",
"reference": "X-123456-N11",
"entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"first_name": "John",
"middle_name": "Fitzgerald",
"last_name": "Kennedy",
"email": "john.kennedy@myemaildomain.com",
"phone_number": {
"country_code": "+1",
"number": "415 555 2671"
},
"date_of_birth": "1985-05-15",
"billing_address": {
"address_line1": "Checkout.com",
"address_line2": "90 Tottenham Court Road",
"city": "London",
"state": "London",
"zip": "W1T 4TJ",
"country": "GB"
},
"residency_address": {
"address_line1": "Checkout.com",
"address_line2": "90 Tottenham Court Road",
"city": "London",
"state": "London",
"zip": "W1T 4TJ",
"country": "GB"
}
}
```
individual
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of cardholder to create.|
|reference|[IssuingReference](#schemaissuingreference)|false|none|Your reference.|
|entity_id|[IssuingEntityId](#schemaissuingentityid)|true|none|The entity's unique identifier.|
|first_name|string|true|none|The cardholder's first name.|
|middle_name|string|false|none|The cardholder's middle name.|
|last_name|string|true|none|The cardholder's last name.|
|email|[IssuingEmail](#schemaissuingemail)|false|none|The cardholder's email address.|
|phone_number|[IssuingPhoneNumber](#schemaissuingphonenumber)|false|none|The cardholder's mobile phone number. This is used in the card tokenization one-time passcode (OTP) challenge flow and in delivery details for physical cards.|
|date_of_birth|string(date)|false|none|The cardholder's date of birth.
Format – `YYYY-MM-DD`|
|billing_address|[IssuingAddress](#schemaissuingaddress)|true|none|The cardholder's billing address.|
|residency_address|[IssuingAddress](#schemaissuingaddress)|false|none|The cardholder's residential address. If this value is not provided, the cardholder's billing address is used instead, by default.|
get-cardholder-response
```json
{
"id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
"type": "individual",
"first_name": "John",
"middle_name": "Fitzgerald",
"last_name": "Kennedy",
"email": "john.kennedy@myemaildomain.com",
"phone_number": {
"country_code": "+1",
"number": "415 555 2671"
},
"date_of_birth": "1985-05-28",
"billing_address": {
"address_line1": "Checkout.com",
"address_line2": "90 Tottenham Court Road",
"city": "London",
"state": "London",
"zip": "W1T 4TJ",
"country": "GB"
},
"residency_address": {
"address_line1": "Checkout.com",
"address_line2": "90 Tottenham Court Road",
"city": "London",
"state": "London",
"zip": "W1T 4TJ",
"country": "GB"
},
"reference": "X-123456-N11",
"client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
"account_entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"parent_sub_entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"status": "active",
"created_date": "2019-09-10T10:11:12Z",
"last_modified_date": "2019-09-11T10:11:12Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cardholders/crh_d3ozhf43pcq2xbldn2g45qnb44",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"cards": {
"href": "https://{prefix}.api.checkout.com/issuing/cards",
"actions": [
"POST"
],
"types": [
"application/json"
]
}
}
}
```
### Properties
*None*
IssuingCardholder
```json
{
"id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
"type": "individual",
"first_name": "John",
"middle_name": "Fitzgerald",
"last_name": "Kennedy",
"email": "john.kennedy@myemaildomain.com",
"phone_number": {
"country_code": "+1",
"number": "415 555 2671"
},
"date_of_birth": "1985-05-28",
"billing_address": {
"address_line1": "Checkout.com",
"address_line2": "90 Tottenham Court Road",
"city": "London",
"state": "London",
"zip": "W1T 4TJ",
"country": "GB"
},
"residency_address": {
"address_line1": "Checkout.com",
"address_line2": "90 Tottenham Court Road",
"city": "London",
"state": "London",
"zip": "W1T 4TJ",
"country": "GB"
},
"reference": "X-123456-N11",
"client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
"account_entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"parent_sub_entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"status": "active",
"created_date": "2019-09-10T10:11:12Z",
"last_modified_date": "2019-09-11T10:11:12Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cardholders/crh_d3ozhf43pcq2xbldn2g45qnb44",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"cards": {
"href": "https://{prefix}.api.checkout.com/issuing/cards",
"actions": [
"POST"
],
"types": [
"application/json"
]
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingCardholderId](#schemaissuingcardholderid)|true|none|The cardholder's unique identifier.|
|type|string|true|none|The cardholder type. Currently `individual` is the only supported value.|
|first_name|string|true|none|The cardholder's first name.|
|middle_name|string|false|none|The cardholder's middle name.|
|last_name|string|true|none|The cardholder's last name.|
|email|[IssuingEmail](#schemaissuingemail)|false|none|The cardholder's email address.|
|phone_number|[IssuingPhoneNumber](#schemaissuingphonenumber)|false|none|The cardholder's mobile phone number. This is used in the card tokenization one-time passcode (OTP) challenge flow and in delivery details for physical cards.|
|date_of_birth|string(date)|false|none|The cardholder's date of birth.
Format – `YYYY-MM-DD`|
|billing_address|[IssuingAddress](#schemaissuingaddress)|true|none|The cardholder's billing address.|
|residency_address|[IssuingAddress](#schemaissuingaddress)|false|none|The cardholder's residential address. If this value is not provided, the cardholder's billing address is used instead, by default.|
|reference|[IssuingReference](#schemaissuingreference)|false|none|Your reference.|
|client_id|[IssuingClientId](#schemaissuingclientid)|true|none|The client's unique identifier.|
|account_entity_id|[IssuingEntityId](#schemaissuingentityid)|false|none|The unique identifier of the entity that holds the cardholder's currency account.|
|parent_sub_entity_id|[IssuingEntityId](#schemaissuingentityid)|false|none|The unique identifier of the cardholder's parent sub-entity, if they have one.|
|entity_id|[IssuingEntityId](#schemaissuingentityid)|true|none|The unique identifier of the cardholder's root client entity.|
|status|string|false|none|The cardholder's status.|
|created_date|string(date-time)|false|none|none|
|last_modified_date|string(date-time)|false|none|none|
|_links|[IssuingCardholderLinks](#schemaissuingcardholderlinks)|false|none|The links related to the current cardholder.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|active|
|status|pending|
|status|restricted|
|status|requirements_due|
|status|inactive|
|status|rejected|
|status|draft|
|status|suspended|
IssuingCardholderLinks
```json
{
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cardholders/crh_d3ozhf43pcq2xbldn2g45qnb44",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"cards": {
"href": "https://{prefix}.api.checkout.com/issuing/cards",
"actions": [
"POST"
],
"types": [
"application/json"
]
}
}
```
The links related to the current cardholder.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|self|[IssuingLink](#schemaissuinglink)|true|none|The URI to retrieve the cardholder|
|cards|[IssuingLink](#schemaissuinglink)|false|none|The URI to add or retrieve the cards issued to the cardholder|
IssuingUpdateCardholderLinks
```json
{
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cardholders/crh_d3ozhf43pcq2xbldn2g45qnb44",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
```
The links related to the current cardholder.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|self|[IssuingLink](#schemaissuinglink)|true|none|none|
update-cardholder-request
```json
{
"first_name": "John",
"middle_name": "Fitzgerald",
"last_name": "Kennedy",
"date_of_birth": "1985-05-15",
"phone_number": {
"country_code": "+1",
"number": "415 555 2671"
},
"email": "john.kennedy@myemaildomain.com",
"billing_address": {
"address_line1": "Checkout.com",
"address_line2": "90 Tottenham Court Road",
"city": "London",
"state": "London",
"zip": "W1T 4TJ",
"country": "GB"
},
"residency_address": {
"address_line1": "Checkout.com",
"address_line2": "90 Tottenham Court Road",
"city": "London",
"state": "London",
"zip": "W1T 4TJ",
"country": "GB"
}
}
```
The cardholder's fields to update.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|first_name|string|false|none|The cardholder's first name.|
|middle_name|string|false|none|The cardholder's middle name. To set this field to null, pass `null` in your request.|
|last_name|string|false|none|The cardholder's last name.|
|date_of_birth|string(date)|false|none|The cardholder's date of birth in the YYYY-MM-DD format. To set this field to null, pass `null` in your request.|
|phone_number|[IssuingPhoneNumber](#schemaissuingphonenumber)|false|none|The cardholder's mobile phone number. This is used in the card tokenization one-time passcode (OTP) challenge flow and in delivery details for physical cards.|
|email|[IssuingEmail](#schemaissuingemail)|false|none|The cardholder's email address. To set this field to null, pass `null` in your request.|
|billing_address|[IssuingAddress](#schemaissuingaddress)|false|none|The cardholder's billing address.|
|residency_address|[IssuingAddress](#schemaissuingaddress)|false|none|The cardholder's residency address. To set this field to null, pass `null` in your request.|
update-cardholder-response
```json
{
"last_modified_date": "2019-09-10T10:11:12Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cardholders/crh_d3ozhf43pcq2xbldn2g45qnb44",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|last_modified_date|string(date-time)|true|none|none|
|_links|[IssuingUpdateCardholderLinks](#schemaissuingupdatecardholderlinks)|true|none|The links related to the current cardholder.|
3ds-enrollment-get-response
```json
{
"locale": "en-US",
"phone_number": {
"country_code": "+1",
"number": "415 555 2671"
},
"security_question": {
"question": "****",
"answer": "****"
},
"password": "string",
"created_date": "2019-09-10T10:11:12Z",
"last_modified_date": "2019-09-11T10:11:12Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/3ds-enrollment",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}
```
The card's 3DS enrollment details.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|locale|[3dsLocale](#schema3dslocale)|true|none|The card's locale, as one of the possible BCP 47 formatted enum values.
The locale determines the language that text messages and 3DS challenge prompts are displayed to the user in, as well as the format used for amounts and dates.
When not provided, the locale of the card product is used.|
|phone_number|[3dsPhoneNumber](#schema3dsphonenumber)|true|none|The phone number to send the one-time password (OTP) for 3DS authentication to.
This phone number is independent of the cardholder's mobile phone number on file.
The number is used for authorizations that require a 3DS challenge.|
|security_question|object|false|none|Obfuscated security question and answer, indicating that this card was enrolled using this method.|
|» question|string|false|none|none|
|» answer|string|false|none|none|
|password|string|false|none|Obfuscated password, indicating that this card was enrolled using this method.|
|created_date|string(date-time)|true|none|none|
|last_modified_date|string(date-time)|true|none|none|
|_links|[3dsLink](#schema3dslink)|false|none|The link to the card's 3DS enrollment details.|
3ds-enrollment-patch-response
```json
{
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/3ds-enrollment",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}
```
The card's 3DS authentication details.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|_links|[3dsLink](#schema3dslink)|false|none|The link to the card's 3DS enrollment details.|
3ds-enrollment-post-response
```json
{
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/3ds-enrollment",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}
```
The card's 3DS authentication details.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|_links|[3dsLink](#schema3dslink)|false|none|The link to the card's 3DS enrollment details.|
3dsLink
```json
{
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/3ds-enrollment",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
```
The link to the card's 3DS enrollment details.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|self|[IssuingLink](#schemaissuinglink)|true|none|The URI to retrieve the card's 3DS enrollment details.|
3dsLocale
```json
"en-US"
```
The card's locale, as one of the possible BCP 47 formatted enum values.
The locale determines the language that text messages and 3DS challenge prompts are displayed to the user in, as well as the format used for amounts and dates.
When not provided, the locale of the card product is used.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string(language-COUNTRY)|false|none|The card's locale, as one of the possible BCP 47 formatted enum values.
The locale determines the language that text messages and 3DS challenge prompts are displayed to the user in, as well as the format used for amounts and dates.
When not provided, the locale of the card product is used.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|en-US|
|*anonymous*|fr-FR|
3dsPassword
```json
"Xtui43FvfiZ"
```
The case-sensitive password used to support knowledge-based 3DS authentication.
Leading and trailing white spaces will be ignored.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The case-sensitive password used to support knowledge-based 3DS authentication.
Leading and trailing white spaces will be ignored.|
3dsPhoneNumber
```json
{
"country_code": "+1",
"number": "415 555 2671"
}
```
The phone number to send the one-time password (OTP) for 3DS authentication to.
This phone number is independent of the cardholder's mobile phone number on file.
The number is used for authorizations that require a 3DS challenge.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|country_code|string|true|none|The phone number's international country calling code.|
|number|string|true|none|A valid phone number without leading zeros.|
3dsSecurityPair
```json
{
"question": "Who are you?",
"answer": "Bond. James Bond."
}
```
The question and answer security pair used to support knowledge-based 3DS authentication.
Security pairs are set per-card, not per-cardholder.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|question|string|true|none|The cardholder’s security question.|
|answer|string|true|none|The cardholder’s answer to the security question.
The answer is not case-sensitive. Leading and trailing white spaces will be ignored.|
Password
```json
{
"password": "Xtui43FvfiZ",
"locale": "en-US",
"phone_number": {
"country_code": "+1",
"number": "415 555 2671"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|password|[3dsPassword](#schema3dspassword)|true|none|The case-sensitive password used to support knowledge-based 3DS authentication.
Leading and trailing white spaces will be ignored.|
|locale|[3dsLocale](#schema3dslocale)|false|none|The card's locale, as one of the possible BCP 47 formatted enum values.
The locale determines the language that text messages and 3DS challenge prompts are displayed to the user in, as well as the format used for amounts and dates.
When not provided, the locale of the card product is used.|
|phone_number|[3dsPhoneNumber](#schema3dsphonenumber)|true|none|The phone number to send the one-time password (OTP) for 3DS authentication to.
This phone number is independent of the cardholder's mobile phone number on file.
The number is used for authorizations that require a 3DS challenge.|
security_question
```json
{
"security_pair": {
"question": "Who are you?",
"answer": "Bond. James Bond."
},
"locale": "en-US",
"phone_number": {
"country_code": "+1",
"number": "415 555 2671"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|security_pair|[3dsSecurityPair](#schema3dssecuritypair)|true|none|The question and answer security pair used to support knowledge-based 3DS authentication.
Security pairs are set per-card, not per-cardholder.|
|locale|[3dsLocale](#schema3dslocale)|false|none|The card's locale, as one of the possible BCP 47 formatted enum values.
The locale determines the language that text messages and 3DS challenge prompts are displayed to the user in, as well as the format used for amounts and dates.
When not provided, the locale of the card product is used.|
|phone_number|[3dsPhoneNumber](#schema3dsphonenumber)|true|none|The phone number to send the one-time password (OTP) for 3DS authentication to.
This phone number is independent of the cardholder's mobile phone number on file.
The number is used for authorizations that require a 3DS challenge.|
activate-card-response
```json
{
"last_activated_on": "2019-09-10T10:11:12Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"revoke": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/revoke",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"suspend": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/suspend",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"controls": {
"href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|last_activated_on|string(date-time)|true|read-only|The time the card was activated.|
|_links|[ActivatedCardLinks](#schemaactivatedcardlinks)|false|none|The links related to the card.|
add-card-request
```json
{
"type": "virtual",
"cardholder_id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
"lifetime": {
"unit": "Months",
"value": 6
},
"reference": "X-123456-N11",
"metadata": {
"udf1": "metadata1",
"udf2": "metadata2",
"udf3": "metadata3",
"udf4": "metadata4",
"udf5": "metadata5"
},
"scheduled_revocation_date": "2027-03-12",
"revocation_date": "2027-03-12",
"scheduled_activation_date": "2026-06-01T10:00Z",
"card_product_id": "pro_7syjig3jq3mezlc3vjrdpfitl4"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The card type.|
|cardholder_id|[IssuingCardholderId](#schemaissuingcardholderid)|true|none|The cardholder's unique identifier.|
|lifetime|[CardLifetime](#schemacardlifetime)|false|none|The duration of time during which the card will accept incoming authorizations.
The `unit` and `value` combination you supply will determine the card's expiry date from the date of issue. For example, to set the card to expire in a year and a half, pass the following:
```
{
"lifetime": {
"unit": "Months",
"value": "18"
}
}
```|
|reference|[IssuingReference](#schemaissuingreference)|false|none|Your reference.|
|metadata|[IssuingCardMetadata](#schemaissuingcardmetadata)|false|none|User's metadata|
|scheduled_revocation_date|[IssuingScheduledRevocationDate](#schemaissuingscheduledrevocationdate)|false|none|The card will be revoked at midnight UTC on the date specified.
- Format: `YYYY-MM-DD`|
|revocation_date|[IssuingRevocationDate](#schemaissuingrevocationdate)|false|none|Deprecated. Use `scheduled_revocation_date` instead.
If you provide both fields, the `scheduled_revocation_date` value overrides this value.|
|scheduled_activation_date|[IssuingScheduledActivationDate](#schemaissuingscheduledactivationdate)|false|none|Date scheduling the card's first activation. Only applies to the initial activation of a card. Two formats are supported:
- Date only: `YYYY-MM-DD` (treated as midnight UTC)
- Date with round hour: `YYYY-MM-DDTHH:mmZ` (UTC) or `YYYY-MM-DDTHH:mm±HH:mm` (offset)
Only round hours are allowed when a time is provided (`HH:00`). The value must be at least the next round hour after the request time.|
|card_product_id|[IssuingCardProductId](#schemaissuingcardproductid)|true|none|The card product's unique identifier. This field is required if there are multiple card products associated with the entity.|
add-card-response
```json
{
"id": "crd_fa6psq242dcd6fdn5gifcq1491",
"client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
"entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"display_name": "JOHN KENNEDY",
"last_four": "1234",
"expiry_month": 5,
"expiry_year": 2025,
"billing_currency": "USD",
"issuing_country": "US",
"status": "active",
"type": "string",
"reference": "X-123456-N11",
"scheme": "mastercard",
"created_date": "2019-09-10T10:11:12Z",
"last_activated_on": "2019-09-10T10:11:12Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"credentials": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/credentials",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"revoke": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/revoke",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"controls": {
"href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingCardId](#schemaissuingcardid)|true|none|The card's unique identifier.|
|client_id|[IssuingClientId](#schemaissuingclientid)|true|none|The client's unique identifier.|
|entity_id|[IssuingEntityId](#schemaissuingentityid)|true|none|The entity's unique identifier.|
|display_name|[DisplayName](#schemadisplayname)|false|none|The name to display on the card.|
|last_four|[LastFour](#schemalastfour)|true|none|The last four digits of the card number, also known as the PAN.|
|expiry_month|[ExpiryMonth](#schemaexpirymonth)|true|none|The card's expiration month.|
|expiry_year|[ExpiryYear](#schemaexpiryyear)|true|none|The card's expiration year.|
|billing_currency|[IssuingCurrency](#schemaissuingcurrency)|true|none|The issuing currency, as a three-letter ISO currency code.|
|issuing_country|[IssuingCountry](#schemaissuingcountry)|true|none|The issuing country, as a two-letter ISO country code.|
|status|[IssuingStatus](#schemaissuingstatus)|true|none|The card's status, which determines whether it can approve incoming authorizations:
- `inactive`: the default state - authorizations will be declined until the card is activated
- `active`: authorization requests can be approved
- `suspended`: incoming authorization requests will be declined - the card can be reactivated to accept new authorizations
- `revoked`: incoming authorization requests will be permanently declined - the card cannot be reactivated from this state|
|type|[IssuingType](#schemaissuingtype)|true|none|The card type.|
|reference|[IssuingReference](#schemaissuingreference)|false|none|Your reference.|
|scheme|[Scheme](#schemascheme)|true|none|the card scheme.|
|created_date|string(date-time)|true|none|none|
|last_activated_on|[LastActivatedOn](#schemalastactivatedon)|false|none|The date and time the card was last activated.
If the card has never been activated, this field returns `null`.|
|_links|[CardLinks](#schemacardlinks)|false|none|The links related to the card.|
add-physical-card-request
```json
{
"type": "physical",
"cardholder_id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
"lifetime": {
"unit": "Months",
"value": 6
},
"reference": "X-123456-N11",
"metadata": {
"udf1": "metadata1",
"udf2": "metadata2",
"udf3": "metadata3",
"udf4": "metadata4",
"udf5": "metadata5"
},
"revocation_date": null,
"scheduled_activation_date": "2026-06-01T10:00Z",
"card_product_id": "pro_7syjig3jq3mezlc3vjrdpfitl4",
"display_name": "JOHN KENNEDY",
"shipping_instructions": {
"shipping_address": {
"address_line1": "Checkout.com",
"address_line2": "90 Tottenham Court Road",
"city": "London",
"state": "London",
"zip": "W1T 4TJ",
"country": "GB"
},
"shipping_recipient": "john kennedy",
"additional_comment": "string"
},
"activate_card": false
}
```
physical
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The card type.|
|cardholder_id|[IssuingCardholderId](#schemaissuingcardholderid)|true|none|The cardholder's unique identifier.|
|lifetime|[CardLifetime](#schemacardlifetime)|false|none|The duration of time during which the card will accept incoming authorizations.
The `unit` and `value` combination you supply will determine the card's expiry date from the date of issue. For example, to set the card to expire in a year and a half, pass the following:
```
{
"lifetime": {
"unit": "Months",
"value": "18"
}
}
```|
|reference|[IssuingReference](#schemaissuingreference)|false|none|Your reference.|
|metadata|[IssuingCardMetadata](#schemaissuingcardmetadata)|false|none|User's metadata|
|revocation_date|any|false|none|Deprecated. Use `scheduled_revocation_date` instead.
If you provide both fields, the `scheduled_revocation_date` value overrides this value.|
|scheduled_activation_date|[IssuingScheduledActivationDate](#schemaissuingscheduledactivationdate)|false|none|Date scheduling the card's first activation. Only applies to the initial activation of a card. Two formats are supported:
- Date only: `YYYY-MM-DD` (treated as midnight UTC)
- Date with round hour: `YYYY-MM-DDTHH:mmZ` (UTC) or `YYYY-MM-DDTHH:mm±HH:mm` (offset)
Only round hours are allowed when a time is provided (`HH:00`). The value must be at least the next round hour after the request time.|
|card_product_id|[IssuingCardProductId](#schemaissuingcardproductid)|true|none|The card product's unique identifier. This field is required if there are multiple card products associated with the entity.|
|display_name|[DisplayName](#schemadisplayname)|true|none|The name to display on the card.|
|shipping_instructions|[IssuingShippingInstruction](#schemaissuingshippinginstruction)|true|none|none|
|activate_card|boolean|false|none|Sets whether to activate the newly created card upon creation.
If set to `false`, the cardholder will not be able to process transactions until you activate the card.|
add-physical-card-response
```json
{
"id": "crd_fa6psq242dcd6fdn5gifcq1491",
"client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
"entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"display_name": "JOHN KENNEDY",
"last_four": "1234",
"expiry_month": 5,
"expiry_year": 2025,
"billing_currency": "USD",
"issuing_country": "US",
"status": "active",
"type": "physical",
"reference": "X-123456-N11",
"scheme": "mastercard",
"created_date": "2019-09-10T10:11:12Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"credentials": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/credentials",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"revoke": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/revoke",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"controls": {
"href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}
```
physical
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingCardId](#schemaissuingcardid)|true|none|The card's unique identifier.|
|client_id|[IssuingClientId](#schemaissuingclientid)|true|none|The client's unique identifier.|
|entity_id|[IssuingEntityId](#schemaissuingentityid)|true|none|The entity's unique identifier.|
|display_name|[DisplayName](#schemadisplayname)|false|none|The name to display on the card.|
|last_four|[LastFour](#schemalastfour)|true|none|The last four digits of the card number, also known as the PAN.|
|expiry_month|[ExpiryMonth](#schemaexpirymonth)|true|none|The card's expiration month.|
|expiry_year|[ExpiryYear](#schemaexpiryyear)|true|none|The card's expiration year.|
|billing_currency|[IssuingCurrency](#schemaissuingcurrency)|true|none|The issuing currency, as a three-letter ISO currency code.|
|issuing_country|[IssuingCountry](#schemaissuingcountry)|true|none|The issuing country, as a two-letter ISO country code.|
|status|[IssuingStatus](#schemaissuingstatus)|true|none|The card's status, which determines whether it can approve incoming authorizations:
- `inactive`: the default state - authorizations will be declined until the card is activated
- `active`: authorization requests can be approved
- `suspended`: incoming authorization requests will be declined - the card can be reactivated to accept new authorizations
- `revoked`: incoming authorization requests will be permanently declined - the card cannot be reactivated from this state|
|type|any|true|none|none|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[IssuingType](#schemaissuingtype)|false|none|The card type.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|[IssuingReference](#schemaissuingreference)|false|none|Your reference.|
|scheme|[Scheme](#schemascheme)|true|none|the card scheme.|
|created_date|string(date-time)|true|none|none|
|_links|[CardLinks](#schemacardlinks)|false|none|The links related to the card.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|physical|
add-virtual-card-control-mcc-limit-request
```json
{
"description": "string",
"control_type": "mcc_limit",
"mcc_limit": {
"type": "allow",
"mcc_list": [
"5932",
"5411"
]
}
}
```
mcc_limit
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|description|string|false|none|A description for the control.|
|control_type|[IssuingControlType](#schemaissuingcontroltype)|true|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
|mcc_limit|[MccLimit](#schemamcclimit)|true|none|The merchant category code (MCC) rule, which determines the types of businesses transactions can be processed from.|
add-virtual-card-control-mid-limit-request
```json
{
"description": "string",
"control_type": "mid_limit",
"mid_limit": {
"type": "allow",
"mid_list": [
"593278",
"541114"
]
}
}
```
mid_limit
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|description|string|false|none|A description for the control.|
|control_type|[IssuingControlType](#schemaissuingcontroltype)|true|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
|mid_limit|[MidLimit](#schemamidlimit)|true|none|The merchant identification (MID) code rule, which determines the merchants from whom transactions can be processed.|
add-virtual-card-control-request
```json
{
"description": "string",
"control_type": "velocity_limit",
"velocity_limit": {
"amount_limit": 50000,
"velocity_window": {
"type": "weekly"
},
"mcc_list": [
"string"
],
"mid_list": [
"1234567890"
]
}
}
```
The control to create.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|description|string|false|none|A description for the control.|
|control_type|[IssuingControlType](#schemaissuingcontroltype)|true|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[add-virtual-card-control-velocity-limit-request](#schemaadd-virtual-card-control-velocity-limit-request)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[add-virtual-card-control-mcc-limit-request](#schemaadd-virtual-card-control-mcc-limit-request)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[add-virtual-card-control-mid-limit-request](#schemaadd-virtual-card-control-mid-limit-request)|false|none|none|
add-virtual-card-control-velocity-limit-request
```json
{
"description": "string",
"control_type": "velocity_limit",
"velocity_limit": {
"amount_limit": 50000,
"velocity_window": {
"type": "weekly"
},
"mcc_list": [
"string"
],
"mid_list": [
"1234567890"
]
}
}
```
velocity_limit
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|description|string|false|none|A description for the control.|
|control_type|[IssuingControlType](#schemaissuingcontroltype)|true|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
|velocity_limit|[VelocityLimit](#schemavelocitylimit)|true|none|The velocity limit, which determines how much a target card can spend over a given timeframe.|
add-virtual-card-request
```json
{
"type": "virtual",
"cardholder_id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
"lifetime": {
"unit": "Months",
"value": 6
},
"reference": "X-123456-N11",
"metadata": {
"udf1": "metadata1",
"udf2": "metadata2",
"udf3": "metadata3",
"udf4": "metadata4",
"udf5": "metadata5"
},
"revocation_date": null,
"scheduled_activation_date": "2026-06-01T10:00Z",
"card_product_id": "pro_7syjig3jq3mezlc3vjrdpfitl4",
"display_name": "JOHN KENNEDY",
"is_single_use": false,
"activate_card": true,
"return_credentials": [
"number",
"cvc2"
],
"control_profiles": [
"cpr_53mkhdc4jjlu5jcryx76bjbrgm"
],
"controls": [
{
"description": "50 euros daily",
"control_type": "velocity_limit",
"velocity_limit": {
"amount_limit": 5000,
"velocity_window": {
"type": "daily"
}
}
},
{
"description": "Block gambling",
"control_type": "mcc_limit",
"mcc_limit": {
"type": "block",
"mcc_list": [
"7995"
]
}
}
]
}
```
virtual
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The card type.|
|cardholder_id|[IssuingCardholderId](#schemaissuingcardholderid)|true|none|The cardholder's unique identifier.|
|lifetime|[CardLifetime](#schemacardlifetime)|false|none|The duration of time during which the card will accept incoming authorizations.
The `unit` and `value` combination you supply will determine the card's expiry date from the date of issue. For example, to set the card to expire in a year and a half, pass the following:
```
{
"lifetime": {
"unit": "Months",
"value": "18"
}
}
```|
|reference|[IssuingReference](#schemaissuingreference)|false|none|Your reference.|
|metadata|[IssuingCardMetadata](#schemaissuingcardmetadata)|false|none|User's metadata|
|revocation_date|any|false|none|Deprecated. Use `scheduled_revocation_date` instead.
If you provide both fields, the `scheduled_revocation_date` value overrides this value.|
|scheduled_activation_date|[IssuingScheduledActivationDate](#schemaissuingscheduledactivationdate)|false|none|Date scheduling the card's first activation. Only applies to the initial activation of a card. Two formats are supported:
- Date only: `YYYY-MM-DD` (treated as midnight UTC)
- Date with round hour: `YYYY-MM-DDTHH:mmZ` (UTC) or `YYYY-MM-DDTHH:mm±HH:mm` (offset)
Only round hours are allowed when a time is provided (`HH:00`). The value must be at least the next round hour after the request time.|
|card_product_id|[IssuingCardProductId](#schemaissuingcardproductid)|true|none|The card product's unique identifier. This field is required if there are multiple card products associated with the entity.|
|display_name|[DisplayName](#schemadisplayname)|false|none|The name to display on the card.|
|is_single_use|boolean|false|none|Sets whether the virtual card should expire after a single use.|
|activate_card|boolean|false|none|Sets whether to activate the newly created card upon creation.
If set to `false`, the cardholder will not be able to process transactions until you activate the card.|
|return_credentials|[string]|false|none|The credentials to retrieve on card creation.|
|control_profiles|[[IssuingControlProfileId](#schemaissuingcontrolprofileid)]|false|none|The control profiles you want to add the card to as a target.|
|controls|[[add-virtual-card-control-request](#schemaadd-virtual-card-control-request)]|false|none|The controls that will be set on the card.|
add-virtual-card-response-control-mcc-limit-response
```json
{
"id": "ctr_gp7vkmxayztufjz6top5bjcdra",
"description": "Allow the card to be used only in restaurants and supermarkets",
"control_type": "mcc_limit",
"mcc_limit": {
"type": "allow",
"mcc_list": [
"5932",
"5411"
]
}
}
```
mcc_limit
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingControlId](#schemaissuingcontrolid)|true|none|The control's unique identifier.|
|description|string|true|none|A description for the control.|
|control_type|[IssuingControlType](#schemaissuingcontroltype)|true|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
|mcc_limit|[MccLimit](#schemamcclimit)|true|none|The merchant category code (MCC) rule, which determines the types of businesses transactions can be processed from.|
add-virtual-card-response-control-mid-limit-response
```json
{
"id": "ctr_gp7vkmxayztufjz6top5bjcdra",
"description": "Allow the card to be used only in AZ Pizza",
"control_type": "mid_limit",
"mid_limit": {
"type": "allow",
"mid_list": [
"593278",
"541114"
]
}
}
```
mid_limit
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingControlId](#schemaissuingcontrolid)|true|none|The control's unique identifier.|
|description|string|true|none|A description for the control.|
|control_type|[IssuingControlType](#schemaissuingcontroltype)|true|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
|mid_limit|[MidLimit](#schemamidlimit)|true|none|The merchant identification (MID) code rule, which determines the merchants from whom transactions can be processed.|
add-virtual-card-response-control-response
```json
{
"id": "ctr_gp7vkmxayztufjz6top5bjcdra",
"description": "Maximum spend of 500€ per week for restaurants",
"control_type": "velocity_limit",
"velocity_limit": {
"amount_limit": 50000,
"velocity_window": {
"type": "weekly"
},
"mcc_list": [
"string"
],
"mid_list": [
"1234567890"
]
}
}
```
The card control's details.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingControlId](#schemaissuingcontrolid)|true|none|The control's unique identifier.|
|description|string|true|none|A description for the control.|
|control_type|[IssuingControlType](#schemaissuingcontroltype)|true|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[add-virtual-card-response-control-velocity-limit-response](#schemaadd-virtual-card-response-control-velocity-limit-response)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[add-virtual-card-response-control-mcc-limit-response](#schemaadd-virtual-card-response-control-mcc-limit-response)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[add-virtual-card-response-control-mid-limit-response](#schemaadd-virtual-card-response-control-mid-limit-response)|false|none|none|
add-virtual-card-response-control-velocity-limit-response
```json
{
"id": "ctr_gp7vkmxayztufjz6top5bjcdra",
"description": "Maximum spend of 500€ per week for restaurants",
"control_type": "velocity_limit",
"velocity_limit": {
"amount_limit": 50000,
"velocity_window": {
"type": "weekly"
},
"mcc_list": [
"string"
],
"mid_list": [
"1234567890"
]
}
}
```
velocity_limit
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingControlId](#schemaissuingcontrolid)|true|none|The control's unique identifier.|
|description|string|true|none|A description for the control.|
|control_type|[IssuingControlType](#schemaissuingcontroltype)|true|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
|velocity_limit|[VelocityLimit](#schemavelocitylimit)|true|none|The velocity limit, which determines how much a target card can spend over a given timeframe.|
add-virtual-card-response
```json
{
"id": "crd_fa6psq242dcd6fdn5gifcq1491",
"client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
"entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"display_name": "JOHN KENNEDY",
"last_four": "1234",
"expiry_month": 5,
"expiry_year": 2025,
"billing_currency": "USD",
"issuing_country": "US",
"status": "active",
"type": "virtual",
"reference": "X-123456-N11",
"scheme": "mastercard",
"created_date": "2019-09-10T10:11:12Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"credentials": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/credentials",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"revoke": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/revoke",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"controls": {
"href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
},
"credentials": {
"number": "4242424242424242",
"cvc2": "604"
},
"controls": [
{
"id": "ctr_s6tfwc6jpieexgcet2pljss6tu",
"description": "Maximum spend of 500€ per week for restaurants",
"control_type": "velocity_limit",
"velocity_limit": {
"amount_limit": 50000,
"velocity_window": {
"type": "weekly"
},
"mcc_list": [
"4121",
"4582"
]
}
},
{
"id": "ctr_gp7vkmxayztufjz6top5bjcdra",
"description": "Allow the card to be used only in restaurants and supermarkets",
"control_type": "mcc_limit",
"mcc_limit": {
"type": "allow",
"mcc_list": [
"5932",
"5411"
]
}
},
{
"id": "ctr_fa6psq42dcdd6fdn5gifcq1491",
"description": "Allow the card to be used only in AZ Pizza",
"control_type": "mid_limit",
"mid_limit": {
"type": "allow",
"mid_list": [
"593278",
"541114"
]
}
}
]
}
```
virtual
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingCardId](#schemaissuingcardid)|true|none|The card's unique identifier.|
|client_id|[IssuingClientId](#schemaissuingclientid)|true|none|The client's unique identifier.|
|entity_id|[IssuingEntityId](#schemaissuingentityid)|true|none|The entity's unique identifier.|
|display_name|[DisplayName](#schemadisplayname)|false|none|The name to display on the card.|
|last_four|[LastFour](#schemalastfour)|true|none|The last four digits of the card number, also known as the PAN.|
|expiry_month|[ExpiryMonth](#schemaexpirymonth)|true|none|The card's expiration month.|
|expiry_year|[ExpiryYear](#schemaexpiryyear)|true|none|The card's expiration year.|
|billing_currency|[IssuingCurrency](#schemaissuingcurrency)|true|none|The issuing currency, as a three-letter ISO currency code.|
|issuing_country|[IssuingCountry](#schemaissuingcountry)|true|none|The issuing country, as a two-letter ISO country code.|
|status|[IssuingStatus](#schemaissuingstatus)|true|none|The card's status, which determines whether it can approve incoming authorizations:
- `inactive`: the default state - authorizations will be declined until the card is activated
- `active`: authorization requests can be approved
- `suspended`: incoming authorization requests will be declined - the card can be reactivated to accept new authorizations
- `revoked`: incoming authorization requests will be permanently declined - the card cannot be reactivated from this state|
|type|any|true|none|none|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[IssuingType](#schemaissuingtype)|false|none|The card type.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|[IssuingReference](#schemaissuingreference)|false|none|Your reference.|
|scheme|[Scheme](#schemascheme)|true|none|the card scheme.|
|created_date|string(date-time)|true|none|none|
|_links|[CardLinks](#schemacardlinks)|false|none|The links related to the card.|
|credentials|[Credentials](#schemacredentials)|false|none|none|
|controls|[[add-virtual-card-response-control-response](#schemaadd-virtual-card-response-control-response)]|false|none|The controls that were set on the card.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|virtual|
DisplayName
```json
"JOHN KENNEDY"
```
The name to display on the card.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The name to display on the card.|
get-card-response
```json
{
"id": "crd_fa6psq242dcd6fdn5gifcq1491",
"client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
"entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"cardholder_id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
"card_product_id": "pro_7syjig3jq3mezlc3vjrdpfitl4",
"user_id": "usr_fa6psq242dcd6fdn5gifcq1491",
"last_four": "1234",
"expiry_month": 5,
"expiry_year": 2025,
"status": "active",
"display_name": "JOHN KENNEDY",
"type": "virtual",
"billing_currency": "USD",
"issuing_country": "US",
"reference": "X-123456-N11",
"metadata": {
"udf1": "metadata1",
"udf2": "metadata2",
"udf3": "metadata3",
"udf4": "metadata4",
"udf5": "metadata5"
},
"scheduled_revocation_date": "2027-03-12",
"revocation_date": "2027-03-12",
"scheduled_activation_date": "2026-06-01T10:00Z",
"last_activated_on": "2019-09-10T10:11:12Z",
"root_card_id": "crd_fa6psq242dcd6fdn5gifcq1491",
"parent_card_id": "crd_qm26t52qz3yejjo2t4btqvxtzi",
"scheme": "mastercard",
"created_date": "2021-09-09T19:41:39Z",
"last_modified_date": "2021-09-09T19:41:39Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"credentials": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/credentials",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"revoke": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/revoke",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"controls": {
"href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
},
"is_single_use": false
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingCardId](#schemaissuingcardid)|true|none|The card's unique identifier.|
|client_id|[IssuingClientId](#schemaissuingclientid)|true|none|The client's unique identifier.|
|entity_id|[IssuingEntityId](#schemaissuingentityid)|true|none|The entity's unique identifier.|
|cardholder_id|[IssuingCardholderId](#schemaissuingcardholderid)|true|none|The cardholder's unique identifier.|
|card_product_id|[IssuingCardProductId](#schemaissuingcardproductid)|true|none|The card product's unique identifier.|
|user_id|[IssuingUserId](#schemaissuinguserid)|false|none|The Dashboard user's unique identifier.|
|last_four|[LastFour](#schemalastfour)|true|none|The last four digits of the card number, also known as the PAN.|
|expiry_month|[ExpiryMonth](#schemaexpirymonth)|true|none|The card's expiration month.|
|expiry_year|[ExpiryYear](#schemaexpiryyear)|true|none|The card's expiration year.|
|status|[IssuingStatus](#schemaissuingstatus)|true|none|The card's status, which determines whether it can approve incoming authorizations:
- `inactive`: the default state - authorizations will be declined until the card is activated
- `active`: authorization requests can be approved
- `suspended`: incoming authorization requests will be declined - the card can be reactivated to accept new authorizations
- `revoked`: incoming authorization requests will be permanently declined - the card cannot be reactivated from this state|
|display_name|[DisplayName](#schemadisplayname)|false|none|The name to display on the card.|
|type|[IssuingType](#schemaissuingtype)|true|none|The card type.|
|billing_currency|[IssuingCurrency](#schemaissuingcurrency)|true|none|The issuing currency, as a three-letter ISO currency code.|
|issuing_country|[IssuingCountry](#schemaissuingcountry)|true|none|The issuing country, as a two-letter ISO country code.|
|reference|[IssuingReference](#schemaissuingreference)|false|none|Your reference.|
|metadata|[IssuingCardMetadata](#schemaissuingcardmetadata)|false|none|User's metadata.|
|scheduled_revocation_date|[IssuingScheduledRevocationDate](#schemaissuingscheduledrevocationdate)|false|none|The card will be revoked at midnight UTC on the date specified.
- Format: `YYYY-MM-DD`|
|revocation_date|[IssuingRevocationDate](#schemaissuingrevocationdate)|false|none|Deprecated. Use `scheduled_revocation_date` instead.|
|scheduled_activation_date|[IssuingScheduledActivationDate](#schemaissuingscheduledactivationdate)|false|none|Date scheduling the card's first activation. Only applies to the initial activation of a card. Two formats are supported:
- Date only: `YYYY-MM-DD` (treated as midnight UTC)
- Date with round hour: `YYYY-MM-DDTHH:mmZ` (UTC) or `YYYY-MM-DDTHH:mm±HH:mm` (offset)
Only round hours are allowed when a time is provided (`HH:00`). The value must be at least the next round hour after the request time.|
|last_activated_on|[LastActivatedOn](#schemalastactivatedon)|false|none|The date and time the card was last activated.
If the card has never been activated, this field returns `null`.|
|root_card_id|[IssuingRootCardId](#schemaissuingrootcardid)|false|none|When a card is renewed, the unique identifier of the first card in the renewal history.|
|parent_card_id|[IssuingParentCardId](#schemaissuingparentcardid)|false|none|When a card is renewed, the unique identifier of the previous card in the renewal history.|
|scheme|[Scheme](#schemascheme)|true|none|the card scheme.|
|created_date|[Datetime](#schemadatetime)|false|none|none|
|last_modified_date|[Datetime](#schemadatetime)|false|none|none|
|_links|[CardLinks](#schemacardlinks)|false|none|The links related to the card.|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[get-virtual-card-response](#schemaget-virtual-card-response)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[get-physical-card-response](#schemaget-physical-card-response)|false|none|none|
get-physical-card-response
```json
{
"id": "crd_fa6psq242dcd6fdn5gifcq1491",
"client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
"entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"cardholder_id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
"card_product_id": "pro_7syjig3jq3mezlc3vjrdpfitl4",
"user_id": "usr_fa6psq242dcd6fdn5gifcq1491",
"last_four": "1234",
"expiry_month": 5,
"expiry_year": 2025,
"status": "active",
"display_name": "JOHN KENNEDY",
"type": "physical",
"billing_currency": "USD",
"issuing_country": "US",
"reference": "X-123456-N11",
"metadata": {
"udf1": "metadata1",
"udf2": "metadata2",
"udf3": "metadata3",
"udf4": "metadata4",
"udf5": "metadata5"
},
"revocation_date": "2027-03-12",
"scheduled_activation_date": "2026-06-01T10:00Z",
"root_card_id": "crd_fa6psq242dcd6fdn5gifcq1491",
"parent_card_id": "crd_qm26t52qz3yejjo2t4btqvxtzi",
"scheme": "mastercard",
"created_date": "2021-09-09T19:41:39Z",
"last_modified_date": "2021-09-09T19:41:39Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"credentials": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/credentials",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"revoke": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/revoke",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"controls": {
"href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}
```
physical
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingCardId](#schemaissuingcardid)|true|none|The card's unique identifier.|
|client_id|[IssuingClientId](#schemaissuingclientid)|true|none|The client's unique identifier.|
|entity_id|[IssuingEntityId](#schemaissuingentityid)|true|none|The entity's unique identifier.|
|cardholder_id|[IssuingCardholderId](#schemaissuingcardholderid)|true|none|The cardholder's unique identifier.|
|card_product_id|[IssuingCardProductId](#schemaissuingcardproductid)|true|none|The card product's unique identifier.|
|user_id|[IssuingUserId](#schemaissuinguserid)|false|none|The Dashboard user's unique identifier.|
|last_four|[LastFour](#schemalastfour)|true|none|The last four digits of the card number, also known as the PAN.|
|expiry_month|[ExpiryMonth](#schemaexpirymonth)|true|none|The card's expiration month.|
|expiry_year|[ExpiryYear](#schemaexpiryyear)|true|none|The card's expiration year.|
|status|[IssuingStatus](#schemaissuingstatus)|true|none|The card's status, which determines whether it can approve incoming authorizations:
- `inactive`: the default state - authorizations will be declined until the card is activated
- `active`: authorization requests can be approved
- `suspended`: incoming authorization requests will be declined - the card can be reactivated to accept new authorizations
- `revoked`: incoming authorization requests will be permanently declined - the card cannot be reactivated from this state|
|display_name|[DisplayName](#schemadisplayname)|false|none|The name to display on the card.|
|type|any|true|none|none|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[IssuingType](#schemaissuingtype)|false|none|The card type.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|billing_currency|[IssuingCurrency](#schemaissuingcurrency)|true|none|The issuing currency, as a three-letter ISO currency code.|
|issuing_country|[IssuingCountry](#schemaissuingcountry)|true|none|The issuing country, as a two-letter ISO country code.|
|reference|[IssuingReference](#schemaissuingreference)|false|none|Your reference.|
|metadata|[IssuingCardMetadata](#schemaissuingcardmetadata)|false|none|User's metadata.|
|revocation_date|[IssuingRevocationDate](#schemaissuingrevocationdate)|false|none|Deprecated. Use `scheduled_revocation_date` instead.
Date scheduling the card's automatic revocation.
- Supported format: `YYYY-MM-DD` (time is midnight UTC)|
|scheduled_activation_date|[IssuingScheduledActivationDate](#schemaissuingscheduledactivationdate)|false|none|Date scheduling the card's first activation. Only applies to the initial activation of a card. Two formats are supported:
- Date only: `YYYY-MM-DD` (treated as midnight UTC)
- Date with round hour: `YYYY-MM-DDTHH:mmZ` (UTC) or `YYYY-MM-DDTHH:mm±HH:mm` (offset)
Only round hours are allowed when a time is provided (`HH:00`). The value must be at least the next round hour after the request time.|
|root_card_id|[IssuingRootCardId](#schemaissuingrootcardid)|false|none|When a card is renewed, the unique identifier of the first card in the renewal history.|
|parent_card_id|[IssuingParentCardId](#schemaissuingparentcardid)|false|none|When a card is renewed, the unique identifier of the previous card in the renewal history.|
|scheme|[Scheme](#schemascheme)|true|none|the card scheme.|
|created_date|[Datetime](#schemadatetime)|false|none|none|
|last_modified_date|[Datetime](#schemadatetime)|false|none|none|
|_links|[CardLinks](#schemacardlinks)|false|none|The links related to the card.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|physical|
get-virtual-card-response
```json
{
"id": "crd_fa6psq242dcd6fdn5gifcq1491",
"client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
"entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"cardholder_id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
"card_product_id": "pro_7syjig3jq3mezlc3vjrdpfitl4",
"user_id": "usr_fa6psq242dcd6fdn5gifcq1491",
"last_four": "1234",
"expiry_month": 5,
"expiry_year": 2025,
"status": "active",
"display_name": "JOHN KENNEDY",
"type": "virtual",
"billing_currency": "USD",
"issuing_country": "US",
"reference": "X-123456-N11",
"metadata": {
"udf1": "metadata1",
"udf2": "metadata2",
"udf3": "metadata3",
"udf4": "metadata4",
"udf5": "metadata5"
},
"revocation_date": "2027-03-12",
"scheduled_activation_date": "2026-06-01T10:00Z",
"root_card_id": "crd_fa6psq242dcd6fdn5gifcq1491",
"parent_card_id": "crd_qm26t52qz3yejjo2t4btqvxtzi",
"scheme": "mastercard",
"created_date": "2021-09-09T19:41:39Z",
"last_modified_date": "2021-09-09T19:41:39Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"credentials": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/credentials",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"revoke": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/revoke",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"controls": {
"href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
},
"is_single_use": false
}
```
virtual
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingCardId](#schemaissuingcardid)|true|none|The card's unique identifier.|
|client_id|[IssuingClientId](#schemaissuingclientid)|true|none|The client's unique identifier.|
|entity_id|[IssuingEntityId](#schemaissuingentityid)|true|none|The entity's unique identifier.|
|cardholder_id|[IssuingCardholderId](#schemaissuingcardholderid)|true|none|The cardholder's unique identifier.|
|card_product_id|[IssuingCardProductId](#schemaissuingcardproductid)|true|none|The card product's unique identifier.|
|user_id|[IssuingUserId](#schemaissuinguserid)|false|none|The Dashboard user's unique identifier.|
|last_four|[LastFour](#schemalastfour)|true|none|The last four digits of the card number, also known as the PAN.|
|expiry_month|[ExpiryMonth](#schemaexpirymonth)|true|none|The card's expiration month.|
|expiry_year|[ExpiryYear](#schemaexpiryyear)|true|none|The card's expiration year.|
|status|[IssuingStatus](#schemaissuingstatus)|true|none|The card's status, which determines whether it can approve incoming authorizations:
- `inactive`: the default state - authorizations will be declined until the card is activated
- `active`: authorization requests can be approved
- `suspended`: incoming authorization requests will be declined - the card can be reactivated to accept new authorizations
- `revoked`: incoming authorization requests will be permanently declined - the card cannot be reactivated from this state|
|display_name|[DisplayName](#schemadisplayname)|false|none|The name to display on the card.|
|type|any|true|none|none|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[IssuingType](#schemaissuingtype)|false|none|The card type.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|billing_currency|[IssuingCurrency](#schemaissuingcurrency)|true|none|The issuing currency, as a three-letter ISO currency code.|
|issuing_country|[IssuingCountry](#schemaissuingcountry)|true|none|The issuing country, as a two-letter ISO country code.|
|reference|[IssuingReference](#schemaissuingreference)|false|none|Your reference.|
|metadata|[IssuingCardMetadata](#schemaissuingcardmetadata)|false|none|User's metadata.|
|revocation_date|[IssuingRevocationDate](#schemaissuingrevocationdate)|false|none|Deprecated. Use `scheduled_revocation_date` instead.
Date scheduling the card's automatic revocation.
- Supported format: `YYYY-MM-DD` (time is midnight UTC)|
|scheduled_activation_date|[IssuingScheduledActivationDate](#schemaissuingscheduledactivationdate)|false|none|Date scheduling the card's first activation. Only applies to the initial activation of a card. Two formats are supported:
- Date only: `YYYY-MM-DD` (treated as midnight UTC)
- Date with round hour: `YYYY-MM-DDTHH:mmZ` (UTC) or `YYYY-MM-DDTHH:mm±HH:mm` (offset)
Only round hours are allowed when a time is provided (`HH:00`). The value must be at least the next round hour after the request time.|
|root_card_id|[IssuingRootCardId](#schemaissuingrootcardid)|false|none|When a card is renewed, the unique identifier of the first card in the renewal history.|
|parent_card_id|[IssuingParentCardId](#schemaissuingparentcardid)|false|none|When a card is renewed, the unique identifier of the previous card in the renewal history.|
|scheme|[Scheme](#schemascheme)|true|none|the card scheme.|
|created_date|[Datetime](#schemadatetime)|false|none|none|
|last_modified_date|[Datetime](#schemadatetime)|false|none|none|
|_links|[CardLinks](#schemacardlinks)|false|none|The links related to the card.|
|is_single_use|boolean|false|none|Specifies whether the virtual card is set to expire after a single use.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|virtual|
get-cardholder-cards-response
```json
{
"cards": [
{
"id": "crd_fa6psq242dcd6fdn5gifcq1491",
"client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
"entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"cardholder_id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
"card_product_id": "pro_7syjig3jq3mezlc3vjrdpfitl4",
"user_id": "usr_fa6psq242dcd6fdn5gifcq1491",
"last_four": "1234",
"expiry_month": 5,
"expiry_year": 2025,
"status": "active",
"display_name": "JOHN KENNEDY",
"type": "virtual",
"billing_currency": "USD",
"issuing_country": "US",
"reference": "X-123456-N11",
"metadata": {
"udf1": "metadata1",
"udf2": "metadata2",
"udf3": "metadata3",
"udf4": "metadata4",
"udf5": "metadata5"
},
"scheduled_revocation_date": "2027-03-12",
"revocation_date": "2027-03-12",
"scheduled_activation_date": "2026-06-01T10:00Z",
"last_activated_on": "2019-09-10T10:11:12Z",
"root_card_id": "crd_fa6psq242dcd6fdn5gifcq1491",
"parent_card_id": "crd_qm26t52qz3yejjo2t4btqvxtzi",
"scheme": "mastercard",
"created_date": "2021-09-09T19:41:39Z",
"last_modified_date": "2021-09-09T19:41:39Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"credentials": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/credentials",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"revoke": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/revoke",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"controls": {
"href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
},
"is_single_use": false
}
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|cards|[[get-card-response](#schemaget-card-response)]|true|none|The list of cards associated with the specified cardholder.|
ActivatedCardLinks
```json
{
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"revoke": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/revoke",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"suspend": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/suspend",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"controls": {
"href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
```
The links related to the card.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|self|[IssuingLink](#schemaissuinglink)|true|none|The URI to retrieve the card's details.|
|revoke|[IssuingLink](#schemaissuinglink)|true|none|The URI to revoke the card.|
|suspend|[IssuingLink](#schemaissuinglink)|true|none|The URI to suspend the card.|
|controls|[IssuingLink](#schemaissuinglink)|true|none|The URI to retrieve the card's controls.|
CardLifetime
```json
{
"unit": "Months",
"value": 6
}
```
The duration of time during which the card will accept incoming authorizations.
The `unit` and `value` combination you supply will determine the card's expiry date from the date of issue. For example, to set the card to expire in a year and a half, pass the following:
```
{
"lifetime": {
"unit": "Months",
"value": "18"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|unit|string|false|none|The unit of time to specify the card lifetime's in.|
|value|integer|true|none|The length of time before the card will expire, in the `unit` of time specified.|
#### Enumerated Values
|Property|Value|
|---|---|
|unit|Months|
|unit|Years|
CardLink
```json
{
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"controls": {
"href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
```
The links related to the card.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|self|[IssuingLink](#schemaissuinglink)|true|none|The URI to retrieve the card's details.|
|controls|[IssuingLink](#schemaissuinglink)|true|none|The URI to retrieve the card's controls.|
CardLinks
```json
{
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"credentials": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/credentials",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"revoke": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/revoke",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"controls": {
"href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
```
The links related to the card.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|self|[IssuingLink](#schemaissuinglink)|true|none|The URI to retrieve the card's details.|
|credentials|[IssuingLink](#schemaissuinglink)|true|none|The URI to retrieve the card's credentials.|
|revoke|[IssuingLink](#schemaissuinglink)|true|none|The URI to revoke the card.|
|controls|[IssuingLink](#schemaissuinglink)|true|none|The URI to retrieve the card's controls.|
CardNumber
```json
"4242424242424242"
```
The unencrypted card number.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string(pan)|false|none|The unencrypted card number.|
Credentials
```json
{
"number": "4242424242424242",
"cvc2": "604"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|number|[CardNumber](#schemacardnumber)|false|none|The unencrypted card number.|
|cvc2|[CVC2](#schemacvc2)|false|none|The card's verification code, also known as the CVV or CVC2.|
CVC2
```json
"604"
```
The card's verification code, also known as the CVV or CVC2.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The card's verification code, also known as the CVV or CVC2.|
DigitalCardLinks
```json
{
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/digital-cards/dcr_5ngxzsynm2me3oxf73esbhda6q",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
```
The links related to the digital card.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|self|[IssuingLink](#schemaissuinglink)|true|none|The URI to retrieve the digital card's details.|
DigitalCardType
```json
"secure_element"
```
The type of digital card
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The type of digital card|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|secure_element|
|*anonymous*|host_card_emulation|
|*anonymous*|card_on_file|
|*anonymous*|e_commerce|
|*anonymous*|qr_code|
ExpiryMonth
```json
5
```
The card's expiration month.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|integer(int32)|false|none|The card's expiration month.|
ExpiryYear
```json
2025
```
The card's expiration year.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|integer(int32)|false|none|The card's expiration year.|
```json
{
"udf1": "metadata1",
"udf2": "metadata2",
"udf3": "metadata3",
"udf4": "metadata4",
"udf5": "metadata5"
}
```
User's metadata.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|udf1|string|false|none|User defined field 1|
|udf2|string|false|none|User defined field 2|
|udf3|string|false|none|User defined field 3|
|udf4|string|false|none|User defined field 4|
|udf5|string|false|none|User defined field 5|
IssuingDevice
```json
{
"id": "04431C7B514E80018306224737548585F11415F67C4E2EB6",
"type": "iphone",
"manufacturer": "ios",
"brand": "string",
"model": "string",
"os_version": "13",
"firmware_version": "string",
"phone_number": "447505551234",
"device_name": "John's iPhone",
"device_parent_id": "string",
"language": "string",
"serial_number": "string",
"time_zone": "string",
"time_zone_setting": "network_set",
"sim_serial_number": "string",
"imei": "000000000000024",
"network_operator": "string",
"network_type": "wifi"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The device ID.|
|type|string|false|none|The device type.|
|manufacturer|string|false|none|The device manufacturer.|
|brand|string|false|none|The device brand.|
|model|string|false|none|The device model.|
|os_version|string|false|none|The device operating system version.|
|firmware_version|string|false|none|The device firmware version.|
|phone_number|string|false|none|The device phone number.|
|device_name|string|false|none|The device name.|
|device_parent_id|string|false|none|The device parent ID.|
|language|string|false|none|The device language.|
|serial_number|string|false|none|The device serial number.|
|time_zone|string|false|none|The device time zone.|
|time_zone_setting|string|false|none|The device time zone setting.|
|sim_serial_number|string|false|none|The device SIM serial number.|
|imei|string|false|none|The device International Mobile Equipment Identity (IMEI) number.|
|network_operator|string|false|none|The device network operator.|
|network_type|string|false|none|The device network type.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|host_card_emulation|
|type|samsung_phone|
|type|samsung_tablet|
|type|samsung_watch|
|type|samsung_tv|
|type|iphone|
|type|iwatch|
|type|ipad|
|type|mac_book|
|type|android_phone|
|type|android_tablet|
|type|android_watch|
|type|mobile_phone|
|type|tablet|
|type|watch|
|type|mobile_phone_or_tablet|
|type|bracelet|
|type|unknown|
|time_zone_setting|network_set|
|time_zone_setting|consumer_set|
|network_type|cellular|
|network_type|wifi|
IssuingDigitalStatus
```json
"active"
```
The digital card's current status, which determines whether it can approve incoming authorizations:
- `inactive`: the default state - authorizations will be declined until the card is activated
- `active`: authorization requests can be approved
- `deleted`: incoming authorization requests will be declined, permanently — the card cannot be reactivated from this state
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The digital card's current status, which determines whether it can approve incoming authorizations:
- `inactive`: the default state - authorizations will be declined until the card is activated
- `active`: authorization requests can be approved
- `deleted`: incoming authorization requests will be declined, permanently — the card cannot be reactivated from this state|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|active|
|*anonymous*|inactive|
|*anonymous*|deleted|
IssuingRequestor
```json
{
"id": "501103353211",
"name": "APPLE PAY"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The requestor ID.|
|name|string|false|none|The requestor name.|
IssuingRevocationDate
```json
"2027-03-12"
```
Deprecated. Use `scheduled_revocation_date` instead.
Date scheduling the card's automatic revocation.
- Supported format: `YYYY-MM-DD` (time is midnight UTC)
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string(date)|false|none|Deprecated. Use `scheduled_revocation_date` instead.
Date scheduling the card's automatic revocation.
- Supported format: `YYYY-MM-DD` (time is midnight UTC)|
IssuingScheduledActivationDate
```json
"2026-06-01T10:00Z"
```
Date scheduling the card's first activation. Only applies to the initial activation of a card. Two formats are supported:
- Date only: `YYYY-MM-DD` (treated as midnight UTC)
- Date with round hour: `YYYY-MM-DDTHH:mmZ` (UTC) or `YYYY-MM-DDTHH:mm±HH:mm` (offset)
Only round hours are allowed when a time is provided (`HH:00`). The value must be at least the next round hour after the request time.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|Date scheduling the card's first activation. Only applies to the initial activation of a card. Two formats are supported:
- Date only: `YYYY-MM-DD` (treated as midnight UTC)
- Date with round hour: `YYYY-MM-DDTHH:mmZ` (UTC) or `YYYY-MM-DDTHH:mm±HH:mm` (offset)
Only round hours are allowed when a time is provided (`HH:00`). The value must be at least the next round hour after the request time.|
IssuingScheduledRevocationDate
```json
"2027-03-12"
```
The card will be revoked at midnight UTC on the date specified.
- Format: `YYYY-MM-DD`
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string(date)|false|none|The card will be revoked at midnight UTC on the date specified.
- Format: `YYYY-MM-DD`|
IssuingStatus
```json
"active"
```
The card's status, which determines whether it can approve incoming authorizations:
- `inactive`: the default state - authorizations will be declined until the card is activated
- `active`: authorization requests can be approved
- `suspended`: incoming authorization requests will be declined - the card can be reactivated to accept new authorizations
- `revoked`: incoming authorization requests will be permanently declined - the card cannot be reactivated from this state
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The card's status, which determines whether it can approve incoming authorizations:
- `inactive`: the default state - authorizations will be declined until the card is activated
- `active`: authorization requests can be approved
- `suspended`: incoming authorization requests will be declined - the card can be reactivated to accept new authorizations
- `revoked`: incoming authorization requests will be permanently declined - the card cannot be reactivated from this state|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|active|
|*anonymous*|inactive|
|*anonymous*|revoked|
|*anonymous*|suspended|
IssuingType
```json
"string"
```
The card type.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The card type.|
LastActivatedOn
```json
"2019-09-10T10:11:12Z"
```
The date and time the card was last activated.
If the card has never been activated, this field returns `null`.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string(date-time)¦null|false|read-only|The date and time the card was last activated.
If the card has never been activated, this field returns `null`.|
LastFour
```json
"1234"
```
The last four digits of the card number, also known as the PAN.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The last four digits of the card number, also known as the PAN.|
RenewedCardLinks
```json
{
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"credentials": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/credentials",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"activate": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/activate",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"controls": {
"href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
```
The links related to the card.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|self|[IssuingLink](#schemaissuinglink)|true|none|The URI to retrieve the card details.|
|credentials|[IssuingLink](#schemaissuinglink)|true|none|The URI to retrieve the card's credentials.|
|activate|[IssuingLink](#schemaissuinglink)|true|none|The URI to activate the card.|
|controls|[IssuingLink](#schemaissuinglink)|true|none|The URI to retrieve the card's controls.|
Scheme
```json
"mastercard"
```
the card scheme.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|the card scheme.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|mastercard|
|*anonymous*|visa|
SuspendedCardLinks
```json
{
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"activate": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/activate",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"revoke": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/revoke",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"controls": {
"href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
```
The links related to the card.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|self|[IssuingLink](#schemaissuinglink)|true|none|The URI to retrieve the card details.|
|activate|[IssuingLink](#schemaissuinglink)|true|none|The URI to activate the card.|
|revoke|[IssuingLink](#schemaissuinglink)|true|none|The URI to revoke the card.|
|controls|[IssuingLink](#schemaissuinglink)|true|none|The URI to retrieve the card's controls.|
physical_card
```json
{
"display_name": "JOHN KENNEDY",
"shipping_instructions": {
"shipping_address": {
"address_line1": "Checkout.com",
"address_line2": "90 Tottenham Court Road",
"city": "London",
"state": "London",
"zip": "W1T 4TJ",
"country": "GB"
},
"shipping_recipient": "john kennedy",
"additional_comment": "string"
},
"reference": "X-123456-N11",
"metadata": {
"udf1": "metadata1",
"udf2": "metadata2",
"udf3": "metadata3",
"udf4": "metadata4",
"udf5": "metadata5"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|display_name|[DisplayName](#schemadisplayname)|false|none|The name to display on the card.|
|shipping_instructions|[IssuingShippingInstruction](#schemaissuingshippinginstruction)|false|none|none|
|reference|[IssuingReference](#schemaissuingreference)|false|none|Your reference.|
|metadata|[IssuingCardMetadata](#schemaissuingcardmetadata)|false|none|User's metadata|
virtual_card
```json
{
"display_name": "JOHN KENNEDY",
"reference": "X-123456-N11",
"metadata": {
"udf1": "metadata1",
"udf2": "metadata2",
"udf3": "metadata3",
"udf4": "metadata4",
"udf5": "metadata5"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|display_name|[DisplayName](#schemadisplayname)|false|none|The name to display on the card.|
|reference|[IssuingReference](#schemaissuingreference)|false|none|Your reference.|
|metadata|[IssuingCardMetadata](#schemaissuingcardmetadata)|false|none|User's metadata|
renew-card-response
```json
{
"parent_card_id": "crd_fa6psq242dcd6fdn5gifcq1491",
"cardholder_id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
"status": "inactive",
"type": "string",
"id": "crd_zdihd7452165pk5lgywaa52147",
"client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
"entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"last_four": "1234",
"expiry_year": 2025,
"expiry_month": 5,
"display_name": "JOHN KENNEDY",
"reference": "X-123456-N11",
"created_date": "2021-09-09T19:41:39Z",
"billing_currency": "USD",
"issuing_country": "US",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"credentials": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/credentials",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"activate": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/activate",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"controls": {
"href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|parent_card_id|[IssuingCardId](#schemaissuingcardid)|false|none|The unique identifier of the card that was renewed.|
|cardholder_id|[IssuingCardholderId](#schemaissuingcardholderid)|false|none|The cardholder's unique identifier.|
|status|[IssuingStatus](#schemaissuingstatus)|false|none|The card's status, which determines whether it can approve incoming authorizations:
- `inactive`: the default state - authorizations will be declined until the card is activated
- `active`: authorization requests can be approved
- `suspended`: incoming authorization requests will be declined - the card can be reactivated to accept new authorizations
- `revoked`: incoming authorization requests will be permanently declined - the card cannot be reactivated from this state|
|type|[IssuingType](#schemaissuingtype)|false|none|The card type.|
|id|[IssuingCardId](#schemaissuingcardid)|false|none|The unique identifier of the new card.|
|client_id|[IssuingClientId](#schemaissuingclientid)|false|none|The client's unique identifier.|
|entity_id|[IssuingEntityId](#schemaissuingentityid)|false|none|The entity's unique identifier.|
|last_four|[LastFour](#schemalastfour)|false|none|The last four digits of the card number, also known as the PAN.|
|expiry_year|[ExpiryYear](#schemaexpiryyear)|false|none|The card's expiration year.|
|expiry_month|[ExpiryMonth](#schemaexpirymonth)|false|none|The card's expiration month.|
|display_name|[DisplayName](#schemadisplayname)|false|none|The name to display on the card.|
|reference|[IssuingReference](#schemaissuingreference)|false|none|Your reference.|
|created_date|[Datetime](#schemadatetime)|false|none|none|
|billing_currency|[IssuingCurrency](#schemaissuingcurrency)|false|none|The issuing currency, as a three-letter ISO currency code.|
|issuing_country|[IssuingCountry](#schemaissuingcountry)|false|none|The issuing country, as a two-letter ISO country code.|
|_links|[RenewedCardLinks](#schemarenewedcardlinks)|false|none|The links related to the card.|
revoke-card-request
```json
{
"reason": "reported_lost"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reason|string|false|none|The reason why the card is being revoked.|
#### Enumerated Values
|Property|Value|
|---|---|
|reason|expired|
|reason|reported_lost|
|reason|reported_stolen|
revoke-card-response
```json
{
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"controls": {
"href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|_links|[CardLink](#schemacardlink)|false|none|The links related to the card.|
suspend-card-request
```json
{
"reason": "suspected_lost"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reason|string|false|none|The reason why the card is being suspended.|
#### Enumerated Values
|Property|Value|
|---|---|
|reason|suspected_lost|
|reason|suspected_stolen|
suspend-card-response
```json
{
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"activate": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/activate",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"revoke": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/revoke",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"controls": {
"href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|_links|[SuspendedCardLinks](#schemasuspendedcardlinks)|false|none|The links related to the card.|
update-card-request
```json
{
"status": "active",
"reference": "X-123456-N11",
"metadata": {
"udf1": "metadata1",
"udf2": "metadata2",
"udf3": "metadata3",
"udf4": "metadata4",
"udf5": "metadata5"
},
"expiry_month": 5,
"expiry_year": 2025,
"scheduled_revocation_date": "2027-03-12",
"revocation_date": "2027-03-12",
"scheduled_activation_date": "2026-06-01T10:00Z"
}
```
The card fields to update.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|status|string|false|none|Set the card's status to `active` to activate an `inactive` or `suspended` card.
If you submit this field, you cannot specify a `scheduled_activation_date`. If you do, you receive a `scheduled_activation_date_conflicts_with_activation` error.|
|reference|[IssuingReference](#schemaissuingreference)|false|none|Your reference.|
|metadata|[IssuingCardMetadata](#schemaissuingcardmetadata)|false|none|User's metadata.|
|expiry_month|[ExpiryMonth](#schemaexpirymonth)|false|none|The card's expiration month.|
|expiry_year|[ExpiryYear](#schemaexpiryyear)|false|none|The card's expiration year.|
|scheduled_revocation_date|[IssuingScheduledRevocationDate](#schemaissuingscheduledrevocationdate)|false|none|The card will be revoked at midnight UTC on the date specified.
- Format: `YYYY-MM-DD`|
|revocation_date|[IssuingRevocationDate](#schemaissuingrevocationdate)|false|none|Deprecated. Use `scheduled_revocation_date` instead.
If you provide both fields, the `scheduled_revocation_date` value overrides this value.|
|scheduled_activation_date|[IssuingScheduledActivationDate](#schemaissuingscheduledactivationdate)|false|none|Date scheduling the card's first activation. Only applies to the initial activation of a card. Two formats are supported:
- Date only: `YYYY-MM-DD` (treated as midnight UTC)
- Date with round hour: `YYYY-MM-DDTHH:mmZ` (UTC) or `YYYY-MM-DDTHH:mm±HH:mm` (offset)
Only round hours are allowed when a time is provided (`HH:00`). The value must be at least the next round hour after the request time.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|active|
update-card-response
```json
{
"id": "crd_fa6psq242dcd6fdn5gifcq1491",
"client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
"entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"cardholder_id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
"card_product_id": "pro_7syjig3jq3mezlc3vjrdpfitl4",
"user_id": "usr_fa6psq242dcd6fdn5gifcq1491",
"last_four": "1234",
"expiry_month": 5,
"expiry_year": 2025,
"status": "active",
"display_name": "JOHN KENNEDY",
"type": "string",
"billing_currency": "USD",
"issuing_country": "US",
"reference": "X-123456-N11",
"metadata": {
"udf1": "metadata1",
"udf2": "metadata2",
"udf3": "metadata3",
"udf4": "metadata4",
"udf5": "metadata5"
},
"scheduled_revocation_date": "2027-03-12",
"revocation_date": "2027-03-12",
"scheduled_activation_date": "2026-06-01T10:00Z",
"last_activated_on": "2019-09-10T10:11:12Z",
"root_card_id": "crd_fa6psq242dcd6fdn5gifcq1491",
"parent_card_id": "crd_qm26t52qz3yejjo2t4btqvxtzi",
"scheme": "mastercard",
"created_date": "2021-09-09T19:41:39Z",
"last_modified_date": "2021-09-09T19:41:39Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"credentials": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/credentials",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"revoke": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/revoke",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"controls": {
"href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingCardId](#schemaissuingcardid)|true|none|The card's unique identifier.|
|client_id|[IssuingClientId](#schemaissuingclientid)|true|none|The client's unique identifier.|
|entity_id|[IssuingEntityId](#schemaissuingentityid)|true|none|The entity's unique identifier.|
|cardholder_id|[IssuingCardholderId](#schemaissuingcardholderid)|true|none|The cardholder's unique identifier.|
|card_product_id|[IssuingCardProductId](#schemaissuingcardproductid)|true|none|The card product's unique identifier.|
|user_id|[IssuingUserId](#schemaissuinguserid)|false|none|The Dashboard user's unique identifier.|
|last_four|[LastFour](#schemalastfour)|true|none|The last four digits of the card number, also known as the PAN.|
|expiry_month|[ExpiryMonth](#schemaexpirymonth)|true|none|The card's expiration month.|
|expiry_year|[ExpiryYear](#schemaexpiryyear)|true|none|The card's expiration year.|
|status|[IssuingStatus](#schemaissuingstatus)|true|none|The card's status, which determines whether it can approve incoming authorizations:
- `inactive`: the default state - authorizations will be declined until the card is activated
- `active`: authorization requests can be approved
- `suspended`: incoming authorization requests will be declined - the card can be reactivated to accept new authorizations
- `revoked`: incoming authorization requests will be permanently declined - the card cannot be reactivated from this state|
|display_name|[DisplayName](#schemadisplayname)|false|none|The name to display on the card.|
|type|[IssuingType](#schemaissuingtype)|true|none|The card type.|
|billing_currency|[IssuingCurrency](#schemaissuingcurrency)|true|none|The issuing currency, as a three-letter ISO currency code.|
|issuing_country|[IssuingCountry](#schemaissuingcountry)|true|none|The issuing country, as a two-letter ISO country code.|
|reference|[IssuingReference](#schemaissuingreference)|false|none|Your reference.|
|metadata|[IssuingCardMetadata](#schemaissuingcardmetadata)|false|none|User's metadata.|
|scheduled_revocation_date|[IssuingScheduledRevocationDate](#schemaissuingscheduledrevocationdate)|false|none|The card will be revoked at midnight UTC on the date specified.
- Format: `YYYY-MM-DD`|
|revocation_date|[IssuingRevocationDate](#schemaissuingrevocationdate)|false|none|Deprecated. Use `scheduled_revocation_date` instead.|
|scheduled_activation_date|[IssuingScheduledActivationDate](#schemaissuingscheduledactivationdate)|false|none|Date scheduling the card's first activation. Only applies to the initial activation of a card. Two formats are supported:
- Date only: `YYYY-MM-DD` (treated as midnight UTC)
- Date with round hour: `YYYY-MM-DDTHH:mmZ` (UTC) or `YYYY-MM-DDTHH:mm±HH:mm` (offset)
Only round hours are allowed when a time is provided (`HH:00`). The value must be at least the next round hour after the request time.|
|last_activated_on|[LastActivatedOn](#schemalastactivatedon)|false|none|The date and time the card was last activated.
If the card has never been activated, this field returns `null`.|
|root_card_id|[IssuingRootCardId](#schemaissuingrootcardid)|false|none|When a card is renewed, the unique identifier of the first card in the renewal history.|
|parent_card_id|[IssuingParentCardId](#schemaissuingparentcardid)|false|none|When a card is renewed, the unique identifier of the previous card in the renewal history.|
|scheme|[Scheme](#schemascheme)|true|none|the card scheme.|
|created_date|[Datetime](#schemadatetime)|false|none|none|
|last_modified_date|[Datetime](#schemadatetime)|true|none|none|
|_links|[CardLinks](#schemacardlinks)|false|none|The links related to the card.|
update-physical-card-response
```json
{
"id": "crd_fa6psq242dcd6fdn5gifcq1491",
"client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
"entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"cardholder_id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
"card_product_id": "pro_7syjig3jq3mezlc3vjrdpfitl4",
"user_id": "usr_fa6psq242dcd6fdn5gifcq1491",
"last_four": "1234",
"expiry_month": 5,
"expiry_year": 2025,
"status": "active",
"display_name": "JOHN KENNEDY",
"type": "string",
"billing_currency": "USD",
"issuing_country": "US",
"reference": "X-123456-N11",
"metadata": {
"udf1": "metadata1",
"udf2": "metadata2",
"udf3": "metadata3",
"udf4": "metadata4",
"udf5": "metadata5"
},
"scheduled_revocation_date": "2027-03-12",
"revocation_date": "2027-03-12",
"scheduled_activation_date": "2026-06-01T10:00Z",
"last_activated_on": "2019-09-10T10:11:12Z",
"root_card_id": "crd_fa6psq242dcd6fdn5gifcq1491",
"parent_card_id": "crd_qm26t52qz3yejjo2t4btqvxtzi",
"scheme": "mastercard",
"created_date": "2021-09-09T19:41:39Z",
"last_modified_date": "2021-09-09T19:41:39Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"credentials": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/credentials",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"revoke": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/revoke",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"controls": {
"href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}
```
### Properties
allOf - discriminator: update-card-response.type
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[update-card-response](#schemaupdate-card-response)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
update-virtual-card-response
```json
{
"id": "crd_fa6psq242dcd6fdn5gifcq1491",
"client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
"entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"cardholder_id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
"card_product_id": "pro_7syjig3jq3mezlc3vjrdpfitl4",
"user_id": "usr_fa6psq242dcd6fdn5gifcq1491",
"last_four": "1234",
"expiry_month": 5,
"expiry_year": 2025,
"status": "active",
"display_name": "JOHN KENNEDY",
"type": "string",
"billing_currency": "USD",
"issuing_country": "US",
"reference": "X-123456-N11",
"metadata": {
"udf1": "metadata1",
"udf2": "metadata2",
"udf3": "metadata3",
"udf4": "metadata4",
"udf5": "metadata5"
},
"scheduled_revocation_date": "2027-03-12",
"revocation_date": "2027-03-12",
"scheduled_activation_date": "2026-06-01T10:00Z",
"last_activated_on": "2019-09-10T10:11:12Z",
"root_card_id": "crd_fa6psq242dcd6fdn5gifcq1491",
"parent_card_id": "crd_qm26t52qz3yejjo2t4btqvxtzi",
"scheme": "mastercard",
"created_date": "2021-09-09T19:41:39Z",
"last_modified_date": "2021-09-09T19:41:39Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"credentials": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/credentials",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"revoke": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/revoke",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"controls": {
"href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
},
"is_single_use": false
}
```
### Properties
allOf - discriminator: update-card-response.type
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[update-card-response](#schemaupdate-card-response)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» is_single_use|boolean|false|none|Specifies whether the virtual card is set to expire after a single use.|
get-digital-card-response
```json
{
"id": "dcr_5ngxzsynm2me3oxf73esbhda6q",
"card_id": "crd_fa6psq242dcd6fdn5gifcq1491",
"client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
"entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"last_four": "1234",
"status": "active",
"type": "secure_element",
"scheme_card_id": "FAPLMC00002572060f2b2213c3964c44b218665ef9dd0d72",
"requestor": {
"id": "501103353211",
"name": "APPLE PAY"
},
"device": {
"id": "04431C7B514E80018306224737548585F11415F67C4E2EB6",
"type": "iphone",
"manufacturer": "ios",
"brand": "string",
"model": "string",
"os_version": "13",
"firmware_version": "string",
"phone_number": "447505551234",
"device_name": "John's iPhone",
"device_parent_id": "string",
"language": "string",
"serial_number": "string",
"time_zone": "string",
"time_zone_setting": "network_set",
"sim_serial_number": "string",
"imei": "000000000000024",
"network_operator": "string",
"network_type": "wifi"
},
"provisioned_on": "2021-09-09T19:41:39Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/digital-cards/dcr_5ngxzsynm2me3oxf73esbhda6q",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingDigitalCardId](#schemaissuingdigitalcardid)|true|none|The digital card's unique identifier.|
|card_id|[IssuingCardId](#schemaissuingcardid)|true|none|The card's unique identifier.|
|client_id|[IssuingClientId](#schemaissuingclientid)|true|none|The client's unique identifier.|
|entity_id|[IssuingEntityId](#schemaissuingentityid)|true|none|The entity's unique identifier.|
|last_four|[LastFour](#schemalastfour)|true|none|The last four digits of the card number, also known as the PAN.|
|status|[IssuingDigitalStatus](#schemaissuingdigitalstatus)|true|none|The digital card's current status, which determines whether it can approve incoming authorizations:
- `inactive`: the default state - authorizations will be declined until the card is activated
- `active`: authorization requests can be approved
- `deleted`: incoming authorization requests will be declined, permanently — the card cannot be reactivated from this state|
|type|[DigitalCardType](#schemadigitalcardtype)|false|none|The type of digital card|
|scheme_card_id|[IssuingSchemeCardId](#schemaissuingschemecardid)|false|none|The ID that the card scheme’s token service provider (TSP) assigns to the PAN at the first tokenization.|
|requestor|[IssuingRequestor](#schemaissuingrequestor)|false|none|none|
|device|[IssuingDevice](#schemaissuingdevice)|false|none|none|
|provisioned_on|[Datetime](#schemadatetime)|false|none|none|
|_links|[DigitalCardLinks](#schemadigitalcardlinks)|false|none|The links related to the digital card.|
BusinessType
```json
"business_account"
```
The type of business.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The type of business.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|issuing|
|*anonymous*|business_account|
Datetime
```json
"2021-09-09T19:41:39Z"
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string(UTC)|false|none|none|
IssuingAddress
```json
{
"address_line1": "Checkout.com",
"address_line2": "90 Tottenham Court Road",
"city": "London",
"state": "London",
"zip": "W1T 4TJ",
"country": "GB"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|address_line1|string|true|none|The first line of the address.|
|address_line2|string|false|none|The second line of the address.|
|city|string|true|none|The address city.|
|state|string|false|none|The address state.|
|zip|string|true|none|The address zip code, or postal code.|
|country|string|true|none|The address country, as an ISO country code.|
IssuingCardholderId
```json
"crh_d3ozhf43pcq2xbldn2g45qnb44"
```
The cardholder's unique identifier.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The cardholder's unique identifier.|
IssuingCardId
```json
"crd_fa6psq242dcd6fdn5gifcq1491"
```
The card's unique identifier.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The card's unique identifier.|
IssuingCardProductId
```json
"pro_7syjig3jq3mezlc3vjrdpfitl4"
```
The card product's unique identifier.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The card product's unique identifier.|
IssuingClientId
```json
"cli_vkuhvk4vjn2edkps7dfsq6emqm"
```
The client's unique identifier.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The client's unique identifier.|
IssuingCountry
```json
"US"
```
The issuing country, as a two-letter ISO country code.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The issuing country, as a two-letter ISO country code.|
IssuingCurrency
```json
"USD"
```
The issuing currency, as a three-letter ISO currency code.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string(ISO4217)|false|none|The issuing currency, as a three-letter ISO currency code.|
IssuingDigitalCardId
```json
"dcr_5ngxzsynm2me3oxf73esbhda6q"
```
The digital card's unique identifier.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The digital card's unique identifier.|
IssuingEmail
```json
"john.kennedy@myemaildomain.com"
```
The cardholder's email address.
Emails are validated against the rfc6530 standard.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string(email)|false|none|The cardholder's email address.
Emails are validated against the rfc6530 standard.|
IssuingEntityId
```json
"ent_fa6psq242dcd6fdn5gifcq1491"
```
The entity's unique identifier.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The entity's unique identifier.|
IssuingFileId
```json
"file_6lbss42ezvoufcb2beo76rvwly"
```
The unique Checkout.com identifier for the uploaded file.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The unique Checkout.com identifier for the uploaded file.|
IssuingLink
```json
{
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|href|string|true|none|The link URL.|
|actions|[string]|true|none|The HTTP Methods that can be performed on the link.|
|types|[string]|true|none|The Content Types for the link to the resource|
IssuingNotFoundError
```json
{
"request_id": "0HLHPN8802NUF:00000003",
"error_type": "not_found",
"error_codes": [
"card_not_found"
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|request_id|string|false|none|none|
|error_type|string|false|none|none|
|error_codes|[string]|false|none|none|
IssuingParentCardId
```json
"crd_qm26t52qz3yejjo2t4btqvxtzi"
```
When a card is renewed, the unique identifier of the previous card in the renewal history.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|When a card is renewed, the unique identifier of the previous card in the renewal history.|
IssuingPhoneNumber
```json
{
"country_code": "+1",
"number": "415 555 2671"
}
```
The cardholder's mobile phone number. This is used in the card tokenization one-time passcode (OTP) challenge flow and in delivery details for physical cards.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|country_code|string|false|none|The international country calling code.|
|number|string|false|none|A valid phone number without leading zeros.|
IssuingReference
```json
"X-123456-N11"
```
Your reference.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|Your reference.|
IssuingRootCardId
```json
"crd_fa6psq242dcd6fdn5gifcq1491"
```
When a card is renewed, the unique identifier of the first card in the renewal history.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|When a card is renewed, the unique identifier of the first card in the renewal history.|
IssuingSchemeCardId
```json
"FAPLMC00002572060f2b2213c3964c44b218665ef9dd0d72"
```
The ID that the card scheme’s token service provider (TSP) assigns to the PAN at the first tokenization.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The ID that the card scheme’s token service provider (TSP) assigns to the PAN at the first tokenization.|
```json
{
"first_name": "John",
"last_name": "Kennedy",
"phone_number": {
"country_code": "+1",
"number": "415 555 2671"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|first_name|string|true|none|The cardholder's first name.|
|last_name|string|true|none|The cardholder's last name.|
|phone_number|[IssuingPhoneNumber](#schemaissuingphonenumber)|true|none|The cardholder's mobile phone number. This is used in the card tokenization one-time passcode (OTP) challenge flow and in delivery details for physical cards.|
IssuingShippingInstruction
```json
{
"shipping_address": {
"address_line1": "Checkout.com",
"address_line2": "90 Tottenham Court Road",
"city": "London",
"state": "London",
"zip": "W1T 4TJ",
"country": "GB"
},
"shipping_recipient": "john kennedy",
"additional_comment": "string"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|shipping_address|[IssuingAddress](#schemaissuingaddress)|true|none|The address to ship the physical card to.|
|shipping_recipient|string|false|none|The name of the person the card will be shipped to.|
|additional_comment|string|false|none|Any additional comment on shipping.|
IssuingUserId
```json
"usr_fa6psq242dcd6fdn5gifcq1491"
```
The Dashboard user's unique identifier.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The Dashboard user's unique identifier.|
IssuingValidationError
```json
{
"request_id": "0HLHPN8802NUF:00000003",
"error_type": "request_invalid",
"error_codes": [
"request_body_malformed"
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|request_id|string|false|none|none|
|error_type|string|false|none|none|
|error_codes|[string]|false|none|none|
cko-request-id
```json
"3729b06b-5a63-4425-bc34-23dfc158ddfe"
```
ID to correlate requests.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|ID to correlate requests.|
add-control-group-mcc-limit-request
```json
{
"description": "string",
"control_type": "mcc_limit",
"mcc_limit": {
"type": "allow",
"mcc_list": [
"5932",
"5411"
]
}
}
```
mcc_limit
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|description|string|false|none|A description for the control.|
|control_type|[IssuingControlType](#schemaissuingcontroltype)|true|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
|mcc_limit|[MccLimit](#schemamcclimit)|true|none|The merchant category code (MCC) rule, which determines the types of businesses transactions can be processed from.|
add-control-group-mid-limit-request
```json
{
"description": "string",
"control_type": "mid_limit",
"mid_limit": {
"type": "allow",
"mid_list": [
"593278",
"541114"
]
}
}
```
mid_limit
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|description|string|false|none|A description for the control.|
|control_type|[IssuingControlType](#schemaissuingcontroltype)|true|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
|mid_limit|[MidLimit](#schemamidlimit)|true|none|The merchant identification (MID) code rule, which determines the merchants from whom transactions can be processed.|
add-control-group-request-control
```json
{
"description": "string",
"control_type": "velocity_limit",
"velocity_limit": {
"amount_limit": 50000,
"velocity_window": {
"type": "weekly"
},
"mcc_list": [
"string"
],
"mid_list": [
"1234567890"
]
}
}
```
The control to create.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|description|string|false|none|A description for the control.|
|control_type|[IssuingControlType](#schemaissuingcontroltype)|true|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[add-control-group-velocity-limit-request](#schemaadd-control-group-velocity-limit-request)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[add-control-group-mcc-limit-request](#schemaadd-control-group-mcc-limit-request)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[add-control-group-mid-limit-request](#schemaadd-control-group-mid-limit-request)|false|none|none|
add-control-group-request
```json
{
"description": "Block grocery shopping except Walmart",
"fail_if": "all_fail",
"target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
"controls": [
{
"description": "Block the card being used for groceries",
"control_type": "mcc_limit",
"mcc_limit": {
"type": "block",
"mcc_list": [
"5422"
]
}
},
{
"description": "Allow the card to be used at Walmart",
"control_type": "mid_limit",
"mid_limit": {
"type": "allow",
"mid_list": [
"1234"
]
}
}
]
}
```
The control group to create.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|description|string|false|none|A description for the control group.|
|target_id|[IssuingTargetIdForAdd](#schemaissuingtargetidforadd)|true|none|The ID of the card or control profile to apply the control to. Note that control profiles cannot be a target for `velocity_limit` controls.|
|fail_if|[ControlGroupCondition](#schemacontrolgroupcondition)|true|none|Sets how to determine the result of the group.|
|controls|[[add-control-group-request-control](#schemaadd-control-group-request-control)]|true|none|The controls that belong to the group.|
add-control-group-response
```json
{
"id": "cgr_oemoyd3otivelkhf4zcnimwdva",
"description": "Block grocery shopping except Walmart",
"target_id": "crd_dba7tjsh7utufgid7yety4gnxq",
"fail_if": "all_fail",
"controls": [
{
"mcc_limit": {
"type": "block",
"mcc_list": [
"5422"
]
},
"description": "Block the card being used for groceries",
"control_type": "mcc_limit"
},
{
"mid_limit": {
"type": "allow",
"mid_list": [
"1234"
]
},
"description": "Allow the card to be used at Walmart",
"control_type": "mid_limit"
}
],
"is_editable": true,
"created_date": "2023-12-06T14:01:31.7155085Z",
"last_modified_date": "2023-12-06T14:01:31.7155085Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/controls/control-groups/cgr_oemoyd3otivelkhf4zcnimwdva",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}
```
The control group's details.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingControlGroupId](#schemaissuingcontrolgroupid)|true|none|The control group's unique identifier.|
|description|string|false|none|A description for the control group.|
|target_id|[IssuingTargetId](#schemaissuingtargetid)|true|none|The ID of the card or control profile.|
|fail_if|[ControlGroupCondition](#schemacontrolgroupcondition)|true|none|Sets how to determine the result of the group.|
|controls|[[add-control-group-request-control](#schemaadd-control-group-request-control)]|true|none|The controls that belong to the group.|
|is_editable|[ControlGroupIsEditable](#schemacontrolgroupiseditable)|true|none|Indicates whether the control group is set to readonly. Control groups marked as non-editable are predefined by Checkout and are not modifiable by clients.|
|created_date|string(date-time)|true|none|none|
|last_modified_date|string(date-time)|true|none|none|
|_links|[ControlGroupLinks](#schemacontrolgrouplinks)|true|none|The links related to the control group.|
add-control-group-velocity-limit-request
```json
{
"description": "string",
"control_type": "velocity_limit",
"velocity_limit": {
"amount_limit": 50000,
"velocity_window": {
"type": "weekly"
},
"mcc_list": [
"string"
],
"mid_list": [
"1234567890"
]
}
}
```
velocity_limit
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|description|string|false|none|A description for the control.|
|control_type|[IssuingControlType](#schemaissuingcontroltype)|true|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
|velocity_limit|[VelocityLimit](#schemavelocitylimit)|true|none|The velocity limit, which determines how much a target card can spend over a given timeframe.|
add-control-profile-request
```json
{
"name": "Low Risk MCC Profile"
}
```
The control profile to create
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|true|none|Control profile name.|
add-control-profile-target-response
```json
{
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/controls/control-profiles/cpr_j4mvlui5qotufgvaeqwhvlbfna",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|_links|[ControlProfileLinks](#schemacontrolprofilelinks)|false|none|The links related to the control profile.|
add-update-control-profile-response
```json
{
"id": "cpr_j4mvlui5qotufgvaeqwhvlbfna",
"name": "Low Risk MCC Profile",
"created_date": "2024-03-12T18:13:45.7155085Z",
"last_modified_date": "2024-03-12T18:13:45.7155085Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/controls/control-profiles/cpr_j4mvlui5qotufgvaeqwhvlbfna",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}
```
The control profile's details.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingControlProfileId](#schemaissuingcontrolprofileid)|true|none|The control profile's unique identifier.|
|name|string|true|none|Control profile name.|
|created_date|string(date-time)|true|none|Creation date of the control profile.|
|last_modified_date|string(date-time)|true|none|none|
|_links|[ControlProfileLinks](#schemacontrolprofilelinks)|true|none|The links related to the control profile.|
add-control-request
```json
{
"description": "Maximum spend of 500€ per week for restaurants",
"control_type": "velocity_limit",
"target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
"velocity_limit": {
"amount_limit": 50000,
"velocity_window": {
"type": "weekly"
},
"mcc_list": [
"string"
],
"mid_list": [
"1234567890"
]
}
}
```
The control to create.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|description|string|false|none|A description for the control.|
|control_type|[IssuingControlType](#schemaissuingcontroltype)|true|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
|target_id|[IssuingTargetIdForAdd](#schemaissuingtargetidforadd)|true|none|The ID of the card or control profile to apply the control to. Note that control profiles cannot be a target for `velocity_limit` controls.|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[velocity-limit-request](#schemavelocity-limit-request)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[mcc-limit-request](#schemamcc-limit-request)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[mid-limit-request](#schemamid-limit-request)|false|none|none|
add-control-response
```json
{
"id": "ctr_gp7vkmxayztufjz6top5bjcdra",
"description": "Maximum spend of 500€ per week for restaurants",
"control_type": "velocity_limit",
"target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
"is_editable": true,
"created_date": "2023-03-12T18:20:12Z",
"last_modified_date": "2023-03-12T18:20:12Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/controls/ctr_mbvprn5bm27ubh4c5rq5tha2wy",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
},
"velocity_limit": {
"amount_limit": 50000,
"velocity_window": {
"type": "weekly"
},
"mcc_list": [
"string"
],
"mid_list": [
"1234567890"
]
}
}
```
The control's details.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingControlId](#schemaissuingcontrolid)|true|none|The control's unique identifier.|
|description|string|false|none|A description for the control.|
|control_type|[IssuingControlType](#schemaissuingcontroltype)|true|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
|target_id|[IssuingTargetId](#schemaissuingtargetid)|true|none|The ID of the card or control profile.|
|is_editable|[ControlIsEditable](#schemacontroliseditable)|true|none|Indicates whether you can change this control.
`false` This is an immutable control applied by Checkout.com and you cannot change it.
`true` You applied this control and can change it.|
|created_date|string(date-time)|true|none|none|
|last_modified_date|string(date-time)|true|none|none|
|_links|[ControlLinks](#schemacontrollinks)|true|none|The links related to the control.|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[velocity-limit-response](#schemavelocity-limit-response)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[mcc-limit-response](#schemamcc-limit-response)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[mid-limit-response](#schemamid-limit-response)|false|none|none|
mcc-limit-request
```json
{
"description": "Allow the card to be used only in restaurants and supermarkets",
"control_type": "mcc_limit",
"target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
"mcc_limit": {
"type": "allow",
"mcc_list": [
"5932",
"5411"
]
}
}
```
mcc_limit
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|description|string|false|none|A description for the control.|
|control_type|[IssuingControlType](#schemaissuingcontroltype)|true|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
|target_id|[IssuingTargetIdForAdd](#schemaissuingtargetidforadd)|true|none|The ID of the card or control profile to apply the control to. Note that control profiles cannot be a target for `velocity_limit` controls.|
|mcc_limit|[MccLimit](#schemamcclimit)|true|none|The merchant category code (MCC) rule, which determines the types of businesses transactions can be processed from.|
mcc-limit-response
```json
{
"id": "ctr_gp7vkmxayztufjz6top5bjcdra",
"description": "Allow the card to be used only in restaurants and supermarkets",
"control_type": "mcc_limit",
"target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
"is_editable": true,
"created_date": "2023-03-12T18:20:12Z",
"last_modified_date": "2023-03-12T18:20:12Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/controls/ctr_mbvprn5bm27ubh4c5rq5tha2wy",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
},
"mcc_limit": {
"type": "allow",
"mcc_list": [
"5932",
"5411"
]
}
}
```
mcc_limit
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingControlId](#schemaissuingcontrolid)|true|none|The control's unique identifier.|
|description|string|false|none|A description for the control.|
|control_type|any|true|none|none|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[IssuingControlType](#schemaissuingcontroltype)|false|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|target_id|[IssuingTargetId](#schemaissuingtargetid)|true|none|The ID of the card or control profile.|
|is_editable|[ControlIsEditable](#schemacontroliseditable)|true|none|Indicates whether you can change this control.
`false` This is an immutable control applied by Checkout.com and you cannot change it.
`true` You applied this control and can change it.|
|created_date|string(date-time)|true|none|none|
|last_modified_date|string(date-time)|true|none|none|
|_links|[ControlLinks](#schemacontrollinks)|true|none|The links related to the control.|
|mcc_limit|[MccLimit](#schemamcclimit)|true|none|The merchant category code (MCC) rule, which determines the types of businesses transactions can be processed from.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|mcc_limit|
mid-limit-request
```json
{
"description": "Allow the card to be used only in AZ Pizza",
"control_type": "mid_limit",
"target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
"mid_limit": {
"type": "allow",
"mid_list": [
"593278",
"541114"
]
}
}
```
mid_limit
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|description|string|false|none|A description for the control.|
|control_type|[IssuingControlType](#schemaissuingcontroltype)|true|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
|target_id|[IssuingTargetIdForAdd](#schemaissuingtargetidforadd)|true|none|The ID of the card or control profile to apply the control to. Note that control profiles cannot be a target for `velocity_limit` controls.|
|mid_limit|[MidLimit](#schemamidlimit)|true|none|The merchant identification (MID) code rule, which determines the merchants from whom transactions can be processed.|
mid-limit-response
```json
{
"id": "ctr_gp7vkmxayztufjz6top5bjcdra",
"description": "Allow the card to be used only in AZ Pizza",
"control_type": "mid_limit",
"target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
"is_editable": true,
"created_date": "2023-03-12T18:20:12Z",
"last_modified_date": "2023-03-12T18:20:12Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/controls/ctr_mbvprn5bm27ubh4c5rq5tha2wy",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
},
"mid_limit": {
"type": "allow",
"mid_list": [
"593278",
"541114"
]
}
}
```
mid_limit
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingControlId](#schemaissuingcontrolid)|true|none|The control's unique identifier.|
|description|string|false|none|A description for the control.|
|control_type|any|true|none|none|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[IssuingControlType](#schemaissuingcontroltype)|false|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|target_id|[IssuingTargetId](#schemaissuingtargetid)|true|none|The ID of the card or control profile.|
|is_editable|[ControlIsEditable](#schemacontroliseditable)|true|none|Indicates whether you can change this control.
`false` This is an immutable control applied by Checkout.com and you cannot change it.
`true` You applied this control and can change it.|
|created_date|string(date-time)|true|none|none|
|last_modified_date|string(date-time)|true|none|none|
|_links|[ControlLinks](#schemacontrollinks)|true|none|The links related to the control.|
|mid_limit|[MidLimit](#schemamidlimit)|true|none|The merchant identification (MID) code rule, which determines the merchants from whom transactions can be processed.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|mid_limit|
velocity-limit-request
```json
{
"description": "Maximum spend of 500€ per week for restaurants",
"control_type": "velocity_limit",
"target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
"velocity_limit": {
"amount_limit": 50000,
"velocity_window": {
"type": "weekly"
},
"mcc_list": [
"string"
],
"mid_list": [
"1234567890"
]
}
}
```
velocity_limit
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|description|string|false|none|A description for the control.|
|control_type|[IssuingControlType](#schemaissuingcontroltype)|true|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
|target_id|[IssuingTargetIdForAdd](#schemaissuingtargetidforadd)|true|none|The ID of the card or control profile to apply the control to. Note that control profiles cannot be a target for `velocity_limit` controls.|
|velocity_limit|[VelocityLimit](#schemavelocitylimit)|true|none|The velocity limit, which determines how much a target card can spend over a given timeframe.|
velocity-limit-response
```json
{
"id": "ctr_gp7vkmxayztufjz6top5bjcdra",
"description": "Maximum spend of 500€ per week for restaurants",
"control_type": "velocity_limit",
"target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
"is_editable": true,
"created_date": "2023-03-12T18:20:12Z",
"last_modified_date": "2023-03-12T18:20:12Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/controls/ctr_mbvprn5bm27ubh4c5rq5tha2wy",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
},
"velocity_limit": {
"amount_limit": 50000,
"velocity_window": {
"type": "weekly"
},
"mcc_list": [
"string"
],
"mid_list": [
"1234567890"
]
}
}
```
velocity_limit
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingControlId](#schemaissuingcontrolid)|true|none|The control's unique identifier.|
|description|string|false|none|A description for the control.|
|control_type|any|true|none|none|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[IssuingControlType](#schemaissuingcontroltype)|false|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|target_id|[IssuingTargetId](#schemaissuingtargetid)|true|none|The ID of the card or control profile.|
|is_editable|[ControlIsEditable](#schemacontroliseditable)|true|none|Indicates whether you can change this control.
`false` This is an immutable control applied by Checkout.com and you cannot change it.
`true` You applied this control and can change it.|
|created_date|string(date-time)|true|none|none|
|last_modified_date|string(date-time)|true|none|none|
|_links|[ControlLinks](#schemacontrollinks)|true|none|The links related to the control.|
|velocity_limit|[VelocityLimit](#schemavelocitylimit)|true|none|The velocity limit, which determines how much a target card can spend over a given timeframe.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|velocity_limit|
get-control-group-response
```json
{
"id": "cgr_oemoyd3otivelkhf4zcnimwdva",
"description": "string",
"target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
"fail_if": "all_fail",
"controls": [
{
"description": "string",
"control_type": "velocity_limit",
"velocity_limit": {
"amount_limit": 50000,
"velocity_window": {
"type": "weekly"
},
"mcc_list": [
"string"
],
"mid_list": [
"1234567890"
]
}
}
],
"is_editable": true,
"created_date": "2019-08-24T14:15:22Z",
"last_modified_date": "2019-08-24T14:15:22Z"
}
```
The control group's details.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingControlGroupId](#schemaissuingcontrolgroupid)|true|none|The control group's unique identifier.|
|description|string|false|none|A description for the control group.|
|target_id|[IssuingTargetId](#schemaissuingtargetid)|true|none|The ID of the card or control profile.|
|fail_if|[ControlGroupCondition](#schemacontrolgroupcondition)|true|none|Sets how to determine the result of the group.|
|controls|[[add-control-group-request-control](#schemaadd-control-group-request-control)]|true|none|The controls that belong to the group.|
|is_editable|[ControlGroupIsEditable](#schemacontrolgroupiseditable)|true|none|Indicates whether the control group is set to readonly. Control groups marked as non-editable are predefined by Checkout and are not modifiable by clients.|
|created_date|string(date-time)|true|none|none|
|last_modified_date|string(date-time)|true|none|none|
get-control-groups-array-response
```json
{
"control_groups": [
{
"id": "cgr_oemoyd3otivelkhf4zcnimwdva",
"description": "Block grocery shopping except Walmart",
"target_id": "crd_dba7tjsh7utufgid7yety4gnxq",
"fail_if": "all_fail",
"controls": [
{
"mcc_limit": {
"type": "block",
"mcc_list": [
"5422"
]
},
"description": "Block the card being used for groceries",
"control_type": "mcc_limit"
},
{
"mid_limit": {
"type": "allow",
"mid_list": [
"1234"
]
},
"description": "Allow the card to be used at Walmart",
"control_type": "mid_limit"
}
],
"is_editable": true,
"created_date": "2023-12-06T14:01:31.7155085Z",
"last_modified_date": "2023-12-06T14:01:31.7155085Z"
},
{
"id": "cgr_xvrszbgkaifuflnslzkt2uimkm",
"description": "Allow restaurants except McDonalds",
"target_id": "crd_dba7tjsh7utufgid7yety4gnxq",
"fail_if": "all_fail",
"controls": [
{
"mcc_limit": {
"type": "allow",
"mcc_list": [
"6789"
]
},
"description": "Allow the card being used for restaurants",
"control_type": "mcc_limit"
},
{
"mid_limit": {
"type": "block",
"mid_list": [
"9876"
]
},
"description": "Block the card to be used at McDonalds",
"control_type": "mid_limit"
}
],
"is_editable": true,
"created_date": "2023-12-06T14:01:31.7155085Z",
"last_modified_date": "2023-12-06T14:01:31.7155085Z"
}
]
}
```
The list of control groups applied to the specified target.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|control_groups|[[get-control-group-response](#schemaget-control-group-response)]|true|none|The list of control groups applied to the specified target.|
get-control-profile-response
```json
{
"id": "cpr_j4mvlui5qotufgvaeqwhvlbfna",
"name": "string",
"created_date": "2019-08-24T14:15:22Z",
"last_modified_date": "2019-08-24T14:15:22Z"
}
```
The control profile's details.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingControlProfileId](#schemaissuingcontrolprofileid)|true|none|The control profile's unique identifier.|
|name|string|true|none|Control profile name.|
|created_date|string(date-time)|true|none|Creation date of the control profile.|
|last_modified_date|string(date-time)|true|none|Last modified date of the control profile.|
get-control-profiles-client-response
```json
{
"control_profiles": [
{
"id": "cpr_j4mvlui5qotufgvaeqwhvlbfna",
"name": "Low Risk MCC Profile",
"created_date": "2024-03-12T18:13:45.7155085Z",
"last_modified_date": "2024-03-13T15:44:56.7155085Z"
},
{
"id": "cpr_53mkhdc4jjlu5jcryx76bjbrgm",
"name": "Medium Risk MCC Profile",
"created_date": "2024-05-05T10:43:13.7155085Z",
"last_modified_date": "2024-06-17T06:32:18.7155085Z"
},
{
"id": "cpr_j4ma3rclvgcu3pn5tsdgb3e3a4",
"name": "High Risk MCC Profile",
"created_date": "2024-02-29T12:55:55.7155085Z",
"last_modified_date": "2024-03-01T10:12:12.7155085Z"
}
]
}
```
The list of control profiles for the specified client.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|control_profiles|[[get-control-profile-response](#schemaget-control-profile-response)]|true|none|The list of control profiles for the specified client.|
get-control-mcc-limit-response
```json
{
"id": "ctr_gp7vkmxayztufjz6top5bjcdra",
"target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
"description": "Allow the card to be used only in restaurants and supermarkets",
"control_type": "mcc_limit",
"is_editable": true,
"created_date": "2021-09-09T19:41:39Z",
"last_modified_date": "2021-09-09T19:41:39Z",
"mcc_limit": {
"type": "allow",
"mcc_list": [
"5932",
"5411"
]
}
}
```
mcc_limit
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingControlId](#schemaissuingcontrolid)|true|none|The control's unique identifier.|
|target_id|[IssuingTargetId](#schemaissuingtargetid)|true|none|The ID of the card or control profile.|
|description|string|true|none|A description for the control.|
|control_type|[IssuingControlType](#schemaissuingcontroltype)|true|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
|is_editable|[ControlIsEditable](#schemacontroliseditable)|true|none|Indicates whether you can change this control.
`false` This is an immutable control applied by Checkout.com and you cannot change it.
`true` You applied this control and can change it.|
|created_date|[Datetime](#schemadatetime)|true|none|none|
|last_modified_date|[Datetime](#schemadatetime)|true|none|none|
|mcc_limit|[MccLimit](#schemamcclimit)|true|none|The merchant category code (MCC) rule, which determines the types of businesses transactions can be processed from.|
get-control-mid-limit-response
```json
{
"id": "ctr_gp7vkmxayztufjz6top5bjcdra",
"target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
"description": "Allow the card to be used only in AZ Pizza",
"control_type": "mid_limit",
"is_editable": true,
"created_date": "2021-09-09T19:41:39Z",
"last_modified_date": "2021-09-09T19:41:39Z",
"mid_limit": {
"type": "allow",
"mid_list": [
"593278",
"541114"
]
}
}
```
mid_limit
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingControlId](#schemaissuingcontrolid)|true|none|The control's unique identifier.|
|target_id|[IssuingTargetId](#schemaissuingtargetid)|true|none|The ID of the card or control profile.|
|description|string|true|none|A description for the control.|
|control_type|[IssuingControlType](#schemaissuingcontroltype)|true|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
|is_editable|[ControlIsEditable](#schemacontroliseditable)|true|none|Indicates whether you can change this control.
`false` This is an immutable control applied by Checkout.com and you cannot change it.
`true` You applied this control and can change it.|
|created_date|[Datetime](#schemadatetime)|true|none|none|
|last_modified_date|[Datetime](#schemadatetime)|true|none|none|
|mid_limit|[MidLimit](#schemamidlimit)|true|none|The merchant identification (MID) code rule, which determines the merchants from whom transactions can be processed.|
get-control-response
```json
{
"id": "ctr_gp7vkmxayztufjz6top5bjcdra",
"target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
"description": "Maximum spend of 500€ per week for restaurants",
"control_type": "velocity_limit",
"is_editable": true,
"created_date": "2021-09-09T19:41:39Z",
"last_modified_date": "2021-09-09T19:41:39Z",
"velocity_limit": {
"amount_remaining": 45000,
"amount_limit": 50000,
"velocity_window": {
"type": "weekly"
},
"mcc_list": [
"4121",
"4582"
],
"mid_list": [
"1234567890"
]
}
}
```
The control's details.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingControlId](#schemaissuingcontrolid)|true|none|The control's unique identifier.|
|target_id|[IssuingTargetId](#schemaissuingtargetid)|true|none|The ID of the card or control profile.|
|description|string|true|none|A description for the control.|
|control_type|[IssuingControlType](#schemaissuingcontroltype)|true|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
|is_editable|[ControlIsEditable](#schemacontroliseditable)|true|none|Indicates whether you can change this control.
`false` This is an immutable control applied by Checkout.com and you cannot change it.
`true` You applied this control and can change it.|
|created_date|[Datetime](#schemadatetime)|true|none|none|
|last_modified_date|[Datetime](#schemadatetime)|true|none|none|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[get-control-velocity-limit-response](#schemaget-control-velocity-limit-response)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[get-control-mcc-limit-response](#schemaget-control-mcc-limit-response)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[get-control-mid-limit-response](#schemaget-control-mid-limit-response)|false|none|none|
get-control-velocity-limit-response
```json
{
"id": "ctr_gp7vkmxayztufjz6top5bjcdra",
"target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
"description": "Maximum spend of 500€ per week for restaurants",
"control_type": "velocity_limit",
"is_editable": true,
"created_date": "2021-09-09T19:41:39Z",
"last_modified_date": "2021-09-09T19:41:39Z",
"velocity_limit": {
"amount_remaining": 45000,
"amount_limit": 50000,
"velocity_window": {
"type": "weekly"
},
"mcc_list": [
"4121",
"4582"
],
"mid_list": [
"1234567890"
]
}
}
```
velocity_limit
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingControlId](#schemaissuingcontrolid)|true|none|The control's unique identifier.|
|target_id|[IssuingTargetId](#schemaissuingtargetid)|true|none|The ID of the card or control profile.|
|description|string|true|none|A description for the control.|
|control_type|[IssuingControlType](#schemaissuingcontroltype)|true|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
|is_editable|[ControlIsEditable](#schemacontroliseditable)|true|none|Indicates whether you can change this control.
`false` This is an immutable control applied by Checkout.com and you cannot change it.
`true` You applied this control and can change it.|
|created_date|[Datetime](#schemadatetime)|true|none|none|
|last_modified_date|[Datetime](#schemadatetime)|true|none|none|
|velocity_limit|[VelocityLimitWithRemainingAmount](#schemavelocitylimitwithremainingamount)|true|none|The velocity limit, which determines how much a target card can spend over a given timeframe.|
get-controls-array-response
```json
{
"controls": [
{
"id": "ctr_gp7vkmxayztufjz6top5bjcdra",
"target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
"description": "Maximum spend of 500€ per week for restaurants",
"control_type": "velocity_limit",
"is_editable": true,
"created_date": "2021-09-09T19:41:39Z",
"last_modified_date": "2021-09-09T19:41:39Z",
"velocity_limit": {
"amount_remaining": 45000,
"amount_limit": 50000,
"velocity_window": {
"type": "weekly"
},
"mcc_list": [
"4121",
"4582"
]
}
},
{
"id": "ctr_gp7vkmxayztufjz6top5bjcdra",
"target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
"description": "Allow the card to be used only in restaurants and supermarkets",
"control_type": "mcc_limit",
"is_editable": true,
"created_date": "2021-09-09T19:41:39Z",
"last_modified_date": "2021-09-09T19:41:39Z",
"mcc_limit": {
"type": "allow",
"mcc_list": [
"5932",
"5411"
]
}
},
{
"id": "ctr_gp7vkmxayztufjz6top5bjcdra",
"target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
"description": "Allow the card to be used only in AZ Pizza",
"control_type": "mid_limit",
"is_editable": true,
"created_date": "2021-09-09T19:41:39Z",
"last_modified_date": "2021-09-09T19:41:39Z",
"mid_limit": {
"type": "allow",
"mid_list": [
"593278",
"541114"
]
}
}
]
}
```
The list of controls applied to the specified target.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|controls|[[get-control-response](#schemaget-control-response)]|true|none|The list of controls applied to the specified target.|
ControlGroupCondition
```json
"all_fail"
```
Sets how to determine the result of the group.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|Sets how to determine the result of the group.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|all_fail|
|*anonymous*|any_fail|
ControlGroupIsEditable
```json
true
```
Indicates whether the control group is set to readonly. Control groups marked as non-editable are predefined by Checkout and are not modifiable by clients.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|boolean|false|none|Indicates whether the control group is set to readonly. Control groups marked as non-editable are predefined by Checkout and are not modifiable by clients.|
ControlGroupLinks
```json
{
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/controls/control-groups/cgr_oemoyd3otivelkhf4zcnimwdva",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
```
The links related to the control group.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|self|[IssuingLink](#schemaissuinglink)|true|none|The URI to retrieve the control group's details.|
ControlIsEditable
```json
true
```
Indicates whether you can change this control.
`false` This is an immutable control applied by Checkout.com and you cannot change it.
`true` You applied this control and can change it.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|boolean|false|none|Indicates whether you can change this control.
`false` This is an immutable control applied by Checkout.com and you cannot change it.
`true` You applied this control and can change it.|
ControlLinks
```json
{
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/controls/ctr_mbvprn5bm27ubh4c5rq5tha2wy",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
```
The links related to the control.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|self|[IssuingLink](#schemaissuinglink)|true|none|The URI to retrieve the control's details.|
ControlProfileLinks
```json
{
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/controls/control-profiles/cpr_j4mvlui5qotufgvaeqwhvlbfna",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
```
The links related to the control profile.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|self|[IssuingLink](#schemaissuinglink)|true|none|The URI to retrieve the control profile's details.|
IssuingControlGroupId
```json
"cgr_oemoyd3otivelkhf4zcnimwdva"
```
The control group's unique identifier.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The control group's unique identifier.|
IssuingControlId
```json
"ctr_gp7vkmxayztufjz6top5bjcdra"
```
The control's unique identifier.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The control's unique identifier.|
IssuingControlProfileId
```json
"cpr_j4mvlui5qotufgvaeqwhvlbfna"
```
The control profile's unique identifier.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The control profile's unique identifier.|
IssuingControlType
```json
"velocity_limit"
```
The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|velocity_limit|
|*anonymous*|mcc_limit|
|*anonymous*|mid_limit|
IssuingTargetId
```json
"crd_fa6psq42dcdd6fdn5gifcq1491"
```
The ID of the card or control profile.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The ID of the card or control profile.|
IssuingTargetIdForAdd
```json
"crd_fa6psq42dcdd6fdn5gifcq1491"
```
The ID of the card or control profile to apply the control to. Note that control profiles cannot be a target for `velocity_limit` controls.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The ID of the card or control profile to apply the control to. Note that control profiles cannot be a target for `velocity_limit` controls.|
IssuingTargetIdToAddToControlProfile
```json
"crd_fa6psq42dcdd6fdn5gifcq1491"
```
The ID of the card to apply the control profile to.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The ID of the card to apply the control profile to.|
IssuingTargetIdToRemoveFromControlProfile
```json
"crd_fa6psq42dcdd6fdn5gifcq1491"
```
The ID of the card the control profile should no longer apply to.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The ID of the card the control profile should no longer apply to.|
MccLimit
```json
{
"type": "allow",
"mcc_list": [
"5932",
"5411"
]
}
```
The merchant category code (MCC) rule, which determines the types of businesses transactions can be processed from.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|Sets whether to allow or block the list of MCCs supplied.|
|mcc_list|[string]|true|none|The list of MCCs to allow or block transactions from, as 4-digit ISO 18245 codes.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|allow|
|type|block|
MidCode
```json
"string"
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|none|
MidLimit
```json
{
"type": "allow",
"mid_list": [
"593278",
"541114"
]
}
```
The merchant identification (MID) code rule, which determines the merchants from whom transactions can be processed.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|Sets whether to allow or block the list of MIDs supplied.|
|mid_list|[[MidCode](#schemamidcode)]|true|none|The list of merchant identification (MID) codes to allow or block transactions from.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|allow|
|type|block|
VelocityLimit
```json
{
"amount_limit": 50000,
"velocity_window": {
"type": "weekly"
},
"mcc_list": [
"string"
],
"mid_list": [
"1234567890"
]
}
```
The velocity limit, which determines how much a target card can spend over a given timeframe.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|amount_limit|integer(int64)|true|none|The amount the target can spend, in minor units.|
|velocity_window|[VelocityWindow](#schemavelocitywindow)|true|none|The period of time over which the specified `amount_limit` can be spent.|
|mcc_list|[string]|false|none|The list of merchant category codes (MCCs) that the velocity limit applies to, as four-digit ISO 18245 codes.|
|mid_list|[[MidCode](#schemamidcode)]|false|none|The list of merchant identification (MID) codes to allow or block transactions from.
You can provide either `mcc_list` or `mid_list`, but not both.|
VelocityLimitWithRemainingAmount
```json
{
"amount_remaining": 45000,
"amount_limit": 50000,
"velocity_window": {
"type": "weekly"
},
"mcc_list": [
"4121",
"4582"
],
"mid_list": [
"1234567890"
]
}
```
The velocity limit, which determines how much a target card can spend over a given timeframe.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|amount_remaining|integer(int64)|true|none|The remaining amount that can be spent, in minor units.|
|amount_limit|integer(int64)|true|none|The amount that can be spent, in minor units.|
|velocity_window|[VelocityWindow](#schemavelocitywindow)|true|none|The period of time over which the specified `amount_limit` can be spent.|
|mcc_list|[string]|false|none|The list of merchant category codes (MCCs) that the velocity limit applies to, as four-digit ISO 18245 codes.|
|mid_list|[string]|false|none|The list of merchant identification (MID) codes to allow or block transactions from.
You can provide either `mcc_list` or `mid_list`, but not both.|
VelocityWindow
```json
{
"type": "weekly"
}
```
The period of time over which the specified `amount_limit` can be spent.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The velocity window's unit of time.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|daily|
|type|weekly|
|type|monthly|
|type|all_time|
remove-control-group-response
```json
{
"id": "cgr_oemoyd3otivelkhf4zcnimwdva"
}
```
The control groups's details.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingControlGroupId](#schemaissuingcontrolgroupid)|true|none|The control group's unique identifier.|
remove-control-profile-target-response
```json
{
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/controls/control-profiles/cpr_j4mvlui5qotufgvaeqwhvlbfna",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|_links|[ControlProfileLinks](#schemacontrolprofilelinks)|false|none|The links related to the control profile.|
remove-control-response
```json
{
"id": "ctr_gp7vkmxayztufjz6top5bjcdra"
}
```
The control's details.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingControlId](#schemaissuingcontrolid)|true|none|The control's unique identifier.|
update-control-profile-request
```json
{
"name": "Low Risk MCC Profile"
}
```
The control profile to update.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|false|none|The control profile name.|
update-control-mcc-limit-response
```json
{
"id": "ctr_gp7vkmxayztufjz6top5bjcdra",
"description": "Allow the card to be used only in restaurants and supermarkets",
"control_type": "velocity_limit",
"target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
"is_editable": true,
"created_date": "2021-09-09T19:41:39Z",
"last_modified_date": "2021-09-09T19:41:39Z",
"mcc_limit": {
"type": "allow",
"mcc_list": [
"5932",
"5411"
]
}
}
```
### Properties
allOf - discriminator: update-control-response.control_type
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[update-control-response](#schemaupdate-control-response)|false|none|The control's details.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» mcc_limit|[MccLimit](#schemamcclimit)|false|none|The merchant category code (MCC) rule, which determines the types of businesses transactions can be processed from.|
|» description|string|false|none|A description for the control.|
update-control-mid-limit-response
```json
{
"id": "ctr_gp7vkmxayztufjz6top5bjcdra",
"description": "Allow the card to be used only in AZ Pizza",
"control_type": "velocity_limit",
"target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
"is_editable": true,
"created_date": "2021-09-09T19:41:39Z",
"last_modified_date": "2021-09-09T19:41:39Z",
"mid_limit": {
"type": "allow",
"mid_list": [
"593278",
"541114"
]
}
}
```
### Properties
allOf - discriminator: update-control-response.control_type
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[update-control-response](#schemaupdate-control-response)|false|none|The control's details.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» mid_limit|[MidLimit](#schemamidlimit)|false|none|The merchant identification (MID) code rule, which determines the merchants from whom transactions can be processed.|
|» description|string|false|none|A description for the control.|
update-control-request-mcc-limit
```json
{
"description": "Allow the card to be used only in restaurants and supermarkets",
"mcc_limit": {
"type": "allow",
"mcc_list": [
"5932",
"5411"
]
}
}
```
The control you want to update.
You can update only one control per request.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|description|string|false|none|A description for the control.|
|mcc_limit|[MccLimit](#schemamcclimit)|false|none|The merchant category code (MCC) rule, which determines the types of businesses transactions can be processed from.|
update-control-request-mid-limit
```json
{
"description": "Allow the card to be used only in AZ Pizza",
"mid_limit": {
"type": "allow",
"mid_list": [
"593278",
"541114"
]
}
}
```
The control you want to update.
You can only update one control per request.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|description|string|false|none|A description for the control.|
|mid_limit|[MidLimit](#schemamidlimit)|false|none|The merchant identification (MID) code rule, which determines the merchants from whom transactions can be processed.|
update-control-request-velocity-limit
```json
{
"description": "Max spend of 500€ per week for restaurants",
"velocity_limit": {
"amount_limit": 50000,
"mcc_list": [
"4121",
"4582"
],
"mid_list": [
"1234567890"
]
}
}
```
The control you want to update.
You can only update one control per request.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|description|string|false|none|A description for the control.|
|velocity_limit|object|false|none|The velocity limit, which determines how much a card can spend over a given period of time.|
|» amount_limit|integer(int64)|false|none|The amount that can be spent using the card, in minor units.|
|» mcc_list|[string]|false|none|The list of merchant category codes (MCCs) that the velocity limit applies to, as 4-digit ISO 18245 codes.|
|» mid_list|[string]|false|none|The list of merchant identification (MID) codes to allow or block transactions from. Note that `mcc_list` and `mid_list` cannot be set together.|
update-control-response
```json
{
"id": "ctr_gp7vkmxayztufjz6top5bjcdra",
"description": "Max spend of 500€ per week for restaurants",
"control_type": "velocity_limit",
"target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
"is_editable": true,
"created_date": "2021-09-09T19:41:39Z",
"last_modified_date": "2021-09-09T19:41:39Z"
}
```
The control's details.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingControlId](#schemaissuingcontrolid)|true|none|The control's unique identifier.|
|description|string|false|none|The description of the control.|
|control_type|[IssuingControlType](#schemaissuingcontroltype)|true|none|The control's type.
A `velocity_limit` determines how much can be spent over a given period of time. An `mcc_limit` determines the types of businesses from which transactions can be processed. A `mid_limit` specifies the merchants from whom transactions can be processed.|
|target_id|[IssuingTargetId](#schemaissuingtargetid)|true|none|The ID of the card or control profile.|
|is_editable|[ControlIsEditable](#schemacontroliseditable)|true|none|Indicates whether you can change this control.
`false` This is an immutable control applied by Checkout.com and you cannot change it.
`true` You applied this control and can change it.|
|created_date|[Datetime](#schemadatetime)|true|none|none|
|last_modified_date|[Datetime](#schemadatetime)|true|none|none|
update-control-velocity-limit-response
```json
{
"id": "ctr_gp7vkmxayztufjz6top5bjcdra",
"description": "Maximum spend of 500€ per week for restaurants",
"control_type": "velocity_limit",
"target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
"is_editable": true,
"created_date": "2021-09-09T19:41:39Z",
"last_modified_date": "2021-09-09T19:41:39Z",
"velocity_limit": {
"amount_remaining": 45000,
"amount_limit": 50000,
"velocity_window": {
"type": "weekly"
},
"mcc_list": [
"4121",
"4582"
],
"mid_list": [
"1234567890"
]
}
}
```
### Properties
allOf - discriminator: update-control-response.control_type
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[update-control-response](#schemaupdate-control-response)|false|none|The control's details.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» velocity_limit|[VelocityLimitWithRemainingAmount](#schemavelocitylimitwithremainingamount)|false|none|The velocity limit, which determines how much a target card can spend over a given timeframe.|
|» description|string|false|none|A description for the control.|
amend-dispute-request
```json
{
"reason": "4807",
"amount": 1500,
"evidence": [
{
"name": "evidence.pdf",
"content": "string",
"description": "Goods were not received."
}
],
"fraud_details": {
"fraud_type": "card_not_present_fraud",
"description": "Cardholder confirmed they made no online purchases on this date."
},
"reason_change_justification": "New evidence confirms this was an unauthorized transaction, making reason 4837 more appropriate.",
"action_response": "Updated reason as requested. The cardholder confirmed the goods were never delivered."
}
```
Submit an amendment to a dispute that is currently blocked from proceeding. This endpoint
handles both chargeback-stage and escalation-stage amendments using the same flat payload
as the server determines the context from the dispute's current state.
Refer to the `action_details` returned in the Get issuing dispute endpoint to view the instructions provided by the Dispute Resolution team and the deadline by which you must submit amendments.
If `reason` specifies a fraud-related dispute, you must provide `fraud_details`.
If you change the `reason` at the escalation stage, you must provide `reason_change_justification`.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reason|string|false|none|The updated four-digit scheme-specific [reason code](https://www.checkout.com/docs/developer-resources/codes/chargeback-codes#Mastercard).
If a value is not provided, the existing reason code is retained.|
|amount|number|false|none|The updated disputed amount, in the [minor unit](https://www.checkout.com/docs/payments/accept-payments/format-the-payment-amount)
of the transaction currency. If not provided, the existing amount is retained.|
|evidence|[[IssuingDisputeEvidence](#schemaissuingdisputeevidence)]|false|none|The updated or additional evidence requested by the Dispute Resolution team.
Follow the [card scheme's requirements](https://www.checkout.com/docs/card-issuing/manage-cardholder-transactions/manage-issuing-disputes#Evidence_file_requirements).|
|fraud_details|[IssuingDisputeFraudDetails](#schemaissuingdisputefrauddetails)|false|none|Provides the fraud category, and additional context if available.
This field is required if `reason` specifies a fraud-related dispute.|
|reason_change_justification|string|false|none|Explains the justification for the reason change. This is shared with the Dispute Resolution review team and may be submitted to the card scheme.
This field is required if you change the `reason` at the escalation stage.|
|action_response|string|false|none|Free-form text that you can use to explain your choices, provide additional context, or ask questions about the requested changes.|
create-dispute-request
```json
{
"transaction_id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
"reason": "4807",
"evidence": [
{
"name": "evidence.pdf",
"content": "string",
"description": "Goods were not received."
}
],
"amount": 100,
"presentment_message_id": "msg_fa6psq242dcd6fdn5gifcq1491",
"fraud_details": {
"fraud_type": "card_not_present_fraud",
"description": "Cardholder confirmed they made no online purchases on this date."
},
"justification": "string"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|transaction_id|[IssuingTransactionId](#schemaissuingtransactionid)|true|none|The transaction's unique identifier.|
|reason|string|true|none|The four-digit scheme-specific [reason code](https://www.checkout.com/docs/developer-resources/codes/chargeback-codes#Mastercard) for the chargeback.
Only provide this if Checkout.com is your issuing processor.
Checkout.com does not validate this value.|
|evidence|[[IssuingDisputeEvidence](#schemaissuingdisputeevidence)]|false|none|Your evidence for raising the chargeback, in line with the [card scheme's requirements](https://www.checkout.com/docs/card-issuing/manage-cardholder-transactions/manage-issuing-disputes#Evidence_file_requirements).|
|amount|number|false|none|The chargeback amount, in the [minor unit](https://www.checkout.com/docs/payments/accept-payments/format-the-payment-amount) of the transaction currency.
If not provided, Checkout.com uses the full amount of the presentment.|
|presentment_message_id|[IssuingMessageId](#schemaissuingmessageid)|false|none|The unique identifier for the disputed presentment message.
If the transaction has multiple presentments, you must provide this field to specify the presentment you want to dispute.
If the transaction has only one presentment, you do not need to provide this field because Checkout.com uses that presentment automatically.
|
|fraud_details|[IssuingDisputeFraudDetails](#schemaissuingdisputefrauddetails)|false|none|Contains all fraud-related information to be sent with the chargeback.
This field is required if the dispute has a fraud-related reason code.|
|justification|string|false|none|Short justification for raising this dispute, to be sent to the scheme.|
create-dispute-response
```json
{
"id": "idsp_fa6psq242dcd6fdn5gifcq1491",
"reason": "4802",
"disputed_amount": {
"amount": 100,
"currency": "USD"
},
"status": "processing",
"status_reason": "chargeback_processed",
"transaction_id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
"presentment_message_id": "msg_fa6psq242dcd6fdn5gifcq1491",
"merchant": {
"id": "(*)123456789",
"name": "Software Company",
"city": "Paris",
"state": "",
"country_code": "FR",
"category_code": "5331",
"evidence": [
"file_6lbss42ezvoufcb2beo76rvwly"
]
},
"created_on": "2019-08-24T14:15:22Z",
"modified_on": "2019-08-24T14:15:22Z",
"action_details": {
"instructions": "string",
"last_action_response": "string"
},
"chargeback": {
"submitted_on": "2025-09-10T10:11:12Z",
"reason": "4802",
"amount": {
"amount": 100,
"currency": "USD"
},
"evidence": [
{
"file_id": "file_6lbss42ezvoufcb2beo76rvwly",
"description": "Goods were not received."
}
],
"justification": "string"
},
"representment": {
"received_on": "2019-08-24T14:15:22Z",
"amount": {
"amount": 100,
"currency": "USD"
},
"evidence": [
{
"file_id": "file_6lbss42ezvoufcb2beo76rvwly",
"description": "Goods were not received."
}
]
},
"pre_arbitration": {
"submitted_on": "2025-09-10T10:11:12Z",
"evidence": [
{
"file_id": "file_6lbss42ezvoufcb2beo76rvwly",
"description": "Goods were not received."
}
],
"amount": {
"amount": 100,
"currency": "USD"
},
"reason_change": {
"reason": "4807",
"justification": "string"
},
"justification": "string",
"merchant_responded_on": "2019-08-24T14:15:22Z",
"merchant_evidence": [
{
"file_id": "file_6lbss42ezvoufcb2beo76rvwly",
"description": "Goods were not received."
}
]
},
"arbitration": {
"submitted_on": "2025-09-10T10:11:12Z",
"amount": {
"amount": 100,
"currency": "USD"
},
"justification": "string",
"decided_on": "2025-01-31T10:20:30Z"
},
"_links": {
"self": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"card": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"cardholder": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"transaction": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"amend": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"escalate": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"cancel": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
}
}
}
```
### Properties
*None*
escalate-dispute-request
```json
{
"additional_evidence": [
{
"name": "evidence.pdf",
"content": "string",
"description": "Goods were not received."
}
],
"amount": 100,
"reason_change": {
"reason": "4807",
"justification": "string"
},
"fraud_details": {
"fraud_type": "card_not_present_fraud",
"description": "Cardholder confirmed they made no online purchases on this date."
},
"justification": "string"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|additional_evidence|[[IssuingDisputeEvidence](#schemaissuingdisputeevidence)]|false|none|Your evidence for escalating the dispute, in line with the [card scheme's requirements](https://www.checkout.com/docs/card-issuing/manage-cardholder-transactions/manage-issuing-disputes#Evidence_file_requirements).
If the request goes to arbitration, the card scheme ignores any evidence you provide at this stage using this request.|
|amount|number|false|none|The updated disputed amount, in the [minor unit](https://www.checkout.com/docs/payments/accept-payments/format-the-payment-amount) of the representment currency.|
|reason_change|[IssuingDisputeReasonChange](#schemaissuingdisputereasonchange)|false|none|The change to the dispute reason and your justification for changing it.|
|fraud_details|[IssuingDisputeFraudDetails](#schemaissuingdisputefrauddetails)|false|none|Provides fraud-related details.
This field is required if the dispute has a fraud-related reason code at the escalation stage, or after a requested reason code change to a fraud code.|
|justification|string|true|none|Justification for escalating the dispute.|
get-dispute-response
```json
{
"id": "idsp_fa6psq242dcd6fdn5gifcq1491",
"reason": "4802",
"disputed_amount": {
"amount": 100,
"currency": "USD"
},
"status": "processing",
"status_reason": "chargeback_processed",
"transaction_id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
"presentment_message_id": "msg_fa6psq242dcd6fdn5gifcq1491",
"merchant": {
"id": "(*)123456789",
"name": "Software Company",
"city": "Paris",
"state": "",
"country_code": "FR",
"category_code": "5331",
"evidence": [
"file_6lbss42ezvoufcb2beo76rvwly"
]
},
"created_on": "2019-08-24T14:15:22Z",
"modified_on": "2019-08-24T14:15:22Z",
"action_details": {
"instructions": "string",
"last_action_response": "string"
},
"chargeback": {
"submitted_on": "2025-09-10T10:11:12Z",
"reason": "4802",
"amount": {
"amount": 100,
"currency": "USD"
},
"evidence": [
{
"file_id": "file_6lbss42ezvoufcb2beo76rvwly",
"description": "Goods were not received."
}
],
"justification": "string"
},
"representment": {
"received_on": "2019-08-24T14:15:22Z",
"amount": {
"amount": 100,
"currency": "USD"
},
"evidence": [
{
"file_id": "file_6lbss42ezvoufcb2beo76rvwly",
"description": "Goods were not received."
}
]
},
"pre_arbitration": {
"submitted_on": "2025-09-10T10:11:12Z",
"evidence": [
{
"file_id": "file_6lbss42ezvoufcb2beo76rvwly",
"description": "Goods were not received."
}
],
"amount": {
"amount": 100,
"currency": "USD"
},
"reason_change": {
"reason": "4807",
"justification": "string"
},
"justification": "string",
"merchant_responded_on": "2019-08-24T14:15:22Z",
"merchant_evidence": [
{
"file_id": "file_6lbss42ezvoufcb2beo76rvwly",
"description": "Goods were not received."
}
]
},
"arbitration": {
"submitted_on": "2025-09-10T10:11:12Z",
"amount": {
"amount": 100,
"currency": "USD"
},
"justification": "string",
"decided_on": "2025-01-31T10:20:30Z"
},
"_links": {
"self": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"card": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"cardholder": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"transaction": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"amend": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"escalate": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"cancel": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
}
}
}
```
The client's dispute response.
### Properties
*None*
IssuingDispute
```json
{
"id": "idsp_fa6psq242dcd6fdn5gifcq1491",
"reason": "4802",
"disputed_amount": {
"amount": 100,
"currency": "USD"
},
"status": "processing",
"status_reason": "chargeback_processed",
"transaction_id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
"presentment_message_id": "msg_fa6psq242dcd6fdn5gifcq1491",
"merchant": {
"id": "(*)123456789",
"name": "Software Company",
"city": "Paris",
"state": "",
"country_code": "FR",
"category_code": "5331",
"evidence": [
"file_6lbss42ezvoufcb2beo76rvwly"
]
},
"created_on": "2019-08-24T14:15:22Z",
"modified_on": "2019-08-24T14:15:22Z",
"action_details": {
"instructions": "string",
"last_action_response": "string"
},
"chargeback": {
"submitted_on": "2025-09-10T10:11:12Z",
"reason": "4802",
"amount": {
"amount": 100,
"currency": "USD"
},
"evidence": [
{
"file_id": "file_6lbss42ezvoufcb2beo76rvwly",
"description": "Goods were not received."
}
],
"justification": "string"
},
"representment": {
"received_on": "2019-08-24T14:15:22Z",
"amount": {
"amount": 100,
"currency": "USD"
},
"evidence": [
{
"file_id": "file_6lbss42ezvoufcb2beo76rvwly",
"description": "Goods were not received."
}
]
},
"pre_arbitration": {
"submitted_on": "2025-09-10T10:11:12Z",
"evidence": [
{
"file_id": "file_6lbss42ezvoufcb2beo76rvwly",
"description": "Goods were not received."
}
],
"amount": {
"amount": 100,
"currency": "USD"
},
"reason_change": {
"reason": "4807",
"justification": "string"
},
"justification": "string",
"merchant_responded_on": "2019-08-24T14:15:22Z",
"merchant_evidence": [
{
"file_id": "file_6lbss42ezvoufcb2beo76rvwly",
"description": "Goods were not received."
}
]
},
"arbitration": {
"submitted_on": "2025-09-10T10:11:12Z",
"amount": {
"amount": 100,
"currency": "USD"
},
"justification": "string",
"decided_on": "2025-01-31T10:20:30Z"
},
"_links": {
"self": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"card": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"cardholder": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"transaction": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"amend": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"escalate": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"cancel": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
}
}
}
```
The client's dispute view.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingDisputeId](#schemaissuingdisputeid)|false|none|The unique identifier for the Issuing dispute.|
|reason|string|false|none|The four-digit scheme-specific [reason code](https://www.checkout.com/docs/developer-resources/codes/chargeback-codes#Mastercard) you provide for the chargeback.|
|disputed_amount|[IssuingTransactionAmount](#schemaissuingtransactionamount)|false|none|The disputed amount, in the [minor unit](https://www.checkout.com/docs/payments/accept-payments/format-the-payment-amount) of the transaction currency.|
|status|[IssuingDisputeStatus](#schemaissuingdisputestatus)|false|none|The [dispute status](https://www.checkout.com/docs/developer-resources/codes/issuing-dispute-codes) as returned to the client.|
|status_reason|[IssuingDisputeStatusReason](#schemaissuingdisputestatusreason)|false|none|The status reason as returned to the client. An empty string indicates no status reason currently applies.|
|transaction_id|[IssuingTransactionId](#schemaissuingtransactionid)|false|none|The unique Checkout.com identifier for the transaction.|
|presentment_message_id|[IssuingMessageId](#schemaissuingmessageid)|false|none|The unique identifier for the disputed presentment message.|
|merchant|[IssuingDisputeMerchant](#schemaissuingdisputemerchant)|false|none|The details of the merchant you raised the dispute with.|
|created_on|string(date-time)|false|none|The date and time when the dispute was created, in UTC.
Format – ISO 8601 code
Example – `2025-01-31T10:20:30.456`|
|modified_on|string(date-time)|false|none|The date and time when the dispute was last modified, in UTC.
Format – ISO 8601 code
Example – `2025-01-31T10:20:30.456`|
|action_details|[IssuingDisputeActionDetails](#schemaissuingdisputeactiondetails)|false|none|Provides instructions on the amendments required before the dispute can proceed, if the dispute `status` is `action_required`.
Use the Amend an Issuing dispute endpoint to submit your amendments.
Use the correct endpoint to send your updates as requested.|
|chargeback|[IssuingDisputeChargeback](#schemaissuingdisputechargeback)|false|none|The dispute details at the chargeback stage.|
|representment|[IssuingDisputeSecondPresentment](#schemaissuingdisputesecondpresentment)|false|none|The information provided by the merchant when they reject the chargeback and send a representment.|
|pre_arbitration|[IssuingDisputePreArbitration](#schemaissuingdisputeprearbitration)|false|none|The dispute details at the pre-arbitration stage.|
|arbitration|[IssuingDisputeArbitration](#schemaissuingdisputearbitration)|false|none|The dispute details during the arbitration stage.|
|_links|object|false|none|The links related to the dispute.|
|» self|[IssuingLink](#schemaissuinglink)|false|none|The URI for the dispute.|
|» card|[IssuingLink](#schemaissuinglink)|false|none|The URI for the card used for the disputed transaction.|
|» cardholder|[IssuingLink](#schemaissuinglink)|false|none|The URI for the cardholder who requested the chargeback.|
|» transaction|[IssuingLink](#schemaissuinglink)|false|none|The URI for the disputed transaction.|
|» amend|[IssuingLink](#schemaissuinglink)|false|none|The URI to amend and resubmit the dispute, if the dispute `status` is `action_required`.
Refer to `action_details` for the required amendments.|
|» escalate|[IssuingLink](#schemaissuinglink)|false|none|The URI for escalating the Issuing dispute.|
|» cancel|[IssuingLink](#schemaissuinglink)|false|none|The URI to cancel the dispute.|
IssuingDisputeActionDetails
```json
{
"instructions": "string",
"last_action_response": "string"
}
```
Provides instructions on the amendments required before the dispute can proceed, if the dispute `status` is `action_required`.
Use the Amend an Issuing dispute endpoint to submit your amendments.
Use the correct endpoint to send your updates as requested.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|instructions|string|false|none|The amendments required before the dispute can proceed. For example, if you need to provide a reason code, or update the submitted evidence.|
|last_action_response|string|false|none|Specifies whether the dispute was previously amended and an action response was provided.|
IssuingDisputeArbitration
```json
{
"submitted_on": "2025-09-10T10:11:12Z",
"amount": {
"amount": 100,
"currency": "USD"
},
"justification": "string",
"decided_on": "2025-01-31T10:20:30Z"
}
```
The dispute details during the arbitration stage.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|submitted_on|string(date-time)|false|none|The date and time when the arbitration was successfully escalated to the card scheme, in UTC.
Format – ISO 8601 code
Example – `2025-01-31T10:20:30.456`|
|amount|[IssuingTransactionAmount](#schemaissuingtransactionamount)|false|none|The disputed amount at the arbitration stage, in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-payment-amount).|
|justification|string|false|none|Your justification for escalating the dispute to arbitration.|
|decided_on|string(date-time)|false|none|The date and time when the card scheme decided the arbitration case, in UTC.
Format – ISO 8601 code
Example – `2025-01-31T10:20:30.456`|
IssuingDisputeChargeback
```json
{
"submitted_on": "2025-09-10T10:11:12Z",
"reason": "4802",
"amount": {
"amount": 100,
"currency": "USD"
},
"evidence": [
{
"file_id": "file_6lbss42ezvoufcb2beo76rvwly",
"description": "Goods were not received."
}
],
"justification": "string"
}
```
The dispute details at the chargeback stage.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|submitted_on|string(date-time)|false|none|The date and time when the chargeback was successfully submitted to the card scheme, in UTC.
Format – ISO 8601 code
Example – `2025-01-31T10:20:30.456`|
|reason|string|false|none|The four-digit scheme-specific [reason code](https://www.checkout.com/docs/developer-resources/codes/chargeback-codes#Mastercard) you provide for the chargeback.|
|amount|[IssuingTransactionAmount](#schemaissuingtransactionamount)|false|none|The disputed amount, in the [minor unit](https://www.checkout.com/docs/payments/accept-payments/format-the-payment-amount) of the transaction currency.|
|evidence|[object]|false|none|Your evidence for the chargeback.|
|» file_id|[IssuingFileId](#schemaissuingfileid)|true|none|The unique identifier for an uploaded file.|
|» description|string|false|none|A brief description of the evidence.|
|justification|string|false|none|A brief description of why the dispute is being raised. This is forwarded to the scheme.|
IssuingDisputeEvidence
```json
{
"name": "evidence.pdf",
"content": "string",
"description": "Goods were not received."
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|true|none|The complete file name, including the extension.|
|content|string|true|none|The base64-encoded string that represents a single JPG, PDF, TIFF, or ZIP file.
ZIP files can contain multiple JPG, PDF, or TIFF files.|
|description|string|false|none|A brief description of the evidence.|
IssuingDisputeFraudDetails
```json
{
"fraud_type": "card_not_present_fraud",
"description": "Cardholder confirmed they made no online purchases on this date."
}
```
Fraud-related information required when the dispute reason code is fraud-related.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|fraud_type|string|true|none|The type of fraud the cardholder is asserting. This can be one of:
- `card_lost`: The cardholder does not have the physical card and cannot explain how it was lost.
- `card_stolen`: The cardholder does not have the physical card and provided an explanation as to how it was lost. For example, their wallet was stolen.
- `card_never_received`: The card was issued and mailed but was not received by the cardholder.
- `fraudulent_account`: The account was opened fraudulently using a stolen, fake, or synthetic identity.
- `counterfeit_card`: The cardholder has their physical card but a duplicate or altered card was used in an unauthorized card-present transaction.
- `account_takeover`: A fraudster gained control of the cardholder's account or credentials. For example, they may have changed the registered address, ordered a new card, or provisioned the card to a digital wallet.
- `card_not_present_fraud`: The cardholder still has the card but the card details were used in an unauthorized card-not-present transaction. For example, it was used in an ecommerce transaction, or in a mail order/telephone order (MOTO) payment.
- `merchant_misrepresentation`: The merchant deliberately misled the cardholder. For example, the goods provided were sub-standard, there were hidden charges, or the services advertised were fake.
- `cardholder_manipulation`: The cardholder was tricked into authorizing the transaction themselves. For example, due to a scam, an impersonation, or authorized push payment (APP) fraud.
- `incorrect_processing`: A security check failed and made fraudulent activity possible. For example, a card verification value (CVV) check was not performed, or the EMV cryptogram was not validated.
- `other`: The confirmed fraud does not fit any of the other fraud type categories, or there were multiple fraud types applicable to the same transaction.|
|description|string|false|none|A description of the fraud circumstances, for internal reference. This is not forwarded to the scheme.|
#### Enumerated Values
|Property|Value|
|---|---|
|fraud_type|card_lost|
|fraud_type|card_stolen|
|fraud_type|card_never_received|
|fraud_type|fraudulent_account|
|fraud_type|counterfeit_card|
|fraud_type|account_takeover|
|fraud_type|card_not_present_fraud|
|fraud_type|merchant_misrepresentation|
|fraud_type|cardholder_manipulation|
|fraud_type|incorrect_processing|
|fraud_type|other|
IssuingDisputeId
```json
"idsp_fa6psq242dcd6fdn5gifcq1491"
```
The unique identifier for the Issuing dispute.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The unique identifier for the Issuing dispute.|
IssuingDisputeMerchant
```json
{
"id": "(*)123456789",
"name": "Software Company",
"city": "Paris",
"state": "",
"country_code": "FR",
"category_code": "5331",
"evidence": [
"file_6lbss42ezvoufcb2beo76rvwly"
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The merchant's identifier. This can vary from one acquirer to another.|
|name|string|false|none|The merchant's name.|
|city|string|false|none|The city where the merchant is located.|
|state|string|false|none|The state where the merchant is located (US only).|
|country_code|string|false|none|The two-digit [country code](https://www.checkout.com/docs/developer-resources/codes/country-codes) where the merchant is located.|
|category_code|string|false|none|The merchant's [category code](https://www.checkout.com/docs/developer-resources/testing/codes/merchant-category-codes) for the disputed transaction.|
|evidence|[[IssuingFileId](#schemaissuingfileid)]|false|none|Any evidence submitted by the merchant during the dispute lifecycle.|
IssuingDisputePreArbitration
```json
{
"submitted_on": "2025-09-10T10:11:12Z",
"evidence": [
{
"file_id": "file_6lbss42ezvoufcb2beo76rvwly",
"description": "Goods were not received."
}
],
"amount": {
"amount": 100,
"currency": "USD"
},
"reason_change": {
"reason": "4807",
"justification": "string"
},
"justification": "string",
"merchant_responded_on": "2019-08-24T14:15:22Z",
"merchant_evidence": [
{
"file_id": "file_6lbss42ezvoufcb2beo76rvwly",
"description": "Goods were not received."
}
]
}
```
The dispute details at the pre-arbitration stage.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|submitted_on|string(date-time)|false|none|The date and time when the pre-arbitration was successfully escalated to the card scheme, in UTC.
Format – ISO 8601 code
Example – `2025-01-31T10:20:30.456`|
|evidence|[object]|false|none|The evidence relating to the Issuing dispute provided at the pre-arbitration stage.|
|» file_id|[IssuingFileId](#schemaissuingfileid)|true|none|The unique identifier for an uploaded file.|
|» description|string|false|none|A brief description of the evidence.|
|amount|[IssuingTransactionAmount](#schemaissuingtransactionamount)|false|none|The disputed amount at the pre-arbitration stage, in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-payment-amount).|
|reason_change|[IssuingDisputeReasonChange](#schemaissuingdisputereasonchange)|false|none|The change to the dispute reason and your justification for changing it.|
|justification|string|false|none|Your justification for escalating the dispute to pre-arbitration.|
|merchant_responded_on|string(date-time)|false|none|The date and time when the merchant provided evidence against the pre-arbitration, in UTC.
Format – ISO 8601 code
Example – `2025-01-31T10:20:30.456`|
|merchant_evidence|[object]|false|none|none|
|» file_id|[IssuingFileId](#schemaissuingfileid)|true|none|The unique identifier for an uploaded file.|
|» description|string|false|none|A brief description of the evidence.|
IssuingDisputeReasonChange
```json
{
"reason": "4807",
"justification": "string"
}
```
The change to the dispute reason and your justification for changing it.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reason|string|true|none|The updated four-digit scheme-specific [reason code](https://www.checkout.com/docs/developer-resources/codes/chargeback-codes) for the chargeback.|
|justification|string|true|none|Your justification for changing the dispute reason.|
IssuingDisputeSecondPresentment
```json
{
"received_on": "2019-08-24T14:15:22Z",
"amount": {
"amount": 100,
"currency": "USD"
},
"evidence": [
{
"file_id": "file_6lbss42ezvoufcb2beo76rvwly",
"description": "Goods were not received."
}
]
}
```
The information provided by the merchant when they reject the chargeback and send a representment.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|received_on|string(date-time)|false|none|The date and time when you received the representment, in UTC.
Format – ISO 8601 code
Example – `2025-01-31T10:20:30.456`|
|amount|[IssuingTransactionAmount](#schemaissuingtransactionamount)|false|none|The representment amount, in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-payment-amount).|
|evidence|[object]|false|none|The evidence provided by the merchant against the chargeback.|
|» file_id|[IssuingFileId](#schemaissuingfileid)|true|none|The unique identifier for an uploaded file.|
|» description|string|false|none|A brief description of the evidence.|
IssuingDisputeStatus
```json
"processing"
```
The [dispute status](https://www.checkout.com/docs/developer-resources/codes/issuing-dispute-codes) as returned to the client.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The [dispute status](https://www.checkout.com/docs/developer-resources/codes/issuing-dispute-codes) as returned to the client.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|created|
|*anonymous*|canceled|
|*anonymous*|processing|
|*anonymous*|action_required|
|*anonymous*|won|
|*anonymous*|lost|
IssuingDisputeStatusReason
```json
"chargeback_processed"
```
The status reason as returned to the client. An empty string indicates no status reason currently applies.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The status reason as returned to the client. An empty string indicates no status reason currently applies.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*||
|*anonymous*|expired|
|*anonymous*|chargeback_pending|
|*anonymous*|chargeback_change_requested|
|*anonymous*|chargeback_evidence_invalid_or_insufficient|
|*anonymous*|chargeback_processed|
|*anonymous*|chargeback_rejected|
|*anonymous*|chargeback_reversal_pending|
|*anonymous*|chargeback_reversed|
|*anonymous*|chargeback_response_accepted|
|*anonymous*|prearbitration_pending|
|*anonymous*|escalation_change_requested|
|*anonymous*|prearbitration_evidence_invalid_or_insufficient|
|*anonymous*|prearbitration_processed|
|*anonymous*|prearbitration_rejected|
|*anonymous*|prearbitration_reversal_pending|
|*anonymous*|prearbitration_reversed|
|*anonymous*|prearbitration_response_accepted|
|*anonymous*|arbitration_pending|
|*anonymous*|arbitration_processed|
|*anonymous*|presentment_reversed|
submit-dispute-request
```json
{
"reason": "4807",
"evidence": [
{
"name": "evidence.pdf",
"content": "string",
"description": "Goods were not received."
}
],
"amount": 100
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reason|string|false|none|The updated four-digit scheme-specific [reason code](https://www.checkout.com/docs/developer-resources/codes/chargeback-codes#Mastercard).
If not provided, Checkout.com uses the existing reason code.|
|evidence|[[IssuingDisputeEvidence](#schemaissuingdisputeevidence)]|false|none|Your evidence for the chargeback, if updated since you created the dispute.|
|amount|number|false|none|The updated disputed amount, in the [minor unit](https://www.checkout.com/docs/payments/accept-payments/format-the-payment-amount) of the transaction or representment currency.
If not provided, Checkout.com uses the existing disputed amount.|
OobSimulateTransactionDetails
```json
{
"last_four": "1234",
"merchant_name": "Acme Ltd",
"purchase_amount": 100,
"purchase_currency": "USD"
}
```
Details for the simulated transaction.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|last_four|[LastFour](#schemalastfour)|false|none|The last four digits of the card number, also known as the PAN.|
|merchant_name|string|false|none|The merchant's name.|
|purchase_amount|number|false|none|The amount of the simulated transaction.|
|purchase_currency|[IssuingCurrency](#schemaissuingcurrency)|false|none|The issuing currency, as a three-letter ISO currency code.|
simulate-oob-authentication-request
```json
{
"card_id": "crd_fa6psq242dcd6fdn5gifcq1491",
"transaction_details": {
"last_four": "1234",
"merchant_name": "Acme Ltd",
"purchase_amount": 100,
"purchase_currency": "USD"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|card_id|[IssuingCardId](#schemaissuingcardid)|true|none|The card's unique identifier.|
|transaction_details|[OobSimulateTransactionDetails](#schemaoobsimulatetransactiondetails)|false|none|Details for the simulated transaction.|
get-transaction-response
```json
{
"id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
"created_on": "2019-08-24T14:15:22Z",
"status": "authorized",
"transaction_type": "purchase",
"client": {
"id": "cli_vkuhvk4vjn2edkps7dfsq6emqm"
},
"entity": {
"id": "ent_fa6psq242dcd6fdn5gifcq1491"
},
"card": {
"id": "crd_fa6psq242dcd6fdn5gifcq1491",
"network": "mastercard"
},
"digital_card": {
"id": "dcr_5ngxzsynm2me3oxf73esbhda6q",
"wallet_type": "googlepay"
},
"cardholder": {
"id": "crh_d3ozhf43pcq2xbldn2g45qnb44"
},
"amounts": {
"total_held": {
"amount": 100,
"currency": "USD"
},
"total_authorized": {
"amount": 100,
"currency": "USD"
},
"total_reversed": {
"amount": 100,
"currency": "USD"
},
"total_cleared": {
"amount": 100,
"currency": "USD"
},
"total_refunded": {
"amount": 100,
"currency": "USD"
}
},
"merchant": {
"id": "(*)123456789",
"name": "My Merchant",
"city": "Paris",
"state": "",
"country_code": "FR",
"category_code": "5331"
},
"reference_transaction": {
"transaction_id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
"reference_type": "original_mit"
},
"messages": [
{
"id": "msg_fa6psq242dcd6fdn5gifcq1491",
"initiator": "cardholder",
"type": "authorization",
"result": "declined",
"is_relayed": true,
"indicator": "incremental_preauthorization",
"decline_reason": "expiry_date_invalid",
"authorization_code": "03C0C0",
"billing_amount": 100,
"billing_currency": "USD",
"transaction_amount": 100,
"transaction_currency": "USD",
"created_on": "2019-09-10T10:11:12Z"
}
],
"_links": {
"self": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"card": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"cardholder": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"reference_transaction": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
}
}
}
```
### Properties
*None*
get-transactions-response
```json
{
"limit": 5,
"skip": 10,
"total_count": 100,
"data": [
{
"id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
"created_on": "2019-08-24T14:15:22Z",
"status": "authorized",
"transaction_type": "purchase",
"client": {
"id": "cli_vkuhvk4vjn2edkps7dfsq6emqm"
},
"entity": {
"id": "ent_fa6psq242dcd6fdn5gifcq1491"
},
"card": {
"id": "crd_fa6psq242dcd6fdn5gifcq1491",
"network": "mastercard"
},
"digital_card": {
"id": "dcr_5ngxzsynm2me3oxf73esbhda6q",
"wallet_type": "googlepay"
},
"cardholder": {
"id": "crh_d3ozhf43pcq2xbldn2g45qnb44"
},
"amounts": {
"total_held": {
"amount": 100,
"currency": "USD"
},
"total_authorized": {
"amount": 100,
"currency": "USD"
},
"total_reversed": {
"amount": 100,
"currency": "USD"
},
"total_cleared": {
"amount": 100,
"currency": "USD"
},
"total_refunded": {
"amount": 100,
"currency": "USD"
}
},
"merchant": {
"id": "(*)123456789",
"name": "My Merchant",
"city": "Paris",
"state": "",
"country_code": "FR",
"category_code": "5331"
},
"reference_transaction": {
"transaction_id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
"reference_type": "original_mit"
},
"messages": [
{
"id": "msg_fa6psq242dcd6fdn5gifcq1491",
"initiator": "cardholder",
"type": "authorization",
"result": "declined",
"is_relayed": true,
"indicator": "incremental_preauthorization",
"decline_reason": "expiry_date_invalid",
"authorization_code": "03C0C0",
"billing_amount": 100,
"billing_currency": "USD",
"transaction_amount": 100,
"transaction_currency": "USD",
"created_on": "2019-09-10T10:11:12Z"
}
],
"_links": {
"self": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"card": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"cardholder": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"reference_transaction": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
}
}
}
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|limit|integer|false|none|The requested maximum number of transactions returned.|
|skip|integer|false|none|The requested number of transactions to skip.|
|total_count|integer|false|none|The total count of available transactions.|
|data|[allOf]|false|none|A list of transactions.|
IssuingMessageId
```json
"msg_fa6psq242dcd6fdn5gifcq1491"
```
The message's unique Checkout.com identifier.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The message's unique Checkout.com identifier.|
IssuingReferenceTransaction
```json
{
"transaction_id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
"reference_type": "original_mit"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|transaction_id|[IssuingTransactionId](#schemaissuingtransactionid)|false|none|The transaction's unique identifier.|
|reference_type|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|reference_type|original_mit|
|reference_type|original_recurring|
IssuingTransaction
```json
{
"id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
"created_on": "2019-08-24T14:15:22Z",
"status": "authorized",
"transaction_type": "purchase",
"client": {
"id": "cli_vkuhvk4vjn2edkps7dfsq6emqm"
},
"entity": {
"id": "ent_fa6psq242dcd6fdn5gifcq1491"
},
"card": {
"id": "crd_fa6psq242dcd6fdn5gifcq1491",
"network": "mastercard"
},
"digital_card": {
"id": "dcr_5ngxzsynm2me3oxf73esbhda6q",
"wallet_type": "googlepay"
},
"cardholder": {
"id": "crh_d3ozhf43pcq2xbldn2g45qnb44"
},
"amounts": {
"total_held": {
"amount": 100,
"currency": "USD"
},
"total_authorized": {
"amount": 100,
"currency": "USD"
},
"total_reversed": {
"amount": 100,
"currency": "USD"
},
"total_cleared": {
"amount": 100,
"currency": "USD"
},
"total_refunded": {
"amount": 100,
"currency": "USD"
}
},
"merchant": {
"id": "(*)123456789",
"name": "My Merchant",
"city": "Paris",
"state": "",
"country_code": "FR",
"category_code": "5331"
},
"reference_transaction": {
"transaction_id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
"reference_type": "original_mit"
},
"messages": [
{
"id": "msg_fa6psq242dcd6fdn5gifcq1491",
"initiator": "cardholder",
"type": "authorization",
"result": "declined",
"is_relayed": true,
"indicator": "incremental_preauthorization",
"decline_reason": "expiry_date_invalid",
"authorization_code": "03C0C0",
"billing_amount": 100,
"billing_currency": "USD",
"transaction_amount": 100,
"transaction_currency": "USD",
"created_on": "2019-09-10T10:11:12Z"
}
],
"_links": {
"self": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"card": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"cardholder": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
},
"reference_transaction": {
"href": "string",
"actions": [
"GET"
],
"types": [
"string"
]
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingTransactionId](#schemaissuingtransactionid)|false|none|The transaction's unique Checkout.com identifier.|
|created_on|string(date-time)|false|none|The date/time the transaction was created.|
|status|string|false|none|The high-level status indicating the stage of the transaction lifecycle.|
|transaction_type|string|false|none|The high-level nature of the transaction.|
|client|[IssuingTransactionClient](#schemaissuingtransactionclient)|false|none|Information about Client to which this transaction belongs.|
|entity|[IssuingTransactionEntity](#schemaissuingtransactionentity)|false|none|Information about Entity to which this transaction belongs.|
|card|[IssuingTransactionCard](#schemaissuingtransactioncard)|false|none|Basic card information used in this transaction.|
|digital_card|[IssuingTransactionDigitalCard](#schemaissuingtransactiondigitalcard)|false|none|Basic digital card information used in this transaction.|
|cardholder|[IssuingTransactionCardholder](#schemaissuingtransactioncardholder)|false|none|Information about Cardholder to which this transaction belongs.|
|amounts|[IssuingTransactionAmounts](#schemaissuingtransactionamounts)|false|none|The list of aggregated amounts related to the current transaction.|
|merchant|[IssuingTransactionMerchant](#schemaissuingtransactionmerchant)|false|none|The merchant details received in the first applicable message.
For example, if a transaction starts at the Authorization stage, then it will be the merchant received in the first Authorization.|
|reference_transaction|[IssuingReferenceTransaction](#schemaissuingreferencetransaction)|false|none|The basic details of a referenced transaction when applicable.|
|messages|[[IssuingTransactionMessage](#schemaissuingtransactionmessage)]|false|none|A summarized list of messages associated to this transaction.
A message can be initiated by the cardholder, merchant, acquirer, or issuer.|
|_links|object|false|none|The links related to the transaction.|
|» self|[IssuingLink](#schemaissuinglink)|false|none|The URI of the current transaction.|
|» card|[IssuingLink](#schemaissuinglink)|false|none|The URI of the associated card.|
|» cardholder|[IssuingLink](#schemaissuinglink)|false|none|The URI of the associated cardholder.|
|» reference_transaction|[IssuingLink](#schemaissuinglink)|false|none|The URI of the reference transaction.
For example, the original authorization in case of a refund, the original authenticated MIT or the first authorization in a series of recurring transactions.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|authorized|
|status|declined|
|status|canceled|
|status|cleared|
|status|refunded|
|status|disputed|
|transaction_type|account_funding|
|transaction_type|account_transfer|
|transaction_type|atm_installment|
|transaction_type|balance_inquiry|
|transaction_type|bill_payment|
|transaction_type|cash_advance|
|transaction_type|cashback|
|transaction_type|credit_adjustment|
|transaction_type|debit_adjustment|
|transaction_type|original_credit|
|transaction_type|payment_account_inquiry|
|transaction_type|payment|
|transaction_type|pin_change|
|transaction_type|pin_unblock|
|transaction_type|purchase_account_inquiry|
|transaction_type|purchase|
|transaction_type|quasi_cash|
|transaction_type|remittance_funding|
|transaction_type|remittance_payment|
|transaction_type|unknown|
|transaction_type|withdrawal|
|transaction_type|refund|
IssuingTransactionAmount
```json
{
"amount": 100,
"currency": "USD"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|amount|number|false|none|The amount is provided in the minor currency unit.|
|currency|[IssuingCurrency](#schemaissuingcurrency)|false|none|The issuing currency, as a three-letter ISO currency code.|
IssuingTransactionAmounts
```json
{
"total_held": {
"amount": 100,
"currency": "USD"
},
"total_authorized": {
"amount": 100,
"currency": "USD"
},
"total_reversed": {
"amount": 100,
"currency": "USD"
},
"total_cleared": {
"amount": 100,
"currency": "USD"
},
"total_refunded": {
"amount": 100,
"currency": "USD"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|total_held|[IssuingTransactionAmount](#schemaissuingtransactionamount)|false|none|The amount held internally to cover the transaction, but not yet debited.
This value is equal to the Total Authorized - Total Reversed - Total Cleared.
The amount is represented in the minor currency units of the cardholder's billing currency.|
|total_authorized|[IssuingTransactionAmount](#schemaissuingtransactionamount)|false|none|The total amount which has been authorized.
This sums the billing amounts from all approved authorizations associated to this transaction.
The amount is represented in the minor currency units of the cardholder's billing currency.|
|total_reversed|[IssuingTransactionAmount](#schemaissuingtransactionamount)|false|none|The total amount which has been reversed by the merchant or by the issuer.
This sums the billing amounts from all approved reversals and issuer initiated reversals associated to this transaction.
The amount is represented in the minor currency units of the cardholder's billing currency.|
|total_cleared|[IssuingTransactionAmount](#schemaissuingtransactionamount)|false|none|The total amount which has been cleared by the scheme.
This sums the billing amounts from all presentments associated to this transaction.
The amount is represented in the minor currency units of the cardholder's billing currency.|
|total_refunded|[IssuingTransactionAmount](#schemaissuingtransactionamount)|false|none|The total amount which has been refunded to the cardholder.
This sums the billing amounts from all presentments of type "refund" associated to this transaction.
The amount is represented in the minor currency units of the cardholder's billing currency.|
IssuingTransactionCard
```json
{
"id": "crd_fa6psq242dcd6fdn5gifcq1491",
"network": "mastercard"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingCardId](#schemaissuingcardid)|false|none|The card's unique identifier.|
|network|string|false|none|The card network.|
#### Enumerated Values
|Property|Value|
|---|---|
|network|mastercard|
IssuingTransactionCardholder
```json
{
"id": "crh_d3ozhf43pcq2xbldn2g45qnb44"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingCardholderId](#schemaissuingcardholderid)|false|none|The cardholder's unique identifier.|
IssuingTransactionClient
```json
{
"id": "cli_vkuhvk4vjn2edkps7dfsq6emqm"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingClientId](#schemaissuingclientid)|false|none|The client's unique identifier.|
IssuingTransactionDigitalCard
```json
{
"id": "dcr_5ngxzsynm2me3oxf73esbhda6q",
"wallet_type": "googlepay"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingDigitalCardId](#schemaissuingdigitalcardid)|false|none|The digital card's unique identifier.|
|wallet_type|string|false|none|The wallet type.|
#### Enumerated Values
|Property|Value|
|---|---|
|wallet_type|googlepay|
|wallet_type|applepay|
|wallet_type|remote_commerce_programs|
IssuingTransactionEntity
```json
{
"id": "ent_fa6psq242dcd6fdn5gifcq1491"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingEntityId](#schemaissuingentityid)|false|none|The entity's unique identifier.|
IssuingTransactionMerchant
```json
{
"id": "(*)123456789",
"name": "My Merchant",
"city": "Paris",
"state": "",
"country_code": "FR",
"category_code": "5331"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The merchant's identifier. The identifier varies from one acquirer to another.|
|name|string|false|none|The merchant's name.|
|city|string|false|none|The city where the merchant is located.|
|state|string|false|none|The state in which the merchant is located (only for US-based merchants).|
|country_code|string|false|none|The country code where the merchant is located.|
|category_code|string|false|none|The merchant's category codes.
All category codes are documented here.|
IssuingTransactionMessage
```json
{
"id": "msg_fa6psq242dcd6fdn5gifcq1491",
"initiator": "cardholder",
"type": "authorization",
"result": "declined",
"is_relayed": true,
"indicator": "incremental_preauthorization",
"decline_reason": "expiry_date_invalid",
"authorization_code": "03C0C0",
"billing_amount": 100,
"billing_currency": "USD",
"transaction_amount": 100,
"transaction_currency": "USD",
"created_on": "2019-09-10T10:11:12Z"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingMessageId](#schemaissuingmessageid)|false|none|The message's unique Checkout.com identifier.|
|initiator|string|false|none|Specifies who initiated the message|
|type|string|false|none|The message type.|
|result|string|false|none|The outcome after processing this message.|
|is_relayed|boolean|false|none|Indicates if this message was relayed through the Auth Relay to the client.|
|indicator|string|false|none|Indicates the type of the authorization, reversal, or presentment.
For authorization, it can be incremental_preauthorization, deferred_authorization, preauthorization, normal_authorization, final_authorization, or unknown.
For reversals, it can be partial_reversal or full_reversal.
For presentments, it can be partial_presentment or final_presentment.
For other message type, it may be null.|
|decline_reason|string|false|none|The reason explaining why the message was declined.
Refer to our documentation for a list of possible decline reasons.
If the message was approved, this will return `Null`.|
|authorization_code|string|false|none|Your issuer authorization code for when the transaction was approved.|
|billing_amount|integer(int64)|false|none|The transaction billing amount.
The amount is provided in the minor currency unit.|
|billing_currency|[IssuingCurrency](#schemaissuingcurrency)|false|none|The issuing currency, as a three-letter ISO currency code.|
|transaction_amount|integer(int64)|false|none|The amount of the message in the currency the card was used in, before any currency conversion.
The amount is provided in the minor currency unit.
This is only returned when the card scheme provided the transaction amount and currency for this message.
This field is only available for messages created on or after October 1, 2026. Messages created before that date have no value.|
|transaction_currency|[IssuingCurrency](#schemaissuingcurrency)|false|none|The currency the card was used in, before any currency conversion.
This is only returned when the card scheme provided the transaction amount and currency for this message.
This field is only available for messages created on or after October 1, 2026. Messages created before that date have no value.|
|created_on|string(date-time)|false|none|The message's creation date/time (UTC).|
#### Enumerated Values
|Property|Value|
|---|---|
|initiator|cardholder|
|initiator|merchant|
|initiator|acquirer|
|initiator|card_network|
|initiator|issuer|
|type|authorization|
|type|reversal|
|type|authorization_advice|
|type|reversal_advice|
|type|presentment|
|type|authorization_refund|
|type|presentment_refund|
|type|presentment_reversed|
|type|presentment_reversed_refund|
|result|approved|
|result|declined|
|result|processed|
|indicator|incremental_preauthorization|
|indicator|deferred_authorization|
|indicator|preauthorization|
|indicator|normal_authorization|
|indicator|final_authorization|
|indicator|partial_reversal|
|indicator|full_reversal|
|indicator|partial_presentment|
|indicator|final_presentment|
|indicator|unknown|
SimulateAuthorizationRequest
```json
{
"card": {
"id": "crd_fa6psq242dcd6fdn5gifcq1491",
"expiry_month": 5,
"expiry_year": 2025
},
"transaction": {
"type": "purchase",
"amount": 6540,
"currency": "GBP",
"merchant": {
"category_code": "7399"
},
"authorization_type": "authorization"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|card|[IssuingSimulateCard](#schemaissuingsimulatecard)|false|none|The card to simulate an authorization with.|
|transaction|[IssuingSimulateTransaction](#schemaissuingsimulatetransaction)|false|none|The transaction to simulate with the specified card. For example, a purchase.|
SimulateAuthorizationResponse
```json
{
"id": "trx_aaqc4uaaybigcaaqc4uaayfiga",
"status": "Authorized"
}
```
Authorization Response.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The transaction's unique identifier.
This same ID is carried throughout all authorization, reversal, and clearing messages related to the given transaction.|
|status|string|true|none|The transaction's status.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Authorized|
|status|Declined|
SimulateIncrementalAuthorizationRequest
```json
{
"amount": 3500
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|amount|integer|false|none|You must provide the amount in the transaction currency's minor currency units.|
SimulateIncrementalAuthorizationResponse
```json
{
"status": "Authorized"
}
```
Authorization Response.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|status|string|true|none|The transaction's status.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Authorized|
|status|Declined|
PresentmentRequest
```json
{
"amount": 2500
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|amount|integer|false|none|The amount to clear. If not specified, the full authorized amount will be cleared.
You must provide the amount in the transaction currency's minor currency units.|
IssuingAuthorizationTypes
```json
"authorization"
```
Use `authorization` for a known final amount or `pre_authorization` for an estimated amount.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|Use `authorization` for a known final amount or `pre_authorization` for an estimated amount.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|authorization|
|*anonymous*|pre_authorization|
IssuingMerchant
```json
{
"category_code": "7399"
}
```
The merchant related data to use for the transaction.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|category_code|string|false|none|The merchant category code (MCC), which determines the types of businesses the card can process the transaction from.|
IssuingSimulateCard
```json
{
"id": "crd_fa6psq242dcd6fdn5gifcq1491",
"expiry_month": 5,
"expiry_year": 2025
}
```
The card to simulate an authorization with.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[IssuingCardId](#schemaissuingcardid)|true|none|The card's unique identifier.|
|expiry_month|[ExpiryMonth](#schemaexpirymonth)|false|none|The card's expiration month.|
|expiry_year|[ExpiryYear](#schemaexpiryyear)|false|none|The card's expiration year.|
IssuingSimulateTransaction
```json
{
"type": "purchase",
"amount": 6540,
"currency": "GBP",
"merchant": {
"category_code": "7399"
},
"authorization_type": "authorization"
}
```
The transaction to simulate with the specified card. For example, a purchase.
### Properties
*None*
IssuingTransactionId
```json
"trx_aayhhfwbdyxwcaeyhhfwbd4xga"
```
The transaction's unique identifier.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The transaction's unique identifier.|
Purchase
```json
{
"type": "purchase",
"amount": 6540,
"currency": "GBP",
"merchant": {
"category_code": "7399"
},
"authorization_type": "authorization"
}
```
purchase
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The transaction type.|
|amount|integer|false|none|The payment amount, in minor currency units.
To perform a card verification, set `amount` to `0`, or omit the field entirely.|
|currency|string|false|none|The currency to use for the transaction, as a three-letter ISO currency code. If this currency differs from the cardholder's billing currency, the billing amount will be adjusted according to the applicable conversion rate. If no currency is provided, the transaction will default to the cardholder's billing currency.|
|merchant|[IssuingMerchant](#schemaissuingmerchant)|false|none|The merchant related data to use for the transaction.|
|authorization_type|[IssuingAuthorizationTypes](#schemaissuingauthorizationtypes)|false|none|Use `authorization` for a known final amount or `pre_authorization` for an estimated amount.|
SimulateRefundRequest
```json
{
"amount": 2500
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|amount|integer|false|none|The amount to refund. If not specified, the full cleared amount will be refunded.
You must provide the amount in the transaction currency's minor currency units .|
ReversalRequest
```json
{
"amount": 2500
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|amount|integer|false|none|The amount to reverse. If unspecified, the full transaction amount will be reversed.
You must provide the amount in the transaction currency's minor currency units.|
ReversalResponse
```json
{
"status": "Reversed"
}
```
Reversal Response.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|status|string|true|none|The status of the transaction (either Reversed or Declined).|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Reversed|
|status|Declined|
Link
```json
{
"href": "string"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|href|string|true|none|The link URL|
RedirectLink
```json
{
"href": "string",
"mobile": {
"android": {
"href": "string"
},
"ios": {
"href": null
}
},
"qr_code": {
"image": "string",
"text": "string"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|href|string|false|none|The redirect link URL|
|mobile|object|false|none|The mobile links for the redirect|
|» android|object|false|none|none|
|»» href|string|false|none|The Android link|
|» ios|object|false|none|none|
|»» href|any|false|none|The iOS link|
|qr_code|object|false|none|The QR code for the redirect|
|» image|string|false|none|The QR code image URL|
|» text|string|false|none|The encoded text for the QR code|
```json
{
"source": {
"type": "card",
"number": "4543474002249996"
},
"format": "basic",
"reference": "ORD-5023-4E89"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|source|[CardMetadataRequestSource](#schemacardmetadatarequestsource)|false|none|The source object|
|format|string|false|none|The format to provide the output in.
A `basic` response will only include standard metadata, while a `card_payouts` formatted response will also include fields specific to card payouts.|
|reference|string|false|none|A reference you can later use to identify this Payment Context. For example, an order number.|
#### Enumerated Values
|Property|Value|
|---|---|
|format|basic|
|format|card_payouts|
```json
{
"type": "card",
"number": "4543474002249996"
}
```
The source object
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[CardMetadataRequestSourceCard](#schemacardmetadatarequestsourcecard)|false|none|An existing payment source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[CardMetadataRequestSourceBin](#schemacardmetadatarequestsourcebin)|false|none|An existing payment source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[CardMetadataRequestSourceToken](#schemacardmetadatarequestsourcetoken)|false|none|An existing payment source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[CardMetadataRequestSourceInstrument](#schemacardmetadatarequestsourceinstrument)|false|none|An existing payment source|
```json
{
"type": "bin",
"bin": "454347"
}
```
bin
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The source type|
|bin|string|true|none|The issuer's Bank Identification Number (BIN)|
```json
{
"type": "card",
"number": "4543474002249996"
}
```
card
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The source type|
|number|string|true|none|The Primary Account Number (PAN)|
```json
{
"type": "id",
"id": "src_wmlfc3zyhqzehihu7giusaaawu"
}
```
id
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The source type|
|id|string|true|none|The unique ID for the payment instrument that was created using the card's details|
```json
{
"type": "token",
"token": "tok_ubfj2q76miwundwlk72vxt2i7q"
}
```
token
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The source type|
|token|string|true|none|The Checkout.com unique token that was generated when the card's details were tokenized|
```json
{
"bin": "45434720",
"scheme": "visa",
"scheme_local": "cartes_bancaires",
"local_schemes": [
"cartes_bancaires",
"upi"
],
"card_type": "CREDIT",
"card_category": "CONSUMER",
"currency": "MUR",
"issuer": "STATE BANK OF MAURITIUS",
"issuer_country": "MU",
"issuer_country_name": "Mauritius",
"is_combo_card": true,
"product_id": "CLASSIC",
"product_type": "F",
"subproduct_id": "VA",
"regulated_indicator": true,
"regulated_type": "base_regulated",
"is_reloadable_prepaid": true,
"anonymous_prepaid_description": "Anonymous prepaid program and not AMLD5 compliant",
"card_payouts": {
"domestic_non_money_transfer": "not_supported",
"cross_border_non_money_transfer": "standard",
"domestic_gambling": "fast_funds",
"cross_border_gambling": "unknown",
"domestic_money_transfer": "not_supported",
"cross_border_money_transfer": "not_supported"
},
"scheme_metadata": {
"accel": [
{
"network_id": "aam",
"network_description": "Accel Money Transfer Advantage",
"bill_pay_indicator": true,
"ecommerce_indicator": true,
"interchange_fee_indicator": "00",
"money_transfer_indicator": true,
"token_indicator": false
}
],
"pulse": [
{
"network_id": "aam",
"network_description": "Accel Money Transfer Advantage",
"bill_pay_indicator": true,
"ecommerce_indicator": true,
"interchange_fee_indicator": "00",
"money_transfer_indicator": true,
"token_indicator": false
}
],
"nyce": [
{
"network_id": "aam",
"network_description": "Accel Money Transfer Advantage",
"bill_pay_indicator": true,
"ecommerce_indicator": true,
"interchange_fee_indicator": "00",
"money_transfer_indicator": true,
"token_indicator": false
}
],
"shazam": [
{
"network_id": "aam",
"network_description": "Accel Money Transfer Advantage",
"bill_pay_indicator": true,
"ecommerce_indicator": true,
"interchange_fee_indicator": "00",
"money_transfer_indicator": true,
"token_indicator": false
}
],
"star": [
{
"network_id": "aam",
"network_description": "Accel Money Transfer Advantage",
"bill_pay_indicator": true,
"ecommerce_indicator": true,
"interchange_fee_indicator": "00",
"money_transfer_indicator": true,
"token_indicator": false
}
]
},
"account_funding_transaction": {
"aft_indicator": {
"pull_funds": {
"cross_border": true,
"domestic": true
}
}
}
}
```
Card Metadata
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|bin|string|true|none|The issuer's Bank Identification Number (BIN). Supports 6, 8, or 11 digit BINs.|
|scheme|string|true|none|The global card scheme. For example, `"american_express"`, `"cartes_bancaires"`, `"diners_club_international"`, `"discover"`, `"eftpos"`, `"jcb"`, `"mastercard"`, or `"visa"`.|
|scheme_local|string|false|none|Replaced by `local_schemes`.
The local card scheme, if the card is co-branded.|
|local_schemes|[string]|false|none|The local card scheme or schemes, if the card is co-branded.|
|card_type|string|false|none|The card type|
|card_category|string|false|none|The card category|
|currency|string|false|none|The card billing currency, as a three-letter ISO-4217 currency code.|
|issuer|string|false|none|The card issuer|
|issuer_country|string|false|none|The card issuer's country, as an ISO-2 code|
|issuer_country_name|string|false|none|The card issuer's country|
|is_combo_card|boolean|false|none|Indicates whether the card is a combo credit and debit card. Applicable to Visa and Mastercard.|
|product_id|string|false|none|The card issuer or scheme's product identifier|
|product_type|string|false|none|The card issuer or scheme's product type|
|subproduct_id|string|false|none|The card issuer or scheme's sub-product identifier|
|regulated_indicator|boolean|false|none|Specifies whether the card is assigned to an interchange regulated BIN range|
|regulated_type|string|false|none|The type of the interchange regulated card BIN range|
|is_reloadable_prepaid|boolean|false|none|Indicates whether the prepaid bank identification number (BIN) is reloadable.|
|anonymous_prepaid_description|string|false|none|The description of the prepaid BIN, specifying if it's an anonymous prepaid card.|
|card_payouts|object|false|none|A card payouts block exists in the response if the format in the request is "card_payouts".|
|» domestic_non_money_transfer|string|false|none|Describes whether the card is eligible for domestic non-money transfer transactions|
|» cross_border_non_money_transfer|string|false|none|Describes whether the card is eligible for cross-border non-money transfer transactions|
|» domestic_gambling|string|false|none|Describes whether the card is eligible for domestic gambling transactions|
|» cross_border_gambling|string|false|none|Describes whether the card is eligible for cross-border gambling transactions|
|» domestic_money_transfer|string|false|none|Describes whether the card is eligible for domestic money transfer transactions|
|» cross_border_money_transfer|string|false|none|Describes whether the card is eligible for cross-border money transfer transactions|
|scheme_metadata|object|false|none|Provides additional information about the scheme or local scheme's capabilities. It is sent if the card is issued in the US and can be used in a PINless debit network.
`scheme_metadata` is returned when you provide:
- The full card number or
- 11 digit bin|
|» accel|[[PinlessDebitSchemeMetadata](#schemapinlessdebitschememetadata)]|false|none|none|
|» pulse|[[PinlessDebitSchemeMetadata](#schemapinlessdebitschememetadata)]|false|none|none|
|» nyce|[[PinlessDebitSchemeMetadata](#schemapinlessdebitschememetadata)]|false|none|none|
|» shazam|[[PinlessDebitSchemeMetadata](#schemapinlessdebitschememetadata)]|false|none|none|
|» star|[[PinlessDebitSchemeMetadata](#schemapinlessdebitschememetadata)]|false|none|none|
|account_funding_transaction|[AccountFundingTransaction](#schemaaccountfundingtransaction)|false|none|Account Funding Transaction|
#### Enumerated Values
|Property|Value|
|---|---|
|scheme_local|cartes_bancaires|
|scheme_local|mada|
|scheme_local|omannet|
|card_type|CREDIT|
|card_type|DEBIT|
|card_type|PREPAID|
|card_type|CHARGE|
|card_type|DEFERRED DEBIT|
|card_type|NETWORK TOKEN|
|card_category|CONSUMER|
|card_category|COMMERCIAL|
|regulated_type|base_regulated|
|regulated_type|fraud_protected_regulated|
|anonymous_prepaid_description|Anonymous prepaid program and not AMLD5 compliant|
|anonymous_prepaid_description|Anonymous prepaid program and AMLD5 compliant|
|anonymous_prepaid_description|Not prepaid or non-anonymous prepaid program/default|
|domestic_non_money_transfer|not_supported|
|domestic_non_money_transfer|standard|
|domestic_non_money_transfer|fast_funds|
|domestic_non_money_transfer|unknown|
|cross_border_non_money_transfer|not_supported|
|cross_border_non_money_transfer|standard|
|cross_border_non_money_transfer|fast_funds|
|cross_border_non_money_transfer|unknown|
|domestic_gambling|not_supported|
|domestic_gambling|standard|
|domestic_gambling|fast_funds|
|domestic_gambling|unknown|
|cross_border_gambling|not_supported|
|cross_border_gambling|standard|
|cross_border_gambling|fast_funds|
|cross_border_gambling|unknown|
|domestic_money_transfer|not_supported|
|domestic_money_transfer|standard|
|domestic_money_transfer|fast_funds|
|domestic_money_transfer|unknown|
|cross_border_money_transfer|not_supported|
|cross_border_money_transfer|standard|
|cross_border_money_transfer|fast_funds|
|cross_border_money_transfer|unknown|
AccountFundingTransaction
```json
{
"aft_indicator": {
"pull_funds": {
"cross_border": true,
"domestic": true
}
}
}
```
Account Funding Transaction
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|aft_indicator|object|false|none|Describes whether the card is eligible for Account Funding Transactions|
|» pull_funds|[PullFunds](#schemapullfunds)|false|none|Describes whether the card is eligible to take funds from different accounts to fund other non-merchant accounts|
```json
{
"network_id": "aam",
"network_description": "Accel Money Transfer Advantage",
"bill_pay_indicator": true,
"ecommerce_indicator": true,
"interchange_fee_indicator": "00",
"money_transfer_indicator": true,
"token_indicator": false
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|network_id|string|false|none|The PINless debit network identifier|
|network_description|string|false|none|The PINless debit network name|
|bill_pay_indicator|boolean|false|none|Describes whether the card is eligible for bill payment transactions|
|ecommerce_indicator|boolean|false|none|Describes whether the card is eligible for e-commerce transactions|
|interchange_fee_indicator|string|false|none|The type of interchange fee used for transactions|
|money_transfer_indicator|boolean|false|none|Describes whether the card is eligible for money transfer transactions|
|token_indicator|boolean|false|none|True indicates that the card PAN is a DPAN, false indicates that it is a FPAN|
PullFunds
```json
{
"cross_border": true,
"domestic": true
}
```
Describes whether the card is eligible to take funds from different accounts to fund other non-merchant accounts
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|cross_border|boolean|false|none|Describes whether the card is eligible for Account Funding Transactions between accounts in different countries|
|domestic|boolean|false|none|Describes whether the card is eligible for Account Funding Transactions between accounts in the same country|
NetworkTokensCard
```json
{
"last4": "6378",
"expiry_month": "5",
"expiry_year": "2025"
}
```
The card details.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|last4|string|true|none|The last four digits of the card number.|
|expiry_month|string|true|none|The card's expiration month.|
|expiry_year|string|true|none|The card's expiration year.|
NetworkTokensCryptogramRequest
```json
{
"transaction_type": "ecom"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|transaction_type|string|true|none|Transaction type the cryptogram is requested for.|
#### Enumerated Values
|Property|Value|
|---|---|
|transaction_type|ecom|
|transaction_type|recurring|
|transaction_type|pos|
|transaction_type|aft|
NetworkTokensCryptogramResponse
```json
{
"cryptogram": "AhJ3hnYAoAbVz5zg1e17MAACAAA=",
"eci": "7",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/network-tokens/nt_xgu3isllqfyu7ktpk5z2yxbwna/cryptograms"
},
"network-token": {
"href": "https://{prefix}.api.checkout.com/network-tokens/nt_xgu3isllqfyu7ktpk5z2yxbwna"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|cryptogram|string|true|none|The cryptogram from the network token. Will only be refreshed for active network tokens and returned when the network token isn't declined or pending|
|eci|string|false|none|Electronic Commerce Indicator (ECI) from the issuer.|
|_links|object|false|none|none|
|» self|[Link](#schemalink)|false|none|Link to request a new cryptogram|
|» network-token|[Link](#schemalink)|false|none|Link to access network token|
NetworkTokensRequest
```json
{
"source": {
"type": "id",
"id": "src_wmlfc3zyhqzehihu7giusaaawu"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|source|[NetworkTokensRequestSource](#schemanetworktokensrequestsource)|true|none|The source object|
NetworkTokensRequestDelete
```json
{
"initiated_by": "token_requestor",
"reason": "other"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|initiated_by|string|true|none|Who initiated/requested the deletion of the token.|
|reason|string|true|none|The reason for deleting the token.|
#### Enumerated Values
|Property|Value|
|---|---|
|initiated_by|cardholder|
|initiated_by|token_requestor|
|reason|fraud|
|reason|other|
NetworkTokensRequestSource
```json
{
"type": "id",
"id": "src_wmlfc3zyhqzehihu7giusaaawu"
}
```
The source object
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[NetworkTokensRequestSourceInstrument](#schemanetworktokensrequestsourceinstrument)|false|none|An existing payment source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[NetworkTokensRequestSourceCard](#schemanetworktokensrequestsourcecard)|false|none|Card details|
NetworkTokensRequestSourceCard
```json
{
"type": "card",
"number": "5436031030606378",
"cvv": "123",
"expiry_month": "5",
"expiry_year": "2025"
}
```
card
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The source type|
|number|string|true|none|The card number.|
|cvv|string|false|none|The CVV number for the card|
|expiry_month|string|true|none|The expiry month of the card.|
|expiry_year|string|true|none|The four-digit expiry year of the card.|
NetworkTokensRequestSourceInstrument
```json
{
"type": "id",
"id": "src_wmlfc3zyhqzehihu7giusaaawu"
}
```
id
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The source type|
|id|string|true|none|The card instrument|
NetworkTokensResponse
```json
{
"card": {
"last4": "6378",
"expiry_month": "5",
"expiry_year": "2025"
},
"network_token": {
"id": "nt_xgu3isllqfyu7ktpk5z2yxbwna",
"state": "active",
"number": "5436424242424242",
"expiry_month": "5",
"expiry_year": "2025",
"type": "vts",
"payment_account_reference": "5001a9f027e5629d11e3949a0800a",
"created_on": "2020-02-11T15:57:32.435+00:00",
"modified_on": "2020-02-11T15:57:32.435+00:00"
},
"token_requestor_id": "1234567890",
"token_scheme_id": "scheme_visa_001",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/network-tokens/nt_xgu3isllqfyu7ktpk5z2yxbwna"
},
"cryptogram": {
"href": "https://{prefix}.api.checkout.com/network-tokens/nt_xgu3isllqfyu7ktpk5z2yxbwna/cryptograms"
},
"card-art": {
"href": "https://card-art.checkout.com/00340aa7bd3de35cb1048369450d8df4"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|card|[NetworkTokensCard](#schemanetworktokenscard)|true|none|The card details.|
|network_token|object|true|none|Network token details|
|» id|string|true|none|Unique token ID assigned by Checkout.com for each token|
|» state|string|true|none|Token status|
|» number|string|true|none|The network token number.|
|» expiry_month|string|true|none|The network token's expiration month.|
|» expiry_year|string|true|none|The network token's expiration year.|
|» type|string|true|none|The type of token|
|» payment_account_reference|string|false|none|Unique Payment account reference value assigned to payment account. All affiliated payment tokens, as well as the underlying PAN, have the same PAR.|
|» created_on|string(date-time)|true|none|When the network token was created|
|» modified_on|string(date-time)|true|none|When the network token was modified|
|token_requestor_id|string|false|none|Token requestor ID|
|token_scheme_id|string|false|none|The scheme-specific identifier for the network token.
For Visa, this is equivalent to the `vProvisionedTokenID`. For Mastercard, this is equivalent to the `tokenUniqueReference`.|
|_links|[NetworkTokensResponseLinks](#schemanetworktokensresponselinks)|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|state|active|
|state|suspended|
|state|inactive|
|type|vts|
|type|mdes|
NetworkTokensResponseLinks
```json
{
"self": {
"href": "https://{prefix}.api.checkout.com/network-tokens/nt_xgu3isllqfyu7ktpk5z2yxbwna"
},
"cryptogram": {
"href": "https://{prefix}.api.checkout.com/network-tokens/nt_xgu3isllqfyu7ktpk5z2yxbwna/cryptograms"
},
"card-art": {
"href": "https://card-art.checkout.com/00340aa7bd3de35cb1048369450d8df4"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|self|[Link](#schemalink)|false|none|Link to access network token|
|cryptogram|[Link](#schemalink)|false|none|Link to request cryptogram|
|card-art|[Link](#schemalink)|false|none|Link to request card art image.
The URL returned contains an image of a non-PCI, digital representation of the cardholder's card.|
NetworkTokensRetrieveResponse
```json
{
"card": {
"last4": "6378",
"expiry_month": "5",
"expiry_year": "2025"
},
"network_token": {
"id": "nt_xgu3isllqfyu7ktpk5z2yxbwna",
"state": "active",
"number": "5436424242424242",
"expiry_month": "5",
"expiry_year": "2025",
"type": "vts",
"payment_account_reference": "5001a9f027e5629d11e3949a0800a",
"created_on": "2020-02-11T15:57:32.435+00:00",
"modified_on": "2020-02-11T15:57:32.435+00:00"
},
"token_requestor_id": "1234567890",
"token_scheme_id": "scheme_visa_001",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/network-tokens/nt_xgu3isllqfyu7ktpk5z2yxbwna"
},
"cryptogram": {
"href": "https://{prefix}.api.checkout.com/network-tokens/nt_xgu3isllqfyu7ktpk5z2yxbwna/cryptograms"
},
"card-art": {
"href": "https://card-art.checkout.com/00340aa7bd3de35cb1048369450d8df4"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|card|[NetworkTokensCard](#schemanetworktokenscard)|true|none|The card details.|
|network_token|object|true|none|Network token details.|
|» id|string|true|none|The unique identifier for the network token.|
|» state|string|true|none|The token's status.|
|» number|string|false|none|The network token number.
This field is only returned when the network token `status` is one of the following:
- `active`
- `suspended`
- `inactive`|
|» expiry_month|string|false|none|The network token's expiration month.
This field is only returned when the network token `status` is one of the following:
- `active`
- `suspended`
- `inactive`|
|» expiry_year|string|false|none|The network token's expiration year.
This field is only returned when the network token `status` is one of the following:
- `active`
- `suspended`
- `inactive`|
|» type|string|true|none|The network token type.|
|» payment_account_reference|string|false|none|The unique reference assigned to the payment account.
All payment tokens and underlying PANs associated with a payment account share the same `payment_account_reference`.|
|» created_on|string(date-time)|true|none|The UTC date and time the network token was created.|
|» modified_on|string(date-time)|true|none|The UTC date and time the network token was modified.|
|token_requestor_id|string|false|none|The unique identifier for the token requestor.|
|token_scheme_id|string|false|none|The scheme-specific identifier for the network token.
For Visa, this is equivalent to the `vProvisionedTokenID`. For Mastercard, this is equivalent to the `tokenUniqueReference`.|
|_links|[NetworkTokensResponseLinks](#schemanetworktokensresponselinks)|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|state|active|
|state|suspended|
|state|inactive|
|state|declined|
|state|requested|
|type|vts|
|type|mdes|
PagingError
```json
{
"request_id": "0HL80RJLS76I7",
"error_type": "request_invalid",
"error_codes": [
"paging_limit_invalid"
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|request_id|string|false|none|none|
|error_type|string|false|none|none|
|error_codes|[string]|false|none|none|
PaymentAuthenticationData
```json
{
"experience": "3ds"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|experience|string|false|none|The authentication experience that was used to authenticate the payment.|
#### Enumerated Values
|Property|Value|
|---|---|
|experience|google_spa|
|experience|3ds|
PaymentAuthenticationRequest
```json
{
"preferred_experiences": [
"google_spa",
"3ds"
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|preferred_experiences|[string]|false|none|An ordered list of preferred authentication experiences to attempt for the payment request.|
AvailablePaymentTypes
```json
[
{
"payment_type": "Regular",
"payment_plan": {
"days_between_payments": 28,
"total_number_of_payments": 5,
"current_payment_number": 3,
"expiry": "20251031",
"name": "Subscription 1234",
"start_date": "20260507",
"amount": 1234
}
}
]
```
Contains information about the available payment type returned by the partner for this purchase.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|payment_type|string|false|none|The available payment type returned by the partner for this purchase.|
|payment_plan|[PaymentPlan](#schemapaymentplan)|false|none|The details of a recurring subscription or installment `payment_plan`.|
#### Enumerated Values
|Property|Value|
|---|---|
|payment_type|Regular|
|payment_type|PayLater|
|payment_type|Installment|
```json
{
"order_id": "test_order_123",
"customer_id": "cus_123",
"session_id": "feb0096d-8486-400d-89fa-2fa716b4521f",
"client_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjgyMzA1ZWJjLWI4MTEtMzYzNy1hYTRjLTY2ZWNhMTg3NGYzZCJ9.eyJzZXNzaW9uX2lkIjoiY2RiNDI0MGQtMTdkYy01MjJkLWJlYjEtYjAyYjRlMzllYTdhIiwiYmFzZV91cmwiOiJodHRwczovL2pzLnBsYXlncm91bmQua2xhcm5hLmNvbS9ldS9rcCIsImRlc2lnbiI6ImtsYXJuYSIsImxhbmd1YWdlIjoiZW4iLCJwdXJjaGFzZV9jb3VudHJ5IjoiREUiLCJlbnZpcm9ubWVudCI6InBsYXlncm91bmQiLCJtZXJjaGFudF9uYW1lIjoiQ2hlY2tvdXQuY29tIiwic2Vzc2lvbl90eXBlIjoiUEFZTUVOVFMiLCJjbGllbnRfZXZlbnRfYmFzZV91cmwiOiJodHRwczovL2V1LnBsYXlncm91bmQua2xhcm5hZXZ0LmNvbSIsInNjaGVtZSI6dHJ1ZSwiZXhwZXJpbWVudHMiOlt7Im5hbWUiOiJrcC1jbGllbnQtb25lLXB1cmNoYXNlLWZsb3ciLCJ2YXJpYXRlIjoidmFyaWF0ZS0xIn0seyJuYW1lIjoia3AtY2xpZW50LXV0b3BpYS1mbG93IiwidmFyaWF0ZSI6InZhcmlhdGUtMSJ9LHsibmFtZSI6ImtwYy0xay1zZXJ2aWNlIiwidmFyaWF0ZSI6InZhcmlhdGUtMSJ9LHsibmFtZSI6ImtwLWNsaWVudC11dG9waWEtc3RhdGljLXdpZGdldCIsInZhcmlhdGUiOiJpbmRleCIsInBhcmFtZXRlcnMiOnsiZHluYW1pYyI6InRydWUifX0seyJuYW1lIjoiaW4tYXBwLXNkay1uZXctaW50ZXJuYWwtYnJvd3NlciIsInBhcmFtZXRlcnMiOnsidmFyaWF0ZV9pZCI6Im5ldy1pbnRlcm5hbC1icm93c2VyLWVuYWJsZSJ9fSx7Im5hbWUiOiJrcC1jbGllbnQtdXRvcGlhLXNkay1mbG93IiwidmFyaWF0ZSI6InZhcmlhdGUtMSJ9LHsibmFtZSI6ImtwLWNsaWVudC11dG9waWEtd2Vidmlldy1mbG93IiwidmFyaWF0ZSI6InZhcmlhdGUtMSJ9LHsibmFtZSI6ImluLWFwcC1zZGstY2FyZC1zY2FubmluZyIsInBhcmFtZXRlcnMiOnsidmFyaWF0ZV9pZCI6ImNhcmQtc2Nhbm5pbmctZW5hYmxlIn19XSwicmVnaW9uIjoiZXUiLCJvcmRlcl9hbW91bnQiOjIwMDAsIm9mZmVyaW5nX29wdHMiOjAsIm9vIjoiY3ciLCJ2ZXJzaW9uIjoidjEuMTAuMC0xNTkwLWczZWJjMzkwNyJ9.ZxThQVo5e0Fck1vwOQ-WWAr7Zw-dsiEhjd3CW-E5p8atUhnBhrzIs6WCBeOOv3ci2VvpykVnDw2qycCTA-7TpTq1wn_kPxxixDQnYJYJzrZMoUhPLZo5pfy2a1S_t2owEQks0THRzu2wRlZwCN4ewDnVqsut60X4r3B92cJENIDtEC4Fs55CjFEmYUtsLXSspNLKvpZe2zg4O_M5yjH7XsBs5YJalZLexf4545G5vJrmVHgiA322mbgWC7BH0IU1A-ql5sFvs190_cjGaLsAvrkh9CVczUPy3X-jr3A5z1YRVfywPpvwKFWL8GZtgrdUZmgiU5_8ZZLkEPzrSucHrQ"
}
```
Processing object
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|order_id|string|false|none|Order id|
|customer_id|string|false|none|Customer id|
|session_id|string|false|none|The unique identifier for the session created.|
|client_token|string|false|none|The client token to pass to the client when initializing the JavaScript SDK.|
PaymentContext
```json
{
"source": {
"type": "klarna",
"account_holder": {
"billing_address": {
"country": "string"
}
}
},
"amount": 6540,
"currency": "USD",
"payment_type": "Recurring",
"capture": true,
"customer": {
"phone": {
"country_code": "+1",
"number": "415 555 2671",
"phone_verified": true
},
"email": "card.success@tabby.ai",
"name": "string",
"email_verified": true,
"summary": {
"registration_date": "2023-05-01",
"first_transaction_date": "2023-07-01",
"last_payment_date": "2023-08-01",
"total_order_count": 15,
"last_payment_amount": 500
}
},
"shipping": {
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@example.com",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"from_address_zip": "123456",
"timeframe": "SameDay",
"method": "BillingAddress",
"delay": 5
},
"processing": {
"plan": {
"type": "MERCHANT_INITIATED_BILLING",
"skip_shipping_address": true,
"immutable_shipping_address": true
},
"discount_amount": 5,
"shipping_amount": 300,
"tax_amount": 3000,
"invoice_id": "string",
"brand_name": "Acme Corporation",
"locale": "en-US",
"shipping_preference": "set_provided_address",
"user_action": "pay_now",
"partner_customer_risk_data": {
"key": "string",
"value": "string"
},
"custom_payment_method_ids": [
"string"
],
"airline_data": [
{
"ticket": {
"number": "045-21351455613",
"issue_date": "2023-05-20",
"issuing_carrier_code": "AI",
"travel_package_indicator": "B",
"travel_agency_name": "World Tours",
"travel_agency_code": "01"
},
"passenger": [
{
"first_name": "John",
"last_name": "White",
"date_of_birth": "1990-05-26",
"address": {
"country": "US"
}
}
],
"flight_leg_details": [
{
"flight_number": "101",
"carrier_code": "BA",
"class_of_travelling": "J",
"departure_airport": "LHR",
"departure_date": "2023-06-19",
"departure_time": "15:30",
"arrival_airport": "LAX",
"stop_over_code": "x",
"fare_basis_code": "SPRSVR"
}
]
}
],
"accommodation_data": [
{
"name": "The Sea View Hotel",
"booking_reference": "HOTEL123",
"check_in_date": "2023-06-20",
"check_out_date": "2023-06-23",
"address": {
"address_line1": "123 Beach Road",
"zip": "10001"
},
"state": "FL",
"country": "USA",
"city": "Los Angeles",
"number_of_rooms": 2,
"guests": [
{
"first_name": "Jane",
"last_name": "Doe",
"date_of_birth": "1985-07-14"
}
],
"room": [
{
"rate": "70",
"number_of_nights_at_room_rate": "3"
}
],
"property_phone": [
{
"country_code": "44",
"number": "7123456789"
}
],
"customer_service_phone": [
{
"country_code": "44",
"number": "7123456789"
}
]
}
]
},
"processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
"reference": "ORD-5023-4E89",
"description": "Set of 3 masks",
"success_url": "https://example.com/payments/success",
"failure_url": "https://example.com/payments/fail",
"items": [
{
"type": "string",
"name": "Test item",
"quantity": 2,
"unit_price": 50,
"reference": "858818ac",
"total_amount": 29000,
"tax_rate": 2000,
"tax_amount": 1000,
"discount_amount": 1000,
"url": "string",
"image_url": "string"
}
],
"metadata": {
"coupon_code": "NY2018"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|source|[PaymentContextSource](#schemapaymentcontextsource)|true|none|The source of the payment.|
|amount|integer|true|none|The Payment Context Payment amount.
The amount must be provided in the minor currency unit.|
|currency|string|true|none|The three-letter ISO currency code.|
|payment_type|string|false|none|"Recurring" must be specified if the payment is paid in multiple installments.|
|capture|boolean|false|none|Whether to capture the later payment (if applicable).|
|customer|[PaymentContextDetailsCustomer](#schemapaymentcontextdetailscustomer)|false|none|The customer details.
Required if `source.type` is `StcPay` or `Tabby`.|
|shipping|[Shipping](#schemashipping)|false|none|The shipping details.|
|processing|[PaymentContextProcessing](#schemapaymentcontextprocessing)|false|none|Use the processing object to influence or override the data during the payment processing.|
|processing_channel_id|string|false|none|The processing channel to be used for the payment.|
|reference|string|false|none|A reference you can later use to identify this Payment Context, such as an order number.
Can only be alphanumeric and must be unique for Benefit.
For Amex, the string limit is 30 characters.|
|description|string|false|none|A description of the Payment Context.|
|success_url|string(uri)|false|none|For redirect payment methods, this overrides the default success redirect URL configured on your account.|
|failure_url|string(uri)|false|none|For redirect payment methods, this overrides the default failure redirect URL configured on your account.|
|items|[PaymentContextItems](#schemapaymentcontextitems)|false|none|The order's line items.
Required for Klarna payments.|
|metadata|object|false|none|A set of key-value pairs store additional information about a transaction. You can send custom fields and up to five user-defined fields, which can be used for reporting purposes. You can supply fields of type
- `string`
- `number`
- `boolean`
Arrays and objects are not supported.
You can provide up to 20 metadata fields per API call, but the value of each field must not exceed 255 characters in length.
You can also reference [`metadata` properties](https://www.checkout.com/docs/business-operations/prevent-fraud/understand-fraud-detection#Metadata) in your custom rules for Fraud Detection.|
#### Enumerated Values
|Property|Value|
|---|---|
|payment_type|Regular|
|payment_type|Recurring|
PaymentContextCustomer
```json
{
"email": "johnsmith@example.com",
"name": "John Smith"
}
```
Customer details
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|email|string|false|none|The customer's email address.|
|name|string|false|none|The customer's name.|
PaymentContextDetails
```json
{
"id": "pct_y3oqhf46pyzuxjbcn2giaqnb44",
"status": "Approved",
"payment_request": {
"source": {
"type": "klarna",
"account_holder": {
"billing_address": {
"country": "string"
}
}
},
"amount": 6540,
"currency": "USD",
"payment_type": "Recurring",
"capture": true,
"customer": {
"email": "johnsmith@example.com",
"name": "John Smith"
},
"shipping": {
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@example.com",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"from_address_zip": "123456",
"timeframe": "SameDay",
"method": "BillingAddress",
"delay": 5
},
"processing": {
"plan": {
"type": "MERCHANT_INITIATED_BILLING",
"skip_shipping_address": true,
"immutable_shipping_address": true
},
"discount_amount": 5,
"shipping_amount": 300,
"tax_amount": 3000,
"invoice_id": "string",
"brand_name": "Acme Corporation",
"locale": "en-US",
"shipping_preference": "set_provided_address",
"user_action": "pay_now",
"partner_customer_risk_data": {
"key": "string",
"value": "string"
},
"custom_payment_method_ids": [
"string"
],
"airline_data": [
{
"ticket": {
"number": "045-21351455613",
"issue_date": "2023-05-20",
"issuing_carrier_code": "AI",
"travel_package_indicator": "B",
"travel_agency_name": "World Tours",
"travel_agency_code": "01"
},
"passenger": [
{
"first_name": "John",
"last_name": "White",
"date_of_birth": "1990-05-26",
"address": {
"country": "US"
}
}
],
"flight_leg_details": [
{
"flight_number": "101",
"carrier_code": "BA",
"class_of_travelling": "J",
"departure_airport": "LHR",
"departure_date": "2023-06-19",
"departure_time": "15:30",
"arrival_airport": "LAX",
"stop_over_code": "x",
"fare_basis_code": "SPRSVR"
}
]
}
],
"accommodation_data": [
{
"name": "The Sea View Hotel",
"booking_reference": "HOTEL123",
"check_in_date": "2023-06-20",
"check_out_date": "2023-06-23",
"address": {
"address_line1": "123 Beach Road",
"zip": "10001"
},
"state": "FL",
"country": "USA",
"city": "Los Angeles",
"number_of_rooms": 2,
"guests": [
{
"first_name": "Jane",
"last_name": "Doe",
"date_of_birth": "1985-07-14"
}
],
"room": [
{
"rate": "70",
"number_of_nights_at_room_rate": "3"
}
],
"property_phone": [
{
"country_code": "44",
"number": "7123456789"
}
],
"customer_service_phone": [
{
"country_code": "44",
"number": "7123456789"
}
]
}
]
},
"processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
"reference": "ORD-5023-4E89",
"description": "Set of 3 masks",
"success_url": "https://example.com/payments/success",
"failure_url": "https://example.com/payments/fail",
"items": [
{
"type": "string",
"name": "Test item",
"quantity": 2,
"unit_price": 50,
"reference": "858818ac",
"total_amount": 29000,
"tax_rate": 2000,
"tax_amount": 1000,
"discount_amount": 1000,
"url": "string",
"image_url": "string"
}
],
"metadata": {
"coupon_code": "NY2018"
}
},
"partner_metadata": {
"order_id": "test_order_123",
"customer_id": "cus_123",
"session_id": "feb0096d-8486-400d-89fa-2fa716b4521f",
"client_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjgyMzA1ZWJjLWI4MTEtMzYzNy1hYTRjLTY2ZWNhMTg3NGYzZCJ9.eyJzZXNzaW9uX2lkIjoiY2RiNDI0MGQtMTdkYy01MjJkLWJlYjEtYjAyYjRlMzllYTdhIiwiYmFzZV91cmwiOiJodHRwczovL2pzLnBsYXlncm91bmQua2xhcm5hLmNvbS9ldS9rcCIsImRlc2lnbiI6ImtsYXJuYSIsImxhbmd1YWdlIjoiZW4iLCJwdXJjaGFzZV9jb3VudHJ5IjoiREUiLCJlbnZpcm9ubWVudCI6InBsYXlncm91bmQiLCJtZXJjaGFudF9uYW1lIjoiQ2hlY2tvdXQuY29tIiwic2Vzc2lvbl90eXBlIjoiUEFZTUVOVFMiLCJjbGllbnRfZXZlbnRfYmFzZV91cmwiOiJodHRwczovL2V1LnBsYXlncm91bmQua2xhcm5hZXZ0LmNvbSIsInNjaGVtZSI6dHJ1ZSwiZXhwZXJpbWVudHMiOlt7Im5hbWUiOiJrcC1jbGllbnQtb25lLXB1cmNoYXNlLWZsb3ciLCJ2YXJpYXRlIjoidmFyaWF0ZS0xIn0seyJuYW1lIjoia3AtY2xpZW50LXV0b3BpYS1mbG93IiwidmFyaWF0ZSI6InZhcmlhdGUtMSJ9LHsibmFtZSI6ImtwYy0xay1zZXJ2aWNlIiwidmFyaWF0ZSI6InZhcmlhdGUtMSJ9LHsibmFtZSI6ImtwLWNsaWVudC11dG9waWEtc3RhdGljLXdpZGdldCIsInZhcmlhdGUiOiJpbmRleCIsInBhcmFtZXRlcnMiOnsiZHluYW1pYyI6InRydWUifX0seyJuYW1lIjoiaW4tYXBwLXNkay1uZXctaW50ZXJuYWwtYnJvd3NlciIsInBhcmFtZXRlcnMiOnsidmFyaWF0ZV9pZCI6Im5ldy1pbnRlcm5hbC1icm93c2VyLWVuYWJsZSJ9fSx7Im5hbWUiOiJrcC1jbGllbnQtdXRvcGlhLXNkay1mbG93IiwidmFyaWF0ZSI6InZhcmlhdGUtMSJ9LHsibmFtZSI6ImtwLWNsaWVudC11dG9waWEtd2Vidmlldy1mbG93IiwidmFyaWF0ZSI6InZhcmlhdGUtMSJ9LHsibmFtZSI6ImluLWFwcC1zZGstY2FyZC1zY2FubmluZyIsInBhcmFtZXRlcnMiOnsidmFyaWF0ZV9pZCI6ImNhcmQtc2Nhbm5pbmctZW5hYmxlIn19XSwicmVnaW9uIjoiZXUiLCJvcmRlcl9hbW91bnQiOjIwMDAsIm9mZmVyaW5nX29wdHMiOjAsIm9vIjoiY3ciLCJ2ZXJzaW9uIjoidjEuMTAuMC0xNTkwLWczZWJjMzkwNyJ9.ZxThQVo5e0Fck1vwOQ-WWAr7Zw-dsiEhjd3CW-E5p8atUhnBhrzIs6WCBeOOv3ci2VvpykVnDw2qycCTA-7TpTq1wn_kPxxixDQnYJYJzrZMoUhPLZo5pfy2a1S_t2owEQks0THRzu2wRlZwCN4ewDnVqsut60X4r3B92cJENIDtEC4Fs55CjFEmYUtsLXSspNLKvpZe2zg4O_M5yjH7XsBs5YJalZLexf4545G5vJrmVHgiA322mbgWC7BH0IU1A-ql5sFvs190_cjGaLsAvrkh9CVczUPy3X-jr3A5z1YRVfywPpvwKFWL8GZtgrdUZmgiU5_8ZZLkEPzrSucHrQ"
}
}
```
Get Payment Context Details response.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|true|none|The unique identifier of the payment context.|
|status|string|false|none|The status of the payment context.|
|payment_request|[PaymentContextDetailsRequest](#schemapaymentcontextdetailsrequest)|true|none|none|
|partner_metadata|[PartnerMetadata](#schemapartnermetadata)|true|none|Processing object|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Created|
|status|Approved|
PaymentContextDetailsCustomer
```json
{
"phone": {
"country_code": "+1",
"number": "415 555 2671",
"phone_verified": true
},
"email": "card.success@tabby.ai",
"name": "string",
"email_verified": true,
"summary": {
"registration_date": "2023-05-01",
"first_transaction_date": "2023-07-01",
"last_payment_date": "2023-08-01",
"total_order_count": 15,
"last_payment_amount": 500
}
}
```
The customer details.
Required if `source.type` is `StcPay` or `Tabby`.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|phone|object|false|none|The customer's phone number.
Required if `source.type` is `StcPay` or `Tabby`.|
|» country_code|string|false|none|The international country calling code.
Required if `source.type` is `StcPay`.|
|» number|string|false|none|The phone number.
Required if `source.type` is `StcPay` or `Tabby`.|
|» phone_verified|boolean|false|none|Indicates if the phone number has been verified.|
|email|string(email)|false|none|The customer's email address.
Required if `source.type` is `Tabby`.|
|name|string|false|none|The customer's full name.
Required if `source.type` is `Tabby`.|
|email_verified|boolean|false|none|Indicates if the email address has been verified.|
|summary|object|false|none|Summary of the customer's transaction history.
Used for risk assessment when `source.type` is `Tabby`|
|» registration_date|string(date)|false|none|The date the customer registered.|
|» first_transaction_date|string(date)|false|none|The date of the customer's first transaction.|
|» last_payment_date|string(date)|false|none|The date of the customer's last payment.|
|» total_order_count|integer|false|none|The total number of orders made by the customer.|
|» last_payment_amount|number(float)|false|none|The amount of the customer's last payment.|
PaymentContextDetailsRequest
```json
{
"source": {
"type": "klarna",
"account_holder": {
"billing_address": {
"country": "string"
}
}
},
"amount": 6540,
"currency": "USD",
"payment_type": "Recurring",
"capture": true,
"customer": {
"email": "johnsmith@example.com",
"name": "John Smith"
},
"shipping": {
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@example.com",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"from_address_zip": "123456",
"timeframe": "SameDay",
"method": "BillingAddress",
"delay": 5
},
"processing": {
"plan": {
"type": "MERCHANT_INITIATED_BILLING",
"skip_shipping_address": true,
"immutable_shipping_address": true
},
"discount_amount": 5,
"shipping_amount": 300,
"tax_amount": 3000,
"invoice_id": "string",
"brand_name": "Acme Corporation",
"locale": "en-US",
"shipping_preference": "set_provided_address",
"user_action": "pay_now",
"partner_customer_risk_data": {
"key": "string",
"value": "string"
},
"custom_payment_method_ids": [
"string"
],
"airline_data": [
{
"ticket": {
"number": "045-21351455613",
"issue_date": "2023-05-20",
"issuing_carrier_code": "AI",
"travel_package_indicator": "B",
"travel_agency_name": "World Tours",
"travel_agency_code": "01"
},
"passenger": [
{
"first_name": "John",
"last_name": "White",
"date_of_birth": "1990-05-26",
"address": {
"country": "US"
}
}
],
"flight_leg_details": [
{
"flight_number": "101",
"carrier_code": "BA",
"class_of_travelling": "J",
"departure_airport": "LHR",
"departure_date": "2023-06-19",
"departure_time": "15:30",
"arrival_airport": "LAX",
"stop_over_code": "x",
"fare_basis_code": "SPRSVR"
}
]
}
],
"accommodation_data": [
{
"name": "The Sea View Hotel",
"booking_reference": "HOTEL123",
"check_in_date": "2023-06-20",
"check_out_date": "2023-06-23",
"address": {
"address_line1": "123 Beach Road",
"zip": "10001"
},
"state": "FL",
"country": "USA",
"city": "Los Angeles",
"number_of_rooms": 2,
"guests": [
{
"first_name": "Jane",
"last_name": "Doe",
"date_of_birth": "1985-07-14"
}
],
"room": [
{
"rate": "70",
"number_of_nights_at_room_rate": "3"
}
],
"property_phone": [
{
"country_code": "44",
"number": "7123456789"
}
],
"customer_service_phone": [
{
"country_code": "44",
"number": "7123456789"
}
]
}
]
},
"processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
"reference": "ORD-5023-4E89",
"description": "Set of 3 masks",
"success_url": "https://example.com/payments/success",
"failure_url": "https://example.com/payments/fail",
"items": [
{
"type": "string",
"name": "Test item",
"quantity": 2,
"unit_price": 50,
"reference": "858818ac",
"total_amount": 29000,
"tax_rate": 2000,
"tax_amount": 1000,
"discount_amount": 1000,
"url": "string",
"image_url": "string"
}
],
"metadata": {
"coupon_code": "NY2018"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|source|[PaymentContextSource](#schemapaymentcontextsource)|true|none|The source of the payment.|
|amount|integer|true|none|The payment context payment amount.
The amount must be provided in the minor currency unit.|
|currency|string|true|none|The three-letter ISO currency code.|
|payment_type|string|false|none|Set this value to `Recurring` if the payment is going to be paid in multiple installments.|
|capture|boolean|false|none|Specifies whether to capture the later payment (if applicable).|
|customer|[PaymentContextCustomer](#schemapaymentcontextcustomer)|false|none|Customer details|
|shipping|[Shipping](#schemashipping)|false|none|The shipping details.|
|processing|[PaymentContextProcessing](#schemapaymentcontextprocessing)|false|none|Use the processing object to influence or override the data during the payment processing.|
|processing_channel_id|string|false|none|The processing channel to be used for the payment.|
|reference|string|false|none|A reference you can later use to identify this payment context, such as an order number.
Can only be alphanumeric and must be unique for Benefit.
For American Express, the string limit is 30 characters.|
|description|string|false|none|A description of the payment context.|
|success_url|string(uri)|false|none|For redirect payment methods, this overrides the default success redirect URL configured on your account.|
|failure_url|string(uri)|false|none|For redirect payment methods, this overrides the default failure redirect URL configured on your account.|
|items|[PaymentContextItems](#schemapaymentcontextitems)|true|none|The order's line items.
Required for Klarna payments.|
|metadata|object|false|none|A set of key-value pairs store additional information about a transaction. You can send custom fields and up to five user-defined fields, which can be used for reporting purposes. You can supply fields of type
- `string`
- `number`
- `boolean`
Arrays and objects are not supported.
You can provide up to 20 metadata fields per API call, but the value of each field must not exceed 255 characters in length.
You can also reference [`metadata` properties](https://www.checkout.com/docs/business-operations/prevent-fraud/understand-fraud-detection#Metadata) in your custom rules for Fraud Detection.|
#### Enumerated Values
|Property|Value|
|---|---|
|payment_type|Regular|
|payment_type|Recurring|
PaymentContextId
```json
"pct_y3oqhf46pyzuxjbcn2giaqnb44"
```
Payment Context's unique identifier.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|Payment Context's unique identifier.|
PaymentContextItems
```json
[
{
"type": "string",
"name": "Test item",
"quantity": 2,
"unit_price": 50,
"reference": "858818ac",
"total_amount": 29000,
"tax_rate": 2000,
"tax_amount": 1000,
"discount_amount": 1000,
"url": "string",
"image_url": "string"
}
]
```
The order's line items.
Required for Klarna payments.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|false|none|The item type. For example, `physical`, `digital`.|
|name|string|false|none|The descriptive name of the line item.|
|quantity|integer|false|none|The number of line items.|
|unit_price|integer|false|none|The unit price of the item in minor currency unit.|
|reference|string|false|none|The item reference or product SKU (stock-keeping unit).|
|total_amount|number|false|none|The total cost of the line item (including any tax and discount amount) in minor currency unit. Value = (quantity x unit_price) - discount_amount.|
|tax_rate|number|false|none|The tax rate of the item line in minor units. The percentage value is represented with two implicit decimals. For example, 2000=20%.|
|tax_amount|number|false|none|The total amount of sales tax or value-added tax (VAT) on the total purchase amount. Tax should be included in the total purchase.|
|discount_amount|number|false|none|The discount applied to each invoice line item.|
|url|string|false|none|Link to the line item's product page.|
|image_url|string|false|none|Link to the line item's product page.|
PaymentContextPaymentRequest
```json
{
"payment_context_id": "pct_y3oqhf46pyzuxjbcn2giaqnb44",
"amount": 6540,
"reference": "ORD-5023-4E89",
"description": "Set of 3 masks",
"processing_channel_id": "string",
"processing": {
"invoice_id": "string",
"shipping_amount": 300,
"discount_amount": 5,
"tax_amount": 3000,
"otp_value": "966557877988",
"airline_data": [
{
"ticket": {
"number": "045-21351455613",
"issue_date": "2023-05-20",
"issuing_carrier_code": "AI",
"travel_package_indicator": "B",
"travel_agency_name": "World Tours",
"travel_agency_code": "01"
},
"passenger": [
{
"first_name": "John",
"last_name": "White",
"date_of_birth": "1990-05-26",
"address": {
"country": "US"
}
}
],
"flight_leg_details": [
{
"flight_number": "101",
"carrier_code": "BA",
"class_of_travelling": "J",
"departure_airport": "LHR",
"departure_date": "2023-06-19",
"departure_time": "15:30",
"arrival_airport": "LAX",
"stop_over_code": "x",
"fare_basis_code": "SPRSVR"
}
]
}
],
"accommodation_data": [
{
"name": "The Sea View Hotel",
"booking_reference": "HOTEL123",
"check_in_date": "2023-06-20",
"check_out_date": "2023-06-23",
"address": {
"address_line1": "123 Beach Road",
"zip": "10001"
},
"state": "FL",
"country": "USA",
"city": "Los Angeles",
"number_of_rooms": 2,
"guests": [
{
"first_name": "Jane",
"last_name": "Doe",
"date_of_birth": "1985-07-14"
}
],
"room": [
{
"rate": "70",
"number_of_nights_at_room_rate": "3"
}
],
"property_phone": [
{
"country_code": "44",
"number": "7123456789"
}
],
"customer_service_phone": [
{
"country_code": "44",
"number": "7123456789"
}
]
}
]
},
"shipping": {
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@example.com",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"from_address_zip": "123456",
"timeframe": "SameDay",
"method": "BillingAddress",
"delay": 5
},
"segment": {
"brand": "Acme Corporation",
"business_category": "Inward Payments",
"market": "UK"
}
}
```
Payment Context
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|payment_context_id|[PaymentContextId](#schemapaymentcontextid)|true|none|Payment Context's unique identifier.|
|amount|integer|false|none|The payment amount.
The amount must be provided in the minor currency unit.|
|reference|string|false|none|A reference you can later use to identify this payment, such as an order number.
Can only be alphanumeric and must be unique for Benefit.
For Amex, the string limit is 30 characters.|
|description|string|false|none|A description of the payment.|
|processing_channel_id|string|false|none|The processing channel to be used for the payment context. Required if this was not set in the request for the OAuth token.|
|processing|object|false|none|Use the processing object to influence or override the data during the payment processing.|
|» invoice_id|string|false|none|The identification number of the invoice.|
|» shipping_amount|number|false|none|The total freight or shipping and handling charges for the transaction.|
|» discount_amount|number|false|none|The discount amount.|
|» tax_amount|number|false|none|The total tax amount for the transaction, in [minor currency units](https://www.checkout.com/docs/payments/accept-payments/calculating-the-amount).|
|» otp_value|string|false|none|One time password sent to customer by SMS.
Required if `source.type` is `StcPay`.|
|» airline_data|[AirlineData](#schemaairlinedata)|false|none|Contains information about the airline ticket and flights booked by the customer.|
|» accommodation_data|[AccommodationData](#schemaaccommodationdata)|false|none|Contains information about the accommodation booked by the customer.|
|shipping|[Shipping](#schemashipping)|false|none|The shipping details.|
|segment|[Segment](#schemasegment)|false|none|The dimension details about business segment for payment request. At least one dimension required.|
PaymentContextPaymentResponse
```json
{
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"payment_type": "Recurring",
"payment_plan": {
"financing": false,
"days_between_payments": 28,
"total_number_of_payments": 5,
"current_payment_number": 3,
"expiry": "20251031",
"name": "Subscription 1234",
"start_date": "20260507",
"amount": 1234
},
"processing": {
"partner_order_id": "5GK24544NA744002L"
},
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "johnsmith@example.com",
"name": "John Smith",
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"summary": {
"registration_date": "2023-05-01",
"first_transaction_date": "2023-07-01",
"last_payment_date": "2023-08-01",
"total_order_count": 15,
"last_payment_amount": 500,
"is_premium_customer": true,
"is_returning_customer": true,
"lifetime_value": 500
}
},
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pezuxjbcn2giaqnb44"
}
}
}
```
PaymentContextResponse
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[PaymentId](#schemapaymentid)|true|none|The payment identifier.|
|payment_type|string|false|none|This is required for card-not-present payments. For example, recurring or mail order / telephone order payments.|
|payment_plan|[PlanInstallment](#schemaplaninstallment)|false|none|The details of the installment plan|
|processing|object|false|none|none|
|» partner_order_id|string|false|none|The partner order ID.|
|customer|[CustomerResponse](#schemacustomerresponse)|false|none|Stored customer details|
|_links|object|true|none|The links related to the payment.|
|» self|[Link](#schemalink)|false|none|The URI of the Payment Context.|
#### Enumerated Values
|Property|Value|
|---|---|
|payment_type|Regular|
|payment_type|Recurring|
|payment_type|Installment|
|payment_type|PayLater|
PaymentContextProcessing
```json
{
"plan": {
"type": "MERCHANT_INITIATED_BILLING",
"skip_shipping_address": true,
"immutable_shipping_address": true
},
"discount_amount": 5,
"shipping_amount": 300,
"tax_amount": 3000,
"invoice_id": "string",
"brand_name": "Acme Corporation",
"locale": "en-US",
"shipping_preference": "set_provided_address",
"user_action": "pay_now",
"partner_customer_risk_data": {
"key": "string",
"value": "string"
},
"custom_payment_method_ids": [
"string"
],
"airline_data": [
{
"ticket": {
"number": "045-21351455613",
"issue_date": "2023-05-20",
"issuing_carrier_code": "AI",
"travel_package_indicator": "B",
"travel_agency_name": "World Tours",
"travel_agency_code": "01"
},
"passenger": [
{
"first_name": "John",
"last_name": "White",
"date_of_birth": "1990-05-26",
"address": {
"country": "US"
}
}
],
"flight_leg_details": [
{
"flight_number": "101",
"carrier_code": "BA",
"class_of_travelling": "J",
"departure_airport": "LHR",
"departure_date": "2023-06-19",
"departure_time": "15:30",
"arrival_airport": "LAX",
"stop_over_code": "x",
"fare_basis_code": "SPRSVR"
}
]
}
],
"accommodation_data": [
{
"name": "The Sea View Hotel",
"booking_reference": "HOTEL123",
"check_in_date": "2023-06-20",
"check_out_date": "2023-06-23",
"address": {
"address_line1": "123 Beach Road",
"zip": "10001"
},
"state": "FL",
"country": "USA",
"city": "Los Angeles",
"number_of_rooms": 2,
"guests": [
{
"first_name": "Jane",
"last_name": "Doe",
"date_of_birth": "1985-07-14"
}
],
"room": [
{
"rate": "70",
"number_of_nights_at_room_rate": "3"
}
],
"property_phone": [
{
"country_code": "44",
"number": "7123456789"
}
],
"customer_service_phone": [
{
"country_code": "44",
"number": "7123456789"
}
]
}
]
}
```
Use the processing object to influence or override the data sent during card processing.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|plan|object|false|none|The plan details for a recurring payment with PayPal. This is required when `payment_type: "recurring"`.|
|» type|string|true|none|Type of payment plan.|
|» skip_shipping_address|boolean|true|none|none|
|» immutable_shipping_address|boolean|true|none|none|
|discount_amount|number|false|none|The discount amount the merchant applied to the transaction.|
|shipping_amount|number|false|none|The total freight or shipping and handling charges for the transaction.|
|tax_amount|number|false|none|The total tax amount for the transaction, in [minor currency units](https://www.checkout.com/docs/payments/accept-payments/calculating-the-amount).|
|invoice_id|string|false|none|Invoice ID number.|
|brand_name|string|false|none|The label that overrides the business name in the PayPal account on the PayPal pages.|
|locale|string|false|none|The language and region of the customer in ISO 639-2 language code; value consists of language-country.|
|shipping_preference|string|false|none|Shipping preference.|
|user_action|string|false|none|Property required by PayPal to have an appropriate payment flow.|
|partner_customer_risk_data|object|false|none|An array of key-and-value pairs with merchant-specific data for the transaction.|
|» key|string|false|none|The key for the pair.|
|» value|string|false|none|The value for the pair.|
|custom_payment_method_ids|[string]|false|none|Promo codes - An array that can be used to define which of the configured payment options within a payment category (pay_later, pay_over_time, etc.) should be shown for this purchase.|
|airline_data|[AirlineData](#schemaairlinedata)|false|none|Contains information about the airline ticket and flights booked by the customer.|
|accommodation_data|[AccommodationData](#schemaaccommodationdata)|false|none|Contains information about the accommodation booked by the customer.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|MERCHANT_INITIATED_BILLING|
|type|MERCHANT_INITIATED_BILLING_SINGLE_AGREEMENT|
|type|CHANNEL_INITIATED_BILLING|
|type|CHANNEL_INITIATED_BILLING_SINGLE_AGREEMENT|
|type|RECURRING_PAYMENTS|
|type|PRE_APPROVED_PAYMENTS|
|shipping_preference|no_shipping|
|shipping_preference|set_provided_address|
|shipping_preference|get_from_file|
|user_action|pay_now|
|user_action|continue|
PaymentContextResponse
```json
{
"id": "pct_y3oqhf46pyzuxjbcn2giaqnb44",
"amount": 0,
"processed_on": "2019-08-24T14:15:22Z",
"status": "Pending",
"response_code": "2000",
"response_summary": "Rejected",
"available_payment_types": [
{
"payment_type": "Regular",
"payment_plan": {
"days_between_payments": 28,
"total_number_of_payments": 5,
"current_payment_number": 3,
"expiry": "20251031",
"name": "Subscription 1234",
"start_date": "20260507",
"amount": 1234
}
}
],
"unavailable_payment_types": [
{
"payment_type": "Regular",
"rejection_reason": "string",
"payment_plan": {
"days_between_payments": 28,
"total_number_of_payments": 5,
"current_payment_number": 3,
"expiry": "20251031",
"name": "Subscription 1234",
"start_date": "20260507",
"amount": 1234
},
"description": "string"
}
],
"partner_metadata": {
"order_id": "test_order_123",
"customer_id": "cus_123",
"session_id": "feb0096d-8486-400d-89fa-2fa716b4521f",
"client_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjgyMzA1ZWJjLWI4MTEtMzYzNy1hYTRjLTY2ZWNhMTg3NGYzZCJ9.eyJzZXNzaW9uX2lkIjoiY2RiNDI0MGQtMTdkYy01MjJkLWJlYjEtYjAyYjRlMzllYTdhIiwiYmFzZV91cmwiOiJodHRwczovL2pzLnBsYXlncm91bmQua2xhcm5hLmNvbS9ldS9rcCIsImRlc2lnbiI6ImtsYXJuYSIsImxhbmd1YWdlIjoiZW4iLCJwdXJjaGFzZV9jb3VudHJ5IjoiREUiLCJlbnZpcm9ubWVudCI6InBsYXlncm91bmQiLCJtZXJjaGFudF9uYW1lIjoiQ2hlY2tvdXQuY29tIiwic2Vzc2lvbl90eXBlIjoiUEFZTUVOVFMiLCJjbGllbnRfZXZlbnRfYmFzZV91cmwiOiJodHRwczovL2V1LnBsYXlncm91bmQua2xhcm5hZXZ0LmNvbSIsInNjaGVtZSI6dHJ1ZSwiZXhwZXJpbWVudHMiOlt7Im5hbWUiOiJrcC1jbGllbnQtb25lLXB1cmNoYXNlLWZsb3ciLCJ2YXJpYXRlIjoidmFyaWF0ZS0xIn0seyJuYW1lIjoia3AtY2xpZW50LXV0b3BpYS1mbG93IiwidmFyaWF0ZSI6InZhcmlhdGUtMSJ9LHsibmFtZSI6ImtwYy0xay1zZXJ2aWNlIiwidmFyaWF0ZSI6InZhcmlhdGUtMSJ9LHsibmFtZSI6ImtwLWNsaWVudC11dG9waWEtc3RhdGljLXdpZGdldCIsInZhcmlhdGUiOiJpbmRleCIsInBhcmFtZXRlcnMiOnsiZHluYW1pYyI6InRydWUifX0seyJuYW1lIjoiaW4tYXBwLXNkay1uZXctaW50ZXJuYWwtYnJvd3NlciIsInBhcmFtZXRlcnMiOnsidmFyaWF0ZV9pZCI6Im5ldy1pbnRlcm5hbC1icm93c2VyLWVuYWJsZSJ9fSx7Im5hbWUiOiJrcC1jbGllbnQtdXRvcGlhLXNkay1mbG93IiwidmFyaWF0ZSI6InZhcmlhdGUtMSJ9LHsibmFtZSI6ImtwLWNsaWVudC11dG9waWEtd2Vidmlldy1mbG93IiwidmFyaWF0ZSI6InZhcmlhdGUtMSJ9LHsibmFtZSI6ImluLWFwcC1zZGstY2FyZC1zY2FubmluZyIsInBhcmFtZXRlcnMiOnsidmFyaWF0ZV9pZCI6ImNhcmQtc2Nhbm5pbmctZW5hYmxlIn19XSwicmVnaW9uIjoiZXUiLCJvcmRlcl9hbW91bnQiOjIwMDAsIm9mZmVyaW5nX29wdHMiOjAsIm9vIjoiY3ciLCJ2ZXJzaW9uIjoidjEuMTAuMC0xNTkwLWczZWJjMzkwNyJ9.ZxThQVo5e0Fck1vwOQ-WWAr7Zw-dsiEhjd3CW-E5p8atUhnBhrzIs6WCBeOOv3ci2VvpykVnDw2qycCTA-7TpTq1wn_kPxxixDQnYJYJzrZMoUhPLZo5pfy2a1S_t2owEQks0THRzu2wRlZwCN4ewDnVqsut60X4r3B92cJENIDtEC4Fs55CjFEmYUtsLXSspNLKvpZe2zg4O_M5yjH7XsBs5YJalZLexf4545G5vJrmVHgiA322mbgWC7BH0IU1A-ql5sFvs190_cjGaLsAvrkh9CVczUPy3X-jr3A5z1YRVfywPpvwKFWL8GZtgrdUZmgiU5_8ZZLkEPzrSucHrQ"
},
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/payment-contexts/pct_y3oqhf46pyzuxjbcn2giaqnb44"
}
}
}
```
Payment Context
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[PaymentContextId](#schemapaymentcontextid)|true|none|Payment Context's unique identifier.|
|amount|integer|false|none|The payment amount.|
|processed_on|[ServerTimestamp](#schemaservertimestamp)|true|none|The date and time when the payment context was processed in UTC.|
|status|string|false|none|The status of the payment context.|
|response_code|string|false|none|The gateway response code.|
|response_summary|string|false|none|The gateway response summary.|
|available_payment_types|[AvailablePaymentTypes](#schemaavailablepaymenttypes)|false|none|Contains information about the available payment type returned by the partner for this purchase.|
|unavailable_payment_types|[UnavailablePaymentTypes](#schemaunavailablepaymenttypes)|false|none|Contains information about the unavailable payment type returned by the partner for this purchase.|
|partner_metadata|[PartnerMetadata](#schemapartnermetadata)|true|none|Processing object|
|_links|object|true|none|The links related to the payment.|
|» self|[Link](#schemalink)|false|none|The URI of the Payment Context.|
PaymentContextSource
```json
{
"type": "klarna",
"account_holder": {
"billing_address": {
"country": "string"
}
}
}
```
The source of the payment.
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentContextKlarnaSource](#schemapaymentcontextklarnasource)|false|none|Klarna Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentContextPayPalSource](#schemapaymentcontextpaypalsource)|false|none|PayPal Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentContextStcPaySource](#schemapaymentcontextstcpaysource)|false|none|StcPay Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentContextTabbySource](#schemapaymentcontexttabbysource)|false|none|PayPal Source|
PaymentContextKlarnaSource
```json
{
"type": "klarna",
"account_holder": {
"billing_address": {
"country": "string"
}
}
}
```
klarna
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The source type of the payment context request.|
|account_holder|object|true|none|none|
|» billing_address|object|true|none|none|
|»» country|string|true|none|The billing country or purchase country of the customer. The two-letter ISO country code of the address|
PaymentContextPayPalSource
```json
{
"type": "paypal"
}
```
paypal
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The source type of the payment context request.|
PaymentContextStcPaySource
```json
{
"type": "stcpay"
}
```
stcpay
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The source type of the payment context request.|
PaymentContextTabbySource
```json
{
"type": "tabby"
}
```
tabby
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The source type of the payment context request.|
UnavailablePaymentTypes
```json
[
{
"payment_type": "Regular",
"rejection_reason": "string",
"payment_plan": {
"days_between_payments": 28,
"total_number_of_payments": 5,
"current_payment_number": 3,
"expiry": "20251031",
"name": "Subscription 1234",
"start_date": "20260507",
"amount": 1234
},
"description": "string"
}
]
```
Contains information about the unavailable payment type returned by the partner for this purchase.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|payment_type|string|false|none|The unavailable payment type returned by the partner for this purchase.|
|rejection_reason|string|false|none|The reason why the payment type is unavailable.|
|payment_plan|[PaymentPlan](#schemapaymentplan)|false|none|The details of a recurring subscription or installment `payment_plan`.|
|description|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|payment_type|Regular|
|payment_type|PayLater|
|payment_type|Installment|
PaymentInterfacesStorePaymentDetails
```json
"disabled"
```
Specifies whether you intend to store the cardholder's payment details.
If you set this field to `enabled`, you must:
- have obtained consent from the cardholder to store their payment details
- provide a customer ID or email address in the request
If the request's `payment_type` is set to one of the following values, you do not need to provide this field:
- `Installment`
- `Recurring`
- `Unscheduled`
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|Specifies whether you intend to store the cardholder's payment details.
If you set this field to `enabled`, you must:
- have obtained consent from the cardholder to store their payment details
- provide a customer ID or email address in the request
If the request's `payment_type` is set to one of the following values, you do not need to provide this field:
- `Installment`
- `Recurring`
- `Unscheduled`|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|disabled|
|*anonymous*|enabled|
GetPaymentLinkResponse
```json
{
"id": "pl_ELqQJXdXzabU",
"status": "Active",
"payment_id": "pay_88cb4e671m1da22e9bbbyx",
"amount": 100,
"currency": "GBP",
"reference": "ORD-123A",
"description": "Payment for Gold Necklace",
"created_on": "2021-08-19T20:25:28.725Z",
"expires_on": "2021-08-20T20:25:28+08:00",
"processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
"amount_allocations": [
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4",
"amount": 1000,
"reference": "ORD-5023-4E89",
"commission": {
"amount": 1000,
"percentage": 1.125
}
}
],
"customer": {
"email": "brucewayne@email.com",
"name": "Bruce Wayne"
},
"shipping": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"billing": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"products": [
{
"reference": "string",
"url": "https://example.com/products/gold-necklace",
"name": "Gold Necklace",
"quantity": 1,
"price": 1000
}
],
"metadata": {},
"locale": "ar",
"return_url": "https://example.com/success",
"_links": {
"self": {
"href": "https://{prefix}.api.sandbox.checkout.com/payment-links/pl_ELqQJXdXzabU"
},
"redirect": {
"href": "https://pay.sandbox.checkout.com/link/pl_ELqQJXdXzabU"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[PaymentLinkId](#schemapaymentlinkid)|true|none|The unique identifier for a Payment Link.|
|status|string|true|none|The status of the Payment Link:
- `Active`: The Payment Link can accept a payment from the customer. A payment may have been attempted by the customer but not completed successfully.
- `Payment Received`: A payment has been received successfully using this Payment Link.
- `Expired`: The Payment Link has expired and can no longer be accessed.|
|payment_id|string|false|none|Unique identifier for an in progress or completed payment for this Payment Link.|
|amount|integer|true|none|The original payment amount.|
|currency|string|true|none|The three-letter ISO currency code of the payment.
|
|reference|string|false|none|Your reference for the payment.|
|description|string|false|none|A description of the payment.|
|created_on|string(date-time)|true|none|The date and time when the Payment Link was created.|
|expires_on|string(date-time)|true|none|The date and time when the Payment Link expires.|
|processing_channel_id|string|false|none|The processing channel to be used for the payment|
|amount_allocations|[AmountAllocations](#schemaamountallocations)|false|none|The sub-entities that the payment is being processed on behalf of|
|customer|object|false|none|The customer's details.|
|» email|string(email)|false|none|The email address for the customer.|
|» name|string|false|none|The customer's name.|
|shipping|object|false|none|The address any products are being sent to.|
|» address|[Address](#schemaaddress)|true|none|The customer's address to ship to.|
|billing|object|true|none|The billing details.|
|» address|[Address](#schemaaddress)|true|none|The billing address.|
|» phone|[PhoneNumber](#schemaphonenumber)|false|none|The customer's phone number.|
|products|[PaymentInterfacesProducts](#schemapaymentinterfacesproducts)|false|none|Contains details about the products in the order.|
|metadata|object|false|none|Any additional information stored at the point of creation.|
|locale|string|false|none|The language that the Payment Link page is displayed in.|
|return_url|string(uri)|false|none|If provided, the success page will include a button that redirects your customer to the provided URL.|
|_links|[PaymentLinkResponseLinks](#schemapaymentlinkresponselinks)|true|none|The links related to the Payment Link.|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentLinkResponseStatusActive](#schemapaymentlinkresponsestatusactive)|false|none|A Payment Link that is active and can accept a payment from a customer.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentLinkResponseStatusPaymentReceived](#schemapaymentlinkresponsestatuspaymentreceived)|false|none|A Payment Link that has received a payment|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentLinkResponseStatusExpired](#schemapaymentlinkresponsestatusexpired)|false|none|An expired Payment Link|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Active|
|status|Payment Received|
|status|Expired|
|locale|ar|
|locale|da-DK|
|locale|de-DE|
|locale|el|
|locale|en-GB|
|locale|es-ES|
|locale|fi-FI|
|locale|fil-PH|
|locale|fr-FR|
|locale|hi-IN|
|locale|id-ID|
|locale|it-IT|
|locale|ja-JP|
|locale|ms-MY|
|locale|nb-NO|
|locale|nl-NL|
|locale|pt-PT|
|locale|sv-SE|
|locale|th-TH|
|locale|vi-VN|
|locale|zh-CN|
|locale|zh-HK|
|locale|zh-TW|
PaymentLinkId
```json
"stringstringstr"
```
The unique identifier for a Payment Link.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The unique identifier for a Payment Link.|
PaymentLinkResponseLinks
```json
{
"self": {
"href": "https://{prefix}.api.sandbox.checkout.com/payment-links/pl_ELqQJXdXzabU"
},
"redirect": {
"href": "https://pay.sandbox.checkout.com/link/pl_ELqQJXdXzabU"
}
}
```
The links related to the Payment Link.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|self|[Link](#schemalink)|true|none|The URI of the Payment Link details.|
|redirect|[Link](#schemalink)|true|none|The link to visit the Payment Link page.|
|payment|[Link](#schemalink)|false|none|The URI of the in progress or completed payment for this Payment Link.|
|payment_actions|[Link](#schemalink)|false|none|The URI of the actions associated with the in progress or completed payment for this Payment Link.|
PaymentLinkResponseStatusActive
```json
{
"id": "pl_ELqQJXdXzabU",
"status": "Active",
"payment_id": "pay_88cb4e671m1da22e9bbbyx",
"amount": 100,
"currency": "GBP",
"reference": "ORD-123A",
"description": "Payment for Gold Necklace",
"created_on": "2021-08-19T20:25:28.725Z",
"expires_on": "2021-08-20T20:25:28+08:00",
"processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
"amount_allocations": [
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4",
"amount": 1000,
"reference": "ORD-5023-4E89",
"commission": {
"amount": 1000,
"percentage": 1.125
}
}
],
"customer": {
"email": "brucewayne@email.com",
"name": "Bruce Wayne"
},
"shipping": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"billing": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"products": [
{
"reference": "string",
"url": "https://example.com/products/gold-necklace",
"name": "Gold Necklace",
"quantity": 1,
"price": 1000
}
],
"metadata": {},
"locale": "ar",
"return_url": "https://example.com/success",
"_links": {
"self": {
"href": "https://{prefix}.api.sandbox.checkout.com/payment-links/pl_ELqQJXdXzabU"
},
"redirect": {
"href": "https://pay.sandbox.checkout.com/link/pl_ELqQJXdXzabU"
}
}
}
```
Active
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[PaymentLinkId](#schemapaymentlinkid)|true|none|The unique identifier for a Payment Link.|
|status|string|true|none|The status of the Payment Link:
- `Active`: The Payment Link can accept a payment from the customer. A payment may have been attempted by the customer but not completed successfully.
- `Payment Received`: A payment has been received successfully using this Payment Link.
- `Expired`: The Payment Link has expired and can no longer be accessed.|
|payment_id|string|false|none|Unique identifier for an in progress or completed payment for this Payment Link.|
|amount|integer|true|none|The original payment amount.|
|currency|string|true|none|The three-letter ISO currency code of the payment.
|
|reference|string|false|none|Your reference for the payment.|
|description|string|false|none|A description of the payment.|
|created_on|string(date-time)|true|none|The date and time when the Payment Link was created.|
|expires_on|string(date-time)|true|none|The date and time when the Payment Link expires.|
|processing_channel_id|string|false|none|The processing channel to be used for the payment|
|amount_allocations|[AmountAllocations](#schemaamountallocations)|false|none|The sub-entities that the payment is being processed on behalf of|
|customer|object|false|none|The customer's details.|
|» email|string(email)|false|none|The email address for the customer.|
|» name|string|false|none|The customer's name.|
|shipping|object|false|none|The address any products are being sent to.|
|» address|[Address](#schemaaddress)|true|none|The customer's address to ship to.|
|billing|object|true|none|The billing details.|
|» address|[Address](#schemaaddress)|true|none|The billing address.|
|» phone|[PhoneNumber](#schemaphonenumber)|false|none|The customer's phone number.|
|products|[PaymentInterfacesProducts](#schemapaymentinterfacesproducts)|false|none|Contains details about the products in the order.|
|metadata|object|false|none|Any additional information stored at the point of creation.|
|locale|string|false|none|The language that the Payment Link page is displayed in.|
|return_url|string(uri)|false|none|If provided, the success page will include a button that redirects your customer to the provided URL.|
|_links|[PaymentLinkResponseLinks](#schemapaymentlinkresponselinks)|true|none|The links related to the Payment Link.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Active|
|locale|ar|
|locale|da-DK|
|locale|de-DE|
|locale|el|
|locale|en-GB|
|locale|es-ES|
|locale|fi-FI|
|locale|fil-PH|
|locale|fr-FR|
|locale|hi-IN|
|locale|id-ID|
|locale|it-IT|
|locale|ja-JP|
|locale|ms-MY|
|locale|nb-NO|
|locale|nl-NL|
|locale|pt-PT|
|locale|sv-SE|
|locale|th-TH|
|locale|vi-VN|
|locale|zh-CN|
|locale|zh-HK|
|locale|zh-TW|
PaymentLinkResponseStatusExpired
```json
{
"id": "pl_ELqQJXdXzabU",
"status": "Expired",
"payment_id": "pay_88cb4e671m1da22e9bbbyx",
"amount": 100,
"currency": "GBP",
"reference": "ORD-123A",
"description": "Payment for Gold Necklace",
"created_on": "2021-08-19T20:25:28.725Z",
"expires_on": "2021-08-20T20:25:28+08:00",
"processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
"amount_allocations": [
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4",
"amount": 1000,
"reference": "ORD-5023-4E89",
"commission": {
"amount": 1000,
"percentage": 1.125
}
}
],
"customer": {
"email": "brucewayne@email.com",
"name": "Bruce Wayne"
},
"shipping": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"billing": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"products": [
{
"reference": "string",
"url": "https://example.com/products/gold-necklace",
"name": "Gold Necklace",
"quantity": 1,
"price": 1000
}
],
"metadata": {},
"locale": "ar",
"return_url": "https://example.com/success",
"_links": {
"self": {
"href": "https://{prefix}.api.sandbox.checkout.com/payment-links/pl_ELqQJXdXzabU"
},
"redirect": {
"href": "https://pay.sandbox.checkout.com/link/pl_ELqQJXdXzabU"
}
}
}
```
Expired
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[PaymentLinkId](#schemapaymentlinkid)|true|none|The unique identifier for a Payment Link.|
|status|string|true|none|The status of the Payment Link:
- `Active`: The Payment Link can accept a payment from the customer. A payment may have been attempted by the customer but not completed successfully.
- `Payment Received`: A payment has been received successfully using this Payment Link.
- `Expired`: The Payment Link has expired and can no longer be accessed.|
|payment_id|string|false|none|Unique identifier for an in progress or completed payment for this Payment Link.|
|amount|integer|true|none|The original payment amount.|
|currency|string|true|none|The three-letter ISO currency code of the payment.
|
|reference|string|false|none|Your reference for the payment.|
|description|string|false|none|A description of the payment.|
|created_on|string(date-time)|true|none|The date and time when the Payment Link was created.|
|expires_on|string(date-time)|true|none|The date and time when the Payment Link expires.|
|processing_channel_id|string|false|none|The processing channel to be used for the payment|
|amount_allocations|[AmountAllocations](#schemaamountallocations)|false|none|The sub-entities that the payment is being processed on behalf of|
|customer|object|false|none|The customer's details.|
|» email|string(email)|false|none|The email address for the customer.|
|» name|string|false|none|The customer's name.|
|shipping|object|false|none|The address any products are being sent to.|
|» address|[Address](#schemaaddress)|true|none|The customer's address to ship to.|
|billing|object|true|none|The billing details.|
|» address|[Address](#schemaaddress)|true|none|The billing address.|
|» phone|[PhoneNumber](#schemaphonenumber)|false|none|The customer's phone number.|
|products|[PaymentInterfacesProducts](#schemapaymentinterfacesproducts)|false|none|Contains details about the products in the order.|
|metadata|object|false|none|Any additional information stored at the point of creation.|
|locale|string|false|none|The language that the Payment Link page is displayed in.|
|return_url|string(uri)|false|none|If provided, the success page will include a button that redirects your customer to the provided URL.|
|_links|[PaymentLinkResponseLinks](#schemapaymentlinkresponselinks)|true|none|The links related to the Payment Link.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Expired|
|locale|ar|
|locale|da-DK|
|locale|de-DE|
|locale|el|
|locale|en-GB|
|locale|es-ES|
|locale|fi-FI|
|locale|fil-PH|
|locale|fr-FR|
|locale|hi-IN|
|locale|id-ID|
|locale|it-IT|
|locale|ja-JP|
|locale|ms-MY|
|locale|nb-NO|
|locale|nl-NL|
|locale|pt-PT|
|locale|sv-SE|
|locale|th-TH|
|locale|vi-VN|
|locale|zh-CN|
|locale|zh-HK|
|locale|zh-TW|
PaymentLinkResponseStatusPaymentReceived
```json
{
"id": "pl_ELqQJXdXzabU",
"status": "Payment Received",
"payment_id": "pay_88cb4e671m1da22e9bbbyx",
"amount": 100,
"currency": "GBP",
"reference": "ORD-123A",
"description": "Payment for Gold Necklace",
"created_on": "2021-08-19T20:25:28.725Z",
"expires_on": "2021-08-20T20:25:28+08:00",
"processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
"amount_allocations": [
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4",
"amount": 1000,
"reference": "ORD-5023-4E89",
"commission": {
"amount": 1000,
"percentage": 1.125
}
}
],
"customer": {
"email": "brucewayne@email.com",
"name": "Bruce Wayne"
},
"shipping": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"billing": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"products": [
{
"reference": "string",
"url": "https://example.com/products/gold-necklace",
"name": "Gold Necklace",
"quantity": 1,
"price": 1000
}
],
"metadata": {},
"locale": "ar",
"return_url": "https://example.com/success",
"_links": {
"self": {
"href": "https://{prefix}.api.sandbox.checkout.com/payment-links/pl_ELqQJXdXzabU"
},
"redirect": {
"href": "https://pay.sandbox.checkout.com/link/pl_ELqQJXdXzabU"
}
}
}
```
Payment Received
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[PaymentLinkId](#schemapaymentlinkid)|true|none|The unique identifier for a Payment Link.|
|status|string|true|none|The status of the Payment Link:
- `Active`: The Payment Link can accept a payment from the customer. A payment may have been attempted by the customer but not completed successfully.
- `Payment Received`: A payment has been received successfully using this Payment Link.
- `Expired`: The Payment Link has expired and can no longer be accessed.|
|payment_id|string|true|none|Unique identifier for an in progress or completed payment for this Payment Link.|
|amount|integer|true|none|The original payment amount.|
|currency|string|true|none|The three-letter ISO currency code of the payment.
|
|reference|string|false|none|Your reference for the payment.|
|description|string|false|none|A description of the payment.|
|created_on|string(date-time)|true|none|The date and time when the Payment Link was created.|
|expires_on|string(date-time)|true|none|The date and time when the Payment Link expires.|
|processing_channel_id|string|false|none|The processing channel to be used for the payment|
|amount_allocations|[AmountAllocations](#schemaamountallocations)|false|none|The sub-entities that the payment is being processed on behalf of|
|customer|object|false|none|The customer's details.|
|» email|string(email)|false|none|The email address for the customer.|
|» name|string|false|none|The customer's name.|
|shipping|object|false|none|The address any products are being sent to.|
|» address|[Address](#schemaaddress)|true|none|The customer's address to ship to.|
|billing|object|true|none|The billing details.|
|» address|[Address](#schemaaddress)|true|none|The billing address.|
|» phone|[PhoneNumber](#schemaphonenumber)|false|none|The customer's phone number.|
|products|[PaymentInterfacesProducts](#schemapaymentinterfacesproducts)|false|none|Contains details about the products in the order.|
|metadata|object|false|none|Any additional information stored at the point of creation.|
|locale|string|false|none|The language that the Payment Link page is displayed in.|
|return_url|string(uri)|false|none|If provided, the success page will include a button that redirects your customer to the provided URL.|
|_links|[PaymentLinkResponseLinks](#schemapaymentlinkresponselinks)|true|none|The links related to the Payment Link.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Payment Received|
|locale|ar|
|locale|da-DK|
|locale|de-DE|
|locale|el|
|locale|en-GB|
|locale|es-ES|
|locale|fi-FI|
|locale|fil-PH|
|locale|fr-FR|
|locale|hi-IN|
|locale|id-ID|
|locale|it-IT|
|locale|ja-JP|
|locale|ms-MY|
|locale|nb-NO|
|locale|nl-NL|
|locale|pt-PT|
|locale|sv-SE|
|locale|th-TH|
|locale|vi-VN|
|locale|zh-CN|
|locale|zh-HK|
|locale|zh-TW|
PaymentLinksRequest
```json
{
"amount": 1000,
"currency": "GBP",
"payment_type": "Regular",
"authorization_type": "Estimated",
"payment_plan": {
"amount_variability": "Variable",
"days_between_payments": 28,
"total_number_of_payments": 5,
"current_payment_number": 3,
"expiry": "20251031",
"name": "Subscription 1234",
"start_date": "20260507",
"amount": 1234
},
"payment_ip": "90.197.169.245",
"billing_descriptor": {
"name": "string",
"city": "string",
"reference": "string"
},
"reference": "ORD-123A",
"description": "Payment for Gold Necklace",
"display_name": "The Jewelry Shop",
"processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
"amount_allocations": [
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4",
"amount": 1000,
"reference": "ORD-5023-4E89",
"commission": {
"amount": 1000,
"percentage": 1.125
}
}
],
"expires_in": 604800,
"customer": {
"email": "ali.farid@example.com",
"name": "Ali Farid",
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"summary": {
"registration_date": "2023-05-01",
"first_transaction_date": "2023-07-01",
"last_payment_date": "2023-08-01",
"total_order_count": 15,
"last_payment_amount": 500,
"is_premium_customer": true,
"is_returning_customer": true,
"lifetime_value": 500
}
},
"shipping": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"billing": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"recipient": {
"dob": "1985-05-15",
"account_number": "5555554444",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"first_name": "Jia",
"last_name": "Tsang"
},
"processing": {
"aft": true,
"discount_amount": 0,
"shipping_amount": 300,
"tax_amount": 3000,
"invoice_id": "string",
"brand_name": "string",
"locale": "en-US",
"partner_customer_risk_data": {
"key": "string",
"value": "string"
},
"custom_payment_method_ids": [
"string"
],
"airline_data": [
{
"ticket": {
"number": "045-21351455613",
"issue_date": "2023-05-20",
"issuing_carrier_code": "AI",
"travel_package_indicator": "B",
"travel_agency_name": "World Tours",
"travel_agency_code": "01"
},
"passenger": [
{
"first_name": "John",
"last_name": "White",
"date_of_birth": "1990-05-26",
"address": {
"country": "US"
}
}
],
"flight_leg_details": [
{
"flight_number": "101",
"carrier_code": "BA",
"class_of_travelling": "J",
"departure_airport": "LHR",
"departure_date": "2023-06-19",
"departure_time": "15:30",
"arrival_airport": "LAX",
"stop_over_code": "x",
"fare_basis_code": "SPRSVR"
}
]
}
],
"accommodation_data": [
{
"name": "The Sea View Hotel",
"booking_reference": "HOTEL123",
"check_in_date": "2023-06-20",
"check_out_date": "2023-06-23",
"address": {
"address_line1": "123 Beach Road",
"zip": "10001"
},
"state": "FL",
"country": "USA",
"city": "Los Angeles",
"number_of_rooms": 2,
"guests": [
{
"first_name": "Jane",
"last_name": "Doe",
"date_of_birth": "1985-07-14"
}
],
"room": [
{
"rate": "70",
"number_of_nights_at_room_rate": "3"
}
]
}
],
"order_id": "123456789",
"surcharge_amount": 200,
"duty_amount": 0,
"shipping_tax_amount": 100,
"affiliate_id": "string",
"affiliate_url": "www.mycrypto.com",
"purchase_country": "string",
"merchant_initiated_reason": "Delayed_charge",
"campaign_id": 0,
"original_order_amount": 10,
"receipt_id": "10",
"merchant_callback_url": "string",
"line_of_business": "Flights",
"pan_preference": "fpan",
"provision_network_token": true,
"reconciliation_id": "4123495123",
"aggregator": {
"sub_merchant_id": "9cf70789ba90123",
"aggregator_id_visa": "10012345",
"aggregator_id_mc": "00000123456"
}
},
"allow_payment_methods": [
"card",
"applepay",
"googlepay"
],
"disabled_payment_methods": [
"eps",
"ideal",
"knet"
],
"products": [
{
"reference": "string",
"url": "https://example.com/products/gold-necklace",
"name": "Gold Necklace",
"quantity": 1,
"price": 1000
}
],
"metadata": {},
"3ds": {
"enabled": false,
"attempt_n3d": false,
"challenge_indicator": "no_preference",
"allow_upgrade": true,
"exemption": "low_value"
},
"risk": {
"enabled": false
},
"customer_retry": {
"max_attempts": 2
},
"sender": {},
"return_url": "https://example.com/success",
"locale": "ar",
"capture": true,
"capture_on": "2019-08-24T14:15:22Z",
"instruction": {
"purpose": "donations"
},
"payment_method_configuration": {
"applepay": {
"account_holder": {},
"store_payment_details": "disabled"
},
"card": {
"store_payment_details": "disabled",
"account_holder": {}
},
"googlepay": {
"account_holder": {},
"store_payment_details": "disabled"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|amount|integer|true|none|The payment amount. The exact format depends on the currency.|
|currency|string|true|none|The three-letter ISO currency code of the payment.
The `currency` and `billing.address.country` fields determine which payment methods are shown on the payment page.|
|payment_type|string|false|none|This must be specified for card payments where the cardholder is not present (i.e., recurring or mail order / telephone order)|
|authorization_type|string|false|none|The authorization type.|
|payment_plan|[PaymentSessionPaymentPlanRecurring](#schemapaymentsessionpaymentplanrecurring)|false|none|The information to process a recurring payment request. To be used when the payment_type is Recurring.|
|payment_ip|[IPAddress](#schemaipaddress)|false|none|The Customers IP address. Only IPv4 and IPv6 addresses are accepted.|
|billing_descriptor|object|false|none|An optional description that is displayed on the customer's statement identifying a purchase|
|» name|string|true|none|A dynamic description of the change|
|» city|string|true|none|The city from which the charge originated|
|» reference|string|false|none|The reference shown on the statement. Required for payouts to bank accounts.|
|reference|[PaymentInterfacesReference](#schemapaymentinterfacesreference)|false|none|A reference you can use to identify the payment. For example, an order number.
- For Amex payments, this must be at most 30 characters.
- For Benefit payments, the reference must be a unique alphanumeric value.
- For iDEAL payments, the reference is required and must be an alphanumeric value with a 35-character limit.|
|description|string|false|none|A description of the payment.|
|display_name|string|false|none|The merchant name to display to customers on the checkout page.|
|processing_channel_id|string|false|none|The processing channel to use for the payment.
This field is required if you have more than one processing channel associated with your API key.|
|amount_allocations|[AmountAllocations](#schemaamountallocations)|false|none|The sub-entities that the payment is being processed on behalf of|
|expires_in|integer|false|none|The time for which the link remains valid, in seconds.|
|customer|object|false|none|The customer's details|
|» email|string(email)|false|none|The customer's email address.|
|» name|string|false|none|The customer's name.
This will only set the name for new customers.|
|» phone|[PaymentInterfacesPhoneNumber](#schemapaymentinterfacesphonenumber)|false|none|The customer's phone number.|
|» summary|[PaymentInterfacesCustomerSummary](#schemapaymentinterfacescustomersummary)|false|none|Summary of the customer's transaction history.
Used for risk assessment when `source.type` is `Tamara`|
|shipping|object|false|none|The address any products are being sent to.|
|» address|[Address](#schemaaddress)|true|none|The customer's address to ship to.|
|» phone|[PhoneNumber](#schemaphonenumber)|false|none|The customer's phone number|
|billing|object|true|none|The billing details.|
|» address|[Address](#schemaaddress)|true|none|The billing address.|
|» phone|[PhoneNumber](#schemaphonenumber)|false|none|The customer's phone number|
|recipient|[PaymentInterfacesRecipient](#schemapaymentinterfacesrecipient)|false|none|Information about the recipient of the payment's funds. Applies to Account Funding Transactions, and VISA or Mastercard domestic UK transactions processed by financial institutions.|
|processing|[PaymentInterfacesProcessing](#schemapaymentinterfacesprocessing)|false|none|Use the processing object to influence or override the data sent during card processing|
|allow_payment_methods|[PaymentInterfacesPaymentMethods](#schemapaymentinterfacespaymentmethods)|false|none|Specifies which payment method options to present to the customer.
The values in this field override any equivalent values in `disabled_payment_methods`.
Some payment methods have additional field requirements. See the documentation for more information.|
|disabled_payment_methods|[PaymentInterfacesPaymentMethods](#schemapaymentinterfacespaymentmethods)|false|none|Specifies which payment method options to not present to the customer.
If you specify the same payment method in this field and in `allow_payment_methods`, the `disabled_payment_methods` value will be overridden.
Any payment method options not explicitly specified in this field will be presented to the customer by default.|
|products|[PaymentInterfacesProducts](#schemapaymentinterfacesproducts)|false|none|Contains details about the products in the order.|
|metadata|object|false|none|Allows you to store additional information about the transaction. This object only allows one level of depth, so cannot accept non-primitive data types such as objects or arrays.|
|3ds|object|false|none|Information required for 3D Secure payments.|
|» enabled|boolean|false|none|Whether to process this payment as a 3D Secure payment.|
|» attempt_n3d|boolean|false|none|Applies only when `3ds.enabled` is set to `true`. Set to `true` to attempt the payment without 3DS when the issuer, card, or network doesn’t support 3DS.|
|» challenge_indicator|string|false|none|Indicates the preference for whether or not a 3DS challenge should be performed. The customer’s bank has the final say on whether or not the customer receives the challenge.|
|» allow_upgrade|boolean|false|none|Whether to process this payment as 3D Secure if the authorization was soft declined because 3DS authentication is required.|
|» exemption|string|false|none|Specifies an exemption reason so that the payment is not processed using 3D Secure authentication. Learn more about exemptions in our SCA compliance guide.|
|risk|object|false|none|Configures the risk assessment performed during payment processing.|
|» enabled|boolean|true|none|Specifies whether to perform a risk assessment.|
|customer_retry|object|false|none|Configures the parameters for customer retries.
A customer retry is a payment attempt performed by the customer on the checkout page. This differs from [authorization request retries](https://api-reference.checkout.com/#operation/requestAPaymentOrPayout!path=0/retry&t=request) performed in the back end by Checkout.com.|
|» max_attempts|integer|false|none|The maximum number of customer retry attempts, excluding the initial payment attempt.|
|sender|[PaymentInterfacesSender](#schemapaymentinterfacessender)|false|none|The sender of the payment.|
|return_url|string(uri)|false|none|If provided, the success page will include a button that redirects your customer to the provided URL.|
|locale|string|false|none|Creates a translated version of the page in the specified language|
|capture|boolean|false|none|Whether to capture the payment (if applicable).|
|capture_on|[Timestamp](#schematimestamp)|false|none|A timestamp (ISO 8601 code) that determines when the payment should be captured.
Providing this field will automatically set `capture` to true.|
|instruction|object|false|none|Details about the payment instruction.|
|» purpose|[Purpose](#schemapurpose)|false|none|The purpose of the payment.
This field might be required for AFT transactions depending on the card's `issuer_country`. To view a card's `issuer_country`, [retrieve the card's metadata](https://api-reference.checkout.com/#operation/requestCardMetadata!c=200&path=issuer_country&t=response).
See the [AFT documentation page](https://www.checkout.com/docs/payments/manage-payments/perform-an-account-funding-transaction) for more details.|
|payment_method_configuration|object|false|none|Configuration options for specific payment methods.|
|» applepay|object|false|none|Configuration options specific to Apple Pay payments.|
|»» account_holder|object|false|none|The account holder's details.|
|»» store_payment_details|[PaymentInterfacesStorePaymentDetails](#schemapaymentinterfacesstorepaymentdetails)|false|none|Specifies whether you intend to store the cardholder's payment details.
If you set this field to `enabled`, you must:
- have obtained consent from the cardholder to store their payment details
- provide a customer ID or email address in the request
If the request's `payment_type` is set to one of the following values, you do not need to provide this field:
- `Installment`
- `Recurring`
- `Unscheduled`|
|» card|object|false|none|Configuration options specific to card payments.|
|»» store_payment_details|string|false|none|Specifies whether you intend to store the cardholder's payment details.
If you set this field to `enabled` or `collect_consent`, you must:
- Have obtained consent from the cardholder to store their payment details
- Provide `customer.id` or `customer.email` in the request
You do not need to provide this field if `payment_type` is set to one of the following values:
- `Installment`
- `Recurring`
- `Unscheduled`|
|»» account_holder|object|false|none|The account holder's details.|
|» googlepay|object|false|none|Configuration options specific to Google Pay payments.|
|»» account_holder|object|false|none|The account holder's details.|
|»» store_payment_details|[PaymentInterfacesStorePaymentDetails](#schemapaymentinterfacesstorepaymentdetails)|false|none|Specifies whether you intend to store the cardholder's payment details.
If you set this field to `enabled`, you must:
- have obtained consent from the cardholder to store their payment details
- provide a customer ID or email address in the request
If the request's `payment_type` is set to one of the following values, you do not need to provide this field:
- `Installment`
- `Recurring`
- `Unscheduled`|
#### Enumerated Values
|Property|Value|
|---|---|
|payment_type|Regular|
|payment_type|Recurring|
|authorization_type|Final|
|authorization_type|Estimated|
|challenge_indicator|no_preference|
|challenge_indicator|no_challenge_requested|
|challenge_indicator|challenge_requested|
|challenge_indicator|challenge_requested_mandate|
|exemption|low_value|
|exemption|secure_corporate_payment|
|exemption|trusted_listing|
|exemption|transaction_risk_assessment|
|exemption|3ds_outage|
|exemption|sca_delegation|
|exemption|out_of_sca_scope|
|exemption|other|
|exemption|low_risk_program|
|exemption|recurring_operation|
|locale|ar|
|locale|da-DK|
|locale|de-DE|
|locale|el|
|locale|en-GB|
|locale|es-ES|
|locale|fi-FI|
|locale|fil-PH|
|locale|fr-FR|
|locale|hi-IN|
|locale|id-ID|
|locale|it-IT|
|locale|ja-JP|
|locale|ms-MY|
|locale|nb-NO|
|locale|nl-NL|
|locale|pt-PT|
|locale|sv-SE|
|locale|th-TH|
|locale|vi-VN|
|locale|zh-CN|
|locale|zh-HK|
|locale|zh-TW|
|store_payment_details|disabled|
|store_payment_details|enabled|
|store_payment_details|collect_consent|
PaymentLinksResponse
```json
{
"id": "pl_ELqQJXdXzabU",
"expires_on": "2020-08-20T20:25:28+08:00",
"reference": "ORD-123A",
"warnings": [
{
"code": "payment_method_unavailable",
"description": "The card was provided in the `allow_payment_methods` object, but no card schemes are configured.",
"value": "card"
}
],
"_links": {
"self": {
"href": "https://{prefix}.api.sandbox.checkout.com/payment-links/pl_ELqQJXdXzabU"
},
"redirect": {
"href": "https://pay.sandbox.checkout.com/link/pl_ELqQJXdXzabU"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[PaymentLinkId](#schemapaymentlinkid)|true|none|The unique identifier for a Payment Link.|
|expires_on|string(date-time)|false|none|The date and time when the Payment Link expires.|
|reference|string|false|none|A reference you can later use to identify this payment, such as an order number.|
|warnings|[object]|false|none|Related to the `allow_payment_methods` object in the request. Included in the response if an alternative payment method is passed through, but no card schemes are configured against the account.|
|» code|string|false|none|The reason for the warning|
|» description|string|false|none|The description of the warning code|
|» value|string|false|none|Payment method for which the warning applies|
|_links|object|true|read-only|The links related to the Payment Link session.|
|» self|[Link](#schemalink)|false|none|none|
|» redirect|[Link](#schemalink)|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|value|card|
|value|sofort|
|value|ideal|
|value|knet|
|value|bancontact|
|value|eps|
|value|p24|
|value|multibanco|
PaymentMethod
```json
{
"type": "accel",
"partner_merchant_id": "Z7X8LKJ3PQR5N"
}
```
PaymentMethod
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment method type.|
|partner_merchant_id|string|false|none|The unique identifier for the merchant, provided by the partner.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|accel|
|type|ach|
|type|alipay_cn|
|type|alipay_hk|
|type|alipay_plus|
|type|alma|
|type|amex|
|type|bancontact|
|type|blik|
|type|boost|
|type|bpi|
|type|card_scheme|
|type|cartes_bancaires|
|type|china_union_pay|
|type|connect_wallet|
|type|bacs|
|type|dana|
|type|dci|
|type|diners|
|type|discover|
|type|eps|
|type|gcash|
|type|ideal|
|type|jcb|
|type|kakaopay|
|type|klarna|
|type|knet|
|type|mada|
|type|mastercard|
|type|mbway|
|type|multibanco|
|type|nyce|
|type|omannet|
|type|p24|
|type|paypal|
|type|paypay|
|type|pulse|
|type|qpay|
|type|rabbit_line_pay|
|type|sepa|
|type|sequra|
|type|shazam|
|type|star|
|type|stcpay|
|type|swish|
|type|tamara|
|type|tng|
|type|truemoney|
|type|upi|
|type|visa|
|type|wechatpay|
PaymentMethodsResponse
```json
{
"methods": [
{
"type": "accel",
"partner_merchant_id": "Z7X8LKJ3PQR5N"
}
]
}
```
PaymentMethodsResponse
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|methods|[[PaymentMethod](#schemapaymentmethod)]|true|none|The payment methods enabled for the processing channel.|
3dsData
```json
{
"downgraded": false,
"enrolled": "Y",
"signature_valid": "Y",
"authentication_response": "Y",
"authentication_status_reason": "string",
"cryptogram": "hv8mUFzPzRZoCAAAAAEQBDMAAAA=",
"xid": "MDAwMDAwMDAwMDAwMDAwMzIyNzY=",
"eci": "string",
"version": "2.1.0",
"exemption": "low_value",
"exemption_applied": "string",
"challenged": true,
"upgrade_reason": "sca_retry",
"trusted_listing": {
"status": "Y",
"source": "01"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|downgraded|boolean|false|none|Indicates whether this was a 3D Secure payment downgraded to non-3D Secure (when `attempt_n3d` is specified)|
|enrolled|string|false|none|Indicates the 3D Secure enrollment status of the issuer
* `Y` - Issuer enrolled
* `N` - Customer not enrolled
* `U` - Unknown|
|signature_valid|string|false|none|Verification to ensure the integrity of the response|
|authentication_response|[ResponseCode](#schemaresponsecode)|false|none|Only available as a result of a 3DS2 authentication.
The response from the DS or ACS which indicates whether a transaction qualifies as an authenticated transaction or account verification.
Only available if communication with the scheme was successful and the Session is in a final state.
• Y = Authentication Verification Successful.
• N = Not Authenticated /Account Not Verified; Transaction denied.
• U = Authentication/ Account Verification Could Not Be Performed; Technical or other problem, as indicated in ARes or RReq.
• A = Attempts Processing Performed; Not Authenticated/Verified, but a proof of attempted authentication/verification is provided.
• C = Challenge Required; Additional authentication is required using the CReq/CRes.
• D = Challenge Required; Decoupled Authentication confirmed.
• R = Authentication/ Account Verification Rejected; Issuer is rejecting authentication/verification and request that authorization not be attempted.
• I = Informational Only; 3DS Requestor challenge preference acknowledged.|
|authentication_status_reason|string|false|none|The response from the Directory Server (DS) or Access Control Server (ACS), which provides information on why you received the given `authentication_response` value.
This field is only returned as a result of a 3DS2 authentication, and only if the returned `authentication_response` value was not `Y`.
Refer to our authentication failures documentation for more information.|
|cryptogram|string|false|none|Base64 encoded cryptographic identifier (CAVV) used by the card schemes to validate the integrity of the 3D secure payment data|
|xid|string|false|none|Unique identifier for the transaction assigned by the MPI|
|eci|string|false|none|The Electronic Commerce Indicator (ECI) security level returned in the payment's authentication response.|
|version|string|false|none|Indicates the version of 3D Secure that was used for authentication|
|exemption|string|false|none|Specifies an exemption reason so that the payment is not processed using 3D Secure authentication. Learn more about exemptions in our SCA compliance guide|
|exemption_applied|string|false|none|Specifies the applied exemption during 3DS authentication|
|challenged|boolean|false|none|Indicates whether this session involved a challenge. This will only be set after communication with the scheme is finished.|
|upgrade_reason|string|false|none|Indicates the reason why the payment was upgraded to 3D Secure.|
|trusted_listing|[TrustedListing](#schematrustedlisting)|false|none|The details of the trusted listing status of the merchant|
#### Enumerated Values
|Property|Value|
|---|---|
|exemption|3ds_outage|
|exemption|data_share|
|exemption|low_risk_program|
|exemption|low_value|
|exemption|none|
|exemption|other|
|exemption|out_of_sca_scope|
|exemption|sca_delegation|
|exemption|secure_corporate_payment|
|exemption|transaction_risk_assessment|
|exemption|trusted_listing|
|exemption|trusted_listing_prompt|
3dsEnrollmentData
```json
{
"downgraded": false,
"enrolled": "Y",
"upgrade_reason": "sca_retry"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|downgraded|boolean|false|none|Indicates whether this was a 3D Secure payment downgraded to non-3D-Secure (when `attempt_n3d` is specified)|
|enrolled|string|false|none|Indicates the 3D Secure enrollment status of the issuer
* `Y` - Issuer enrolled
* `N` - Customer not enrolled
* `U` - Unknown|
|upgrade_reason|string|false|none|Indicates the reason why the payment was upgraded to 3D Secure.|
3dsRequest
```json
{
"enabled": "false",
"challenge_indicator": "no_preference",
"allow_upgrade": true,
"exemption": "low_value"
}
```
Integrated authentication
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|enabled|string|true|none|Whether to process this payment as a 3D Secure payment. Payments where `merchant_initiated` is `true` will be processed as 3DS Requestor Initiated.|
|challenge_indicator|string|false|none|Indicates the preference for whether or not a 3DS challenge should be performed. The customer’s bank has the final say on whether or not the customer receives the challenge.|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[3dsRequestNonEnabled](#schema3dsrequestnonenabled)|false|none|3DS authentication not enabled|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[3dsRequestEnabled](#schema3dsrequestenabled)|false|none|3DS authentication enabled|
#### Enumerated Values
|Property|Value|
|---|---|
|enabled|true|
|enabled|false|
|challenge_indicator|no_preference|
|challenge_indicator|no_challenge_requested|
|challenge_indicator|challenge_requested|
|challenge_indicator|challenge_requested_mandate|
3dsRequestEnabled
```json
{
"enabled": "true",
"challenge_indicator": "no_preference",
"attempt_n3d": true,
"exemption": "low_value",
"merchant_authentication_info": {
"three_ds_req_auth_method": "no_threeds_requestor_authentication_occurred",
"three_ds_req_auth_timestamp": "2019-08-24T14:15:22Z",
"three_ds_req_auth_data": "string"
},
"account_info": {
"purchase_count": 10,
"account_age": "no_account",
"add_card_attempts": 10,
"shipping_address_age": "this_transaction",
"account_name_matches_shipping_name": true,
"suspicious_account_activity": true,
"transactions_today": 10,
"authentication_method": "no_authentication",
"cardholder_account_age_indicator": "no_account,",
"account_change": "2019-08-24T14:15:22Z",
"account_change_indicator": "this_transaction",
"account_date": "2019-08-24T14:15:22Z",
"account_password_change": "2019-08-24T14:15:22Z",
"account_password_change_indicator": "no_change",
"transactions_per_year": 2,
"payment_account_age": "2019-08-24T14:15:22Z",
"shipping_address_usage": "2019-08-24T14:15:22Z",
"account_type": "not_applicable",
"account_id": "string"
}
}
```
true
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|enabled|string|true|none|Whether to process this payment as a 3D Secure payment. Payments where `merchant_initiated` is `true` will be processed as 3DS Requestor Initiated.|
|challenge_indicator|string|false|none|Indicates the preference for whether or not a 3DS challenge should be performed. The customer’s bank has the final say on whether or not the customer receives the challenge.|
|attempt_n3d|boolean|false|none|Applies only when `3ds.enabled` is set to `true`. Set to `true` to attempt the payment without 3DS when the issuer, card, or network doesn’t support 3DS.|
|exemption|string|false|none|Specifies an exemption reason so that the payment is not processed using 3D Secure authentication. Learn more about exemptions in our SCA compliance guide|
|merchant_authentication_info|[MerchantAuthenticationInfo](#schemamerchantauthenticationinfo)|false|none|The information about how the 3DS Requestor authenticated the cardholder before or during the transaction|
|account_info|[AccountInfo](#schemaaccountinfo)|false|none|Additional information about the cardholder's account|
#### Enumerated Values
|Property|Value|
|---|---|
|enabled|true|
|enabled|false|
|challenge_indicator|no_preference|
|challenge_indicator|no_challenge_requested|
|challenge_indicator|challenge_requested|
|challenge_indicator|challenge_requested_mandate|
|exemption|low_value|
|exemption|trusted_listing|
|exemption|trusted_listing_prompt|
|exemption|transaction_risk_assessment|
|exemption|data_share|
3dsRequestNonEnabled
```json
{
"enabled": "false",
"challenge_indicator": "no_preference",
"allow_upgrade": true,
"exemption": "low_value"
}
```
false
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|enabled|string|true|none|Whether to process this payment as a 3D Secure payment. Payments where `merchant_initiated` is `true` will be processed as 3DS Requestor Initiated.|
|challenge_indicator|string|false|none|Indicates the preference for whether or not a 3DS challenge should be performed. The customer’s bank has the final say on whether or not the customer receives the challenge.|
|allow_upgrade|boolean|false|none|Indicates whether to process this payment as 3D Secure if the authorization was soft declined due to 3DS authentication required. For processing channels created before October 12, 2022, the value will default to `false`.|
|exemption|string|false|none|Specifies an exemption reason so that the payment is not processed using 3D Secure authentication. Learn more about exemptions in our SCA compliance guide|
#### Enumerated Values
|Property|Value|
|---|---|
|enabled|true|
|enabled|false|
|challenge_indicator|no_preference|
|challenge_indicator|no_challenge_requested|
|challenge_indicator|challenge_requested|
|challenge_indicator|challenge_requested_mandate|
|exemption|low_value|
|exemption|trusted_listing|
|exemption|trusted_listing_prompt|
|exemption|transaction_risk_assessment|
|exemption|3ds_outage|
|exemption|sca_delegation|
|exemption|out_of_sca_scope|
|exemption|low_risk_program|
|exemption|recurring_operation|
|exemption|data_share|
|exemption|other|
3dsRequestStandalone
```json
{
"enabled": true,
"authentication_id": "sid_y3oqhf46pyzuxjbcn2giaqnb44"
}
```
Standalone authentication
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|enabled|boolean|true|none|Whether to process this payment as a 3D Secure payment|
|authentication_id|string|true|none|The unique identifier for your 3D Secure session.|
#### Enumerated Values
|Property|Value|
|---|---|
|enabled|true|
3dsRequestThirdParty
```json
{
"enabled": true,
"eci": "05",
"cryptogram": "AgAAAAAAAIR8CQrXcIhbQAAAAAA=",
"xid": "MDAwMDAwMDAwMDAwMDAwMzIyNzY=",
"version": "2.0.1",
"exemption": "low_value",
"status": "Y",
"authentication_date": "2020-09-03T10:11:12Z",
"authentication_amount": 200,
"flow_type": "challenged",
"challenge_indicator": "no_preference",
"status_reason_code": "01",
"challenge_cancel_reason": "01",
"score": "string",
"cryptogram_algorithm": "1",
"initial_authentication": {
"acs_transaction_id": "stringstringstringstringstringstring",
"authentication_method": "frictionless_authentication",
"authentication_timestamp": "2023-02-06T15:00:00.000Z",
"authentication_data": "string",
"initial_session_id": "sid_p6prbhogijnuxgv4grm3ber55u"
}
}
```
Third party authentication
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|enabled|boolean|true|none|Whether to process this payment as a 3D Secure payment|
|eci|string|true|none|The Electronic Commerce Indicator security level associated with the 3D Secure enrollment result. Required if using a third-party merchant plug-in (MPI)|
|cryptogram|string|true|none|A Base64 encoded cryptographic identifier (CAVV) used by the card schemes to validate the cardholder authentication result (3D Secure). Required if using an external MPI|
|xid|string|true|none|The 3D Secure transaction identifier. Required if using an external MPI with 3D Secure 2.X.X and a Mastercard card, or with 3D Secure 1.X.X for any supported card scheme|
|version|string|true|none|Indicates the version of 3D Secure that was used for authentication. Defaults to 1.0.0 if not provided|
|exemption|string|false|none|Specifies an exemption reason so that the payment is not processed using 3D Secure authentication. Learn more about exemptions in our SCA compliance guide|
|status|string|false|none|The transaction status returned from the card Issuer’s Access Control Server (ACS) or Scheme Directory Server (DS). For 3DS Secure 1, this is the PaRes Status. for 3D Secure 2, this is the transaction status of ARes(frictionless flow) or RReq (Challenge flow)|
|authentication_date|string¦null|false|none|Authentication date and time. Format ISO-8601|
|authentication_amount|number¦null|false|none|Authentication amount|
|flow_type|string|false|none|Indicates whether the 3D Secure 2 authentication was challenged or frictionless.|
|challenge_indicator|string|false|none|Indicates the preference for whether or not a 3DS challenge should be performed. The customer’s bank has the final say on whether or not the customer receives the challenge.|
|status_reason_code|string|false|none|A code indicating the reason for the transaction status|
|challenge_cancel_reason|string|false|none|Indicates a cancel reason for a challenge in the case of authentication. Can be any number from 00 to 99, with 00 being specific ONLY to Cartes Bancaires.|
|score|string|false|none|Risk score calculated by Directory Server (DS). Cartes Bancaires 3D Secure 2 only.|
|cryptogram_algorithm|string|false|none|The algorithm used by the Issuer Access Control Server (ACS) to calculate the Authentication cryptogram. This is the AVALGO data returned in Cartes Bancaires Authentication.|
|initial_authentication|[InitialAuthentication](#schemainitialauthentication)|false|none|The details of a previous authentication|
#### Enumerated Values
|Property|Value|
|---|---|
|enabled|true|
|exemption|low_value|
|exemption|secure_corporate_payment|
|exemption|trusted_listing|
|exemption|transaction_risk_assessment|
|exemption|3ds_outage|
|exemption|sca_delegation|
|exemption|out_of_sca_scope|
|exemption|other|
|exemption|low_risk_program|
|exemption|recurring_operation|
|flow_type|challenged|
|flow_type|frictionless|
|flow_type|frictionless_delegated|
|challenge_indicator|no_preference|
|challenge_indicator|no_challenge_requested|
|challenge_indicator|challenge_requested|
|challenge_indicator|challenge_requested_mandate|
AccommodationData
```json
[
{
"name": "The Sea View Hotel",
"booking_reference": "HOTEL123",
"check_in_date": "2023-06-20",
"check_out_date": "2023-06-23",
"address": {
"address_line1": "123 Beach Road",
"zip": "10001"
},
"state": "FL",
"country": "USA",
"city": "Los Angeles",
"number_of_rooms": 2,
"guests": [
{
"first_name": "Jane",
"last_name": "Doe",
"date_of_birth": "1985-07-14"
}
],
"room": [
{
"rate": "70",
"number_of_nights_at_room_rate": "3"
}
],
"property_phone": [
{
"country_code": "44",
"number": "7123456789"
}
],
"customer_service_phone": [
{
"country_code": "44",
"number": "7123456789"
}
]
}
]
```
Contains information about the accommodation booked by the customer.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|Accommodation Data|object|false|none|none|
|» name|string|false|none|For lodging, contains the lodging name that appears on the storefront/customer receipts. For cruise, contains the ship name booked for the cruise.|
|» booking_reference|string|false|none|A unique identifier for the booking.|
|» check_in_date|string(date)|false|none|For lodging, contains the actual or scheduled date the guest checked-in. For cruise, contains the cruise departure date also known as sail date.|
|» check_out_date|string(date)|false|none|For lodging, contains the actual or scheduled date the guest checked-out. For cruise, contains the cruise return date also known as sail end date.|
|» address|object|false|none|The address details of the accommodation.|
|»» address_line1|string|false|none|The first line of the address.|
|»» zip|string|false|none|The postal code for the address.|
|» state|string|false|none|The state or province of the address country (ISO 3166-2 code of up to two alphanumeric characters).|
|» country|string|false|none|The ISO country code of the address.|
|» city|string|false|none|The address city.|
|» number_of_rooms|integer|false|none|The total number of rooms booked for the accommodation.|
|» guests|[object]|false|none|Contains information about the guests staying at the accommodation.|
|»» first_name|string|false|none|The first name of the guest.|
|»» last_name|string|false|none|The last name of the guest.|
|»» date_of_birth|string(date)|false|none|The date of birth of the guest.|
|» room|[object]|false|none|Contains information about the rooms booked by the customer.|
|»» rate|string|false|none|For lodging, contains the nightly rate for one room. For cruise, contains the total cost of the cruise.|
|»» number_of_nights_at_room_rate|string|false|none|For lodging, contains the number of nights charged at the rate provided in the rate field. For cruise, contains the length of the cruise in days.|
|» property_phone|[object]|false|none|The property's phone information.|
|»» country_code|string|false|none|The property's phone country code.|
|»» number|string|false|none|The property's phone number.|
|» customer_service_phone|[object]|false|none|The customer service phone information.|
|»» country_code|string|false|none|The customer service phone country code.|
|»» number|string|false|none|The customer service phone number.|
AccountInfo
```json
{
"purchase_count": 10,
"account_age": "no_account",
"add_card_attempts": 10,
"shipping_address_age": "this_transaction",
"account_name_matches_shipping_name": true,
"suspicious_account_activity": true,
"transactions_today": 10,
"authentication_method": "no_authentication",
"cardholder_account_age_indicator": "no_account,",
"account_change": "2019-08-24T14:15:22Z",
"account_change_indicator": "this_transaction",
"account_date": "2019-08-24T14:15:22Z",
"account_password_change": "2019-08-24T14:15:22Z",
"account_password_change_indicator": "no_change",
"transactions_per_year": 2,
"payment_account_age": "2019-08-24T14:15:22Z",
"shipping_address_usage": "2019-08-24T14:15:22Z",
"account_type": "not_applicable",
"account_id": "string"
}
```
AccountInfo
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|purchase_count|number|false|none|The number of purchases with this cardholder's account during the last six months|
|account_age|string|false|none|The length of time that the payment account was enrolled in the cardholder's account|
|add_card_attempts|number|false|none|The number of _Add Card_ attempts in the last 24 hours|
|shipping_address_age|string|false|none|Indicates when the shipping address for this transaction was first used|
|account_name_matches_shipping_name|boolean|false|none|Indicates if the cardholder name on the account is identical to the shipping name used for this transaction|
|suspicious_account_activity|boolean|false|none|Indicates whether suspicious activity on the cardholder account has been observed|
|transactions_today|number|false|none|The number of transactions (successful and abandoned) for the cardholder account across all payment accounts in the previous 24 hours|
|authentication_method|string|false|none|Information about how the cardholder was authenticated before or during the transaction|
|cardholder_account_age_indicator|string|false|none|The length of time the cardholder has held the account with the 3DS Requestor|
|account_change|string(date-time)|false|none|The UTC date and time the cardholder’s account with the 3DS Requestor was last changed, in ISO 8601 format.
Changes that affect this value include:
- updating the billing or shipping address
- adding a new payment account
- adding a new user|
|account_change_indicator|string|false|none|The amount of time since the cardholder’s account information with the 3DS Requestor was last changed.
Changes that affect this value include:
- updating the billing or shipping address
- adding a new payment account
- adding a new user|
|account_date|string(date-time)|false|none|The UTC date and time the cardholder opened the account with the 3DS Requestor, in ISO 8601 format.|
|account_password_change|string(date-time)|false|none|The UTC date and time the cardholder’s account with the 3DS Requestor was last reset or had a password change, in ISO 8601 format.|
|account_password_change_indicator|string|false|none|The amount of time since the cardholder’s account with the 3DS Requestor was last reset or had a password change.|
|transactions_per_year|integer|false|none|The number of transactions associated with the cardholder's account with the 3DS Requestor in the previous year. This value includes both successful and abandoned transactions, across all payment accounts.
Set this value to `999` if the number of transactions is `1000` or greater.|
|payment_account_age|string(date-time)|false|none|The UTC date and time the payment account was enrolled in the cardholder’s account with the 3DS Requestor, in ISO 8601 format.|
|shipping_address_usage|string(date-time)|false|none|The UTC date and time the shipping address used for the transaction was first used with the 3DS Requestor, in ISO 8601 format.|
|account_type|string|false|none|The type of account, in the case of a card product with multiple accounts.|
|account_id|string|false|none|Additional information about the account optionally provided by the 3DS Requestor|
#### Enumerated Values
|Property|Value|
|---|---|
|account_age|no_account|
|account_age|created_during_transaction|
|account_age|less_than_thirty_days|
|account_age|thirty_to_sixty_days|
|account_age|more_than_sixty_days|
|shipping_address_age|this_transaction|
|shipping_address_age|less_than_thirty_days|
|shipping_address_age|thirty_to_sixty_days|
|shipping_address_age|more_than_sixty_days|
|authentication_method|no_authentication|
|authentication_method|own_credentials|
|authentication_method|federated_id|
|authentication_method|issuer_credentials|
|authentication_method|third_party_authentication|
|authentication_method|fido|
|cardholder_account_age_indicator|no_account,|
|cardholder_account_age_indicator|this_transaction|
|cardholder_account_age_indicator|less_than_thirty_days|
|cardholder_account_age_indicator|thirty_to_sixty_days|
|cardholder_account_age_indicator|more_than_sixty_days|
|account_change_indicator|this_transaction|
|account_change_indicator|less_than_thirty_days|
|account_change_indicator|thirty_to_sixty_days|
|account_change_indicator|more_than_sixty_days|
|account_password_change_indicator|no_change|
|account_password_change_indicator|this_transaction|
|account_password_change_indicator|less_than_thirty_days|
|account_password_change_indicator|thirty_to_sixty_days|
|account_password_change_indicator|more_than_sixty_days|
|account_type|not_applicable|
|account_type|credit|
|account_type|debit|
ActionId
```json
"act_y3oqhf46pyzuxjbcn2giaqnb44"
```
The action identifier
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The action identifier|
Aggregator
```json
{
"sub_merchant_id": "9cf70789ba90123",
"aggregator_id_visa": "10012345",
"aggregator_id_mc": "00000123456"
}
```
Aggregator
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|sub_merchant_id|string|false|none|The sub-merchant ID.|
|aggregator_id_visa|string|false|none|The Visa identifier for the payment aggregator.|
|aggregator_id_mc|string|false|none|The Mastercard identifier for the payment aggregator.|
AirlineData
```json
[
{
"ticket": {
"number": "045-21351455613",
"issue_date": "2023-05-20",
"issuing_carrier_code": "AI",
"travel_package_indicator": "B",
"travel_agency_name": "World Tours",
"travel_agency_code": "01"
},
"passenger": [
{
"first_name": "John",
"last_name": "White",
"date_of_birth": "1990-05-26",
"address": {
"country": "US"
}
}
],
"flight_leg_details": [
{
"flight_number": "101",
"carrier_code": "BA",
"class_of_travelling": "J",
"departure_airport": "LHR",
"departure_date": "2023-06-19",
"departure_time": "15:30",
"arrival_airport": "LAX",
"stop_over_code": "x",
"fare_basis_code": "SPRSVR"
}
]
}
]
```
Contains information about the airline ticket and flights booked by the customer.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|Airline Data|object|false|none|none|
|» ticket|object|false|none|Contains information about the airline ticket.|
|»» number|string|false|none|The ticket's unique identifier.|
|»» issue_date|string(date)|false|none|Date the airline ticket was issued.|
|»» issuing_carrier_code|string|false|none|Carrier code of the ticket issuer.|
|»» travel_package_indicator|string|false|none|C = Car rental reservation, A = Airline flight reservation, B = Both car rental and airline flight reservations included, N = Unknown.|
|»» travel_agency_name|string|false|none|The name of the travel agency.|
|»» travel_agency_code|string|false|none|The unique identifier from IATA or ARC for the travel agency that issues the ticket.|
|» passenger|[object]|false|none|Contains information about the passenger(s) on the flight.|
|»» Passenger Data|object|false|none|none|
|»»» first_name|string|false|none|The passenger's first name.|
|»»» last_name|string|false|none|The passenger's last name.|
|»»» date_of_birth|string(date)|false|none|The passenger's date of birth.|
|»»» address|object|false|none|Contains information about the passenger's address.|
|»»»» country|string|false|none|The two-letter ISO country code of the passenger's country residence.|
|» flight_leg_details|[object]|false|none|Contains information about the flight leg(s) booked by the customer.|
|»» flight_number|string|false|none|The flight identifier.|
|»» carrier_code|string|false|none|The IATA 2-letter accounting code (PAX) that identifies the carrier. This field is required if the airline data includes leg details.|
|»» class_of_travelling|string|false|none|A one-letter travel class identifier. The following are common: F = First class, J = Business class, Y = Economy class, W = Premium economy.|
|»» departure_airport|string|false|none|The IATA three-letter airport code of the departure airport. This field is required if the airline data includes leg details.|
|»» departure_date|string(date)|false|none|The date of the scheduled take off.|
|»» departure_time|string|false|none|The time of the scheduled take off.|
|»» arrival_airport|string|false|none|The IATA 3-letter airport code of the destination airport. This field is required if the airline data includes leg details.|
|»» stop_over_code|string|false|none|A one-letter code that indicates whether the passenger is entitled to make a stopover. Can be a space, O if the passenger is entitled to make a stopover, or X if they are not.|
|»» fare_basis_code|string|false|none|The fare basis code, alphanumeric.|
AmountAllocations
```json
[
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4",
"amount": 1000,
"reference": "ORD-5023-4E89",
"commission": {
"amount": 1000,
"percentage": 1.125
}
}
]
```
The sub-entities that the payment is being processed on behalf of
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|Amount Allocations|object|false|none|none|
|» id|string|true|none|The id of the sub-entity.|
|» amount|integer(int64)|true|none|The split amount - this will be credited to your sub-entity's currency account. The sum of all split amounts must be equal to the payment amount.
The amount must be provided in the minor currency unit.|
|» reference|string|false|none|A reference you can later use to identify this split, such as an order number.|
|» commission|object|false|none|Commission you'd like to collect from this split - this will be credited to your currency account. The commission cannot exceed the split amount.
Commission = (`amount` * `commission.percentage`) + `commission.amount`|
|»» amount|integer|false|none|Optional fixed amount of commission to collect.
The amount must be provided in the minor currency unit.|
|»» percentage|number|false|none|Optional percentage of commission to collect.
Supports up to 8 decimal places.|
AuthorizationRequest
```json
{
"amount": 6540,
"reference": "ORD-5023-4E89",
"metadata": {
"coupon_code": "NY2018",
"partner_id": 123989
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|amount|integer(int64)|false|none|The amount to increase the authorization by. Omit the amount or provide a value of `0` to extend the authorization validity period|
|reference|string|false|none|A reference you can later use to identify this authorization request|
|metadata|object|false|none|A set of key-value pairs to attach to the authorization request. You can use this to store additional information in a structured format.
The `metadata` object only supports primitive data types. Objects and arrays are not supported.|
AuthorizationResponse
```json
{
"action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
"amount": 6540,
"currency": "USD",
"approved": true,
"status": "Authorized",
"auth_code": "643381",
"response_code": "10000",
"response_summary": "Approved",
"expires_on": "string",
"balances": {
"total_authorized": 6540,
"total_voided": 0,
"available_to_void": 6540,
"total_captured": 0,
"available_to_capture": 6540,
"total_refunded": 0,
"available_to_refund": 0
},
"processed_on": "2019-08-24T14:15:22Z",
"reference": "ORD-5023-4E89",
"processing": {
"retrieval_reference_number": "909913440644",
"acquirer_transaction_id": "440644309099499894406",
"recommendation_code": "02",
"surcharge_amount": 200,
"scheme_transaction_link_id": "string"
},
"eci": "06",
"scheme_id": "489341065491658",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
},
"actions": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/actions"
},
"authorize": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/authorizations"
},
"void": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/voids"
},
"capture": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/capture"
}
}
}
```
Authorization Response
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|action_id|[ActionId](#schemaactionid)|true|none|The unique identifier for the action performed against this payment|
|amount|integer|true|none|The payment amount|
|currency|string|true|none|The three-letter ISO currency code of the payment|
|approved|boolean|true|none|Whether or not the authorization was successful|
|status|string|true|none|The status of the payment|
|auth_code|string|false|none|The acquirer authorization code if the payment was authorized|
|response_code|string|true|none|The Gateway response code|
|response_summary|string|false|none|The Gateway response summary|
|expires_on|string|false|none|The timestamp (ISO 8601 code) for when the authorization's validity period ends|
|balances|[PaymentResponseBalances](#schemapaymentresponsebalances)|false|none|The payment balances|
|processed_on|[ServerTimestamp](#schemaservertimestamp)|true|none|The date/time the payment was processed|
|reference|string|false|none|Your reference for the payment|
|processing|object|false|none|Returns information related to the processing of the payment|
|» retrieval_reference_number|string|false|none|A unique identifier for the authorization that is submitted to the card scheme during processing|
|» acquirer_transaction_id|string|false|none|A unique identifier for the transaction generated by the acquirer|
|» recommendation_code|string|false|none|A code that represents the next recommended action for the payment|
|» surcharge_amount|integer(int64)|false|none|Surcharge amount applied to the transaction in minor units by the merchant|
|» scheme_transaction_link_id|string|false|none|The scheme transaction link identifier.|
|eci|string|false|none|The final Electronic Commerce Indicator (ECI) security level used to authorize the payment. Applicable for 3D Secure and network token payments|
|scheme_id|string|false|none|The scheme transaction identifier|
|_links|object|true|none|The links related to the payment|
|» self|[Link](#schemalink)|true|none|The URI of the payment|
|» actions|[Link](#schemalink)|true|none|A link to the payment's associated actions|
|» authorize|[Link](#schemalink)|false|none|A link to increment the authorization, where applicable|
|» void|[Link](#schemalink)|false|none|A link to void the payment, where applicable|
|» capture|[Link](#schemalink)|false|none|A link to capture the payment, where applicable|
|» refund|[Link](#schemalink)|false|none|A link to refund the payment, where applicable|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Authorized|
|status|Declined|
BankAccountFields
```json
{
"sections": [
{
"name": "Account Details",
"fields": [
{
"id": "iban",
"type": "string",
"display": "IBAN",
"description": "Number (which can contain letters) that identifies the account",
"section": "account",
"required": true,
"validation_regex": "^[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,18}$",
"min_length": 22,
"max_length": 22
},
{
"id": "account_holder.first_name",
"type": "string",
"display": "First name",
"description": "The account holder's first name",
"section": "account",
"required": true
},
{
"id": "account_holder.last_name",
"type": "string",
"display": "First name",
"description": "The account holder's last name",
"section": "account",
"required": true
}
]
}
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|sections|[object]|false|none|none|
|» name|string|true|none|The name of the section|
|» fields|[object]|false|none|none|
|»» id|string|true|none|The field identifier|
|»» section|string|false|none|The section to display the field in|
|»» display|string|true|none|The field's display name|
|»» help_text|string|false|none|The help text that explains the purpose of the field|
|»» type|string|true|none|The type of field|
|»» required|boolean|true|none|Whether the field is required|
|»» validation_regex|string|false|none|A regular expression that can be used to validate the input of the field|
|»» min_length|integer|false|none|The minimum length of the field|
|»» max_length|integer|false|none|The maximum length of the field|
|»» allowed_options|[object]|false|none|The allowed options for the field|
|»»» id|string|false|none|The option identifier|
|»»» display|string|false|none|The option display value|
|»» dependencies|[object]|false|none|The field's dependencies|
|»»» field_id|string|false|none|The field identifier|
|»»» value|string|false|none|The value of the dependent field that match in order for this field to be displayed|
BankPayoutAcceptedResponse
```json
{
"id": "pay_dvxl6j6stpqufkzfgbaahmfrzm",
"status": "Pending",
"reference": "PO-215-5721",
"instruction": {
"value_date": "2020-06-12T22:27:42.512594Z"
},
"_links": {
"self": {
"href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_dvxl6j6stpqufkzfgbaahmfrzm"
},
"actions": {
"href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_dvxl6j6stpqufkzfgbaahmfrzm/actions"
}
}
}
```
Bank Payout
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|true|none|The payout's unique identifier.|
|status|string|true|none|The status of the payout.|
|reference|string|false|none|The payout reference.|
|instruction|[PaymentInstructionResponse](#schemapaymentinstructionresponse)|true|none|Instruction details for payouts to bank accounts.|
|_links|object|true|none|The links related to the payout.|
|» self|object|false|none|The URI of the payout.|
|»» href|string|false|none|The link URL.|
|» actions|object|false|none|The actions URI of the payout.|
|»» href|string|false|none|The link URL.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Pending|
BankPayoutRequest
```json
{
"source": {
"type": "entity",
"id": "ca_y3oqhf46pyzuxjbcn2giaqnb44"
},
"destination": {
"type": "id",
"id": "src_wmlfc3zyhqzehihu7giusaaawu"
},
"amount": 6540,
"currency": "USD",
"reference": "Withdrawal",
"billing_descriptor": {
"reference": "stringstrin"
},
"sender": {
"type": "instrument",
"reference": "string"
},
"instruction": {
"scheme": "local",
"remittance": {
"reference": "string"
}
},
"processing_channel_id": "string",
"segment": {
"brand": "Acme Corporation",
"business_category": "Inward Payments",
"market": "UK"
}
}
```
Bank Payout
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|source|[BankPayoutRequestSource](#schemabankpayoutrequestsource)|true|none|The source from which the payout is funded.|
|destination|[PaymentRequestDestination](#schemapaymentrequestdestination)|true|none|The destination of the payout.|
|amount|integer|true|none|The amount to pay out. Value must be provided in the minor currency unit. For example, cents for USD.|
|currency|string|true|none|The three-letter ISO code of the destination currency
The currency should match that of the destination account.|
|reference|string|false|none|A reference you can use to identify the payment. For example, an order number.|
|billing_descriptor|[PayoutBillingDescriptor](#schemapayoutbillingdescriptor)|true|none|Beneficiary banks typically construct the billing descriptor using the billing descriptor reference and sender information. For direct sellers, the sender is typically your entity’s legal company name. If the ultimate sender is provided, then it is the values of the Sender object.|
|sender|[PayoutSender](#schemapayoutsender)|false|none|The ultimate sender of the payout – that is, your customer.
Not supported for Platform or Direct Seller Checkout.com clients.|
|instruction|[PaymentInstruction](#schemapaymentinstruction)|false|none|Details about the instruction for payouts to bank accounts.|
|processing_channel_id|string|true|none|The processing channel identifier|
|segment|[Segment](#schemasegment)|false|none|The dimension details about business segment for payment request. At least one dimension required.|
BankPayoutRequestSource
```json
{
"type": "entity",
"id": "ca_y3oqhf46pyzuxjbcn2giaqnb44"
}
```
The source from which the payout is funded.
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[BankPayoutRequestCurrencyAccountSource](#schemabankpayoutrequestcurrencyaccountsource)|false|none|A currency account source.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[BankPayoutRequestEntitySource](#schemabankpayoutrequestentitysource)|false|none|A currency account source.|
BillingDescriptor
```json
{
"name": "SUPERHEROES.COM",
"city": "GOTHAM",
"reference": "string",
"local_descriptors": [
{
"name": "漢字",
"character_set": "kanji"
}
]
}
```
An optional description that is displayed on the customer's statement identifying a purchase.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|true|none|A dynamic description of the payment.
Applies to card payments only.|
|city|string|true|none|The city from which the payment originated.
Applies to card payments only.|
|reference|string|false|none|The reference that should be shown on the statement.
Required for payouts to bank accounts.|
|local_descriptors|[[LocalBillingDescriptor](#schemalocalbillingdescriptor)]¦null|false|none|[An optional description that is displayed on the customer's statement identifying a purchase, in the specified local character set.
This does not override the value supplied in `BillingDescriptor`.
]|
CancellationAcceptedResponse
```json
{
"action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
"reference": "ORD-5023-4E89",
"_links": {
"payment": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
}
}
}
```
Cancellation response
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|action_id|[ActionId](#schemaactionid)|true|none|The unique identifier for the cancellation action.|
|reference|string|false|none|Your reference for the cancellation request.|
|_links|object|false|read-only|The links related to the cancellation.|
|» payment|[Link](#schemalink)|true|none|The URI of the payment to be canceled. Use this to check the status of the payment.|
CancellationRequest
```json
{
"reference": "ORD-5023-4E89"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|false|none|A reference you can later use to identify this cancellation request. You can use this value to identify the cancellation request later.|
CaptureAcceptedResponse
```json
{
"action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
"reference": "ORD-5023-4E89",
"_links": {
"payment": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
},
"redirect": {
"href": "https://{prefix}.api.checkout.com/redirect/act_y3oqhf46pyzuxjbcn2giaqnb44"
}
}
}
```
Capture response
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|action_id|[ActionId](#schemaactionid)|true|none|The unique identifier for the capture action|
|reference|string|false|none|Your reference for the capture request|
|_links|object|false|read-only|The links related to the capture|
|» payment|[Link](#schemalink)|true|none|The URI of the payment to be captured. Use this to check the status of the payment|
|» redirect|[Link](#schemalink)|false|none|For some alternative payments, the URI that the customer should be redirected to to complete the capture|
CaptureRequest
```json
{
"amount": 6540,
"capture_type": "Final",
"reference": "ORD-5023-4E89",
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "brucewayne@gmail.com",
"name": "Bruce Wayne",
"tax_number": "1350693505279",
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"summary": {
"registration_date": "2023-05-01",
"first_transaction_date": "2023-07-01",
"last_payment_date": "2023-08-01",
"total_order_count": 15,
"last_payment_amount": 500,
"is_premium_customer": true,
"is_returning_customer": true,
"lifetime_value": 500
}
},
"description": "Set of 3 masks",
"billing_descriptor": {
"name": "SUPERHEROES.COM",
"city": "GOTHAM",
"reference": "string",
"local_descriptors": [
{
"name": "漢字",
"character_set": "kanji"
}
]
},
"shipping": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"from_address_zip": "10014",
"tracking_info": [
{
"return_shipping_company": "DHL US",
"return_tracking_number": "GM275322484009027685",
"return_tracking_uri": "https://example.com/tracking/GM275322484009027685",
"shipping_company": "DHL US",
"tracking_number": "GM275322484009027685",
"tracking_uri": "https://example.com/tracking/GM275322484009027685"
}
]
},
"items": [
{
"type": "digital",
"sub_type": "stablecoin",
"name": "Necklace",
"quantity": 2,
"unit_price": 50,
"reference": "858818ac",
"commodity_code": "DEF123",
"unit_of_measure": "metres",
"total_amount": 29000,
"tax_rate": 2000,
"tax_amount": 1000,
"tax_exempt": true,
"discount_amount": 1000,
"wxpay_goods_id": "1001",
"url": "string",
"image_url": "string",
"service_ends_on": "2025-01-01",
"purchase_country": "GB",
"foreign_retailer_amount": 200
}
],
"amount_allocations": [
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4",
"amount": 1000,
"reference": "ORD-5023-4E89",
"commission": {
"amount": 1000,
"percentage": 1.125
}
}
],
"processing": {
"order_id": "123456789",
"otp_value": "966557877988",
"tax_amount": 3000,
"surcharge_amount": 200,
"discount_amount": 0,
"duty_amount": 0,
"shipping_amount": 300,
"shipping_tax_amount": 100,
"purchase_country": "GB",
"foreign_retailer_amount": 20000
},
"metadata": {
"coupon_code": "NY2018",
"partner_id": 123989
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|amount|integer(int64)|false|none|The amount to capture. If not specified, the full payment amount will be captured.|
|capture_type|string|false|none|The type of capture. If set to `Final`, the remaining available-to-capture balance will be voided.|
|reference|string|false|none|A reference you can later use to identify this capture request.
For Amex, the string limit is 30 characters.|
|customer|[CustomerRequest](#schemacustomerrequest)|false|none|The customer's details. Required if `source.type` is `tamara`|
|description|string|false|none|A description of the payment.|
|billing_descriptor|[BillingDescriptor](#schemabillingdescriptor)|false|none|An optional description that is displayed on the customer's statement identifying a purchase.|
|shipping|object|false|none|The shipping details.|
|» address|[Address](#schemaaddress)|false|none|The shipping address.|
|» phone|[PhoneNumber](#schemaphonenumber)|false|none|The phone number associated with the shipping address.|
|» from_address_zip|string|false|none|The postal code or zip code of the location being shipped from.|
|» tracking_info|[[TrackingInfo](#schematrackinginfo)]|false|none|The tracking information for the payment capture.|
|items|[Items](#schemaitems)|false|none|The order's line items.|
|amount_allocations|[AmountAllocations](#schemaamountallocations)|false|none|The sub-entities that the payment is being processed on behalf of|
|processing|[CaptureRequestProcessingSettings](#schemacapturerequestprocessingsettings)|false|none|Use the processing object to influence or override the data sent during card processing|
|metadata|object|false|none|A set of key-value pairs to attach to the authorization request. You can use this to store additional information in a structured format.
The `metadata` object only supports primitive data types. Objects and arrays are not supported.|
#### Enumerated Values
|Property|Value|
|---|---|
|capture_type|NonFinal|
|capture_type|Final|
CaptureRequestProcessingSettings
```json
{
"order_id": "123456789",
"otp_value": "966557877988",
"tax_amount": 3000,
"surcharge_amount": 200,
"discount_amount": 0,
"duty_amount": 0,
"shipping_amount": 300,
"shipping_tax_amount": 100,
"purchase_country": "GB",
"foreign_retailer_amount": 20000
}
```
Use the processing object to influence or override the data sent during card processing
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|order_id|string|false|none|The number provided by the cardholder. Purchase order or invoice number may be used.|
|otp_value|string|false|none|One time password sent to customer by SMS.|
|tax_amount|number|false|none|The total amount of sales tax on the total purchase amount.|
|surcharge_amount|integer(int64)|false|none|Surcharge amount applied to the partial capture transaction in minor units by the merchant|
|discount_amount|number|false|none|The discount amount applied to the transaction by the merchant.|
|duty_amount|number|false|none|The total charges for any import/export duty included in the transaction.|
|shipping_amount|number|false|none|The total freight or shipping and handling charges for the transaction.|
|shipping_tax_amount|number|false|none|The tax amount of the freight or shipping and handling charges for the transaction.|
|purchase_country|string|false|none|The country where the goods are purchased or the seller is based. ISO 3166 alpha-2 purchase country code.|
|foreign_retailer_amount|integer|false|none|The amount of the transaction that originates from a foreign retailer, in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value).|
CustomerSummary
```json
{
"registration_date": "2023-05-01",
"first_transaction_date": "2023-07-01",
"last_payment_date": "2023-08-01",
"total_order_count": 15,
"last_payment_amount": 500,
"is_premium_customer": true,
"is_returning_customer": true,
"lifetime_value": 500
}
```
Summary of the customer's transaction history.
Used for risk assessment when `source.type` is `Tamara`
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|registration_date|string(date)|false|none|The date the customer registered.|
|first_transaction_date|string(date)|false|none|The date of the customer's first transaction.|
|last_payment_date|string(date)|false|none|The date of the customer's last payment.|
|total_order_count|integer|false|none|The total number of orders made by the customer.|
|last_payment_amount|number(float)|false|none|The amount of the customer's last payment.|
|is_premium_customer|boolean|false|none|Specifies whether the customer is a premium customer.|
|is_returning_customer|boolean|false|none|Specifies whether the customer is a returning customer.|
|lifetime_value|number(float)|false|none|The customer's lifetime value. This is the total monetary amount that the customer has ordered, in their local currency, excluding the following:
- canceled orders
- rejected payments
- refunded payments
- Tamara payments
The lifetime value is an indicator of how valuable the relationship with the customer is to your company.|
DeviceDetails
```json
{
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
"network": {
"ipv4": "63.33.82.13",
"ipv6": "2001:0000:130F:0000:0000:09C0:876A:130B",
"tor": false,
"vpn": false,
"proxy": false
},
"provider": {
"id": "1728646225211.AfUgxG",
"name": "List [ \"merchant\", \"fingerprintjs\", \"riskify\" ]"
},
"timestamp": "2024-02-06T15:00:00.000Z",
"timezone": "60",
"virtual_machine": false,
"incognito": false,
"jailbroken": false,
"rooted": false,
"java_enabled": false,
"javascript_enabled": false,
"language": "FR-fr",
"color_depth": "16",
"screen_height": "1080",
"screen_width": "1920",
"user_agent_client_hint": "string",
"iframe_payment_allowed": true,
"accept_header": "string"
}
```
Details of the device from which the payment originated.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|user_agent|string|false|none|The contents of the HTTP User-Agent request header.
This field is required to process the device with the risk engine.|
|network|[Network](#schemanetwork)|false|none|Details of the device network.
Either ipv4 or ipv6 is required field.|
|provider|[DeviceProvider](#schemadeviceprovider)|false|none|Details of the device ID provider.|
|timestamp|string|false|none|The UTC date and time the payment was performed as reported by the device.
Format – ISO 8601 code
This field is required to process the device with the risk engine.|
|timezone|string|false|none|The time difference between UTC time and the local time reported by the browser, in minutes.
This field is required to process the device with the risk engine.|
|virtual_machine|boolean|false|none|Specifies if the device is running in a virtual machine.|
|incognito|boolean|false|none|Specifies if the browser is in incognito mode.|
|jailbroken|boolean|false|none|Specifies if the device is jailbroken.|
|rooted|boolean|false|none|Specifies if the device is rooted.|
|java_enabled|boolean|false|none|Specifies if the browser has the ability to execute Java, as reported by the browser's `navigator.javaEnabled` property.|
|javascript_enabled|boolean|false|none|Specifies if the browser has the ability to execute Javascript, as reported by the browser's `navigator.javascriptEnabled` property.
Only required for 3D Secure authentications processed with 3DS 2.2. If the payment is processed with an older 3DS version, this field is ignored.|
|language|string|false|none|The browser language, as reported by the browser's `navigator.language` property.
Format – IETF BCP47 language tag|
|color_depth|string|false|none|The bit depth of the color palette for displaying images in bits per pixel, as reported by the browser's `screen.colorDepth` property.|
|screen_height|string|false|none|The total height of the device screen in pixels, as reported by the browser's `screen.height` property.|
|screen_width|string|false|none|The total width of the device screen in pixels, as reported by the browser's `screen.width` property.|
|user_agent_client_hint|string|false|none|The raw `Sec-CH-UA` header value. This field improves Google Single-Page Application (SPA) support, as it provides more accurate information about the customer's browser.|
|iframe_payment_allowed|boolean|false|none|Indicates whether the Payments API is enabled for all parent frames.|
|accept_header|string|false|none|The exact content of the HTTP `Accept` headers as sent to the 3DS Requestor from the cardholder’s browser.|
DeviceProvider
```json
{
"id": "1728646225211.AfUgxG",
"name": "List [ \"merchant\", \"fingerprintjs\", \"riskify\" ]"
}
```
Details of the device ID provider.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The unique identifier for the device.|
|name|string|false|none|The name of the provider that generated the device identifier.|
DowntimeRetryRequest
```json
{
"enabled": true
}
```
Configuration of Downtime retries.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|enabled|boolean|true|none|Indicates if Checkout.com retries the payment when it's declined due to issuer or acquirer downtime.|
DunningRetryRequest
```json
{
"enabled": true,
"max_attempts": 6,
"end_after_days": 30
}
```
Configuration of Dunning retries.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|enabled|boolean|true|none|Indicates if Checkout.com retries the payment when it's declined with a supported decline code.|
|max_attempts|integer|false|none|The maximum number of authorization retry attempts, excluding the initial authorization.|
|end_after_days|integer|false|none|The maximum number of days between the initial request and the final retry attempt.|
PaymentGetResponseAlmaSource
```json
{
"type": "alma"
}
```
alma
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The payment source type|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentDetailsResponseSourceType](#schemapaymentdetailsresponsesourcetype)|false|none|Ordered list of payment details response source types|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|alma|
PaymentGetResponseBacsSource
```json
{
"type": "bacs",
"id": "src_wmlfc3zyhqzehihu7giusaaawu"
}
```
bacs
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The payment source type|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentDetailsResponseSourceType](#schemapaymentdetailsresponsesourcetype)|false|none|Ordered list of payment details response source types|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|true|none|The instrument ID|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|bacs|
```json
{
"type": "bancontact",
"iban": "string",
"bic": "string"
}
```
bancontact
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The payment source type|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentDetailsResponseSourceType](#schemapaymentdetailsresponsesourcetype)|false|none|Ordered list of payment details response source types|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|iban|string|false|none|The IBAN of the Consumer Bank account used for payment (if applicable).|
|bic|string|false|none|The Bank Code of the Consumer Bank account used for payment (if applicable). Example: BIC, Sort Code.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|bancontact|
PaymentGetResponseBlikSource
```json
{
"type": "blik",
"id": "src_iz65kt6uiq4enbm6wkjqssehsm"
}
```
blik
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentDetailsResponseSourceType](#schemapaymentdetailsresponsesourcetype)|false|none|Ordered list of payment details response source types|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The Checkout.com source identifier for the partner agreement created during a Blik recurring payment.
Use this value as `source.id` (with `source.type: id`) to process subsequent merchant-initiated payments against the same agreement.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|blik|
PaymentGetResponseCardSource
```json
{
"type": "card",
"id": "src_nwd3m4in3hkuddfpjsaevunhdy",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"expiry_month": 6,
"expiry_year": 2025,
"name": "Bruce Wayne",
"scheme": "VISA",
"scheme_local": "Cartes_Bancaires",
"local_schemes": [
"cartes_bancaires",
"visa"
],
"last4": "9996",
"fingerprint": "F639CAB2745BEE4140BF86DF6B6D6",
"bin": "45434748",
"card_type": "CREDIT",
"card_category": "CONSUMER",
"card_wallet_type": "applepay",
"issuer": "GOTHAM STATE BANK",
"issuer_country": "US",
"product_id": "F",
"product_type": "CLASSIC",
"avs_check": "S",
"cvv_check": "Y",
"payment_account_reference": "EUNIX9AX7THOOJIEJ2AP6OOFAHGH4",
"encrypted_card_number": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz...",
"account_update_status": "card_updated",
"account_update_failure_code": "VAU009",
"account_holder": {}
}
```
card
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentDetailsResponseSourceType](#schemapaymentdetailsresponsesourcetype)|false|none|Ordered list of payment details response source types|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The payment source identifier that can be used for subsequent payments. For new sources, this will only be returned if the payment was approved|
|billing_address|[Address](#schemaaddress)|false|none|The payment source owner's billing address|
|phone|[PhoneNumber](#schemaphonenumber)|false|none|The payment source owner's phone number|
|expiry_month|integer|true|none|The expiry month|
|expiry_year|integer|true|none|The expiry year|
|name|string|false|none|The cardholder's name|
|scheme|string|false|none|The card scheme|
|scheme_local|string|false|none|Replaced by `local_schemes`
The local co-branded card scheme.|
|local_schemes|[string]|false|none|The local co-branded card schemes.|
|last4|string|true|none|The last four digits of the card number|
|fingerprint|string|true|none|Uniquely identifies this particular card number. You can use this to compare cards across customers.|
|bin|string|true|none|The card issuer's Bank Identification Number (BIN)|
|card_type|string|false|none|The card type|
|card_category|string|false|none|The card category|
|card_wallet_type|string|false|none|The card wallet type|
|issuer|string|false|none|The name of the card issuer|
|issuer_country|string|false|none|The card issuer's country (two-letter ISO code)|
|product_id|string|false|none|The issuer/card scheme product identifier|
|product_type|string|false|none|The issuer/card scheme product type|
|avs_check|string|false|none|The Address Verification System check result|
|cvv_check|string|false|none|The card verification value (CVV) check result|
|payment_account_reference|string|false|none|A unique reference to the underlying card for network tokens (e.g., Apple Pay, Google Pay)|
|encrypted_card_number|string|false|none|The JWE encrypted full card number that has been updated by real-time account updater.|
|account_update_status|string|false|none|Specifies what card information was updated by the Real-Time Account Updater.|
|account_update_failure_code|string|false|none|Provides the failure code if the Real-Time Account Updater fails to update the card information.|
|account_holder|object|false|none|Information about the account holder of the card|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|card|
|card_type|CREDIT|
|card_type|DEBIT|
|card_type|PREPAID|
|card_type|CHARGE|
|card_type|DEFERRED DEBIT|
|card_category|CONSUMER|
|card_category|COMMERCIAL|
|card_wallet_type|applepay|
|card_wallet_type|googlepay|
|account_update_status|card_updated|
|account_update_status|card_expiry_updated|
|account_update_status|card_closed|
|account_update_status|contact_cardholder|
PaymentGetResponseCurrencyAccountSource
```json
{
"type": "currency_account",
"id": "string",
"amount": 0
}
```
currency_account
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The payment source type|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentDetailsResponseSourceType](#schemapaymentdetailsresponsesourcetype)|false|none|Ordered list of payment details response source types|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|true|none|The ID of the currency account|
|amount|integer|false|none|If specified, indicates the amount in the source currency to be paid out. If omitted, the root amount in the destination currency will be used.
The amount must be provided in the minor currency unit.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|currency_account|
PaymentGetResponseEPSSource
```json
{
"type": "eps",
"purpose": "string",
"bic": "string",
"iban": "string",
"account_holder_name": "string",
"account_holder": {
"first_name": "John",
"last_name": "Smith"
}
}
```
eps
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The payment source type|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentDetailsResponseSourceType](#schemapaymentdetailsresponsesourcetype)|false|none|Ordered list of payment details response source types|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|purpose|string|false|none|Purpose of the payment as appearing on customer's bank statement.|
|bic|string|false|none|Bank Identifier Code (BIC). It can be exactly 8 characters or 11 characters long.|
|iban|string|false|none|International Bank Account Number (IBAN) without whitespaces.|
|account_holder_name|string|false|none|Account holder information.|
|account_holder|[AccountHolderEps](#schemaaccountholdereps)|false|none|The account holder details|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|eps|
PaymentGetResponseIdealSource
```json
{
"type": "ideal",
"account_holder": "M.P.H. Nordhausen",
"account_holder_name": "M.P.H. Nordhausen",
"bic": "RABONL2U",
"description": "MEXC 18652552",
"iban": "NL73RABO0117816396"
}
```
ideal
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The payment source type|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentDetailsResponseSourceType](#schemapaymentdetailsresponsesourcetype)|false|none|Ordered list of payment details response source types|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|account_holder|string|false|none|The account holder information|
|account_holder_name|string|false|none|The account holder's name|
|bic|string|false|none|Bank Identifier Code (BIC). It can be exactly 8 characters or 11 characters long|
|description|string|false|none|Description of the product(s) or services being paid for|
|iban|string|false|none|The IBAN of the Consumer Bank account used for payment (if applicable).|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|ideal|
PaymentGetResponseKlarnaSource
```json
{
"type": "klarna",
"account_holder": {
"first_name": "Hannah",
"last_name": "Bret",
"billing_address": {
"address_line1": "123 Example St.",
"address_line2": "Apt. 456",
"city": "Berlin",
"zip": "10115",
"country": "DE"
},
"email": "string",
"date_of_birth": "string",
"account_holder_name": "string",
"iban": "string",
"account_number": "string",
"bank_code": "string",
"bank_name": "string",
"bic": "string",
"gender": "string",
"phone": {
"country_code": "44",
"number": "1234 567890"
}
}
}
```
klarna
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentDetailsResponseSourceType](#schemapaymentdetailsresponsesourcetype)|false|none|Ordered list of payment details response source types|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|account_holder|object|false|none|The account holder's details.|
|» first_name|string|false|none|The account holder's first name.|
|» last_name|string|false|none|The account holder's last name.|
|» billing_address|object|false|none|The account holder's billing address.|
|»» address_line1|string|false|none|The first line of the billing address.|
|»» address_line2|string|false|none|The second line of the billing address.|
|»» city|string|true|none|The billing address city.|
|»» zip|string|true|none|The billing address ZIP or postal code.|
|»» country|string|true|none|The two-letter ISO country code of the billing address.|
|» email|string|false|none|The account holder's email address.|
|» date_of_birth|string|false|none|The account holder's date of birth.|
|» account_holder_name|string|false|none|The account holder's full name.|
|» iban|string|false|none|The account's international bank account number (IBAN). The IBAN is a standardized international format for identifying bank accounts across countries.|
|» account_number|string|false|none|The account holder's account number.|
|» bank_code|string|false|none|A unique code that identifies the bank the account is held with.|
|» bank_name|string|false|none|The name of the bank the account is held with.|
|» bic|string|false|none|The account's bank identifier code (BIC). A BIC is a standardized international code used by banks to identify themselves in financial transactions.
Also referred to as a SWIFT code.|
|» gender|string|false|none|The account holder's gender.|
|» phone|object|false|none|The account holder's phone number.|
|»» country_code|string|false|none|The international country calling code.|
|»» number|string|false|none|The phone number.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|klarna|
PaymentGetResponseKnetSource
```json
{
"type": "knet",
"language": "ar",
"user_defined_field1": "string",
"user_defined_field2": "string",
"user_defined_field3": "string",
"user_defined_field4": "string",
"user_defined_field5": "string",
"card_token": "string",
"ptlf": "string",
"knet_payment_id": "string",
"knet_result": "string",
"inquiry_result": "string",
"bank_reference": "123456789012",
"knet_transaction_id": "1234567890123456",
"auth_code": "999554",
"auth_response_code": "5",
"post_date": "1127",
"avr": "A",
"error": "IPAY0100044",
"error_text": "IPAY0100044-Problem occured while loading payment page."
}
```
knet
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The payment source type|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentDetailsResponseSourceType](#schemapaymentdetailsresponsesourcetype)|false|none|Ordered list of payment details response source types|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|language|string|false|none|Required for KNet Gateway payments.
This field enables the issuer's site to select the consumer's preferred language. For example, the language selected on the merchant's site – if the issuer's site supports it. Code list in accordance with ISO 639-1. (Arabic = 'ar', English = 'en'). Note that 'ar' corresponds to 'ARA' and 'en' to 'USA'. Both values accepted by KNet Gateway.|
|user_defined_field1|string|false|none|User-defined field that can be used to pass and store any additional transaction data required to be archived with the transaction and available as a searching criterion. Only alphanumeric characters and spaces are allowed.|
|user_defined_field2|string|false|none|User-defined field can be used to pass and store any additional transaction data required to be archived with the transaction and available as a searching criterion. Only alphanumeric characters and spaces are allowed.|
|user_defined_field3|string|false|none|User-defined field can be used to pass and store any additional transaction data required to be archived with the transaction and available as a searching criterion. Only alphanumeric characters and spaces are allowed. Note that this field must be omitted when the `card_token` field is not empty. This restriction exists because a card token is passed to KNet Gateway as `user_defined_field3`.|
|user_defined_field4|string|false|none|User-defined field can be used to pass and store any additional transaction data required to be archived with the transaction and available as a searching criterion. Only alphanumeric characters and spaces are allowed.|
|user_defined_field5|string|false|none|User-defined field can be used to pass and store any additional transaction data required to be archived with the transaction and available as a searching criterion. Only alphanumeric characters and spaces are allowed. Note that this field must be omitted when the `ptlf` field is not empty. This restriction exists because a PTLF value is passed to KNet Gateway as `user_defined_field5`.|
|card_token|string|false|none|This token allows re-usage of card details for multiple payments. This 8-digit token should be generated by a merchant. When a subsequent payment is initialized with the same card token, a customer is presented with two options. The customer can choose to pay with KFast (doesn't need to enter card details again), or with KNet as usual. The payment flow stays the same i.e. a merchant should redirect a customer to the redirect URL which is provided in the payment creation response. Note that `user_defined_field3` must be omitted when the `card_token` field is not empty. This restriction exists because a card token is passed to KNet Gateway as `user_defined_field3`.|
|ptlf|string|false|none|This is an ID for merchant PTLF functionality tracking. Only alphanumeric characters are allowed. Note that `user_defined_field5` must be omitted when the `ptlf` field is not empty. This restriction exists because a PTLF value is passed to KNet Gateway as `user_defined_field5`.|
|knet_payment_id|string|false|none|The payment identifier assigned by KNet Gateway.|
|knet_result|string|false|none|The state of the payment, returned by KNet Gateway after the customer is redirected from the payment page.|
|inquiry_result|string|false|none|The state of the payment, returned by KNet Gateway in the response from the payment inquiry. This field is populated in rare cases when the redirection from the payment page did not occur properly.|
|bank_reference|string|false|none|The result transaction reference, given by some banks/institutions.|
|knet_transaction_id|string|false|none|The transaction identifier assigned by KNet Gateway.|
|auth_code|string|false|none|The resulting authorization code from the issuing bank.|
|auth_response_code|string|false|none|The auth response code / reason code relating to the issuing bank authorization code.|
|post_date|string|false|none|The transaction date in the authorization system format, with the value defined by the issuing bank, so may not match the actual transaction date. The format is `MMDD`.|
|avr|string|false|none|The Address Verification Response returned from the address verification service.|
|error|string|false|none|The KNET error code for transaction processing.|
|error_text|string|false|none|The KNET text detail for the error, including an error code.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|knet|
|language|ar|
|language|en|
PaymentGetResponseMultibancoSource
```json
{
"type": "multibanco",
"payment_reference": "string",
"service_supplier_id": "string"
}
```
multibanco
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The payment source type|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentDetailsResponseSourceType](#schemapaymentdetailsresponsesourcetype)|false|none|Ordered list of payment details response source types|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|payment_reference|string|false|none|Multibanco payment reference|
|service_supplier_id|string|false|none|The identifier of a supplier charging for its service or product|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|multibanco|
PaymentGetResponseP24Source
```json
{
"type": "p24",
"p24_descriptor": "string"
}
```
p24
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The payment source type|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentDetailsResponseSourceType](#schemapaymentdetailsresponsesourcetype)|false|none|Ordered list of payment details response source types|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|p24_descriptor|string|false|none|P24-generated payment descriptor, which contains the requested billing descriptor or the merchant's default descriptor (subject to truncation).|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|p24|
PaymentGetResponsePayPalSource
```json
{
"type": "paypal",
"account_holder": {
"email": "user@example.com",
"full_name": "John Smith"
}
}
```
paypal
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The payment source type|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentDetailsResponseSourceType](#schemapaymentdetailsresponsesourcetype)|false|none|Ordered list of payment details response source types|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|account_holder|object|false|none|The account holder details|
|» email|string(email)|false|none|The account holder email address.|
|» full_name|string|false|none|The full name of the account holder|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|paypal|
PaymentGetResponseQPaySource
```json
{
"type": "qpay",
"description": "string",
"qpay_status": "string",
"status_message": "string",
"confirmation_id": "string",
"pun": "string"
}
```
qpay
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The payment source type|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentDetailsResponseSourceType](#schemapaymentdetailsresponsesourcetype)|false|none|Ordered list of payment details response source types|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|description|string|true|none|Alphanumeric string containing a description of the payment order.|
|qpay_status|string|false|none|The status code returned from the QPay gateway on payment, if available.|
|status_message|string|false|none|A message giving further detail on the payment status, for failure/cancelled/success status payments.|
|confirmation_id|string|false|none|An identifier from the QPay gateway for a successful payment.|
|pun|string|true|none|QPay Payment Unique Number|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|qpay|
PaymentGetResponseSEPAV4Source
```json
{
"type": "sepa",
"id": "src_q2euotsbrciupfgmwxkyzuoevq"
}
```
sepa
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The payment source type|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentDetailsResponseSourceType](#schemapaymentdetailsresponsesourcetype)|false|none|Ordered list of payment details response source types|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|true|none|The instrument ID|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|sepa|
PaymentGetResponseSequraSource
```json
{
"type": "sequra"
}
```
sequra
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The payment source type|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentDetailsResponseSourceType](#schemapaymentdetailsresponsesourcetype)|false|none|Ordered list of payment details response source types|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|sequra|
PaymentGetResponseSwishSource
```json
{
"type": "swish"
}
```
swish
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The payment source type|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentDetailsResponseSourceType](#schemapaymentdetailsresponsesourcetype)|false|none|Ordered list of payment details response source types|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|swish|
PaymentGetResponseTamaraSource
```json
{
"type": "tamara"
}
```
tamara
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The payment source type|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentDetailsResponseSourceType](#schemapaymentdetailsresponsesourcetype)|false|none|Ordered list of payment details response source types|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|tamara|
IdempotentActionResponse
```json
{
"action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
"_links": {
"payment": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
}
}
}
```
The response received when you attempt a repeated payment action. For example, if you attempt to refund a payment that is already refunded.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|action_id|[ActionId](#schemaactionid)|true|none|The unique identifier for the previously completed payment action.|
|_links|object|false|read-only|Links related to the payment.|
|» payment|[Link](#schemalink)|true|none|The URI of the refunded payment. Use this to check the status of the payment.|
InitialAuthentication
```json
{
"acs_transaction_id": "stringstringstringstringstringstring",
"authentication_method": "frictionless_authentication",
"authentication_timestamp": "2023-02-06T15:00:00.000Z",
"authentication_data": "string",
"initial_session_id": "sid_p6prbhogijnuxgv4grm3ber55u"
}
```
InitialAuthentication
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|acs_transaction_id|string|false|none|The Access Control Server (ACS) transaction ID for a previously authenticated transaction|
|authentication_method|string|false|none|none|
|authentication_timestamp|string|false|none|The timestamp of the previous authentication, in ISO 8601 format.|
|authentication_data|string|false|none|The data that documents and supports a specific authentication process|
|initial_session_id|string|false|none|The ID for a previous session, which is used for retrieve the initial transaction's properties|
#### Enumerated Values
|Property|Value|
|---|---|
|authentication_method|frictionless_authentication|
|authentication_method|challenge_occurred|
|authentication_method|avs_verified|
|authentication_method|other_issuer_methods|
Items
```json
[
{
"type": "digital",
"sub_type": "stablecoin",
"name": "Necklace",
"quantity": 2,
"unit_price": 50,
"reference": "858818ac",
"commodity_code": "DEF123",
"unit_of_measure": "metres",
"total_amount": 29000,
"tax_rate": 2000,
"tax_amount": 1000,
"tax_exempt": true,
"discount_amount": 1000,
"wxpay_goods_id": "1001",
"url": "string",
"image_url": "string",
"service_ends_on": "2025-01-01",
"purchase_country": "GB",
"foreign_retailer_amount": 200
}
]
```
The order's line items.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|false|none|The item type. For example, `physical` or `digital`.
This field is used to provide item level metadata where applicable. If `source.type` is `sequra`, this field is required.|
|sub_type|string|false|none|The digital item type.
If `type` is set to `digital`, this field is required.|
|name|string|false|none|The descriptive name of the line item.
If `source.type` is `sequra`, this field is required.|
|quantity|integer|false|none|The number of line items.
If `source.type` is `sequra`, this field is required.|
|unit_price|integer|false|none|The unit price of the item the minor currency unit. Required if `source.type` is `sequra`|
|reference|string|false|none|The item reference or product SKU (stock-keeping unit).
For Visa and Mastercard's interchange reduction programs, this value has a maximum length of 12 characters.
If `source.type` is `sequra`, this field is required.|
|commodity_code|string|false|none|A code identifying a Commodity for value-added tax (VAT) purposes.|
|unit_of_measure|string|false|none|Unit of Measure code used for an item in transaction.|
|total_amount|number|false|none|The total cost of the line item, in minor currency units. Calculate this using the following formula:
`total_amount` = (`quantity` * `unit_price`) - `discount_amount`.
If `source.type` is `sequra`, this field is required.|
|tax_rate|number|false|none|The tax rate of the item line in minor units. The percentage value is represented with two implicit decimals. For example, 2000=20%.|
|tax_amount|number|false|none|Contains the total amount of sales tax or value-added tax (VAT) on the total purchase amount. Tax should be included in the total purchase.|
|tax_exempt|boolean|false|none|Indicates whether the products or services are tax-exempt.
Set to `true` if:
- You are processing a card payment.
- The `tax_amount` field is `0` due to a tax-exempt product or service.|
|discount_amount|number|false|none|The discount applied to each invoice line item.|
|wxpay_goods_id|string|false|none|Unified product No. defined by WeChat Pay|
|url|string|false|none|Link to the line item's product page|
|image_url|string|false|none|Link to the line item's product page|
|service_ends_on|string(date)|false|none|Maximum date for the service to be rendered or ended.
If `source.type` is `sequra` and `item.type` is `digital`, this field is required.|
|purchase_country|string|false|none|The country where the purchase was made.
Format – ISO alpha-2 country code|
|foreign_retailer_amount|integer|false|none|The foreign retailer amount the merchant applied to the transaction, in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value).|
#### Enumerated Values
|Property|Value|
|---|---|
|type|digital|
|type|discount|
|type|physical|
|sub_type|blockchain|
|sub_type|cbdc|
|sub_type|cryptocurrency|
|sub_type|nft|
|sub_type|stablecoin|
LocalBillingDescriptor
```json
{
"name": "漢字",
"character_set": "kanji"
}
```
An optional description that is displayed on the customer's statement identifying a purchase, in the specified local character set.
This does not override the value supplied in `BillingDescriptor`.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|true|none|A dynamic description of the card payment. Other payment methods will not display this description.
The character set specified will determine the maximum length of the field. For `katakana`, the maximum length is 23 characters, equivalent to 23 katakana characters. For `kanji`, the maximum length is 40 characters, equivalent to 20 kanji characters.|
|character_set|any|true|none|none|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[LocalCharacterSets](#schemalocalcharactersets)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|any|false|none|The character set of the descriptor|
LocalCharacterSets
```json
"kanji"
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|kanji|
|*anonymous*|katakana|
MerchantAuthenticationInfo
```json
{
"three_ds_req_auth_method": "no_threeds_requestor_authentication_occurred",
"three_ds_req_auth_timestamp": "2019-08-24T14:15:22Z",
"three_ds_req_auth_data": "string"
}
```
MerchantAuthenticationInfo
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|three_ds_req_auth_method|string|false|none|The mechanism used by the cardholder to authenticate with the 3DS Requestor|
|three_ds_req_auth_timestamp|string(date-time)|false|none|The UTC date and time the cardholder authenticated with the 3DS Requestor, in ISO 8601 format.|
|three_ds_req_auth_data|string|false|none|The data that documents and supports a specific authentication process|
#### Enumerated Values
|Property|Value|
|---|---|
|three_ds_req_auth_method|no_threeds_requestor_authentication_occurred|
|three_ds_req_auth_method|three3ds_requestor_own_credentials|
|three_ds_req_auth_method|federated_id|
|three_ds_req_auth_method|issuer_credentials|
|three_ds_req_auth_method|third_party_authentication|
|three_ds_req_auth_method|fido_authenticator|
|three_ds_req_auth_method|fido_authenticator_fido_assurance_data_signed|
|three_ds_req_auth_method|src_assurance_data|
Network
```json
{
"ipv4": "63.33.82.13",
"ipv6": "2001:0000:130F:0000:0000:09C0:876A:130B",
"tor": false,
"vpn": false,
"proxy": false
}
```
Details of the device network.
Either ipv4 or ipv6 is required field.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|ipv4|string|false|none|The device's IPV4 address.
Not required if you provide the `ipv6` field.|
|ipv6|string|false|none|The device's IPV6 address.
Not required if you provide the `ipv4` field.|
|tor|boolean|false|none|Specifies if the Tor network was used in the browser session.|
|vpn|boolean|false|none|Specifies if a virtual private network (VPN) was used in the browser session.|
|proxy|boolean|false|none|Specifies if a proxy was used in the browser session.|
PartialAuthorization
```json
{
"enabled": true
}
```
Required information to allow partial authorization
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|enabled|boolean|true|none|Specifies whether to allow partial authorizations.|
PaymentAcceptedResponse
```json
{
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"status": "Pending",
"reference": "ORD-5023-4E89",
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "johnsmith@example.com",
"name": "John Smith",
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"summary": {
"registration_date": "2023-05-01",
"first_transaction_date": "2023-07-01",
"last_payment_date": "2023-08-01",
"total_order_count": 15,
"last_payment_amount": 500,
"is_premium_customer": true,
"is_returning_customer": true,
"lifetime_value": 500
}
},
"3ds": {
"downgraded": false,
"enrolled": "Y",
"upgrade_reason": "sca_retry"
},
"subscription": {
"id": "string"
},
"processing": {
"continuation_payload": "{\\\"prepay_id\\\":\\\"wx02161421698644ab471821297252eb0000\\\",\\\"partner_id\\\":\\\"1900012731\\\",\\\"timestamp\\\":1651479262,\\\"app_id\\\":\\\"sub_application_id\\\",\\\"nonce\\\":\\\"476d17edadf44915ad533107bd3c71c2\\\",\\\"sign\\\":\\\"QM1CCVAkexZLq00Uz/IxgbqC2ke7Xl9xUayutALc1EebLT1cI85H0biNNjhzQrzFdJ0YCq8KR2Hc9bD01vxRsn18fHzE5bhvn2qlUSOeY7hATfaLYS7+f+gKVj+0iIuUp3qamquErrKYl1g1Vhvlwn1U8TrcjhU0w666YYJuwIP9qPNy6F8wj3ORWM1uYmB9D4v09sTnmZfBPFwuGJzj2PTBGyvoKLu+V1T1HzlC2rwhpDmrSCq0rcFL2smztWGVktpZ2NoggEAVWLjHWsvS8OmzgeosM3ltoCeWjlp1SusmXtlMtUJWyjiVQYHnjb/a42NYk/qynZ/w+BAqLTlDKA==\\\",\\\"pkg\\\":\\\"Sign=WXPay\\\"}",
"partner_payment_id": "440644309099499894406",
"pan_type_processed": "fpan",
"fallback_source_used": false,
"cko_network_token_available": false,
"scheme_merchant_id": "123456",
"payment_reference": "999999964",
"service_supplier_id": "11854"
},
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
},
"redirect": {
"href": "https://{prefix}.api.checkout.com/3ds/pay_mbabizu24mvu3mela5njyhpit4",
"mobile": {
"android": {
"href": "app-scheme://android.com"
},
"ios": {
"href": "app-scheme://ios.com"
}
},
"qr_code": {
"image": "https://{prefix}.api.sandbox.checkout.com/qr/medium",
"text": "abc"
}
}
}
}
```
Payment
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[PaymentId](#schemapaymentid)|true|read-only|The payment's unique identifier|
|status|string|true|none|The status of the payment|
|reference|string|false|none|Your reference for the payment request|
|customer|[CustomerResponse](#schemacustomerresponse)|false|none|The customer associated with the payment, if provided in the request|
|3ds|[3dsEnrollmentData](#schema3dsenrollmentdata)|false|none|Provides 3D Secure enrollment status|
|subscription|[Subscription](#schemasubscription)|false|none|The details of the subscription.|
|processing|object|false|read-only|Returns information related to the processing of the payment|
|» continuation_payload|string|false|none|The payload for an in-app payment the merchant can use to continue a payments.|
|» partner_payment_id|string|false|none|The partner-originated unique payment identifier|
|» pan_type_processed|string|false|none|The type of Primary Account Number (PAN) used for the payment. DPAN indicates network token was used, FPAN indicates the full card was used|
|» fallback_source_used|boolean|false|none|Indicates whether the `fallback_source` field was used for the payment.|
|» cko_network_token_available|boolean|false|none|The flag indicating if Checkout Network Token was available for the payment|
|» scheme_merchant_id|string|false|none|The merchant identifier that was configured with the scheme and used for the payment.|
|» payment_reference|string|false|none|The payment reference of the transaction. Can be used to build your own payment slip. Applicable for Multibanco payments.|
|» service_supplier_id|string|false|none|The merchant/service provider identifier of the transaction. Can be used to build your own payment slip. Applicable for Multibanco payments.|
|_links|object|false|read-only|The links related to the payment|
|» self|[Link](#schemalink)|true|none|The URI of the payment|
|» redirect|[RedirectLink](#schemaredirectlink)|false|none|The URI to which the customer is redirected to complete the payment.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Pending|
|pan_type_processed|fpan|
|pan_type_processed|dpan|
PaymentAction
```json
{
"id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
"type": "Authorization",
"processed_on": "2019-08-24T14:15:22Z",
"amount": 6540,
"approved": true,
"auth_code": "643381",
"response_code": "10000",
"response_summary": "Approved",
"authorization_type": "Estimated",
"reference": "ORD-5023-4E89",
"amount_allocations": [
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4",
"amount": 1000,
"reference": "ORD-5023-4E89",
"commission": {
"amount": 1000,
"percentage": 1.125
}
}
],
"processing": {
"retrieval_reference_number": "909913440644",
"acquirer_reference_number": "24021219099007452440793",
"acquirer_transaction_id": "440644309099499894406",
"capture_action_id": "act_fd3h6evhpn3uxdoqbuu3lqnqbm"
},
"items": [
{
"type": "digital",
"sub_type": "stablecoin",
"name": "Necklace",
"quantity": 2,
"unit_price": 50,
"reference": "858818ac",
"commodity_code": "DEF123",
"unit_of_measure": "metres",
"total_amount": 29000,
"tax_rate": 2000,
"tax_amount": 1000,
"tax_exempt": true,
"discount_amount": 1000,
"wxpay_goods_id": "1001",
"url": "string",
"image_url": "string",
"service_ends_on": "2025-01-01",
"purchase_country": "GB",
"foreign_retailer_amount": 200
}
],
"metadata": {}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[ActionId](#schemaactionid)|true|none|The unique identifier of the payment action|
|type|string|true|none|The type of action|
|processed_on|[ServerTimestamp](#schemaservertimestamp)|true|none|The date/time the action was processed|
|amount|integer|true|none|The action amount|
|approved|boolean|false|none|Whether the action was successful|
|auth_code|string|false|none|The issuer authorization code for cards.
Only applicable for payins.|
|response_code|string|true|none|The Gateway response code|
|response_summary|string|false|none|The Gateway response summary|
|authorization_type|string|false|none|The authorization type.
Only applicable for payins.|
|reference|string|false|none|Your reference for the action.
Only applicable for payins.|
|amount_allocations|[AmountAllocations](#schemaamountallocations)|false|none|The sub-entities that the payment is being processed on behalf of.
Only applicable for payins.|
|processing|object|false|none|Returns information related to the processing of the payment.
Only applicable for payins.|
|» retrieval_reference_number|string|false|none|A unique identifier for the authorization that is submitted to the card scheme during processing|
|» acquirer_reference_number|string|false|none|A unique identifier for the capture that is submitted to the card scheme during processing|
|» acquirer_transaction_id|string|false|none|A unique identifier for the transaction generated by the acquirer|
|» capture_action_id|string|false|none|The Checkout.com action ID of the capture you wanted to refund. Required only for PayPal and Riverty.|
|items|[Items](#schemaitems)|false|none|The order's line item or product that is being purchased.
Only applicable for payins.|
|metadata|object|false|none|A set of key-value pairs that you can attach to an action.
Only applicable for payins.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|Authorization|
|type|Card Verification|
|type|Void|
|type|Capture|
|type|Refund|
|type|Payout|
|type|Return|
|authorization_type|Final|
|authorization_type|Estimated|
|authorization_type|Incremental|
PaymentActionsResponse
```json
[
{
"id": "act_fd3h6evhpn3uxdoqbuu3lqnqbm",
"type": "Refund",
"processed_on": "2018-01-20T10:30:48Z",
"amount": 1000,
"approved": true,
"response_code": "10000",
"response_summary": "Approved"
},
{
"id": "act_gefycn3jcvuupboxfmqrhk2aym",
"type": "Capture",
"processed_on": "2018-01-17T10:30:48Z",
"amount": 6540,
"approved": true,
"response_code": "10000",
"response_summary": "Approved",
"processing": {
"acquirer_reference_number": "24021219099007452440793",
"acquirer_transaction_id": "00745244079"
},
"metadata": {
"shipping_ref": "MQIBN2"
}
},
{
"id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
"type": "Authorization",
"processed_on": "2018-01-17T09:30:48Z",
"amount": 6540,
"approved": true,
"auth_code": "643381",
"response_code": "10000",
"response_summary": "Approved",
"reference": "ORD-5023-4E89",
"processing": {
"retrieval_reference_number": "909913440644",
"acquirer_transaction_id": "440644309099499894406"
}
}
]
```
The payment actions
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[[PaymentAction](#schemapaymentaction)]|false|none|The payment actions|
PaymentActionSummary
```json
{
"id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
"type": "Authorization",
"response_code": "10000",
"response_summary": "Approved"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[ActionId](#schemaactionid)|true|none|The unique identifier of the payment action|
|type|string|true|none|The type of action|
|response_code|string|true|none|The Gateway response code|
|response_summary|string|false|none|The Gateway response summary|
#### Enumerated Values
|Property|Value|
|---|---|
|type|Authorization|
|type|Card Verification|
|type|Void|
|type|Capture|
|type|Refund|
PaymentDetails
```json
{
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"requested_on": "2019-08-24T14:15:22Z",
"source": {
"type": "card",
"id": "src_nwd3m4in3hkuddfpjsaevunhdy",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"expiry_month": 6,
"expiry_year": 2025,
"name": "Bruce Wayne",
"scheme": "VISA",
"scheme_local": "Cartes_Bancaires",
"local_schemes": [
"cartes_bancaires",
"visa"
],
"last4": "9996",
"fingerprint": "F639CAB2745BEE4140BF86DF6B6D6",
"bin": "45434748",
"card_type": "CREDIT",
"card_category": "CONSUMER",
"card_wallet_type": "applepay",
"issuer": "GOTHAM STATE BANK",
"issuer_country": "US",
"product_id": "F",
"product_type": "CLASSIC",
"avs_check": "S",
"cvv_check": "Y",
"payment_account_reference": "EUNIX9AX7THOOJIEJ2AP6OOFAHGH4",
"encrypted_card_number": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz...",
"account_update_status": "card_updated",
"account_update_failure_code": "VAU009",
"account_holder": {}
},
"destination": {
"type": "bank_account",
"id": "string"
},
"amount": 6540,
"amount_requested": 6540,
"currency": "USD",
"payment_type": "Recurring",
"payment_plan": {
"amount_variability": "Variable",
"days_between_payments": 28,
"total_number_of_payments": 5,
"current_payment_number": 3,
"expiry": "20251031",
"name": "Subscription 1234",
"start_date": "20260507",
"amount": 1234
},
"reference": "ORD-5023-4E89",
"description": "Set of 3 masks",
"approved": true,
"expires_on": "string",
"status": "Authorized",
"balances": {
"total_authorized": 6540,
"total_voided": 0,
"available_to_void": 6540,
"total_captured": 0,
"available_to_capture": 6540,
"total_refunded": 0,
"available_to_refund": 0
},
"3ds": {
"downgraded": false,
"enrolled": "Y",
"signature_valid": "Y",
"authentication_response": "Y",
"authentication_status_reason": "string",
"cryptogram": "hv8mUFzPzRZoCAAAAAEQBDMAAAA=",
"xid": "MDAwMDAwMDAwMDAwMDAwMzIyNzY=",
"eci": "string",
"version": "2.1.0",
"exemption": "low_value",
"exemption_applied": "string",
"challenged": true,
"upgrade_reason": "sca_retry",
"trusted_listing": {
"status": "Y",
"source": "01"
}
},
"authentication": {
"experience": "3ds"
},
"risk": {
"flagged": true,
"score": 22
},
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "brucewayne@gmail.com",
"name": "Bruce Wayne",
"summary": {
"registration_date": "2023-05-01",
"first_transaction_date": "2023-07-01",
"last_payment_date": "2023-08-01",
"total_order_count": 15,
"last_payment_amount": 500,
"is_premium_customer": true,
"is_returning_customer": true,
"lifetime_value": 500
}
},
"billing_descriptor": {
"name": "SUPERHEROES.COM",
"city": "GOTHAM",
"reference": "string",
"local_descriptors": [
{
"name": "漢字",
"character_set": "kanji"
}
]
},
"shipping": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"payment_ip": "90.197.169.245",
"sender": {
"type": "individual",
"reference": "8285282045818",
"first_name": "John",
"last_name": "Jones",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"amount_allocations": [
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4",
"amount": 1000,
"reference": "ORD-5023-4E89",
"commission": {
"amount": 1000,
"percentage": 1.125
}
}
],
"recipient": {
"dob": "1985-05-15",
"account_number": "5555554444",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"zip": "SW1A",
"first_name": "John",
"last_name": "Jones"
},
"processing": {
"preferred_scheme": "cartes_bancaires",
"app_id": "com.iap.linker_portal",
"airline_data": [
{
"ticket": {
"number": "045-21351455613",
"issue_date": "2023-05-20",
"issuing_carrier_code": "AI",
"travel_package_indicator": "B",
"travel_agency_name": "World Tours",
"travel_agency_code": "01"
},
"passenger": [
{
"first_name": "John",
"last_name": "White",
"date_of_birth": "1990-05-26",
"address": {
"country": "US"
}
}
],
"flight_leg_details": [
{
"flight_number": "101",
"carrier_code": "BA",
"class_of_travelling": "J",
"departure_airport": "LHR",
"departure_date": "2023-06-19",
"departure_time": "15:30",
"arrival_airport": "LAX",
"stop_over_code": "x",
"fare_basis_code": "SPRSVR"
}
]
}
],
"accommodation_data": [
{
"name": "The Sea View Hotel",
"booking_reference": "HOTEL123",
"check_in_date": "2023-06-20",
"check_out_date": "2023-06-23",
"address": {
"address_line1": "123 Beach Road",
"zip": "10001"
},
"state": "FL",
"country": "USA",
"city": "Los Angeles",
"number_of_rooms": 2,
"guests": [
{
"first_name": "Jane",
"last_name": "Doe",
"date_of_birth": "1985-07-14"
}
],
"room": [
{
"rate": "70",
"number_of_nights_at_room_rate": "3"
}
],
"property_phone": [
{
"country_code": "44",
"number": "7123456789"
}
],
"customer_service_phone": [
{
"country_code": "44",
"number": "7123456789"
}
]
}
],
"partner_customer_id": "2102209000001106125F8",
"partner_payment_id": "440644309099499894406",
"partner_code": "999111",
"failure_code": "partner_error",
"partner_response_code": "ER_WRONG_TICKET",
"tax_amount": 1000,
"locale": "en-US",
"retrieval_reference_number": "909913440644",
"partner_order_id": "string",
"partner_status": "string",
"partner_transaction_id": "string",
"partner_error_codes": [
"string"
],
"partner_merchant_advice_code": "24",
"partner_error_message": "string",
"partner_authorization_code": "string",
"partner_authorization_response_code": "string",
"partner_fraud_status": "string",
"pan_type_processed": "fpan",
"fallback_source_used": false,
"custom_payment_method_ids": [
"string"
],
"aft": true,
"merchant_category_code": "5311",
"scheme_merchant_id": "123456",
"scheme": "ACCEL",
"scheme_transaction_link_id": "string"
},
"items": [
{
"type": "digital",
"sub_type": "stablecoin",
"name": "Necklace",
"quantity": 2,
"unit_price": 50,
"reference": "858818ac",
"commodity_code": "DEF123",
"unit_of_measure": "metres",
"total_amount": 29000,
"tax_rate": 2000,
"tax_amount": 1000,
"tax_exempt": true,
"discount_amount": 1000,
"wxpay_goods_id": "1001",
"url": "string",
"image_url": "string",
"service_ends_on": "2025-01-01",
"purchase_country": "GB",
"foreign_retailer_amount": 200
}
],
"metadata": {
"coupon_code": "NY2018",
"partner_id": 123989
},
"eci": "06",
"scheme_id": "488341541494658",
"actions": [
{
"id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
"type": "Authorization",
"response_code": "10000",
"response_summary": "Approved"
}
],
"retry": {
"enabled": true,
"attempts_made": 0,
"max_attempts": 6,
"ends_on": "2019-08-24T14:15:22Z",
"next_attempt_on": "2019-08-24T14:15:22Z"
},
"cko_network_token_available": false,
"instruction": {
"purpose": "financial_services"
},
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
},
"actions": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/actions"
},
"authorize": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/authorizations"
},
"refund": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/refund"
}
}
}
```
Payment response
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[PaymentId](#schemapaymentid)|true|none|Payment unique identifier|
|requested_on|[ServerTimestamp](#schemaservertimestamp)|true|none|The date/time the payment was requested|
|source|[PaymentDetailsResponseSource](#schemapaymentdetailsresponsesource)|false|none|The source of the payment|
|destination|[PaymentResponseDestination](#schemapaymentresponsedestination)|false|none|The destination of the payment|
|amount|integer|true|none|The original payment amount|
|amount_requested|integer|false|none|The full amount from the original authorization, if a partial authorization was requested.|
|currency|string|true|none|The three-letter ISO currency code of the payment|
|payment_type|string|false|none|This must be specified for card payments where the cardholder is not present (For example, recurring or mail order / telephone order)|
|payment_plan|object|false|none|The details of a recurring subscription or installment|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PlanRecurring](#schemaplanrecurring)|false|none|The information to process a recurring payment request. To be used when the `payment_type` is `recurring`.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PlanInstallment](#schemaplaninstallment)|false|none|The information to process a installment payment request. To be used when the `payment_type` is `installment`.|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|false|none|Your reference for the payment|
|description|string|false|none|A description of the payment|
|approved|boolean|true|none|Whether the payment was successful|
|expires_on|string|false|none|The timestamp (ISO 8601 code) for when the authorization's validity period expires|
|status|string|true|none|The status of the payment|
|balances|[PaymentResponseBalances](#schemapaymentresponsebalances)|false|none|The payment balances|
|3ds|[3dsData](#schema3dsdata)|false|none|Provides information relating to the processing of 3D Secure payments|
|authentication|[PaymentAuthenticationData](#schemapaymentauthenticationdata)|false|none|Provides information relating to the authentication of the payment.|
|risk|object|false|none|Returns the payments risk assessment results|
|» flagged|boolean|false|none|Whether the payment was flagged by a risk check|
|» score|number|false|none|The risk score calculated by our Fraud Detection engine. Absent if not enough data provided.|
|customer|object|false|none|The customer to which this payment is linked|
|» id|string|true|none|The unique identifier of the customer. This can be passed as a source when making a payment|
|» email|string|false|none|The customer's email address|
|» name|string|false|none|The customer's name|
|» summary|[CustomerSummary](#schemacustomersummary)|false|none|Summary of the customer's transaction history.
Used for risk assessment when `source.type` is `Tamara`|
|billing_descriptor|[BillingDescriptor](#schemabillingdescriptor)|false|none|An optional description that is displayed on the customer's statement identifying a purchase.|
|shipping|object|false|none|The payment shipping details|
|» address|[Address](#schemaaddress)|false|none|The shipping address|
|» phone|[PhoneNumber](#schemaphonenumber)|false|none|The phone number associated with the shipping address|
|payment_ip|[IPAddress](#schemaipaddress)|false|none|The IP address used to make the payment. Used by Checkout.com's risk engine to check the customer's IP address – only accepts IPv4 and IPv6 addresses.|
|sender|[PaymentDetailsResponseSender](#schemapaymentdetailsresponsesender)|false|none|Information about the sender of the payment's funds|
|amount_allocations|[AmountAllocations](#schemaamountallocations)|false|none|The sub-entities that the payment is being processed on behalf of|
|recipient|[PaymentRecipient](#schemapaymentrecipient)|false|none|Information about the recipient of the payment's funds. Relevant for [Account Funding Transactions](https://www.checkout.com/docs/payments/manage-payments/account-funding-transactions) and VISA or Mastercard [domestic UK transactions processed by financial institutions](https://www.checkout.com/docs/payments/regulation-support/requirements-for-financial-institutions).|
|processing|[ProcessingData](#schemaprocessingdata)|false|none|Returns information related to the processing of the payment|
|items|[Items](#schemaitems)|false|none|The order's line items.|
|metadata|object|false|none|A set of key-value pairs that you can attach to a payment. It can be useful for storing additional information in a structured format|
|eci|string|false|none|The final Electronic Commerce Indicator (ECI) security level used to authorize the payment.
Applicable for 3D Secure and network token payments|
|scheme_id|string|false|none|The scheme transaction identifier|
|actions|[[PaymentActionSummary](#schemapaymentactionsummary)]|false|none|A summary of the payment's actions,
returned when a session ID is used to get the payment details|
|retry|[RetryGetResponse](#schemaretrygetresponse)|false|none|Configuration relating to asynchronous retries|
|cko_network_token_available|boolean|false|none|The flag indicating if Checkout Network Token was available for the payment|
|instruction|object|false|none|Details about the payment instruction.|
|» purpose|string|false|none|The purpose of the payment.|
|_links|object|true|none|The links related to the payment|
|» self|[Link](#schemalink)|true|none|The URI of the payment|
|» actions|[Link](#schemalink)|true|none|A link to the payment's associated actions|
|» authorize|[Link](#schemalink)|false|none|A link to increment the authorization, where applicable|
|» void|[Link](#schemalink)|false|none|A link to void the payment, where applicable|
|» capture|[Link](#schemalink)|false|none|A link to capture the payment, where applicable|
|» refund|[Link](#schemalink)|false|none|A link to refund the payment, where applicable|
#### Enumerated Values
|Property|Value|
|---|---|
|payment_type|Regular|
|payment_type|Recurring|
|payment_type|MOTO|
|payment_type|Installment|
|payment_type|PayLater|
|payment_type|Unscheduled|
|status|Pending|
|status|Authorized|
|status|Card Verified|
|status|Voided|
|status|Partially Captured|
|status|Captured|
|status|Partially Refunded|
|status|Refunded|
|status|Declined|
|status|Canceled|
|status|Expired|
|status|Paid|
|status|Retry Scheduled|
PaymentDetailsResponseSender
```json
{
"type": "individual",
"reference": "8285282045818",
"first_name": "John",
"last_name": "Jones",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
}
```
Information about the sender of the payment's funds
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of sender|
|reference|string|false|none|The sender's reference for the payout|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[01_PaymentResponseIndividualSender](#schema01_paymentresponseindividualsender)|false|none|Store a previously tokenized instrument|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[02_PaymentResponseCorporateSender](#schema02_paymentresponsecorporatesender)|false|none|Store a previously tokenized instrument|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[03_PaymentResponseInstrumentSender](#schema03_paymentresponseinstrumentsender)|false|none|Store a previously tokenized instrument|
#### Enumerated Values
|Property|Value|
|---|---|
|type|individual|
|type|corporate|
|type|instrument|
PaymentDetailsResponseSource
```json
{
"type": "card",
"id": "src_nwd3m4in3hkuddfpjsaevunhdy",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"expiry_month": 6,
"expiry_year": 2025,
"name": "Bruce Wayne",
"scheme": "VISA",
"scheme_local": "Cartes_Bancaires",
"local_schemes": [
"cartes_bancaires",
"visa"
],
"last4": "9996",
"fingerprint": "F639CAB2745BEE4140BF86DF6B6D6",
"bin": "45434748",
"card_type": "CREDIT",
"card_category": "CONSUMER",
"card_wallet_type": "applepay",
"issuer": "GOTHAM STATE BANK",
"issuer_country": "US",
"product_id": "F",
"product_type": "CLASSIC",
"avs_check": "S",
"cvv_check": "Y",
"payment_account_reference": "EUNIX9AX7THOOJIEJ2AP6OOFAHGH4",
"encrypted_card_number": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz...",
"account_update_status": "card_updated",
"account_update_failure_code": "VAU009",
"account_holder": {}
}
```
source
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentGetResponseCardSource](#schemapaymentgetresponsecardsource)|false|none|A card payment source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentGetResponseAlmaSource](#schemapaymentgetresponsealmasource)|false|none|Alma Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentGetResponseBancontactSource](#schemapaymentgetresponsebancontactsource)|false|none|Bancontact Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentGetResponseBlikSource](#schemapaymentgetresponsebliksource)|false|none|Blik Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentGetResponseCurrencyAccountSource](#schemapaymentgetresponsecurrencyaccountsource)|false|none|Currency Account Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentGetResponseEPSSource](#schemapaymentgetresponseepssource)|false|none|EPS Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentGetResponseIdealSource](#schemapaymentgetresponseidealsource)|false|none|Ideal Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentGetResponseKlarnaSource](#schemapaymentgetresponseklarnasource)|false|none|Klarna Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentGetResponseKnetSource](#schemapaymentgetresponseknetsource)|false|none|KNet Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentGetResponseMultibancoSource](#schemapaymentgetresponsemultibancosource)|false|none|Multibanco Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentGetResponseP24Source](#schemapaymentgetresponsep24source)|false|none|P24 Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentGetResponsePayPalSource](#schemapaymentgetresponsepaypalsource)|false|none|PayPal Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentGetResponseQPaySource](#schemapaymentgetresponseqpaysource)|false|none|QPay Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentGetResponseSEPAV4Source](#schemapaymentgetresponsesepav4source)|false|none|SEPA DD Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentGetResponseBacsSource](#schemapaymentgetresponsebacssource)|false|none|Bacs Direct Debit Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentGetResponseSwishSource](#schemapaymentgetresponseswishsource)|false|none|Swish Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentGetResponseSequraSource](#schemapaymentgetresponsesequrasource)|false|none|Sequra Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentGetResponseTamaraSource](#schemapaymentgetresponsetamarasource)|false|none|Tamara Source|
PaymentDetailsResponseSourceType
```json
"card"
```
Ordered list of payment details response source types
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|Ordered list of payment details response source types|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|card|
|*anonymous*|alma|
|*anonymous*|bacs|
|*anonymous*|bancontact|
|*anonymous*|blik|
|*anonymous*|currency_account|
|*anonymous*|eps|
|*anonymous*|ideal|
|*anonymous*|klarna|
|*anonymous*|knet|
|*anonymous*|multibanco|
|*anonymous*|p24|
|*anonymous*|paypal|
|*anonymous*|qpay|
|*anonymous*|sepa|
|*anonymous*|sequra|
|*anonymous*|swish|
|*anonymous*|tamara|
PaymentId
```json
"pay_mbabizu24mvu3mela5njyhpit4"
```
The payment identifier.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The payment identifier.|
PaymentInstruction
```json
{
"scheme": "local",
"remittance": {
"reference": "string"
}
}
```
Details about the instruction for payouts to bank accounts.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|scheme|string|false|none|An option to restrict the payment scheme type, when not available payouts will fail.|
|remittance|object|false|none|none|
|» reference|string|false|none|A merchant-provided reference for the remittance payment. This value is used for payment reconciliation and is reviewed by our banking partner.|
#### Enumerated Values
|Property|Value|
|---|---|
|scheme|local|
|scheme|instant|
PaymentInstructionResponse
```json
{
"value_date": "2020-06-12T22:27:42.512594Z"
}
```
Instruction details for payouts to bank accounts.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|value_date|string(date-time)|false|none|The date (in ISO 8601 format) and time at which the recipient's account will be credited.|
PaymentPaged
```json
{
"limit": 10,
"skip": 10,
"total_count": 1,
"data": [
{
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"requested_on": "2019-08-24T14:15:22Z",
"source": {
"type": "card",
"id": "src_nwd3m4in3hkuddfpjsaevunhdy",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"expiry_month": 6,
"expiry_year": 2025,
"name": "Bruce Wayne",
"scheme": "VISA",
"scheme_local": "Cartes_Bancaires",
"local_schemes": [
"cartes_bancaires",
"visa"
],
"last4": "9996",
"fingerprint": "F639CAB2745BEE4140BF86DF6B6D6",
"bin": "45434748",
"card_type": "CREDIT",
"card_category": "CONSUMER",
"card_wallet_type": "applepay",
"issuer": "GOTHAM STATE BANK",
"issuer_country": "US",
"product_id": "F",
"product_type": "CLASSIC",
"avs_check": "S",
"cvv_check": "Y",
"payment_account_reference": "EUNIX9AX7THOOJIEJ2AP6OOFAHGH4",
"encrypted_card_number": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz...",
"account_update_status": "card_updated",
"account_update_failure_code": "VAU009",
"account_holder": {}
},
"destination": {
"type": "bank_account",
"id": "string"
},
"amount": 6540,
"amount_requested": 6540,
"currency": "USD",
"payment_type": "Recurring",
"payment_plan": {
"amount_variability": "Variable",
"days_between_payments": 28,
"total_number_of_payments": 5,
"current_payment_number": 3,
"expiry": "20251031",
"name": "Subscription 1234",
"start_date": "20260507",
"amount": 1234
},
"reference": "ORD-5023-4E89",
"description": "Set of 3 masks",
"approved": true,
"expires_on": "string",
"status": "Authorized",
"balances": {
"total_authorized": 6540,
"total_voided": 0,
"available_to_void": 6540,
"total_captured": 0,
"available_to_capture": 6540,
"total_refunded": 0,
"available_to_refund": 0
},
"3ds": {
"downgraded": false,
"enrolled": "Y",
"signature_valid": "Y",
"authentication_response": "Y",
"authentication_status_reason": "string",
"cryptogram": "hv8mUFzPzRZoCAAAAAEQBDMAAAA=",
"xid": "MDAwMDAwMDAwMDAwMDAwMzIyNzY=",
"eci": "string",
"version": "2.1.0",
"exemption": "low_value",
"exemption_applied": "string",
"challenged": true,
"upgrade_reason": "sca_retry",
"trusted_listing": {
"status": "Y",
"source": "01"
}
},
"authentication": {
"experience": "3ds"
},
"risk": {
"flagged": true,
"score": 22
},
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "brucewayne@gmail.com",
"name": "Bruce Wayne",
"summary": {
"registration_date": "2023-05-01",
"first_transaction_date": "2023-07-01",
"last_payment_date": "2023-08-01",
"total_order_count": 15,
"last_payment_amount": 500,
"is_premium_customer": true,
"is_returning_customer": true,
"lifetime_value": 500
}
},
"billing_descriptor": {
"name": "SUPERHEROES.COM",
"city": "GOTHAM",
"reference": "string",
"local_descriptors": [
{
"name": "漢字",
"character_set": "kanji"
}
]
},
"shipping": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"payment_ip": "90.197.169.245",
"sender": {
"type": "individual",
"reference": "8285282045818",
"first_name": "John",
"last_name": "Jones",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"amount_allocations": [
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4",
"amount": 1000,
"reference": "ORD-5023-4E89",
"commission": {
"amount": 1000,
"percentage": 1.125
}
}
],
"recipient": {
"dob": "1985-05-15",
"account_number": "5555554444",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"zip": "SW1A",
"first_name": "John",
"last_name": "Jones"
},
"processing": {
"preferred_scheme": "cartes_bancaires",
"app_id": "com.iap.linker_portal",
"airline_data": [
{
"ticket": {
"number": "045-21351455613",
"issue_date": "2023-05-20",
"issuing_carrier_code": "AI",
"travel_package_indicator": "B",
"travel_agency_name": "World Tours",
"travel_agency_code": "01"
},
"passenger": [
{
"first_name": "John",
"last_name": "White",
"date_of_birth": "1990-05-26",
"address": {
"country": "US"
}
}
],
"flight_leg_details": [
{
"flight_number": "101",
"carrier_code": "BA",
"class_of_travelling": "J",
"departure_airport": "LHR",
"departure_date": "2023-06-19",
"departure_time": "15:30",
"arrival_airport": "LAX",
"stop_over_code": "x",
"fare_basis_code": "SPRSVR"
}
]
}
],
"accommodation_data": [
{
"name": "The Sea View Hotel",
"booking_reference": "HOTEL123",
"check_in_date": "2023-06-20",
"check_out_date": "2023-06-23",
"address": {
"address_line1": "123 Beach Road",
"zip": "10001"
},
"state": "FL",
"country": "USA",
"city": "Los Angeles",
"number_of_rooms": 2,
"guests": [
{
"first_name": "Jane",
"last_name": "Doe",
"date_of_birth": "1985-07-14"
}
],
"room": [
{
"rate": "70",
"number_of_nights_at_room_rate": "3"
}
],
"property_phone": [
{
"country_code": "44",
"number": "7123456789"
}
],
"customer_service_phone": [
{
"country_code": "44",
"number": "7123456789"
}
]
}
],
"partner_customer_id": "2102209000001106125F8",
"partner_payment_id": "440644309099499894406",
"partner_code": "999111",
"failure_code": "partner_error",
"partner_response_code": "ER_WRONG_TICKET",
"tax_amount": 1000,
"locale": "en-US",
"retrieval_reference_number": "909913440644",
"partner_order_id": "string",
"partner_status": "string",
"partner_transaction_id": "string",
"partner_error_codes": [
"string"
],
"partner_merchant_advice_code": "24",
"partner_error_message": "string",
"partner_authorization_code": "string",
"partner_authorization_response_code": "string",
"partner_fraud_status": "string",
"pan_type_processed": "fpan",
"fallback_source_used": false,
"custom_payment_method_ids": [
"string"
],
"aft": true,
"merchant_category_code": "5311",
"scheme_merchant_id": "123456",
"scheme": "ACCEL",
"scheme_transaction_link_id": "string"
},
"items": [
{
"type": "digital",
"sub_type": "stablecoin",
"name": "Necklace",
"quantity": 2,
"unit_price": 50,
"reference": "858818ac",
"commodity_code": "DEF123",
"unit_of_measure": "metres",
"total_amount": 29000,
"tax_rate": 2000,
"tax_amount": 1000,
"tax_exempt": true,
"discount_amount": 1000,
"wxpay_goods_id": "1001",
"url": "string",
"image_url": "string",
"service_ends_on": "2025-01-01",
"purchase_country": "GB",
"foreign_retailer_amount": 200
}
],
"metadata": {
"coupon_code": "NY2018",
"partner_id": 123989
},
"eci": "06",
"scheme_id": "488341541494658",
"actions": [
{
"id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
"type": "Authorization",
"response_code": "10000",
"response_summary": "Approved"
}
],
"retry": {
"enabled": true,
"attempts_made": 0,
"max_attempts": 6,
"ends_on": "2019-08-24T14:15:22Z",
"next_attempt_on": "2019-08-24T14:15:22Z"
},
"cko_network_token_available": false,
"instruction": {
"purpose": "financial_services"
},
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
},
"actions": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/actions"
},
"authorize": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/authorizations"
},
"refund": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/refund"
}
}
}
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|limit|integer|false|none|The numbers of results to retrieve|
|skip|integer|false|none|The number of results to skip|
|total_count|integer|false|none|The total number of results matching the payment reference. This number is unaffected by the values of the `skip` and `limit` parameters|
|data|[[PaymentDetails](#schemapaymentdetails)]|false|none|The list of payments|
PaymentPlan
```json
{
"days_between_payments": 28,
"total_number_of_payments": 5,
"current_payment_number": 3,
"expiry": "20251031",
"name": "Subscription 1234",
"start_date": "20260507",
"amount": 1234
}
```
PaymentPlan
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|days_between_payments|integer|false|none|Indicates the minimum number of days between payments|
|total_number_of_payments|integer|false|none|Indicates the agreed total number of payments|
|current_payment_number|integer|false|none|The number of the current installment payment|
|expiry|string|false|none|The date after which no further payments will be performed in the format YYYYMMDD|
|name|string|false|none|The name of the payment plan.
Required when `source.type` is `blik`. For Blik merchant-initiated requests using an external `partner_agreement_id`, this value is used as the Blik Alias Label.|
|start_date|string|false|none|The date on which the first payment will be taken, in `YYYYMMDD` format.
Required when `source.type` is `blik` and the recurring agreement is created without an initial payment (`amount` set to `0`).|
|amount|integer|false|none|The amount to charge for each payment in the plan, in the [minor currency unit](https://www.checkout.com/docs/resources/calculating-the-amount).
Required when `source.type` is `blik`, `payment_plan.amount_variability` is `Fixed`, and the recurring agreement is created without an initial payment (`amount` set to `0`).|
PaymentRecipient
```json
{
"dob": "1985-05-15",
"account_number": "5555554444",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"zip": "SW1A",
"first_name": "John",
"last_name": "Jones"
}
```
Information about the recipient of the payment's funds. Relevant for [Account Funding Transactions](https://www.checkout.com/docs/payments/manage-payments/account-funding-transactions) and VISA or Mastercard [domestic UK transactions processed by financial institutions](https://www.checkout.com/docs/payments/regulation-support/requirements-for-financial-institutions).
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|dob|string(date)|false|none|The recipient's date of birth (yyyy-mm-dd)|
|account_number|string|false|none|Any identifier like part of the PAN (first six digits and last four digits), an IBAN, an internal account number, or a phone number related to the primary recipient's account|
|address|[Address](#schemaaddress)|false|none|The recipient's address|
|zip|string|false|none|Replaced by `address.zip`
The first part of the UK postcode (e.g., SW1A 1AA would be SW1A).|
|first_name|string|false|none|The recipient's first name|
|last_name|string|false|none|The recipient's last name|
PaymentRequest
```json
{
"source": {
"number": "4543474002249996",
"expiry_month": 6,
"expiry_year": 2030,
"name": "Bruce Wayne",
"cvv": "956",
"stored": true,
"store_for_future_use": false,
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"account_holder": {},
"allow_update": false,
"type": "card"
},
"fallback_source": {
"number": "4543474002249996",
"expiry_month": 6,
"expiry_year": 2030,
"name": "Bruce Wayne",
"cvv": "956",
"stored": true,
"store_for_future_use": false,
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"account_holder": {},
"allow_update": false,
"type": "card"
},
"amount": 6540,
"currency": "USD",
"payment_type": "Recurring",
"payment_plan": {
"amount_variability": "Variable",
"days_between_payments": 28,
"total_number_of_payments": 5,
"current_payment_number": 3,
"expiry": "20251031",
"name": "Subscription 1234",
"start_date": "20260507",
"amount": 1234
},
"merchant_initiated": true,
"reference": "ORD-5023-4E89",
"description": "Set of 3 masks",
"authorization_type": "Estimated",
"partial_authorization": {
"enabled": true
},
"capture": true,
"capture_on": "2019-08-24T14:15:22Z",
"expire_on": "2019-08-24T14:15:22Z",
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "brucewayne@gmail.com",
"name": "Bruce Wayne",
"tax_number": "1350693505279",
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"summary": {
"registration_date": "2023-05-01",
"first_transaction_date": "2023-07-01",
"last_payment_date": "2023-08-01",
"total_order_count": 15,
"last_payment_amount": 500,
"is_premium_customer": true,
"is_returning_customer": true,
"lifetime_value": 500
}
},
"billing_descriptor": {
"name": "SUPERHEROES.COM",
"city": "GOTHAM",
"reference": "string",
"local_descriptors": [
{
"name": "漢字",
"character_set": "kanji"
}
]
},
"shipping": {
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@example.com",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"from_address_zip": "123456",
"timeframe": "SameDay",
"method": "BillingAddress",
"delay": 5
},
"3ds": {
"enabled": "false",
"challenge_indicator": "no_preference",
"allow_upgrade": true,
"exemption": "low_value"
},
"authentication": {
"preferred_experiences": [
"google_spa",
"3ds"
]
},
"processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
"previous_payment_id": "pay_fun26akvvjjerahhctaq2uzhu4",
"risk": {
"enabled": false,
"device_session_id": "dsid_ipsmclhxwq72phhr32iwfvrflm",
"device": {
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
"network": {
"ipv4": "63.33.82.13",
"ipv6": "2001:0000:130F:0000:0000:09C0:876A:130B",
"tor": false,
"vpn": false,
"proxy": false
},
"provider": {
"id": "1728646225211.AfUgxG",
"name": "List [ \"merchant\", \"fingerprintjs\", \"riskify\" ]"
},
"timestamp": "2024-02-06T15:00:00.000Z",
"timezone": "60",
"virtual_machine": false,
"incognito": false,
"jailbroken": false,
"rooted": false,
"java_enabled": false,
"javascript_enabled": false,
"language": "FR-fr",
"color_depth": "16",
"screen_height": "1080",
"screen_width": "1920",
"user_agent_client_hint": "string",
"iframe_payment_allowed": true,
"accept_header": "string"
}
},
"success_url": "https://example.com/payments/success",
"failure_url": "https://example.com/payments/fail",
"payment_ip": "90.197.169.245",
"sender": {
"type": "individual",
"reference": "string",
"first_name": "John",
"last_name": "Jones",
"date_of_birth": "1985-05-15",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"identification": {
"type": "driving_licence",
"number": "1234",
"issuing_country": "GT"
}
},
"recipient": {
"dob": "1985-05-15",
"account_number": "5555554444",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"zip": "SW1A",
"first_name": "John",
"last_name": "Jones"
},
"amount_allocations": [
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4",
"amount": 1000,
"reference": "ORD-5023-4E89",
"commission": {
"amount": 1000,
"percentage": 1.125
}
}
],
"processing": {
"order_id": "123456789",
"tax_amount": 3000,
"surcharge_amount": 200,
"discount_amount": 0,
"duty_amount": 0,
"shipping_amount": 300,
"shipping_tax_amount": 100,
"aft": true,
"preferred_scheme": "mastercard",
"merchant_initiated_reason": "Delayed_charge",
"campaign_id": 0,
"product_type": "QR Code",
"open_id": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
"original_order_amount": 10,
"receipt_id": "10",
"terminal_type": "WAP",
"os_type": "ANDROID",
"invoice_id": "string",
"locale": "en-US",
"airline_data": [
{
"ticket": {
"number": "045-21351455613",
"issue_date": "2023-05-20",
"issuing_carrier_code": "AI",
"travel_package_indicator": "B",
"travel_agency_name": "World Tours",
"travel_agency_code": "01"
},
"passenger": [
{
"first_name": "John",
"last_name": "White",
"date_of_birth": "1990-05-26",
"address": {
"country": "US"
}
}
],
"flight_leg_details": [
{
"flight_number": "101",
"carrier_code": "BA",
"class_of_travelling": "J",
"departure_airport": "LHR",
"departure_date": "2023-06-19",
"departure_time": "15:30",
"arrival_airport": "LAX",
"stop_over_code": "x",
"fare_basis_code": "SPRSVR"
}
]
}
],
"accommodation_data": [
{
"name": "The Sea View Hotel",
"booking_reference": "HOTEL123",
"check_in_date": "2023-06-20",
"check_out_date": "2023-06-23",
"address": {
"address_line1": "123 Beach Road",
"zip": "10001"
},
"state": "FL",
"country": "USA",
"city": "Los Angeles",
"number_of_rooms": 2,
"guests": [
{
"first_name": "Jane",
"last_name": "Doe",
"date_of_birth": "1985-07-14"
}
],
"room": [
{
"rate": "70",
"number_of_nights_at_room_rate": "3"
}
],
"property_phone": [
{
"country_code": "44",
"number": "7123456789"
}
],
"customer_service_phone": [
{
"country_code": "44",
"number": "7123456789"
}
]
}
],
"merchant_callback_url": "string",
"line_of_business": "Flights",
"pan_preference": "fpan",
"service_type": "standard",
"partner_code": "902111",
"provision_network_token": true,
"card_type": "credit",
"affiliate_id": "string",
"affiliate_url": "www.mycrypto.com",
"purchase_country": "GB",
"foreign_retailer_amount": 200,
"reconciliation_id": "4123495123",
"aggregator": {
"sub_merchant_id": "9cf70789ba90123",
"aggregator_id_visa": "10012345",
"aggregator_id_mc": "00000123456"
},
"scheme_transaction_link_id": "string"
},
"items": [
{
"type": "digital",
"sub_type": "stablecoin",
"name": "Necklace",
"quantity": 2,
"unit_price": 50,
"reference": "858818ac",
"commodity_code": "DEF123",
"unit_of_measure": "metres",
"total_amount": 29000,
"tax_rate": 2000,
"tax_amount": 1000,
"tax_exempt": true,
"discount_amount": 1000,
"wxpay_goods_id": "1001",
"url": "string",
"image_url": "string",
"service_ends_on": "2025-01-01",
"purchase_country": "GB",
"foreign_retailer_amount": 200
}
],
"retry": {
"enabled": true,
"dunning": {
"enabled": true,
"max_attempts": 6,
"end_after_days": 30
},
"downtime": {
"enabled": true
}
},
"subscription": {
"id": "string"
},
"metadata": {
"coupon_code": "NY2018"
},
"segment": {
"brand": "Acme Corporation",
"business_category": "Inward Payments",
"market": "UK"
},
"instruction": {
"purpose": "donations"
},
"routing": {
"attempts": [
{
"scheme": "accel"
}
]
}
}
```
Payment
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|source|[PaymentRequestSource](#schemapaymentrequestsource)|false|none|The source of the payment|
|fallback_source|[PaymentRequestFallbackSource](#schemapaymentrequestfallbacksource)|false|none|A card payment source|
|amount|integer(int64)|false|none|The payment amount. To perform a card verification, do not provide the amount or provide a value of `0`.
The amount must be provided in the minor currency unit.|
|currency|string|true|none|The three-letter ISO currency code|
|payment_type|string|false|none|The type of payment.
This field is required for card payments in which the cardholder is not present. For example, mail orders, telephone orders, or merchant-initiated transactions (MITs) in a [recurring payment](https://www.checkout.com/docs/payments/accept-payments/pay-with-stored-card-details/recurring-payments-with-stored-card-details) series.
For MITs, this field must not be set to `Regular`.|
|payment_plan|object|false|none|The details of a recurring subscription or installment|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PlanRecurring](#schemaplanrecurring)|false|none|The information to process a recurring payment request. To be used when the `payment_type` is `recurring`.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PlanInstallment](#schemaplaninstallment)|false|none|The information to process a installment payment request. To be used when the `payment_type` is `installment`.|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|merchant_initiated|boolean|false|none|Whether the payment is a merchant-initiated transaction (MIT).
Must be set to `true` for all MITs.
If you set this field to `true`, the value for `payment_type` must not be set to `Regular`.|
|reference|string|false|none|A reference you can use to identify the payment. For example, an order number.
- For Amex payments, the reference has a 30-character limit.
- For Benefit payments, the reference must be a unique alphanumeric value.
- For Blik payments, the reference has a 35-character limit.
- For Discover payments, the reference has a 60-character limit.
- For iDEAL payments, the reference is required and must be an alphanumeric value with a 35-character limit.
- For OmanNet payments, the reference must be a unique alphanumeric value between 12 and 30 characters long, generated for every payment action.
- For seQura payments, the reference is required and must be a unique value.
- For TWINT payments, the reference has a 50 character limit.|
|description|string|false|none|A description of the payment.|
|authorization_type|string|false|none|The authorization type|
|partial_authorization|[PartialAuthorization](#schemapartialauthorization)|false|none|Required information to allow partial authorization|
|capture|boolean|false|none|Whether to capture the payment (if applicable)|
|capture_on|[Timestamp](#schematimestamp)|false|none|A timestamp (ISO 8601 code) that determines when the payment should be captured.
Providing this field will automatically set `capture` to true|
|expire_on|[Timestamp](#schematimestamp)|false|none|The date and time when the Multibanco payment expires in UTC. Format – ISO 8601
Example– `2025-01-31T10:20:30.456`|
|customer|[CustomerRequest](#schemacustomerrequest)|false|none|The customer's details. Required if `source.type` is `tamara`|
|billing_descriptor|[BillingDescriptor](#schemabillingdescriptor)|false|none|An optional description that is displayed on the customer's statement identifying a purchase.|
|shipping|[Shipping](#schemashipping)|false|none|The shipping details.|
|3ds|object|false|none|Information required for 3D Secure authentication payments.|
anyOf - discriminator: 3dsRequest.enabled
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[3dsRequest](#schema3dsrequest)|false|none|Required information to process a 3DS authentication with the payment request|
or
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[3dsRequestStandalone](#schema3dsrequeststandalone)|false|none|Required information to process a payment that has been 3DS authenticated using our Standalone authentication|
or
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[3dsRequestThirdParty](#schema3dsrequestthirdparty)|false|none|Required information to process a payment that has been 3DS authenticated using a Third Party provider|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|authentication|[PaymentAuthenticationRequest](#schemapaymentauthenticationrequest)|false|none|Provides information required to authenticate payments.|
|processing_channel_id|string|false|none|The processing channel to be used for the payment|
|previous_payment_id|string|false|none|An identifier that links the payment to an existing series of payments.
You must only pass this field if the transaction is a merchant-initiated transaction (MIT) in a recurring payment series.
To link the payment, pass one of the following as its value:
- a payment identifier (for example, `pay_cr4hxwizzp6k7biycuk2ibltnm`) from the recurring series, or
- the scheme transaction ID|
|risk|[RiskRequest](#schemariskrequest)|false|none|Configures the risk assessment performed during the processing of the payment|
|success_url|string(uri)|false|none|For redirect payment methods, this overrides the default success redirect URL configured on your account|
|failure_url|string(uri)|false|none|For redirect payment methods, this overrides the default failure redirect URL configured on your account|
|payment_ip|[IPAddress](#schemaipaddress)|false|none|Use the `risk.device.network.ipv4` or `risk.device.network.ipv6` field instead.
The IP address used to make the payment. Used by Checkout.com's risk engine to check the customer's IP address – only accepts IPv4 and IPv6 addresses. Required if `source.type` is `sequra`|
|sender|[PaymentRequestSender](#schemapaymentrequestsender)|false|none|Information about the sender of the payment's funds|
|recipient|[PaymentRecipient](#schemapaymentrecipient)|false|none|Information about the recipient of the payment's funds. Relevant for [Account Funding Transactions](https://www.checkout.com/docs/payments/manage-payments/account-funding-transactions) and VISA or Mastercard [domestic UK transactions processed by financial institutions](https://www.checkout.com/docs/payments/regulation-support/requirements-for-financial-institutions).|
|amount_allocations|[AmountAllocations](#schemaamountallocations)|false|none|The sub-entities that the payment is being processed on behalf of|
|processing|[PaymentRequestProcessing](#schemapaymentrequestprocessing)|false|none|Use the processing object to influence or override the data sent during card processing|
|items|[Items](#schemaitems)|false|none|The order's line items.|
|retry|[RetryRequest](#schemaretryrequest)|false|none|Configuration of asynchronous retries.
For more information about asynchronous retries and supported response codes, see [Configure scheduled retries](https://www.checkout.com/docs/payments/manage-payments/configure-scheduled-retries).|
|subscription|[Subscription](#schemasubscription)|false|none|The details of the subscription.|
|metadata|object|false|none|Stores additional information about a transaction with custom fields and up to five user-defined fields, which you can use for reporting purposes. The object supports `string`, `number`, and `boolean` fields, but not arrays or objects.
You can provide up to 20 metadata fields per API call, but the value of each field must not exceed 255 characters in length.
You can also reference [`metadata` properties](https://www.checkout.com/docs/business-operations/prevent-fraud/understand-fraud-detection#Metadata) in your custom rules for Fraud Detection. For example, `$coupon_code = '1234’`.|
|segment|[Segment](#schemasegment)|false|none|The dimension details about business segment for payment request. At least one dimension required.|
|instruction|object|false|none|Details about the payment instruction.|
|» purpose|[Purpose](#schemapurpose)|false|none|The purpose of the payment.
This field might be required for AFT transactions depending on the card's `issuer_country`. To view a card's `issuer_country`, [retrieve the card's metadata](https://api-reference.checkout.com/#operation/requestCardMetadata!c=200&path=issuer_country&t=response).
See the [AFT documentation page](https://www.checkout.com/docs/payments/manage-payments/perform-an-account-funding-transaction) for more details.|
|routing|object|false|none|Controls processor attempts at the payment level.|
|» attempts|[[Attempt](#schemaattempt)]|false|none|Specifies the processing rules for the payment. Each object in the array should be a unique expression of rules that determine the routing attempts to process the payment with. For example:
```
"attempts": [
{
"scheme": "mastercard"
},
{
"scheme": "visa"
}
]
```|
#### Enumerated Values
|Property|Value|
|---|---|
|payment_type|Regular|
|payment_type|Recurring|
|payment_type|MOTO|
|payment_type|Installment|
|payment_type|PayLater|
|payment_type|Unscheduled|
|authorization_type|Final|
|authorization_type|Estimated|
PaymentRequestDestination
```json
{
"type": "id",
"id": "src_wmlfc3zyhqzehihu7giusaaawu"
}
```
The destination of the payout.
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestIdDestination](#schemapaymentrequestiddestination)|false|none|An existing payment instrument.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentBankAccountDestination](#schemapaymentbankaccountdestination)|false|none|An existing payment instrument.|
PaymentRequestProcessing
```json
{
"order_id": "123456789",
"tax_amount": 3000,
"surcharge_amount": 200,
"discount_amount": 0,
"duty_amount": 0,
"shipping_amount": 300,
"shipping_tax_amount": 100,
"aft": true,
"preferred_scheme": "mastercard",
"merchant_initiated_reason": "Delayed_charge",
"campaign_id": 0,
"product_type": "QR Code",
"open_id": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
"original_order_amount": 10,
"receipt_id": "10",
"terminal_type": "WAP",
"os_type": "ANDROID",
"invoice_id": "string",
"locale": "en-US",
"airline_data": [
{
"ticket": {
"number": "045-21351455613",
"issue_date": "2023-05-20",
"issuing_carrier_code": "AI",
"travel_package_indicator": "B",
"travel_agency_name": "World Tours",
"travel_agency_code": "01"
},
"passenger": [
{
"first_name": "John",
"last_name": "White",
"date_of_birth": "1990-05-26",
"address": {
"country": "US"
}
}
],
"flight_leg_details": [
{
"flight_number": "101",
"carrier_code": "BA",
"class_of_travelling": "J",
"departure_airport": "LHR",
"departure_date": "2023-06-19",
"departure_time": "15:30",
"arrival_airport": "LAX",
"stop_over_code": "x",
"fare_basis_code": "SPRSVR"
}
]
}
],
"accommodation_data": [
{
"name": "The Sea View Hotel",
"booking_reference": "HOTEL123",
"check_in_date": "2023-06-20",
"check_out_date": "2023-06-23",
"address": {
"address_line1": "123 Beach Road",
"zip": "10001"
},
"state": "FL",
"country": "USA",
"city": "Los Angeles",
"number_of_rooms": 2,
"guests": [
{
"first_name": "Jane",
"last_name": "Doe",
"date_of_birth": "1985-07-14"
}
],
"room": [
{
"rate": "70",
"number_of_nights_at_room_rate": "3"
}
],
"property_phone": [
{
"country_code": "44",
"number": "7123456789"
}
],
"customer_service_phone": [
{
"country_code": "44",
"number": "7123456789"
}
]
}
],
"merchant_callback_url": "string",
"line_of_business": "Flights",
"pan_preference": "fpan",
"service_type": "standard",
"partner_code": "902111",
"provision_network_token": true,
"card_type": "credit",
"affiliate_id": "string",
"affiliate_url": "www.mycrypto.com",
"purchase_country": "GB",
"foreign_retailer_amount": 200,
"reconciliation_id": "4123495123",
"aggregator": {
"sub_merchant_id": "9cf70789ba90123",
"aggregator_id_visa": "10012345",
"aggregator_id_mc": "00000123456"
},
"scheme_transaction_link_id": "string"
}
```
Use the processing object to influence or override the data sent during card processing
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|order_id|string|false|none|The number provided by the cardholder. Purchase order or invoice number may be used.|
|tax_amount|number|false|none|The total amount of sales tax on the total purchase amount.|
|surcharge_amount|integer|false|none|Surcharge amount applied to the transaction in minor units by the merchant.|
|discount_amount|number|false|none|The discount amount applied to the transaction by the merchant.|
|duty_amount|number|false|none|The total charges for any import/export duty included in the transaction.|
|shipping_amount|number|false|none|The total freight or shipping and handling charges for the transaction.|
|shipping_tax_amount|number|false|none|The tax amount of the freight or shipping and handling charges for the transaction.|
|aft|boolean|false|none|Indicates if the payment is an [Account Funding Transaction](https://www.checkout.com/docs/payments/manage-payments/account-funding-transactions)|
|preferred_scheme|string|false|none|The preferred scheme for co-badged card payment processing. If performing 3DS via a third party, set this value to the scheme that processed 3DS. This field does not support PINless debit schemes in the US (STAR, PULSE, NYCE, ACCEL, SHAZAM).|
|merchant_initiated_reason|string|false|none|Indicates the reason for a merchant-initiated payment request.|
|campaign_id|integer|false|none|Unique number of the campaign this payment will be running in. Only required for Afterpay campaign invoices.|
|product_type|string|false|none|Product type of the payment. Used when `source.type` is
- `wechatpay` - required. Enum:
- `QR Code`
- `In-App`
- `Official Account`
- `Mini Program`
- `tamara` - optional. You can omit this if you've chosen the default pay installment option or want the payment provider to show all the available Tamara options to the customer during redirection. Enum:
- `pay_in_full`
- `pay_by_instalment_2`
- `pay_by_instalment_3`
- `pay_by_instalment_4`
- `pay_by_instalment_6`
- `sequra` - required. Enum:
- `invoice`
- `pay_later`
- `pay_by_instalment_3`
- `pay_by_instalment`
|
|open_id|string|false|none|Value obtained from WeChat Web Authorization API before initiating Official Account or Mini Program payments. Required if `source.type` is `wechatpay` and `processing.product_type` is `Official Account` or `Mini Program`.|
|original_order_amount|number|false|none|The payment for a merchant's order may be split, and the original order price indicates the transaction amount of the entire order.|
|receipt_id|string|false|none|Merchant receipt ID.|
|terminal_type|string|false|none|The client-side terminal type, if it is a website that is opened via a PC browser or a mobile browser or mobile application.|
|os_type|string|false|none|This field is required when `terminalType` is not `WEB`.|
|invoice_id|string|false|none|Invoice ID number.|
|locale|string|false|none|The language and region of the customer in ISO 639-2 language code; value consists of language-country.|
|airline_data|[AirlineData](#schemaairlinedata)|false|none|Contains information about the airline ticket and flights booked by the customer.|
|accommodation_data|[AccommodationData](#schemaaccommodationdata)|false|none|Contains information about the accommodation booked by the customer.|
|merchant_callback_url|string|false|none|A URL which you can use to notify the customer that the order has been created.|
|line_of_business|string|false|none|Beta
The line of business that the payment is associated with.|
|pan_preference|string|false|none|Specifies the preferred type of Primary Account Number (PAN) for the payment.
Note: This only works for source.type cards, instruments and tokens.
* **DPAN**: Indicates a preference for using the Checkout.com Network Token.
* **FPAN**: Indicates a preference for using the full card number.|
|service_type|string|false|none|Specifies which ACH service to use for the payment, if you set `source.type` to `ach`.|
|partner_code|string|false|none|The customer's 6-digit Blik code.
Required when `source.type` is `blik` and `merchant_initiated` is `false` (For example, for `Regular` payments and the initial payment of a `Recurring` agreement).|
|provision_network_token|boolean|false|none|Indicates whether to provision a network token for the payment.|
|card_type|string|false|none|Specifies whether to process the payment as a credit or debit transaction, if a combo card is used.
This field is required for domestic payments in Brazil performed using a Brazilian card.|
|affiliate_id|string|false|none|The unique identifier for Visa-registered ramp providers.
Must only contain alphanumeric characters.
If you're a Visa-registered ramp provider operating with affiliates, this field is required.|
|affiliate_url|string|false|none|The affiliate URL.
If you're a Visa-registered ramp provider operating with affiliates, this field is required.|
|purchase_country|string|false|none|The two-letter ISO country code of the purchase country.
If you're a Visa-registered ramp provider operating with affiliates, this field is required.|
|foreign_retailer_amount|integer|false|none|The foreign retailer amount the merchant applied to the transaction, in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value).|
|reconciliation_id|string|false|none|The transaction identifier to track a payment request.|
|aggregator|[Aggregator](#schemaaggregator)|false|none|Information about the payment aggregator.|
|scheme_transaction_link_id|string|false|none|The scheme transaction link identifier.|
#### Enumerated Values
|Property|Value|
|---|---|
|preferred_scheme|mastercard|
|preferred_scheme|visa|
|preferred_scheme|cartes_bancaires|
|merchant_initiated_reason|Delayed_charge|
|merchant_initiated_reason|Resubmission|
|merchant_initiated_reason|No_show|
|merchant_initiated_reason|Reauthorization|
|terminal_type|APP|
|terminal_type|WAP|
|terminal_type|WEB|
|os_type|ANDROID|
|os_type|IOS|
|pan_preference|fpan|
|pan_preference|dpan|
|service_type|same_day|
|service_type|standard|
|card_type|credit|
|card_type|debit|
PaymentRequestSender
```json
{
"type": "individual",
"reference": "string",
"first_name": "John",
"last_name": "Jones",
"date_of_birth": "1985-05-15",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"identification": {
"type": "driving_licence",
"number": "1234",
"issuing_country": "GT"
}
}
```
Information about the sender of the payment's funds
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The sender type. If set to `instrument`, the sender information (name and address) will be retrieved from the payment instrument.|
|reference|string|false|none|The unique reference for the sender of the payment.|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[01_PaymentRequestIndividualSender](#schema01_paymentrequestindividualsender)|false|none|Store a previously tokenized instrument|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[02_PaymentRequestCorporateSender](#schema02_paymentrequestcorporatesender)|false|none|Store a previously tokenized instrument|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[03_PaymentRequestInstrumentSender](#schema03_paymentrequestinstrumentsender)|false|none|Store a previously tokenized instrument|
#### Enumerated Values
|Property|Value|
|---|---|
|type|individual|
|type|corporate|
|type|instrument|
PaymentRequestSource
```json
{
"number": "4543474002249996",
"expiry_month": 6,
"expiry_year": 2030,
"name": "Bruce Wayne",
"cvv": "956",
"stored": true,
"store_for_future_use": false,
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"account_holder": {},
"allow_update": false,
"type": "card"
}
```
The source of the payment
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestCardSource](#schemapaymentrequestcardsource)|false|none|A card payment source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestWeChatPaySource](#schemapaymentrequestwechatpaysource)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestVippsSource](#schemapaymentrequestvippssource)|false|none|Vipps Request Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestTwintSource](#schemapaymentrequesttwintsource)|false|none|Twint Request Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestTamaraSource](#schemapaymentrequesttamarasource)|false|none|A Tamara payment source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestStcPaySource](#schemapaymentrequeststcpaysource)|false|none|STC Pay request source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestSEPAV4Source](#schemapaymentrequestsepav4source)|false|none|SEPA DD Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestBacsSource](#schemapaymentrequestbacssource)|false|none|Bacs Direct Debit Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestSequraSource](#schemapaymentrequestsequrasource)|false|none|A seQura payment source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestQPaySource](#schemapaymentrequestqpaysource)|false|none|QPay Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestP24Source](#schemapaymentrequestp24source)|false|none|P24 Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestPlaidSource](#schemapaymentrequestplaidsource)|false|none|A Plaid source.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestPayNowSource](#schemapaymentrequestpaynowsource)|false|none|PayNow Request Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestOctopusPaySource](#schemapaymentrequestoctopuspaysource)|false|none|Octopus Pay Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestMultibancoSource](#schemapaymentrequestmultibancosource)|false|none|Multibanco Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestMobilePaySource](#schemapaymentrequestmobilepaysource)|false|none|MobilePay Request Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestMBWaySource](#schemapaymentrequestmbwaysource)|false|none|MBWay payment request source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestKnetSource](#schemapaymentrequestknetsource)|false|none|KNet Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestIdealSource](#schemapaymentrequestidealsource)|false|none|iDEAL Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestFawrySource](#schemapaymentrequestfawrysource)|false|none|Fawry Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestEpsSource](#schemapaymentrequestepssource)|false|none|EPS Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestBizumSource](#schemapaymentrequestbizumsource)|false|none|Bizum Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestBlikSource](#schemapaymentrequestbliksource)|false|none|Blik source. Use this to process Blik payments in Poland.
When `source.type` is `blik`:
- `currency` must be `PLN`.
- `amount` must not exceed `5000000` (in the [minor currency unit](https://www.checkout.com/docs/resources/calculating-the-amount)).
- `reference` is limited to 35 characters.
For customer-initiated payments (`merchant_initiated: false`), provide the customer's 6-digit Blik code in `processing.partner_code`. This applies to one-off (`payment_type: Regular`) payments and to the initial payment of a recurring agreement (`payment_type: Recurring`).
For merchant-initiated recurring payments (`merchant_initiated: true`), use either:
- `source.type: id` with a `source.id` value returned from a previous Blik recurring payment, or
- `source.type: blik` with `partner_agreement_id` set to an external Blik PAYID created with another PSP.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestBancontactSource](#schemapaymentrequestbancontactsource)|false|none|Bancontact Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestAlmaSource](#schemapaymentrequestalmasource)|false|none|Alma payment source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestAlipayCnSource](#schemapaymentrequestalipaycnsource)|false|none|Alipay CN Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestAlipayHkSource](#schemapaymentrequestalipayhksource)|false|none|Alipay HK Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestAlipayPlusSource](#schemapaymentrequestalipayplussource)|false|none|Alipay Plus Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestDanaSource](#schemapaymentrequestdanasource)|false|none|Dana Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestGcashSource](#schemapaymentrequestgcashsource)|false|none|GCash Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestKakaopaySource](#schemapaymentrequestkakaopaysource)|false|none|Kakaopay Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestTngSource](#schemapaymentrequesttngsource)|false|none|TNG Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestTruemoneySource](#schemapaymentrequesttruemoneysource)|false|none|TrueMoney Source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestAchSource](#schemapaymentrequestachsource)|false|none|An ach payment source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestTokenSource](#schemapaymentrequesttokensource)|false|none|A token payment source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestNetworkTokenSource](#schemapaymentrequestnetworktokensource)|false|none|A network token payment source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestIdSource](#schemapaymentrequestidsource)|false|none|An existing payment source. Payment Method required for ACH payment|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestCustomerSource](#schemapaymentrequestcustomersource)|false|none|A customer source|
PaymentResponse
```json
{
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
"amount": 6540,
"amount_requested": 6540,
"currency": "USD",
"approved": true,
"status": "Authorized",
"auth_code": "643381",
"response_code": "10000",
"response_summary": "Approved",
"expires_on": "string",
"3ds": {
"downgraded": true,
"enrolled": "N"
},
"risk": {
"flagged": true,
"score": 22
},
"source": {
"type": "card",
"id": "src_nwd3m4in3hkuddfpjsaevunhdy",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"expiry_month": 6,
"expiry_year": 2025,
"name": "Bruce Wayne",
"scheme": "VISA",
"scheme_local": "Cartes_Bancaires",
"local_schemes": [
"cartes_bancaires",
"visa"
],
"last4": "9996",
"fingerprint": "F639CAB2745BEE4140BF86DF6B6D6",
"bin": "45434748",
"card_type": "CREDIT",
"card_category": "CONSUMER",
"card_wallet_type": "applepay",
"issuer": "GOTHAM STATE BANK",
"issuer_country": "US",
"product_id": "F",
"product_type": "CLASSIC",
"avs_check": "S",
"cvv_check": "Y",
"payment_account_reference": "EUNIX9AX7THOOJIEJ2AP6OOFAHGH4",
"encrypted_card_number": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz...",
"account_update_status": "card_updated",
"account_update_failure_code": "VAU009",
"account_holder": {}
},
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "johnsmith@example.com",
"name": "John Smith",
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"summary": {
"registration_date": "2023-05-01",
"first_transaction_date": "2023-07-01",
"last_payment_date": "2023-08-01",
"total_order_count": 15,
"last_payment_amount": 500,
"is_premium_customer": true,
"is_returning_customer": true,
"lifetime_value": 500
}
},
"balances": {
"total_authorized": 6540,
"total_voided": 0,
"available_to_void": 6540,
"total_captured": 0,
"available_to_capture": 6540,
"total_refunded": 0,
"available_to_refund": 0
},
"processed_on": "2019-08-24T14:15:22Z",
"reference": "ORD-5023-4E89",
"subscription": {
"id": "string"
},
"processing": {
"retrieval_reference_number": "909913440644",
"acquirer_transaction_id": "440644309099499894406",
"recommendation_code": "02",
"scheme": "string",
"partner_merchant_advice_code": "string",
"partner_response_code": "string",
"partner_order_id": "5GK24544NA744002L",
"partner_payment_id": "string",
"partner_status": "string",
"partner_transaction_id": "string",
"partner_error_codes": [
"string"
],
"partner_error_message": "string",
"partner_authorization_code": "string",
"partner_authorization_response_code": "string",
"surcharge_amount": 200,
"pan_type_processed": "fpan",
"fallback_source_used": false,
"cko_network_token_available": false,
"purchase_country": "GB",
"foreign_retailer_amount": 200,
"scheme_merchant_id": "123456",
"reconciliation_id": "4123495123",
"aggregator": {
"sub_merchant_id": "9cf70789ba90123",
"aggregator_id_visa": "10012345",
"aggregator_id_mc": "00000123456"
},
"scheme_transaction_link_id": "string"
},
"eci": "06",
"scheme_id": "489341065491658",
"retry": {
"enabled": true,
"max_attempts": 6,
"ends_on": "2019-08-24T14:15:22Z",
"next_attempt_on": "2019-08-24T14:15:22Z"
},
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
},
"actions": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/actions"
},
"authorize": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/authorizations"
},
"void": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/voids"
},
"capture": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/capture"
},
"cancel": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/cancel"
}
}
}
```
Payment Response
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[PaymentId](#schemapaymentid)|true|none|The payment's unique identifier|
|action_id|[ActionId](#schemaactionid)|true|none|The unique identifier for the action performed against this payment|
|amount|integer|true|none|The payment amount.|
|amount_requested|integer|false|none|The full amount from the original authorization, if a partial authorization was requested and approved.|
|currency|string|true|none|The three-letter ISO currency code of the payment|
|approved|boolean|true|none|Whether or not the authorization or capture was successful|
|status|string|true|none|The status of the payment|
|auth_code|string|false|none|The acquirer authorization code if the payment was authorized|
|response_code|string|true|none|The Gateway response code|
|response_summary|string|false|none|The Gateway response summary|
|expires_on|string|false|none|The timestamp (ISO 8601 code) for when the authorization's validity period expires|
|3ds|[3dsEnrollmentData](#schema3dsenrollmentdata)|false|none|Provides 3D Secure enrollment status if the payment was downgraded to non-3D Secure|
|risk|object|false|none|Returns the payment's risk assessment results|
|» flagged|boolean|false|none|Whether or not the payment was flagged by a risk check|
|» score|number|false|none|The risk score calculated by our Fraud Detection engine. Absent if not enough data provided.|
|source|[PaymentResponseSource](#schemapaymentresponsesource)|false|none|The source of the payment|
|customer|[CustomerResponse](#schemacustomerresponse)|false|none|The customer associated with the payment, if provided in the request|
|balances|[PaymentResponseBalances](#schemapaymentresponsebalances)|false|none|The payment balances|
|processed_on|[ServerTimestamp](#schemaservertimestamp)|true|none|The date/time the payment was processed|
|reference|string|false|none|Your reference for the payment|
|subscription|[Subscription](#schemasubscription)|false|none|The details of the subscription.|
|processing|object|false|none|Returns information related to the processing of the payment|
|» retrieval_reference_number|string|false|none|A unique identifier for the authorization that is submitted to the card scheme during processing|
|» acquirer_transaction_id|string|false|none|A unique identifier for the transaction generated by the acquirer|
|» recommendation_code|string|false|none|A code representing the follow-up action to take with the payment, as recommended by Checkout.com|
|» scheme|string|false|none|The scheme the transaction was processed with|
|» partner_merchant_advice_code|string|false|none|The Merchant Advice Code (MAC) provided by Mastercard, which contains additional information about the transaction.
For example, the MAC can inform you if the transaction was performed using a consumer non-reloadable prepaid card or a consumer single-use virtual card.
For declined transactions, the MAC will also let you know whether the payment can be retried, and how long you should wait before doing so.|
|» partner_response_code|string|false|none|The original authorization response code sent by the scheme. This is also referred to as the raw response code.
This differs from the `recommendation_code` value, which is provided by Checkout.com and is standardized across all schemes.|
|» partner_order_id|string|false|none|Unique order identification of an Afterpay payment|
|» partner_payment_id|string|false|none|Unique identification of a payment provided by partner|
|» partner_status|string|false|none|Status of a payment provided by partner|
|» partner_transaction_id|string|false|none|Unique transaction identification provided by partner|
|» partner_error_codes|[string]|false|none|Error codes provided by partner|
|» partner_error_message|string|false|none|Error description provided by partner|
|» partner_authorization_code|string|false|none|Authorization code provided by partner|
|» partner_authorization_response_code|string|false|none|Authorization response code provided by partner|
|» surcharge_amount|integer(int64)|false|none|Surcharge amount applied to the transaction in minor units|
|» pan_type_processed|string|false|none|The type of Primary Account Number (PAN) used for the payment. DPAN indicates network token was used, FPAN indicates the full card was used|
|» fallback_source_used|boolean|false|none|Indicates whether the `fallback_source` field was used for the payment.|
|» cko_network_token_available|boolean|false|none|The flag indicating if Checkout Network Token was available for the payment|
|» purchase_country|string|false|none|The country where the purchase was made.
Format – ISO alpha-2 country code|
|» foreign_retailer_amount|integer|false|none|The foreign retailer amount the merchant applied to the transaction, in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value).|
|» scheme_merchant_id|string|false|none|The merchant identifier that was configured with the scheme and used for the payment.|
|» reconciliation_id|string|false|none|The transaction identifier to track a payment request.|
|» aggregator|[Aggregator](#schemaaggregator)|false|none|Information about the payment aggregator.|
|» scheme_transaction_link_id|string|false|none|The scheme transaction link identifier.|
|eci|string|false|none|The final Electronic Commerce Indicator (ECI) security level used to authorize the payment. Applicable for 3D Secure and network token payments|
|scheme_id|string|false|none|The scheme transaction identifier|
|retry|[RetryPostResponse](#schemaretrypostresponse)|false|none|Beta|
|_links|object|true|none|The links related to the payment|
|» self|[Link](#schemalink)|true|none|The URI of the payment|
|» actions|[Link](#schemalink)|true|none|A link to the payment's associated actions|
|» authorize|[Link](#schemalink)|false|none|A link to increment the authorization, where applicable|
|» void|[Link](#schemalink)|false|none|A link to void the payment, where applicable|
|» capture|[Link](#schemalink)|false|none|A link to capture the payment, where applicable|
|» refund|[Link](#schemalink)|false|none|A link to refund the payment, where applicable|
|» cancel|[Link](#schemalink)|false|none|A link to cancel the upcoming scheduled retry, where applicable.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Authorized|
|status|Pending|
|status|Card Verified|
|status|Declined|
|status|Retry Scheduled|
|pan_type_processed|fpan|
|pan_type_processed|dpan|
PaymentResponseBalances
```json
{
"total_authorized": 6540,
"total_voided": 0,
"available_to_void": 6540,
"total_captured": 0,
"available_to_capture": 6540,
"total_refunded": 0,
"available_to_refund": 0
}
```
The balances of the payment
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|total_authorized|integer|false|none|The total amount that has been authorized|
|total_voided|integer|false|none|The total amount that has been voided|
|available_to_void|integer|false|none|The total amount that is still available for voiding|
|total_captured|integer|false|none|The total amount that has been captured|
|available_to_capture|integer|false|none|The total amount that is still available for capture|
|total_refunded|integer|false|none|The total amount that has been refunded|
|available_to_refund|integer|false|none|The total amount that is still available for refund|
PaymentResponseDestination
```json
{
"type": "bank_account",
"id": "string"
}
```
Payment destination
### Properties
*None*
PaymentResponseSource
```json
{
"type": "card",
"id": "src_nwd3m4in3hkuddfpjsaevunhdy",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"expiry_month": 6,
"expiry_year": 2025,
"name": "Bruce Wayne",
"scheme": "VISA",
"scheme_local": "Cartes_Bancaires",
"local_schemes": [
"cartes_bancaires",
"visa"
],
"last4": "9996",
"fingerprint": "F639CAB2745BEE4140BF86DF6B6D6",
"bin": "45434748",
"card_type": "CREDIT",
"card_category": "CONSUMER",
"card_wallet_type": "applepay",
"issuer": "GOTHAM STATE BANK",
"issuer_country": "US",
"product_id": "F",
"product_type": "CLASSIC",
"avs_check": "S",
"cvv_check": "Y",
"payment_account_reference": "EUNIX9AX7THOOJIEJ2AP6OOFAHGH4",
"encrypted_card_number": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz...",
"account_update_status": "card_updated",
"account_update_failure_code": "VAU009",
"account_holder": {}
}
```
Payment source in /payments successfully created response
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentResponseCardSource](#schemapaymentresponsecardsource)|false|none|A card payment source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentDeclinedSourceResponse](#schemapaymentdeclinedsourceresponse)|false|none|A source-based APM Declined payment source response|
PaymentReversalAcceptedResponse
```json
{
"action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
"reference": "ORD-5023-4E89",
"action_type": "Refund",
"_links": {
"payment": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
}
}
}
```
Reversal response
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|action_id|[ActionId](#schemaactionid)|true|none|The unique identifier for the payment reversal action.|
|reference|string|false|none|A unique reference for the payment reversal.|
|action_type|string|false|none|The payment action performed during the reversal.
Determined by the payment's state at the time of processing:
- `Refund` if the payment has been fully or partially captured
- `Void` if the payment is in an `Authorized` state.|
|_links|object|false|read-only|Links related to the payment reversal.|
|» payment|any|true|none|The URI of the payment to be reversed.
You can use this value to check the status of the payment reversal.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»» *anonymous*|[Link](#schemalink)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»» *anonymous*|any|false|none|none|
PaymentReversalRequest
```json
{
"reference": "ORD-5023-4E89",
"metadata": {
"coupon_code": "NY2018",
"partner_id": 123989
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|false|none|An internal reference to identify the payment reversal.
For American Express payment reversals, there is a 30-character limit.|
|metadata|object|false|none|Stores additional information about the transaction with custom fields.
You can only supply primitive data types with one level of depth. Fields of type `object` or `array` are not supported.|
PayoutBillingDescriptor
```json
{
"reference": "stringstrin"
}
```
Beneficiary banks typically construct the billing descriptor using the billing descriptor reference and sender information. For direct sellers, the sender is typically your entity’s legal company name. If the ultimate sender is provided, then it is the values of the Sender object.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|true|none|The reference shown on the beneficiary's bank statement.
Format – The length varies per beneficiary bank. In general, we recommend fewer than 11 characters.
Note – References are not supported in the US.|
PayoutDetails
```json
{
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"requested_on": "2019-08-24T14:15:22Z",
"source": {
"id": "ca_y3oqhf46pyzuxjbcn2giaqnb44",
"type": "currency_account",
"currency": "GBP",
"amount": 1000
},
"destination": {
"type": "bank_account",
"id": "src_4pakgjwmv5re5m5ivqohsqpxnm"
},
"amount": 1000,
"currency": "GBP",
"reference": "PO-215-5721",
"billing_descriptor": {
"reference": "Withdrawal"
},
"status": "Pending",
"approved": true,
"sender": {
"type": "individual",
"reference": "8285282045818",
"first_name": "John",
"last_name": "Jones",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"instruction": {
"value_date": "2020-06-13T01:49:19.1864428Z",
"purpose": "Wallet Withdrawal",
"quote_id": "qte_xrhaw53z5m6ehbbxz2n6n5lk74"
},
"_links": {
"self": {
"href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_gwlowf7eap7uzm4cyaaqoq62au"
},
"actions": {
"href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_gwlowf7eap7uzm4cyaaqoq62au/actions"
}
}
}
```
Payment response
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[PaymentId](#schemapaymentid)|false|none|Payment unique identifier|
|requested_on|[ServerTimestamp](#schemaservertimestamp)|false|none|The date/time the payment was requested|
|source|object|false|none|The source of the payout|
|» id|string|false|none|The payment source identifier, which can be used for subsequent payments|
|» type|string|false|none|The payment source type. This is always `currency_account` for payouts.|
|» currency|string|false|none|The three-letter ISO currency code of the payout source|
|» amount|integer|false|none|The amount paid out, in minor units, from the source currency account.|
|destination|object|false|none|The destination of the payout|
|» type|string|false|none|The payout destination type|
|» id|string|false|none|The payment instrument identifier|
|amount|integer|false|none|The original payout amount|
|currency|string|false|none|The three-letter ISO currency code of the payment|
|reference|string|false|none|Your reference for the payout|
|billing_descriptor|object|false|none|Details about the billing descriptor|
|» reference|string|false|none|The reference that is displayed on the account holder's statement|
|status|string|false|none|The status of the payout|
|approved|boolean|false|none|Whether the authorization was successful|
|sender|[PaymentDetailsResponseSender](#schemapaymentdetailsresponsesender)|false|none|Information about the sender of the payment's funds|
|instruction|object|false|none|Details about the instruction for payouts to bank accounts
The fields will depend on which ones were included in the request.|
|» value_date|string|false|none|The date (in ISO 8601 format) on which the recipient's account will be credited|
|» purpose|string|false|none|An optional description of the payout purpose, like `Insurance_claim` or `Remittance`|
|» charge_bearer|string|false|none|Who should be charged the payout fee|
|» repair|boolean|false|none|Determines whether the payout details can be modified to attempt to prevent a payout from being returned|
|» scheme|string|false|none|The preferred payment scheme or network the bank transfer will be sent through|
|» quote_id|string|false|none|The FX quote identifier|
|_links|object|false|none|Links related to the payouts|
|» self|object|false|none|The direct link to the payout|
|»» href|string|false|none|The link URL|
|» actions|object|false|none|The link to the list of actions related to the payout|
|»» href|string|false|none|The link URL|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Pending|
|status|Paid|
|status|Declined|
|status|Returned|
|charge_bearer|OUR|
|charge_bearer|SHA|
|scheme|swift|
|scheme|local|
|scheme|instant|
PayoutSender
```json
{
"type": "instrument",
"reference": "string"
}
```
The ultimate sender of the payout – that is, your customer.
Not supported for Platform or Direct Seller Checkout.com clients.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The sender type. Given it is set to `instrument`, then the sender parameters are retrieved from the destination.|
|reference|string|true|none|A unique reference to the underlying client's customer. A global KYC requirement.|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[03_PayoutRequestInstrumentSender](#schema03_payoutrequestinstrumentsender)|false|none|Store a previously tokenized instrument|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[01_PayoutRequestIndividualSender](#schema01_payoutrequestindividualsender)|false|none|Store a previously tokenized instrument|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[02_PayoutRequestCorporateSender](#schema02_payoutrequestcorporatesender)|false|none|Store a previously tokenized instrument|
#### Enumerated Values
|Property|Value|
|---|---|
|type|instrument|
|type|individual|
|type|corporate|
PlanInstallment
```json
{
"financing": false,
"days_between_payments": 28,
"total_number_of_payments": 5,
"current_payment_number": 3,
"expiry": "20251031",
"name": "Subscription 1234",
"start_date": "20260507",
"amount": 1234
}
```
Installment
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» financing|boolean|false|none|If the installment plan has financing.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentPlan](#schemapaymentplan)|false|none|The details of a recurring subscription or installment `payment_plan`.|
PlanRecurring
```json
{
"amount_variability": "Variable",
"days_between_payments": 28,
"total_number_of_payments": 5,
"current_payment_number": 3,
"expiry": "20251031",
"name": "Subscription 1234",
"start_date": "20260507",
"amount": 1234
}
```
Recurring
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» amount_variability|string|false|none|Specifies whether the amount is fixed or variable for each recurrence.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentPlan](#schemapaymentplan)|false|none|The details of a recurring subscription or installment `payment_plan`.|
#### Enumerated Values
|Property|Value|
|---|---|
|amount_variability|Fixed|
|amount_variability|Variable|
ProcessingData
```json
{
"preferred_scheme": "cartes_bancaires",
"app_id": "com.iap.linker_portal",
"airline_data": [
{
"ticket": {
"number": "045-21351455613",
"issue_date": "2023-05-20",
"issuing_carrier_code": "AI",
"travel_package_indicator": "B",
"travel_agency_name": "World Tours",
"travel_agency_code": "01"
},
"passenger": [
{
"first_name": "John",
"last_name": "White",
"date_of_birth": "1990-05-26",
"address": {
"country": "US"
}
}
],
"flight_leg_details": [
{
"flight_number": "101",
"carrier_code": "BA",
"class_of_travelling": "J",
"departure_airport": "LHR",
"departure_date": "2023-06-19",
"departure_time": "15:30",
"arrival_airport": "LAX",
"stop_over_code": "x",
"fare_basis_code": "SPRSVR"
}
]
}
],
"accommodation_data": [
{
"name": "The Sea View Hotel",
"booking_reference": "HOTEL123",
"check_in_date": "2023-06-20",
"check_out_date": "2023-06-23",
"address": {
"address_line1": "123 Beach Road",
"zip": "10001"
},
"state": "FL",
"country": "USA",
"city": "Los Angeles",
"number_of_rooms": 2,
"guests": [
{
"first_name": "Jane",
"last_name": "Doe",
"date_of_birth": "1985-07-14"
}
],
"room": [
{
"rate": "70",
"number_of_nights_at_room_rate": "3"
}
],
"property_phone": [
{
"country_code": "44",
"number": "7123456789"
}
],
"customer_service_phone": [
{
"country_code": "44",
"number": "7123456789"
}
]
}
],
"partner_customer_id": "2102209000001106125F8",
"partner_payment_id": "440644309099499894406",
"partner_code": "999111",
"failure_code": "partner_error",
"partner_response_code": "ER_WRONG_TICKET",
"tax_amount": 1000,
"locale": "en-US",
"retrieval_reference_number": "909913440644",
"partner_order_id": "string",
"partner_status": "string",
"partner_transaction_id": "string",
"partner_error_codes": [
"string"
],
"partner_merchant_advice_code": "24",
"partner_error_message": "string",
"partner_authorization_code": "string",
"partner_authorization_response_code": "string",
"partner_fraud_status": "string",
"pan_type_processed": "fpan",
"fallback_source_used": false,
"custom_payment_method_ids": [
"string"
],
"aft": true,
"merchant_category_code": "5311",
"scheme_merchant_id": "123456",
"scheme": "ACCEL",
"scheme_transaction_link_id": "string"
}
```
Returns information related to the processing of the payment
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|preferred_scheme|string|false|none|The preferred scheme for co-badged card payment processing. If performing 3DS via a third party, set this value to the scheme that processed 3DS. This field does not support PINless debit schemes in the US (STAR, PULSE, NYCE, ACCEL, SHAZAM).|
|app_id|string|false|none|The customer's application identifier.|
|airline_data|[AirlineData](#schemaairlinedata)|false|none|Contains information about the airline ticket and flights booked by the customer.|
|accommodation_data|[AccommodationData](#schemaaccommodationdata)|false|none|Contains information about the accommodation booked by the customer.|
|partner_customer_id|string|false|none|The customer's ID on the partner platform.|
|partner_payment_id|string|false|none|The partner-originated unique payment identifier|
|partner_code|string|false|none|The 6-digit partner code returned by the payment provider. Returned when `source.type` is `blik`.|
|failure_code|string|false|none|A high-level failure category returned by the payment provider when a payment is declined or fails. Not all payment methods return this field.|
|partner_response_code|string|false|none|The raw response code returned by the payment provider when a payment is declined or fails. Not all payment methods return this field.|
|tax_amount|number|false|none|Total tax amount of the order.|
|locale|string|false|none|The language and region of the customer. ISO 639-2 language code, its value consists of language-country|
|retrieval_reference_number|string|false|none|A unique identifier for the authorization provided by partner|
|partner_order_id|string|false|none|The Klarna order ID associated with the payment.|
|partner_status|string|false|none|Status of a payment provided by partner|
|partner_transaction_id|string|false|none|Unique transaction identification provided by partner|
|partner_error_codes|[string]|false|none|The list of error codes that led the payment to fail or be declined, as given by the payment provider|
|partner_merchant_advice_code|string|false|none|The Merchant Advice Code (MAC) provided by Mastercard, which contains additional information about the transaction.
For example, the MAC can inform you if the transaction was performed using a consumer non-reloadable prepaid card or a consumer single-use virtual card.
For declined transactions, the MAC will also let you know whether the payment can be retried, and how long you should wait before doing so.|
|partner_error_message|string|false|none|Error description provided by partner|
|partner_authorization_code|string|false|none|Authorization code provided by partner|
|partner_authorization_response_code|string|false|none|Authorization response code provided by partner|
|partner_fraud_status|string|false|none|Partner fraud status. If the status is Pending, and the Merchant captures before it changes to Accepted the risk of the transaction is solely of the merchant.|
|pan_type_processed|string|false|none|The type of Primary Account Number (PAN) used for the payment. DPAN indicates network token was used, FPAN indicates the full card was used|
|fallback_source_used|boolean|false|none|Indicates whether the `fallback_source` field was used for the payment.|
|custom_payment_method_ids|[string]|false|none|An array defining which of the configured payment options within a payment category (for example, `pay_later` or `pay_over_time`) should be displayed for this purchase.|
|aft|boolean|false|none|Indicates whether the payment is an [Account Funding Transaction](https://www.checkout.com/docs/payments/manage-payments/account-funding-transactions)|
|merchant_category_code|string|false|none|Four-digit code for retail financial services expressed in ISO 18245 format, classifying the types of goods or services you provide.|
|scheme_merchant_id|string|false|none|The merchant identifier that was configured with the scheme and used for the payment.|
|scheme|string|false|read-only|The scheme on which the payment was authorized. This may differ from the card's scheme used for the payment if the card is co-badged and the payment was authorized on a different network.|
|scheme_transaction_link_id|string|false|none|The scheme transaction link identifier.|
#### Enumerated Values
|Property|Value|
|---|---|
|preferred_scheme|mastercard|
|preferred_scheme|visa|
|preferred_scheme|cartes_bancaires|
|pan_type_processed|fpan|
|pan_type_processed|dpan|
RefundAcceptedResponse
```json
{
"action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
"reference": "ORD-5023-4E89",
"_links": {
"payment": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
}
}
}
```
Refund response
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|action_id|[ActionId](#schemaactionid)|true|none|The unique identifier for the refund action|
|reference|string|false|none|Your reference for the refund request|
|_links|object|false|read-only|The links related to the refund|
|» payment|[Link](#schemalink)|true|none|The URI of the payment to be refunded. Use this to check the status of the payment|
RefundBankAccountDestination
```json
{
"account_type": "savings",
"account_number": "13654567455",
"bank_code": "123-456",
"branch_code": "6443",
"iban": "HU93116000060000000012345676",
"bban": "3704 0044 0532 0130 00",
"swift_bic": "37040044",
"country": "GB",
"account_holder": {
"type": "individual",
"first_name": "John",
"last_name": "Smith",
"company_name": "Test company",
"tax_id": "123456",
"date_of_birth": "1986-01-01",
"country_of_birth": "GB",
"residential_status": "resident",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"identification": {
"type": "passport",
"number": "09876",
"issuing_country": "US"
},
"email": "test.user@checkout.com"
},
"bank": {
"name": "Lloyds TSB",
"branch": "Bournemouth",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
}
}
```
The destination of the refund.
This field is required for giropay and EPS refunds.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|account_type|string|false|none|The type of account to which the refund will be sent.|
|account_number|string|true|none|The account number.|
|bank_code|string|true|none|The code that identifies the bank.|
|branch_code|string|false|none|The code that identifies the bank branch.|
|iban|string|false|none|The account's International Bank Account Number (IBAN).|
|bban|string|false|none|The account's Basic Bank Account Number (BBAN).
The BBAN is a combination of the account number and the bank or branch code, or both.|
|swift_bic|string|false|none|An 8 or 11-digit code that identifies the bank or bank branch.|
|country|string|true|none|The two-letter ISO country code of the country where the account is based.|
|account_holder|[RefundDestinationAccountHolder](#schemarefunddestinationaccountholder)|true|none|The account holder details.|
|bank|[BankDetails](#schemabankdetails)|false|none|Details of the bank|
#### Enumerated Values
|Property|Value|
|---|---|
|account_type|savings|
|account_type|current|
|account_type|cash|
RefundDestinationAccountHolder
```json
{
"type": "individual",
"first_name": "John",
"last_name": "Smith",
"company_name": "Test company",
"tax_id": "123456",
"date_of_birth": "1986-01-01",
"country_of_birth": "GB",
"residential_status": "resident",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"identification": {
"type": "passport",
"number": "09876",
"issuing_country": "US"
},
"email": "test.user@checkout.com"
}
```
The account holder details.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|false|none|The account holder type.|
|first_name|string|true|none|The account holder's first name.|
|last_name|string|true|none|The account holder's last name.|
|company_name|string|false|none|The corporate account holder's company name.|
|tax_id|string|false|none|The account holder's tax number or reference.|
|date_of_birth|string(date)|false|none|The account holder's date of birth, in the format `YYYY-MM-DD`.|
|country_of_birth|string|false|none|The two-letter ISO country code of the account holder's country of birth.|
|residential_status|string|false|none|The account holder's residential status.|
|billing_address|[Address](#schemaaddress)|false|none|The account holder's billing address.|
|phone|[PhoneNumber](#schemaphonenumber)|false|none|The account holder's phone number.|
|identification|[AccountHolderIdentification](#schemaaccountholderidentification)|false|none|Bank account holder's proof of identification|
|email|string(email)|false|none|The account holder's email address.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|individual|
|type|corporate|
|type|government|
|residential_status|resident|
|residential_status|non_resident|
RefundRequest
```json
{
"amount": 6540,
"reference": "ORD-5023-4E89",
"amount_allocations": [
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4",
"amount": 1000,
"reference": "ORD-5023-4E89",
"commission": {
"amount": 1000,
"percentage": 1.125
}
}
],
"capture_action_id": "act_fd3h6evhpn3uxdoqbuu3lqnqbm",
"items": [
{
"type": "digital",
"sub_type": "stablecoin",
"name": "Necklace",
"quantity": 2,
"unit_price": 50,
"reference": "858818ac",
"commodity_code": "DEF123",
"unit_of_measure": "metres",
"total_amount": 29000,
"tax_rate": 2000,
"tax_amount": 1000,
"tax_exempt": true,
"discount_amount": 1000,
"wxpay_goods_id": "1001",
"url": "string",
"image_url": "string",
"service_ends_on": "2025-01-01",
"purchase_country": "GB",
"foreign_retailer_amount": 200
}
],
"destination": {
"account_type": "savings",
"account_number": "13654567455",
"bank_code": "123-456",
"branch_code": "6443",
"iban": "HU93116000060000000012345676",
"bban": "3704 0044 0532 0130 00",
"swift_bic": "37040044",
"country": "GB",
"account_holder": {
"type": "individual",
"first_name": "John",
"last_name": "Smith",
"company_name": "Test company",
"tax_id": "123456",
"date_of_birth": "1986-01-01",
"country_of_birth": "GB",
"residential_status": "resident",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"identification": {
"type": "passport",
"number": "09876",
"issuing_country": "US"
},
"email": "test.user@checkout.com"
},
"bank": {
"name": "Lloyds TSB",
"branch": "Bournemouth",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
}
},
"metadata": {
"coupon_code": "NY2018",
"partner_id": 123989
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|amount|integer|false|none|The amount to refund. If not specified, the full payment amount will be refunded.|
|reference|string|false|none|A reference you can later use to identify this refund request.
For Amex, the string limit is 30 characters.
For TWINT, the string limit is 50 characters.|
|amount_allocations|[AmountAllocations](#schemaamountallocations)|false|none|The sub-entities that the payment is being processed on behalf of|
|capture_action_id|string|false|none|The Checkout.com action ID of the capture you want to refund. Only for PayPal and Riverty.|
|items|[Items](#schemaitems)|false|none|The order's line items.|
|destination|[RefundBankAccountDestination](#schemarefundbankaccountdestination)|false|none|The destination of the refund.
This field is required for giropay and EPS refunds.|
|metadata|object|false|none|A set of key-value pairs to attach to the authorization request. You can use this to store additional information in a structured format.
The `metadata` object only supports primitive data types. Objects and arrays are not supported.|
01_PayoutRequestIndividualAccountHolder
```json
{
"type": "individual",
"first_name": "John",
"last_name": "Smith",
"tax_id": "123456",
"date_of_birth": "1986-01-01",
"country_of_birth": "GB",
"residential_status": "resident",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"identification": {
"type": "SSN",
"issuing_country": "string",
"number": "string"
}
}
```
individual
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of the legal account holder.|
|first_name|string|true|none|The legal first name of the account holder.|
|last_name|string|true|none|The legal last name of the account holder.|
|tax_id|string|false|none|The legal account holder's tax number or reference.|
|date_of_birth|string(date)|false|none|The account holder's date of birth in a `YYYY-MM-DD` format. Strongly recommended where available.|
|country_of_birth|string|false|none|The two-letter ISO country code of the account holder's country of birth.|
|residential_status|string|false|none|The account holder's residential status.|
|billing_address|[Address](#schemaaddress)|true|none|The current billing address associated with the destination account. Required for payouts to individuals. Strongly recommended when available.|
|phone|[PhoneNumber](#schemaphonenumber)|false|none|The phone number of the account holder.|
|identification|object|false|none|The account holder's government document identification. For example, the social security number (SSN).|
|» type|string|false|none|The document type|
|» issuing_country|string|false|none|The country where the document was issued|
|» number|string|false|none|The document number|
#### Enumerated Values
|Property|Value|
|---|---|
|type|individual|
|type|corporate|
|type|government|
|residential_status|resident|
|residential_status|non_resident|
02_PayoutRequestCorporateAccountHolder
```json
{
"type": "corporate",
"company_name": "Test company",
"tax_id": "123456",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
}
```
corporate
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of the legal account holder.|
|company_name|string|true|none|The full legal name of a registered company that holds the account.|
|tax_id|string|false|none|The legal account holder's tax number or reference.|
|billing_address|[Address](#schemaaddress)|false|none|The current billing address associated with the destination account. Strongly recommended when available.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|individual|
|type|corporate|
|type|government|
03_PayoutRequestGovernmentAccountHolder
```json
{
"type": "government",
"company_name": "Test company",
"tax_id": "123456",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
}
```
government
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of the legal account holder.|
|company_name|string|true|none|The full legal name of a registered company that holds the account.|
|tax_id|string|false|none|The legal account holder's tax number or reference.|
|billing_address|[Address](#schemaaddress)|false|none|The current billing address associated with the destination account. Strongly recommended when available.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|individual|
|type|corporate|
|type|government|
PaymentBankAccountDestination
```json
{
"type": "bank_account",
"country": "GB",
"iban": "HU93116000060000000012345676",
"account_number": "13654567455",
"bank_code": "123-456",
"branch_code": "6443",
"bban": "3704 0044 0532 0130 00",
"swift_bic": "37040044",
"account_type": "savings",
"account_holder": {
"type": "individual",
"first_name": "John",
"last_name": "Smith",
"tax_id": "123456",
"date_of_birth": "1986-01-01",
"country_of_birth": "GB",
"residential_status": "resident",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"identification": {
"type": "SSN",
"issuing_country": "string",
"number": "string"
}
}
}
```
bank_account
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payout destination type.|
|country|string|true|none|The two-letter ISO country code of where the account is based. Note that not all countries are available, see our docs for details.|
|iban|string|false|none|Internationally agreed standard for identifying bank accounts. Lengths vary per `destination_country`. See the glossary for details.|
|account_number|string|false|none|Number (which can contain letters) that identifies the local account.|
|bank_code|string|false|none|Code that identifies the bank. Also referred as Routing Number in the United States.|
|branch_code|string|false|none|Code that identifies the bank branch.|
|bban|string|false|none|The combination of bank code and/or branch code and account number.|
|swift_bic|string|false|none|8 or 11 character code which identifies the bank or bank branch.|
|account_type|string|true|none|The type of the bank account. Note: that some beneficiary banks do not accept payouts to savings accounts.|
|account_holder|[AccountHolder](#schemaaccountholder)|false|none|The bank account holder details. Having accurate and complete data improves payout performance (increases success rate and the prevents delays).|
#### Enumerated Values
|Property|Value|
|---|---|
|account_type|savings|
|account_type|current|
|account_type|cash|
PaymentRequestIdDestination
```json
{
"type": "id",
"id": "src_wmlfc3zyhqzehihu7giusaaawu"
}
```
id
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payout destination type.|
|id|string|true|none|The existing payment instrument's identifier. It is advisable that payment instruments are reused, see the documentation for more information.|
01_PaymentRequestIndividualSender
```json
{
"type": "individual",
"reference": "string",
"first_name": "John",
"last_name": "Jones",
"date_of_birth": "1985-05-15",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"identification": {
"type": "driving_licence",
"number": "1234",
"issuing_country": "GT"
}
}
```
individual
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The sender type. If set to `instrument`, the sender information (name and address) will be retrieved from the payment instrument.|
|reference|string|false|none|The unique reference for the sender of the payment.|
|first_name|string|true|none|The sender's first name|
|last_name|string|true|none|The sender's last name|
|date_of_birth|string(date)|false|none|The sender's date of birth (yyyy-mm-dd)|
|address|[Address](#schemaaddress)|true|none|The sender's address|
|identification|object|false|none|none|
|» type|string|false|none|The type of identification used to identify the sender|
|» number|string|false|none|The identification number|
|» issuing_country|string|false|none|The two-letter ISO country code of the country that issued the identification|
#### Enumerated Values
|Property|Value|
|---|---|
|type|individual|
|type|corporate|
|type|instrument|
|type|passport|
|type|driving_licence|
|type|national_id|
01_PayoutRequestIndividualSender
```json
{
"type": "individual",
"reference": "string",
"first_name": "John",
"last_name": "Jones",
"dob": "1985-05-15",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"identification": {
"type": "driving_licence",
"number": "1234",
"issuing_country": "GT"
}
}
```
individual
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The sender type. Given it is set to `instrument`, then the sender parameters are retrieved from the destination.|
|reference|string|true|none|A unique reference to the underlying client's customer. A global KYC requirement.|
|first_name|string|true|none|The legal first name of the ultimate sender.|
|last_name|string|true|none|The legal last name of the ultimate sender.|
|dob|string(date)|false|none|The sender's date of birth in a `YYYY-MM-DD` format. Strongly recommended where available.|
|address|[Address](#schemaaddress)|true|none|The sender's address.|
|identification|object|false|none|none|
|» type|string|false|none|The type of identification used to identify the sender.|
|» number|string|false|none|The identification number.|
|» issuing_country|string|false|none|The two-letter ISO country code that issued the identification.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|instrument|
|type|individual|
|type|corporate|
|type|passport|
|type|driving_licence|
|type|national_id|
02_PaymentRequestCorporateSender
```json
{
"type": "corporate",
"reference": "string",
"company_name": "string",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
}
```
corporate
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The sender type. If set to `instrument`, the sender information (name and address) will be retrieved from the payment instrument.|
|reference|string|false|none|The unique reference for the sender of the payment.|
|company_name|string|true|none|The sender's company name|
|address|[Address](#schemaaddress)|true|none|The sender's address|
#### Enumerated Values
|Property|Value|
|---|---|
|type|individual|
|type|corporate|
|type|instrument|
02_PayoutRequestCorporateSender
```json
{
"type": "corporate",
"reference": "string",
"company_name": "string",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
}
```
corporate
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The sender type. Given it is set to `instrument`, then the sender parameters are retrieved from the destination.|
|reference|string|true|none|A unique reference to the underlying client's customer. A global KYC requirement.|
|company_name|string|true|none|The sender's company name|
|address|[Address](#schemaaddress)|true|none|The sender's address|
#### Enumerated Values
|Property|Value|
|---|---|
|type|instrument|
|type|individual|
|type|corporate|
03_PaymentRequestInstrumentSender
```json
{
"type": "instrument",
"reference": "string"
}
```
instrument
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The sender type. If set to `instrument`, the sender information (name and address) will be retrieved from the payment instrument.|
|reference|string|false|none|The unique reference for the sender of the payment.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|individual|
|type|corporate|
|type|instrument|
03_PayoutRequestInstrumentSender
```json
{
"type": "instrument",
"reference": "string"
}
```
instrument
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The sender type. Given it is set to `instrument`, then the sender parameters are retrieved from the destination.|
|reference|string|true|none|A unique reference to the underlying client's customer. A global KYC requirement.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|instrument|
|type|individual|
|type|corporate|
PaymentRequestAchSource
```json
{
"account_type": "savings",
"country": "US",
"account_number": "136549956",
"bank_code": "021000021",
"account_holder": {
"type": "individual",
"first_name": "John",
"last_name": "Smith",
"company_name": "Test company",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"date_of_birth": "string",
"identification": {
"type": "SSN",
"issuing_country": "string",
"number": "string"
}
},
"type": "ach"
}
```
ach
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|account_type|string|true|none|The type of Direct Debit account|
|country|string|true|none|The source country|
|account_number|string|true|none|The account number of the Direct Debit account|
|bank_code|string|true|none|The bank code of the Direct Debit account|
|account_holder|[AccountHolderAch](#schemaaccountholderach)|true|none|The account holder details|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|account_type|savings|
|account_type|checking|
|account_type|cash|
|*anonymous*|ach|
PaymentRequestAlipayCnSource
```json
{
"type": "alipay_cn"
}
```
alipay_cn
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|alipay_cn|
PaymentRequestAlipayHkSource
```json
{
"type": "alipay_hk"
}
```
alipay_hk
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|alipay_hk|
PaymentRequestAlipayPlusSource
```json
{
"type": "alipay_plus"
}
```
alipay_plus
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|alipay_plus|
PaymentRequestAlmaSource
```json
{
"type": "alma",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
}
```
alma
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|billing_address|any|false|none|The billing address of the cardholder|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[Address](#schemaaddress)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|object|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|alma|
PaymentRequestBacsSource
```json
{
"type": "bacs",
"id": "src_wmlfc3zyhqzehihu7giusaaawu"
}
```
bacs
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|true|none|The Bacs Direct Debit instrument ID.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|bacs|
```json
{
"payment_country": "BE",
"account_holder_name": "string",
"billing_descriptor": "string",
"language": "nl",
"type": "bancontact"
}
```
bancontact
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|payment_country|string|true|none|The 2-letter ISO country code of the country in which the payment instrument is issued/operated.|
|account_holder_name|string|true|none|The account holder.|
|billing_descriptor|string|false|none|Payment billing descriptor.|
|language|string|false|none|The 2-letter ISO language code that should be preferred when presenting payment pages to the consumer.|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|payment_country|BE|
|language|fr|
|language|nl|
|language|de|
|language|en|
|*anonymous*|bancontact|
PaymentRequestBizumSource
```json
{
"type": "bizum"
}
```
bizum
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|bizum|
PaymentRequestBlikSource
```json
{
"type": "blik",
"partner_agreement_id": "blik_payid_123456789"
}
```
blik
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|partner_agreement_id|string|false|none|The Blik PAYID identifying an external partner agreement created with another PSP.
Only used when processing merchant-initiated recurring payments (`merchant_initiated: true`) without a stored Checkout.com source.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|blik|
PaymentRequestCardSource
```json
{
"number": "4543474002249996",
"expiry_month": 6,
"expiry_year": 2030,
"name": "Bruce Wayne",
"cvv": "956",
"stored": true,
"store_for_future_use": false,
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"account_holder": {},
"allow_update": false,
"type": "card"
}
```
card
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|number|string|true|none|The card number (without separators)|
|expiry_month|integer|true|none|The expiry month of the card|
|expiry_year|integer|true|none|4-digit expiry year of the card|
|name|string|false|none|The name of the cardholder|
|cvv|string|false|none|The card verification value/code. 3 digits, except for American Express (4 digits)|
|stored|boolean|false|none|Indicates whether this card is being submitted from your own stored card-on-file system, rather than being entered by the customer at the time of payment. Set to `true` when you provide card details that you already have on file for the customer.|
|store_for_future_use|boolean|false|none|This must be set to true if you intend to reuse the payment credentials in subsequent payments. Setting the field as false will mean that a payment instrument will not be included in the payment response.|
|billing_address|[Address](#schemaaddress)|false|none|The billing address of the cardholder|
|phone|[PhoneNumber](#schemaphonenumber)|false|none|The phone number of the cardholder|
|account_holder|object|false|none|Information about the account holder of the card|
|allow_update|boolean|false|none|Specifies whether to use the Real-Time Account Updater to update the card information.|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|card|
PaymentRequestCustomerSource
```json
{
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"account_holder": {},
"allow_update": false,
"type": "customer"
}
```
customer
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|true|none|The customer's identifier.|
|billing_address|[Address](#schemaaddress)|false|none|The cardholder's billing address.|
|phone|[PhoneNumber](#schemaphonenumber)|false|none|The cardholder's phone number.|
|account_holder|object|false|none|Information about the account holder of the customer's default payment instrument|
|allow_update|boolean|false|none|Specifies whether to use the Real-Time Account Updater to update the card information.|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|customer|
PaymentRequestDanaSource
```json
{
"type": "dana"
}
```
dana
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|dana|
PaymentRequestEpsSource
```json
{
"type": "eps",
"purpose": "string",
"account_holder": {
"first_name": "John",
"last_name": "Smith"
}
}
```
eps
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|purpose|string|true|none|Purpose of the payment as appearing on customer's bank statement.|
|account_holder|[AccountHolderEps](#schemaaccountholdereps)|false|none|The account holder details|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|eps|
PaymentRequestFallbackSource
```json
{
"number": "4543474002249996",
"expiry_month": 6,
"expiry_year": 2030,
"name": "Bruce Wayne",
"cvv": "956",
"stored": true,
"store_for_future_use": false,
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"account_holder": {},
"allow_update": false,
"type": "card"
}
```
A card payment source
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|number|string|true|none|The card number (without separators)|
|expiry_month|integer|true|none|The expiry month of the card|
|expiry_year|integer|true|none|4-digit expiry year of the card|
|name|string|false|none|The name of the cardholder|
|cvv|string|false|none|The card verification value/code. 3 digits, except for American Express (4 digits)|
|stored|boolean|false|none|Indicates whether this card is being submitted from your own stored card-on-file system, rather than being entered by the customer at the time of payment. Set to `true` when you provide card details that you already have on file for the customer.|
|store_for_future_use|boolean|false|none|This must be set to true if you intend to reuse the payment credentials in subsequent payments. Setting the field as false will mean that a payment instrument will not be included in the payment response.|
|billing_address|[Address](#schemaaddress)|false|none|The billing address of the cardholder|
|phone|[PhoneNumber](#schemaphonenumber)|false|none|The phone number of the cardholder|
|account_holder|object|false|none|Information about the account holder of the card|
|allow_update|boolean|false|none|Specifies whether to use the Real-Time Account Updater to update the card information.|
|type|string|true|none|The payment source type.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|card|
PaymentRequestFawrySource
```json
{
"description": "string",
"customer_profile_id": "string",
"customer_email": "string",
"customer_mobile": "string",
"expires_on": "2019-08-24T14:15:22Z",
"products": [
{
"product_id": "string",
"quantity": 0,
"price": 0,
"description": "string"
}
],
"type": "fawry"
}
```
fawry
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|description|string|true|none|The payment description.|
|customer_profile_id|string|false|none|The customer's id within merchant's system.|
|customer_email|string|true|none|The customer's email address.|
|customer_mobile|string|true|none|The customer's mobile phone number.|
|expires_on|string(date-time)|false|none|The date on which the payment expires.|
|products|[object]|true|none|List of Products|
|» product_id|string|true|none|The id of the product.|
|» quantity|integer|true|none|The quantity of the product.|
|» price|integer|true|none|The price of the item. Expressed using Checkout.com's standard rules for calculating payment values.|
|» description|string|true|none|The description of the product.|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|fawry|
PaymentRequestGcashSource
```json
{
"type": "gcash"
}
```
gcash
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|gcash|
PaymentRequestIdealSource
```json
{
"description": "string",
"language": "st",
"type": "ideal"
}
```
ideal
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|description|string|true|none|Description of the product(s) or services being paid for. This field must not contain characters that can lead to problems (for example those occurring in HTML editing codes). To prevent any possible errors most iDEAL systems will reject any description that contains HTML-tags and such other code.|
|language|string|false|none|This field enables the issuer's site to select the consumer's preferred language.
For example, the language selected on the merchant's site – if the issuer's site supports it. Code list in accordance with ISO 639-1. (Dutch = 'nl', English = 'en').
If a non-supported or non-existing language is entered, the standard language of the issuer is used. Because not all issuers support other languages, it is recommended to send 'nl' by default.|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|ideal|
PaymentRequestIdSource
```json
{
"id": "src_wmlfc3zyhqzehihu7giusaaawu",
"cvv": "956",
"payment_method": "ach",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"account_holder": {},
"allow_update": false,
"type": "id"
}
```
id
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|true|none|The payment source identifier (e.g., a card source identifier)|
|cvv|string|false|none|The card verification value (CVV) or code, if the source is a card. The expected format varies:
- for American Express cards, this should be a 4-digit code
- for other cards, this should be a 3-digit code
- for Checkout.com CVV tokens, this should be an ID value with the prefix `tok_`|
|payment_method|string|false|none|The payment method. Payment Method required for ACH payment|
|billing_address|[Address](#schemaaddress)|false|none|The cardholder's billing address.|
|phone|[PhoneNumber](#schemaphonenumber)|false|none|The cardholder's phone number.|
|account_holder|object|false|none|Information about the account holder of the payment instrument|
|allow_update|boolean|false|none|Specifies whether to use the Real-Time Account Updater to update the card information.|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|id|
PaymentRequestKakaopaySource
```json
{
"type": "kakaopay"
}
```
kakaopay
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|kakaopay|
PaymentRequestKnetSource
```json
{
"type": "knet",
"language": "ar",
"user_defined_field1": "string",
"user_defined_field2": "string",
"user_defined_field3": "string",
"user_defined_field4": "string",
"user_defined_field5": "string",
"card_token": "string",
"ptlf": "string",
"token_type": "applepay",
"token_data": {
"version": "EC_v1",
"data": "t7GeajLB9skXB6QSWfEpPA4WPhDqB7ekdd+F7588arLzvebKp3P0TekUslSQ8nkuacUgLdks2IKyCm7U3OL/PEYLXE7w60VkQ8WE6FXs/cqHkwtSW9vkzZNDxSLDg9slgLYxAH2/iztdipPpyIYKl0Kb6Rn9rboF+lwgRxM1B3n84miApwF5Pxl8ZOOXGY6F+3DsDo7sMCUTaJK74DUJJcjIXrigtINWKW6RFa/4qmPEC/Y+syg04x7B99mbLQQzWFm7z6HfRmynPM9/GA0kbsqd/Kn5Mkqssfhn/m6LuNKsqEmbKi85FF6kip+F17LRawG48bF/lT8wj/QEuDY0G7t/ryOnGLtKteXmAf0oJnwkelIyfyj2KI8GChBuTJonGlXKr5klPE89/ycmkgDl+T6Ms7PhiNZpuGEE2QE=",
"signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID5jCCA4ugAwIBAgIIaGD2mdnMpw8wCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE2MDYwMzE4MTY0MFoXDTIxMDYwMjE4MTY0MFowYjEoMCYGA1UEAwwfZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtU0FOREJPWDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgjD9q8Oc914gLFDZm0US5jfiqQHdbLPgsc1LUmeY+M9OvegaJajCHkwz3c6OKpbC9q+hkwNFxOh6RCbOlRsSlaOCAhEwggINMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDIwHQYDVR0OBBYEFAIkMAua7u1GMZekplopnkJxghxFMAwGA1UdEwEB/wQCMAAwHwYDVR0jBBgwFoAUI/JJxE+T5O8n5sT2KGw/orv9LkswggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMA4GA1UdDwEB/wQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0kAMEYCIQDaHGOui+X2T44R6GVpN7m2nEcr6T6sMjOhZ5NuSo1egwIhAL1a+/hp88DKJ0sv3eT3FxWcs71xmbLKD/QJ3mWagrJNMIIC7jCCAnWgAwIBAgIISW0vvzqY2pcwCgYIKoZIzj0EAwIwZzEbMBkGA1UEAwwSQXBwbGUgUm9vdCBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwHhcNMTQwNTA2MjM0NjMwWhcNMjkwNTA2MjM0NjMwWjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATwFxGEGddkhdUaXiWBB3bogKLv3nuuTeCN/EuT4TNW1WZbNa4i0Jd2DSJOe7oI/XYXzojLdrtmcL7I6CmE/1RFo4H3MIH0MEYGCCsGAQUFBwEBBDowODA2BggrBgEFBQcwAYYqaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZXJvb3RjYWczMB0GA1UdDgQWBBQj8knET5Pk7yfmxPYobD+iu/0uSzAPBgNVHRMBAf8EBTADAQH/MB8GA1UdIwQYMBaAFLuw3qFYM4iapIqZ3r6966/ayySrMDcGA1UdHwQwMC4wLKAqoCiGJmh0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlcm9vdGNhZzMuY3JsMA4GA1UdDwEB/wQEAwIBBjAQBgoqhkiG92NkBgIOBAIFADAKBggqhkjOPQQDAgNnADBkAjA6z3KDURaZsYb7NcNWymK/9Bft2Q91TaKOvvGcgV5Ct4n4mPebWZ+Y1UENj53pwv4CMDIt1UQhsKMFd2xd8zg7kGf9F3wsIW2WT8ZyaYISb1T4en0bmcubCYkhYQaZDwmSHQAAMYIBjTCCAYkCAQEwgYYwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTAghoYPaZ2cynDzANBglghkgBZQMEAgEFAKCBlTAYBgkqhkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0xNzA4MDIxNjA5NDZaMCoGCSqGSIb3DQEJNDEdMBswDQYJYIZIAWUDBAIBBQChCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEIGEfVr+4x9RQXyfF8IYA0kraoK0pcZEaBlINo6EGrOReMAoGCCqGSM49BAMCBEgwRgIhAKunK47QEr/ZjxPlVl+etzVzbKA41xPLWtO01oUOlulmAiEAiaFH9F9LK6uqTFAUW/WIDkHWiFuSm5a3NVox7DlyIf0AAAAAAAA=",
"header": {
"ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEX1ievoT8DRB8T5zGkhHZHeDr0oBmYEgsDSxyT0MD0IZ2Mpfjz2LdWq6LUwSH9EmxdPEzMunsZKWMyOr3K/zlsw==",
"publicKeyHash": "tqYV+tmG9aMh+l/K6cicUnPqkb1gUiLjSTM9gEz6Nl0=",
"transactionId": "3cee89679130a4b2617c76118a1c62fd400cd45b49dc0916d5b951b560cd17b4"
}
},
"payment_method_details": {
"display_name": "Visa 1234",
"type": "debit",
"network": "Visa"
}
}
```
knet
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|language|string|false|none|Required for KNet Gateway payments.
This field enables the issuer's site to select the consumer's preferred language.
For example, the language selected on the merchant's site – if the issuer's site supports it.
Code list in accordance with ISO 639-1. (Arabic = 'ar', English = 'en').
Note that 'ar' corresponds to 'ARA' and 'en' to 'USA'. Both values accepted by KNet Gateway.|
|user_defined_field1|string|false|none|User-defined field that can be used to pass and store any additional transaction data required to be archived with the transaction and available as a searching criterion. Only alphanumeric characters and spaces are allowed|
|user_defined_field2|string|false|none|User-defined field that can be used to pass and store any additional transaction data required to be archived with the transaction and available as a searching criterion. Only alphanumeric characters and spaces are allowed|
|user_defined_field3|string|false|none|User-defined field that can be used to pass and store any additional transaction data required to be archived with the transaction and available as a searching criterion. Only alphanumeric characters and spaces are allowed. Note that this field must be omitted when the `card_token` field is not empty. This restriction exists because a card token is passed to KNet Gateway as `user_defined_field3`|
|user_defined_field4|string|false|none|User-defined field that can be used to pass and store any additional transaction data required to be archived with the transaction and available as a searching criterion. Only alphanumeric characters and spaces are allowed.|
|user_defined_field5|string|false|none|User-defined field that can be used to pass and store any additional transaction data required to be archived with the transaction and available as a searching criterion. Only alphanumeric characters and spaces are allowed. Note that this field must be omitted when the `ptlf` field is not empty. This restriction exists because a PTLF value is passed to KNet Gateway as `user_defined_field5`|
|card_token|string|false|none|This token allows re-use of card details for multiple payments. This 8-digit token should be generated by a merchant. When a subsequent payment is initialized with the same card token, a customer is presented with two options. The customer can choose to pay with KFast (doesn't need to enter card details again), or with KNet as usual. The payment flow stays the same i.e. a merchant should redirect a customer to the redirect URL which is provided in the payment creation response. Note that `user_defined_field3` must be omitted when the `card_token` field is not empty. This restriction exists because a card token is passed to KNet Gateway as `user_defined_field3`|
|ptlf|string|false|none|This is an ID for merchant PTLF functionality tracking. Only alphanumeric characters are allowed. Note that `user_defined_field5` must be omitted when the `ptlf` field is not empty. This restriction exists because a PTLF value is passed to KNet Gateway as `user_defined_field5`.|
|token_type|string|false|none|The token type. This field is always `applepay` for KNet Apple Pay payments.|
|token_data|[TokenData](#schematokendata)|false|none|The Apple Pay payment token. Required for Apple Pay payments.|
|payment_method_details|object|false|none|The payment data received in the Apple Pay payload. Required for Apple Pay payments.|
|» display_name|string|false|none|The payment type display name.|
|» type|string|false|none|The payment method type.|
|» network|string|false|none|The card network.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|knet|
|language|ar|
|language|en|
|token_type|applepay|
PaymentRequestMBWaySource
```json
{
"type": "mbway"
}
```
mbway
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|mbway|
PaymentRequestMobilePaySource
```json
{
"type": "mobilepay"
}
```
mobilepay
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|mobilepay|
PaymentRequestMultibancoSource
```json
{
"payment_country": "PT",
"account_holder_name": "string",
"billing_descriptor": "string",
"type": "multibanco"
}
```
multibanco
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|payment_country|string|true|none|The 2-letter ISO country code of the country in which the payment instrument is issued/operated.|
|account_holder_name|string|true|none|The account holder.|
|billing_descriptor|string|false|none|Payment billing descriptor.|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|payment_country|PT|
|*anonymous*|multibanco|
PaymentRequestNetworkTokenSource
```json
{
"token": "4543474002249996",
"expiry_month": 6,
"expiry_year": 2025,
"token_type": "vts",
"cryptogram": "hv8mUFzPzRZoCAAAAAEQBDMAAAA=",
"eci": "05",
"stored": true,
"store_for_future_use": false,
"name": "Bruce Wayne",
"cvv": "956",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"account_holder": {},
"type": "network_token"
}
```
network_token
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|token|string|true|none|The network token PAN|
|expiry_month|integer|true|none|The expiry month of the token|
|expiry_year|integer|true|none|The expiry year of the token|
|token_type|string|true|none|The type of token|
|cryptogram|string|true|none|The Base64 encoded cryptographic identifier (TAVV) used by card schemes to validate the token verification result. Optional if `previous_payment_id` is specified and `3ds.enabled` is false|
|eci|string|true|none|The Electronic Commerce Indicator (ECI) security level associated with the token. Optional if `previous_payment_id` is specified and `3ds.enabled` is false|
|stored|boolean|false|none|Indicates whether this card is being submitted from your own stored card-on-file system, rather than being entered by the customer at the time of payment. Set to `true` when you provide card details that you already have on file for the customer.|
|store_for_future_use|boolean|false|none|This must be set to true if you intend to reuse the payment credentials in subsequent payments. Setting the field as false will mean that a payment instrument will not be included in the payment response.|
|name|string|false|none|The customer's name|
|cvv|string|false|none|The card verification value/code. 3 digits, except for American Express (4 digits)|
|billing_address|[Address](#schemaaddress)|false|none|The customer's billing address|
|phone|[PhoneNumber](#schemaphonenumber)|false|none|The customer's phone number|
|account_holder|object|false|none|Information about the account holder of the card|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|token_type|vts|
|token_type|mdes|
|token_type|applepay|
|token_type|googlepay|
|*anonymous*|network_token|
PaymentRequestOctopusPaySource
```json
{
"type": "octopus"
}
```
octopus
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|octopus|
PaymentRequestP24Source
```json
{
"type": "p24",
"payment_country": "PL",
"account_holder_name": "string",
"account_holder_email": "string",
"billing_descriptor": "string"
}
```
p24
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|payment_country|string|true|none|The 2-letter ISO country code of the country in which the payment instrument is issued/operated.|
|account_holder_name|string|true|none|The account holder.|
|account_holder_email|string|true|none|RFC-compliant email address of the account holder.|
|billing_descriptor|string|false|none|Payment billing descriptor.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|p24|
|payment_country|PL|
PaymentRequestPayNowSource
```json
{
"type": "paynow"
}
```
paynow
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|paynow|
PaymentRequestPlaidSource
```json
{
"token": "string",
"account_holder": {
"type": "individual",
"first_name": "John",
"last_name": "Smith",
"tax_id": "123456",
"date_of_birth": "1986-01-01",
"country_of_birth": "GB",
"residential_status": "resident",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"identification": {
"type": "SSN",
"issuing_country": "string",
"number": "string"
}
},
"type": "plaid"
}
```
plaid
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|token|string|true|none|The `processor_token` returned from Plaid’s `/processor/token/create` endpoint.
In the sandbox environment, this token will have the format `processor-sandbox-xxx`.|
|account_holder|[AccountHolder](#schemaaccountholder)|true|none|The account holder details.|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|plaid|
PaymentRequestQPaySource
```json
{
"type": "qpay",
"quantity": 1,
"description": "string",
"language": "string",
"national_id": "string"
}
```
qpay
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|quantity|integer|false|none|A numeric value greater than zero that represents the quantity of a purchased item. The value is used for display purposes only and does not affect the total amount of the payment. The minimum allowed value is 1.|
|description|string|true|none|Alphanumeric string containing a description of the payment order. Note: The maximum allowed length of this property is 255 characters after UTF-8 URL encoding.|
|language|string|false|none|Alphabetic value representing the language of the interface displayed to customer at merchant site, and used as language for the payment description parameter. PG will use this value to display the interface supporting selected language to the customer during the payment process. Supported values are: `En`, `Ar`. The default value is `En`.|
|national_id|string|false|none|Alphanumeric value representing the national ID of the customer performing the transaction. The maximum allowed length of this property is 32.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|qpay|
PaymentRequestSEPAV4Source
```json
{
"country": "FR",
"account_number": "FR7630006000011234567890189",
"currency": "EUR",
"mandate_id": "123456",
"mandate_type": "Core",
"date_of_signature": "2022-08-02",
"account_holder": {
"first_name": "John",
"last_name": "Wick",
"company_name": "Checkout.com",
"type": "Individual",
"billing_address": {
"address_line1": "Evergreen Terrace",
"address_line2": "742",
"city": "Paris",
"zip": "75000",
"country": "FR"
}
},
"type": "sepa"
}
```
sepa
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|country|string|true|none|The account's country, as an ISO 3166-1 alpha-2 code.|
|account_number|string|true|none|The account holder's IBAN.|
|currency|string|true|none|The account holder's account currency.|
|mandate_id|string|false|none|The ID of the mandate.|
|mandate_type|string|false|none|The type of mandate.|
|date_of_signature|string|false|none|The date the mandate was signed, in the format yyyy-MM-dd|
|account_holder|object|true|none|The account holder's personal information.|
|» first_name|string|false|none|The account holder's first name.|
|» last_name|string|false|none|The account holder's last name.|
|» company_name|string|false|none|The account holder's company name.|
|» type|string|false|none|The type of account holder|
|» billing_address|object|true|none|The account holder's billing address.|
|»» address_line1|string|true|none|The account holder's street name.|
|»» address_line2|string|true|none|The account holder's street number.|
|»» city|string|true|none|The account holder's city.|
|»» zip|string|true|none|The account holder's zip code.|
|»» country|string|true|none|The account holder's country, as an ISO 3166-1 alpha-2 code.|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|mandate_type|Core|
|mandate_type|B2B|
|type|Individual|
|type|Corporate|
|*anonymous*|sepa|
PaymentRequestSequraSource
```json
{
"type": "sequra",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
}
```
sequra
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|billing_address|[Address](#schemaaddress)|true|none|The billing address of the cardholder|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|sequra|
PaymentRequestSourceType
```json
"string"
```
Ordered list of payment request source types used for discriminators
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|Ordered list of payment request source types used for discriminators|
PaymentRequestStcPaySource
```json
{
"type": "stcpay"
}
```
stcpay
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|stcpay|
PaymentRequestSwishSource
```json
{
"payment_country": "SE",
"account_holder": {
"first_name": "string",
"last_name": "string"
},
"billing_descriptor": {
"name": "string"
},
"type": "swish"
}
```
swish
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|payment_country|string|true|none|The 2-letter ISO country code of the country in which the payment instrument is issued or operated.|
|account_holder|object|true|none|Information about the account holder's details|
|» first_name|string|true|none|The account holder's first name|
|» last_name|string|true|none|The account holder's last name|
|billing_descriptor|object|false|none|Payment billing descriptor|
|» name|string|true|none|A description for the payment, which displays on the customer's statement|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|payment_country|SE|
|*anonymous*|swish|
PaymentRequestTamaraSource
```json
{
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"type": "tamara"
}
```
tamara
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|billing_address|[Address](#schemaaddress)|true|none|The billing address of the cardholder|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|tamara|
PaymentRequestTngSource
```json
{
"type": "tng"
}
```
tng
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|tng|
PaymentRequestTokenSource
```json
{
"type": "token",
"token": "tok_ubfj2q76miwundwlk72vxt2i7q",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"store_for_future_use": false,
"account_holder": {}
}
```
token
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|token|string|false|none|The Checkout.com token (e.g., a card token)|
|billing_address|[Address](#schemaaddress)|false|none|The customer's billing address. This will override the billing address specified during tokenization|
|phone|[PhoneNumber](#schemaphonenumber)|false|none|The customer's phone number. This will override the phone number specified during tokenization|
|store_for_future_use|boolean|false|none|This must be set to true if you intend to reuse the payment credentials in subsequent payments. Setting the field as false will mean that a payment instrument will not be included in the payment response.|
|account_holder|object|false|none|Information about the account holder of the card|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|token|
PaymentRequestTruemoneySource
```json
{
"type": "truemoney"
}
```
truemoney
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|truemoney|
PaymentRequestTwintSource
```json
{
"type": "twint"
}
```
twint
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|twint|
PaymentRequestVippsSource
```json
{
"type": "vipps"
}
```
vipps
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|vipps|
PaymentRequestWeChatPaySource
```json
{
"billing_address": {
"address_line1": "150 Kennedy Road",
"address_line2": "Acacia Building",
"city": "Wan Chai",
"state": "Hong Kong",
"zip": 42345,
"country": "HK"
},
"type": "wechatpay"
}
```
wechatpay
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|billing_address|object|false|none|none|
|» address_line1|string|false|none|The first line of the address|
|» address_line2|string|false|none|The second line of the address|
|» city|string|false|none|The address city|
|» state|string|false|none|The address state|
|» zip|number|false|none|The address zip/postal code|
|» country|string|false|none|The two-letter ISO country code of the address|
|type|string|true|none|The payment source type.|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[PaymentRequestSourceType](#schemapaymentrequestsourcetype)|false|none|Ordered list of payment request source types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|wechatpay|
BankPayoutRequestCurrencyAccountSource
```json
{
"type": "entity",
"id": "ca_y3oqhf46pyzuxjbcn2giaqnb44"
}
```
currency_account
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payout source type.|
|id|string|true|none|The currency account's identifier.
Its holding currency must match the payout's `currency`.|
BankPayoutRequestEntitySource
```json
{
"type": "entity",
"id": "ent_w4jelhppmfiufdnatam37wrfc4"
}
```
entity
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payout source type.|
|id|string|true|none|The entity or sub-entity's identifier, only applies to Platform Clients.|
01_RequestSources_AccountHolderIndividual
```json
{
"type": "individual",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"account_name_inquiry": true
}
```
individual
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The card account holder type|
|first_name|string|true|none|The card account holder's first name
*A valid and legal name must be populated in this field. The populated value cannot be only one character or all non-alphabet.*|
|middle_name|string|false|none|The card account holder's middle name
***Conditional*** - required when the [card metadata](https://api-reference.checkout.com/#operation/requestCardMetadata!c=200&path=issuer_country&t=response) `issuer_country` = `ZA` (South Africa)|
|last_name|string|true|none|The card account holder's last name
*A valid and legal name must be populated in this field. The populated value cannot be only one character or all non-alphabet.*|
|account_name_inquiry|boolean|false|none|Whether the ANI (account name inquiry) check should be performed with the scheme (Visa or MasterCard)|
02_RequestSources_AccountHolderCorporate
```json
{
"type": "corporate",
"company_name": "string",
"account_name_inquiry": true
}
```
corporate
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The card account holder type|
|company_name|string|true|none|The card account holder's company name
*A valid and legal name must be populated in this field. The populated value cannot be only one character or all non-alphabet.*|
|account_name_inquiry|boolean|false|none|Whether the ANI (account name inquiry) check should be performed with the scheme (Visa or MasterCard)|
03_RequestSources_AccountHolderGovernment
```json
{
"type": "government",
"company_name": "string",
"account_name_inquiry": true
}
```
government
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The card account holder type|
|company_name|string|true|none|The card account holder's company name
*A valid and legal name must be populated in this field. The populated value cannot be only one character or all non-alphabet.*|
|account_name_inquiry|boolean|false|none|Whether the ANI (account name inquiry) check should be performed with the scheme (Visa or MasterCard)|
PaymentResponseBankAccountDestination
```json
{
"type": "bank_account",
"id": "string"
}
```
bank_account
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment destination type.|
|id|string|true|none|The payment instrument identifier|
#### Enumerated Values
|Property|Value|
|---|---|
|type|bank_account|
01_PaymentResponseIndividualSender
```json
{
"type": "individual",
"reference": "8285282045818",
"first_name": "John",
"last_name": "Jones",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
}
```
individual
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of sender|
|reference|string|false|none|The sender's reference for the payout|
|first_name|string|true|none|The sender's first name|
|last_name|string|true|none|The sender's last name|
|address|[Address](#schemaaddress)|true|none|The sender's address|
#### Enumerated Values
|Property|Value|
|---|---|
|type|individual|
|type|corporate|
|type|instrument|
02_PaymentResponseCorporateSender
```json
{
"type": "corporate",
"reference": "8285282045818",
"company_name": "string",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
}
```
corporate
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of sender|
|reference|string|false|none|The sender's reference for the payout|
|company_name|string|true|none|The sender's company name|
|address|[Address](#schemaaddress)|false|none|The sender's address|
#### Enumerated Values
|Property|Value|
|---|---|
|type|individual|
|type|corporate|
|type|instrument|
03_PaymentResponseInstrumentSender
```json
{
"type": "instrument",
"reference": "8285282045818"
}
```
instrument
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of sender|
|reference|string|false|none|The sender's reference for the payout|
#### Enumerated Values
|Property|Value|
|---|---|
|type|individual|
|type|corporate|
|type|instrument|
PaymentDeclinedSourceResponse
```json
{
"id": "string",
"type": "card"
}
```
A source-based APM Declined payment source response
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|true|none|The payment instrument identifier|
|type|string|true|none|The type of payment source|
#### Enumerated Values
|Property|Value|
|---|---|
|type|card|
|type|ach|
|type|alipay_cn|
|type|bank_account|
|type|sepa|
|type|bacs|
PaymentResponseCardSource
```json
{
"type": "card",
"id": "src_nwd3m4in3hkuddfpjsaevunhdy",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"expiry_month": 6,
"expiry_year": 2025,
"name": "Bruce Wayne",
"scheme": "VISA",
"scheme_local": "Cartes_Bancaires",
"local_schemes": [
"cartes_bancaires",
"visa"
],
"last4": "9996",
"fingerprint": "F639CAB2745BEE4140BF86DF6B6D6",
"bin": "45434748",
"card_type": "CREDIT",
"card_category": "CONSUMER",
"card_wallet_type": "applepay",
"issuer": "GOTHAM STATE BANK",
"issuer_country": "US",
"product_id": "F",
"product_type": "CLASSIC",
"avs_check": "S",
"cvv_check": "Y",
"payment_account_reference": "EUNIX9AX7THOOJIEJ2AP6OOFAHGH4",
"encrypted_card_number": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz...",
"account_update_status": "card_updated",
"account_update_failure_code": "VAU009",
"account_holder": {}
}
```
card
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type.|
|id|string|false|none|The payment source identifier that can be used for subsequent payments. For new sources, this will only be returned if the payment was approved|
|billing_address|[Address](#schemaaddress)|false|none|The payment source owner's billing address|
|phone|[PhoneNumber](#schemaphonenumber)|false|none|The payment source owner's phone number|
|expiry_month|integer|true|none|The expiry month|
|expiry_year|integer|true|none|The expiry year|
|name|string|false|none|The cardholder's name|
|scheme|string|false|none|The card scheme|
|scheme_local|string|false|none|Replaced by `local_schemes`
The local co-branded card scheme.|
|local_schemes|[string]|false|none|The local co-branded card schemes.|
|last4|string|true|none|The last four digits of the card number|
|fingerprint|string|true|none|Uniquely identifies this particular card number. You can use this to compare cards across customers.|
|bin|string|true|none|The card issuer's Bank Identification Number (BIN)|
|card_type|string|false|none|The card type|
|card_category|string|false|none|The card category|
|card_wallet_type|string|false|none|The card wallet type|
|issuer|string|false|none|The name of the card issuer|
|issuer_country|string|false|none|The card issuer's country (two-letter ISO code)|
|product_id|string|false|none|The issuer/card scheme product identifier|
|product_type|string|false|none|The issuer/card scheme product type|
|avs_check|string|false|none|The Address Verification System check result|
|cvv_check|string|false|none|The card verification value (CVV) check result|
|payment_account_reference|string|false|none|A unique reference to the underlying card for network tokens (e.g., Apple Pay, Google Pay)|
|encrypted_card_number|string|false|none|The JWE encrypted full card number that has been updated by real-time account updater.|
|account_update_status|string|false|none|Specifies what card information was updated by the Real-Time Account Updater.|
|account_update_failure_code|string|false|none|Provides the failure code if the Real-Time Account Updater fails to update the card information.|
|account_holder|object|false|none|Information about the account holder of the card|
#### Enumerated Values
|Property|Value|
|---|---|
|type|card|
|card_type|CREDIT|
|card_type|DEBIT|
|card_type|PREPAID|
|card_type|CHARGE|
|card_type|DEFERRED DEBIT|
|card_category|CONSUMER|
|card_category|COMMERCIAL|
|card_wallet_type|applepay|
|card_wallet_type|googlepay|
|account_update_status|card_updated|
|account_update_status|card_expiry_updated|
|account_update_status|card_closed|
|account_update_status|contact_cardholder|
01_ResponseSources_AccountHolderIndividual
```json
{
"type": "individual",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"account_name_inquiry": "full_match",
"account_name_inquiry_details": {
"first_name": "full_match",
"middle_name": "full_match",
"last_name": "full_match"
}
}
```
individual
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of the card account holder|
|first_name|string|true|none|The card account holder's first name
*A valid and legal name must be populated in this field. The populated value cannot be only one character or all non-alphabet.*|
|middle_name|string|false|none|The card account holder's middle name
***Conditional*** - required when the [card metadata](https://api-reference.checkout.com/#operation/requestCardMetadata!c=200&path=issuer_country&t=response) `issuer_country` = `ZA` (South Africa)|
|last_name|string|true|none|The card account holder's last name
*A valid and legal name must be populated in this field. The populated value cannot be only one character or all non-alphabet.*|
|account_name_inquiry|string|true|none|The result of the Account Name Inquiry check.|
|account_name_inquiry_details|[ResponseSources_AccountHolderIndividual_Names_Enquiry](#schemaresponsesources_accountholderindividual_names_enquiry)|false|none|Details of the Account Name Inquiry check.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|individual|
|account_name_inquiry|full_match|
|account_name_inquiry|partial_match|
|account_name_inquiry|no_match|
|account_name_inquiry|not_performed|
|account_name_inquiry|not_supported|
02_ResponseSources_AccountHolderCorporate
```json
{
"type": "corporate",
"company_name": "string",
"account_name_inquiry": "full_match"
}
```
corporate
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of the card account holder|
|company_name|string|true|none|The card account holder's company name
*A valid and legal name must be populated in this field. The populated value cannot be only one character or all non-alphabet.*|
|account_name_inquiry|string|true|none|The Account Name Inquiry check result.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|corporate|
|account_name_inquiry|full_match|
|account_name_inquiry|partial_match|
|account_name_inquiry|no_match|
|account_name_inquiry|not_performed|
|account_name_inquiry|not_supported|
03_ResponseSources_AccountHolderGovernment
```json
{
"type": "government",
"company_name": "string",
"account_name_inquiry": "full_match"
}
```
government
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of the card account holder|
|company_name|string|true|none|The card account holder's company name
*A valid and legal name must be populated in this field. The populated value cannot be only one character or all non-alphabet.*|
|account_name_inquiry|string|true|none|The Account Name Inquiry check result.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|government|
|account_name_inquiry|full_match|
|account_name_inquiry|partial_match|
|account_name_inquiry|no_match|
|account_name_inquiry|not_performed|
|account_name_inquiry|not_supported|
ResponseSources_AccountHolderIndividual_Names_Enquiry
```json
{
"first_name": "full_match",
"middle_name": "full_match",
"last_name": "full_match"
}
```
The granular results of the Account Name Inquiry check performed on the individual that owns the account.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|first_name|string|false|none|The result of the first name check.|
|middle_name|string|false|none|The result of the middle name check.|
|last_name|string|false|none|The result of the last name check.|
#### Enumerated Values
|Property|Value|
|---|---|
|first_name|full_match|
|first_name|partial_match|
|first_name|no_match|
|middle_name|full_match|
|middle_name|partial_match|
|middle_name|no_match|
|last_name|full_match|
|last_name|partial_match|
|last_name|no_match|
RetryGetResponse
```json
{
"enabled": true,
"attempts_made": 0,
"max_attempts": 6,
"ends_on": "2019-08-24T14:15:22Z",
"next_attempt_on": "2019-08-24T14:15:22Z"
}
```
Configuration relating to asynchronous retries
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|enabled|boolean|true|none|Indicates whether asynchronous retries are enabled for the payment.|
|attempts_made|integer|false|none|The number of retries attempted so far.|
|max_attempts|integer|false|none|The maximum number of authorization retry attempts, excluding the initial authorization.|
|ends_on|[Timestamp](#schematimestamp)|false|none|A timestamp that details the date on which the retry schedule expires, in ISO 8601 format.|
|next_attempt_on|[Timestamp](#schematimestamp)|false|none|A timestamp that details the date on which the next authorization attempt will take place, in ISO 8601 format.|
RetryPostResponse
```json
{
"enabled": true,
"max_attempts": 6,
"ends_on": "2019-08-24T14:15:22Z",
"next_attempt_on": "2019-08-24T14:15:22Z"
}
```
Configuration relating to asynchronous retries
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|enabled|boolean|true|none|Indicates whether asynchronous retries are enabled for the payment.|
|max_attempts|integer|false|none|The maximum number of authorization retry attempts, excluding the initial authorization.|
|ends_on|[Timestamp](#schematimestamp)|false|none|A timestamp that details the date on which the retry schedule expires, in ISO 8601 format.|
|next_attempt_on|[Timestamp](#schematimestamp)|false|none|A timestamp of the date on which the next authorization attempt will take place, in ISO 8601 format.|
RetryRequest
```json
{
"enabled": true,
"dunning": {
"enabled": true,
"max_attempts": 6,
"end_after_days": 30
},
"downtime": {
"enabled": true
}
}
```
Configuration of asynchronous retries.
For more information about asynchronous retries and supported response codes, see [Configure scheduled retries](https://www.checkout.com/docs/payments/manage-payments/configure-scheduled-retries).
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|enabled|boolean|true|none|Indicates whether asynchronous retries are enabled for the payment.|
|dunning|[DunningRetryRequest](#schemadunningretryrequest)|false|none|Configuration of asynchronous Dunning retries.|
|downtime|[DowntimeRetryRequest](#schemadowntimeretryrequest)|false|none|Configuration of asynchronous Downtime retries.|
RiskRequest
```json
{
"enabled": false,
"device_session_id": "dsid_ipsmclhxwq72phhr32iwfvrflm",
"device": {
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
"network": {
"ipv4": "63.33.82.13",
"ipv6": "2001:0000:130F:0000:0000:09C0:876A:130B",
"tor": false,
"vpn": false,
"proxy": false
},
"provider": {
"id": "1728646225211.AfUgxG",
"name": "List [ \"merchant\", \"fingerprintjs\", \"riskify\" ]"
},
"timestamp": "2024-02-06T15:00:00.000Z",
"timezone": "60",
"virtual_machine": false,
"incognito": false,
"jailbroken": false,
"rooted": false,
"java_enabled": false,
"javascript_enabled": false,
"language": "FR-fr",
"color_depth": "16",
"screen_height": "1080",
"screen_width": "1920",
"user_agent_client_hint": "string",
"iframe_payment_allowed": true,
"accept_header": "string"
}
}
```
Configures the risk assessment performed during the processing of the payment
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|enabled|boolean|false|none|Whether a risk assessment should be performed|
|device_session_id|string|false|none|Device session ID collected from our standalone Risk.js package. If you integrate using our [Frames](https://www.checkout.com/docs/integrate/frames) solution, this ID is not required.|
|device|[DeviceDetails](#schemadevicedetails)|false|none|Details of the device from which the payment originated.|
Ach
```json
{
"status": "ready",
"flags": [
"string"
],
"account_type": "savings",
"account_holder": {
"type": "individual",
"first_name": "string",
"last_name": "string",
"company_name": "string",
"date_of_birth": "string",
"identification": {
"type": "string",
"issuing_country": "string",
"number": "string"
}
},
"account_number": "string",
"bank_code": "stringst",
"country": "st"
}
```
The ACH payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» account_type|string|false|none|The type of Direct Debit account.|
|» account_holder|object|false|none|The account holder details.|
|»» type|string|false|none|The type of account holder.|
|»» first_name|string|false|none|The first name of the account holder.|
|»» last_name|string|false|none|The last name of the account holder.|
|»» company_name|string|false|none|The legal name of a registered company that holds the account.|
|»» date_of_birth|string|false|none|The account holder's date of birth.|
|»» identification|object|false|write-only|The account holder's government document identification, for example a Social Security Number (SSN).|
|»»» type|string|false|none|The document type.|
|»»» issuing_country|string|false|none|The country where the document was issued.|
|»»» number|string|false|none|The document number.|
|» account_number|string|false|write-only|The account number of the Direct Debit account.|
|» bank_code|string|false|write-only|The bank code of the Direct Debit account.|
|» country|string|false|none|The two-letter ISO country code of the bank account.|
#### Enumerated Values
|Property|Value|
|---|---|
|account_type|savings|
|account_type|current|
|account_type|cash|
|type|individual|
|type|corporate|
|type|government|
AlipayCn
```json
{
"status": "ready",
"flags": [
"string"
],
"terminal_type": "web",
"os_type": "android"
}
```
The Alipay CN payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» terminal_type|[TerminalType](#schematerminaltype)|false|none|The client-side terminal type. Indicates whether the customer is using a PC browser, mobile browser, or mobile application.|
|» os_type|[OsType](#schemaostype)|false|none|The customer's operating system type. Required when `terminal_type` is not `web`.|
AlipayHK
```json
{
"status": "ready",
"flags": [
"string"
],
"terminal_type": "web",
"os_type": "android"
}
```
The Alipay HK payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» terminal_type|[TerminalType](#schematerminaltype)|false|none|The client-side terminal type. Indicates whether the customer is using a PC browser, mobile browser, or mobile application.|
|» os_type|[OsType](#schemaostype)|false|none|The customer's operating system type. Required when `terminal_type` is not `web`.|
Alma
```json
{
"status": "ready",
"flags": [
"string"
]
}
```
The Alma payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
ApplePay
```json
{
"status": "ready",
"flags": [
"string"
],
"token_data": {
"version": "string",
"data": "string",
"signature": "string",
"header": {
"ephemeral_public_key": "string",
"public_key_hash": "string",
"transaction_id": "string"
}
},
"token": {
"id": "string",
"expires_on": "2019-08-24T14:15:22Z"
},
"store_for_future_use": true,
"phone": {
"country_code": "+44",
"number": "207 946 0000"
},
"account_holder": {
"type": "individual",
"first_name": "string",
"last_name": "string",
"middle_name": "string",
"company_name": "string",
"account_name_inquiry": true
},
"schemes": [
"accel"
],
"preferred_scheme": "visa"
}
```
The Apple Pay payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» token_data|object|false|write-only|none|
|»» version|string|false|write-only|The version of the payment token. The token uses `EC_v1` for ECC-encrypted data, and `RSA_v1` for RSA-encrypted data.|
|»» data|string|false|write-only|The encrypted payment data, Base64-encoded.|
|»» signature|string|false|write-only|The signature of the payment and header data. The signature includes the signing certificate, its intermediate CA certificate, and information about the signing algorithm.|
|»» header|object|false|write-only|Additional version-dependent information used to decrypt and verify the payment.|
|»»» ephemeral_public_key|string|false|write-only|none|
|»»» public_key_hash|string|false|write-only|none|
|»»» transaction_id|string|false|write-only|none|
|» token|object|false|none|The Checkout.com Apple Pay token.|
|»» id|string|true|none|The token identifier, prefixed by `tok_`.|
|»» expires_on|string(date-time)|false|none|The date and time the token expires, in ISO 8601 format.|
|» store_for_future_use|boolean|false|write-only|Set to `true` if you intend to reuse the payment credentials in subsequent payments. If set to `false`, a payment instrument will not be included in the payment response.|
|» phone|[PaymentSetupPhone](#schemapaymentsetupphone)|false|none|The customer's phone number.|
|» account_holder|[PaymentSetupAccountHolder](#schemapaymentsetupaccountholder)|false|none|Account holder details for the payment.|
|» schemes|[string]|false|read-only|The list of supported card scheme names.|
|» preferred_scheme|string|false|none|The preferred card scheme to process the payment.|
#### Enumerated Values
|Property|Value|
|---|---|
|preferred_scheme|visa|
|preferred_scheme|mastercard|
|preferred_scheme|cartes_bancaires|
Bacs
```json
{
"status": "ready",
"flags": [
"string"
],
"initialization": "disabled",
"instrument_id": "src_wkq7552u245upl5h75x24554xy",
"account_holder": {
"type": "individual",
"first_name": "string",
"last_name": "string",
"company_name": "string",
"email": "john.smith@example.com"
},
"account_number": "string",
"bank_code": "string",
"country": "st",
"currency": "string",
"allow_partial_match": false
}
```
The Bacs payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentMethodInitialization](#schemapaymentmethodinitialization)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» instrument_id|string|false|read-only|The ID of the Bacs instrument used for the payment.|
|» account_holder|object|false|none|The account holder details.|
|»» type|string|false|none|The type of account holder.|
|»» first_name|string|false|none|The first name of the account holder.|
|»» last_name|string|false|none|The last name of the account holder.|
|»» company_name|string|false|none|The legal name of a registered company that holds the account.|
|»» email|string|false|none|The email address of the account holder.|
|» account_number|string|false|write-only|The account number of the Bacs Direct Debit account.|
|» bank_code|string|false|write-only|The sort code of the Bacs Direct Debit account.|
|» country|string|false|none|The account's country, as an ISO 3166-1 alpha-2 code.|
|» currency|string|false|none|The account holder's account currency.|
|» allow_partial_match|boolean|false|none|Indicates whether the Bacs instrument is created when account validation returns a partial match. When `true`, the instrument is created on a partial match; when `false`, instrument creation fails on a partial match.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|individual|
|type|corporate|
```json
{
"status": "ready",
"flags": [
"string"
],
"account_holder_name": "string"
}
```
The Bancontact payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» account_holder_name|string|false|none|The account holder's name.|
Benefit
```json
{
"status": "ready",
"flags": [
"string"
]
}
```
The Benefit payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
Bizum
```json
{
"status": "ready",
"flags": [
"string"
]
}
```
The Bizum payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
Blik
```json
{
"status": "ready",
"flags": [
"string"
],
"partner_code": "999111"
}
```
The Blik payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» partner_code|string|false|write-only|The 6-digit BLIK code generated by the customer's banking app.|
Card
```json
{
"status": "ready",
"flags": [
"string"
],
"token": {
"id": "string"
},
"details": {
"number": "string",
"last4": "string",
"bin": "string",
"scheme": "string",
"expiry_month": 0,
"expiry_year": 0,
"name": "string",
"cvv": "string",
"stored": true,
"expires_on": "2019-08-24T14:15:22Z",
"allow_update": true
},
"store_for_future_use": true,
"phone": {
"country_code": "+44",
"number": "207 946 0000"
},
"account_holder": {
"type": "individual",
"first_name": "string",
"last_name": "string",
"middle_name": "string",
"company_name": "string",
"account_name_inquiry": true
},
"schemes": [
"accel"
],
"preferred_scheme": "visa"
}
```
The Card payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» token|object|false|none|none|
|»» id|string|false|none|The Checkout.com card token identifier.|
|» details|object|false|none|none|
|»» number|string|false|write-only|The card number (without separators).|
|»» last4|string|false|read-only|The last four digits of the card number.|
|»» bin|string|false|read-only|The card issuer's Bank Identification Number (BIN).|
|»» scheme|string|false|read-only|The card scheme.|
|»» expiry_month|integer|false|none|The expiry month of the card.|
|»» expiry_year|integer|false|none|The expiry year of the card.|
|»» name|string|false|write-only|The cardholder's name.|
|»» cvv|string|false|write-only|The card verification value/code. 3 digits, except for American Express (4 digits).|
|»» stored|boolean|false|write-only|Indicates whether this card is being submitted from your own stored card-on-file system, rather than being entered by the customer at the time of payment. Set to `true` when you provide card details that you already have on file for the customer.|
|»» expires_on|string(date-time)|false|read-only|The time by which the card details must be confirmed.|
|»» allow_update|boolean|false|none|Indicates whether to use the Real-Time Account Updater to update the card information.|
|» store_for_future_use|boolean|false|write-only|Set to `true` if you intend to reuse the payment credentials in subsequent payments. If set to `false`, a payment instrument will not be included in the payment response.|
|» phone|[PaymentSetupPhone](#schemapaymentsetupphone)|false|none|The customer's phone number.|
|» account_holder|[PaymentSetupAccountHolder](#schemapaymentsetupaccountholder)|false|none|Account holder details for the payment.|
|» schemes|[string]|false|read-only|The list of supported card scheme names.|
|» preferred_scheme|string|false|none|The preferred card scheme to process the payment.|
#### Enumerated Values
|Property|Value|
|---|---|
|preferred_scheme|visa|
|preferred_scheme|mastercard|
|preferred_scheme|cartes_bancaires|
CashApp
```json
{
"status": "ready",
"flags": [
"string"
],
"initialization": "disabled",
"customer_profile_sharing": true,
"customer_profile": {
"customer_id": "CST_AYVkuLzfsRqEhf4OyQFxQNv22m7IjNFjO6f2J5CDE2nxAC4-21wJ2H8_2kvsdIsDZMN4",
"cashtag": "$CASHTAG_C_TOKEN",
"reference_id": "value",
"full_name": "John Middle Doe",
"given_name": "John",
"middle_name": "Middle",
"family_name": "Doe",
"suffix": "Jr.",
"birth_date": "1990-01-01",
"address": {
"address_line_1": "123 Main St",
"address_line_2": "string",
"address_line_3": "string",
"locality": "Springfield",
"sublocality": "string",
"administrative_district_level_1": "IL",
"postal_code": "62701",
"country": "US"
},
"phone_number": "5555555555",
"email_address": "cash@cash.com",
"customer_since": "1970-01-18T12:46:04.8Z"
},
"reference": "ORDER-99",
"action": {
"type": "redirect",
"redirect_url": "https://sandbox.api.cash.app/customer-request/v1/requests/GRR_f5xg6wrxhtv3p4w24g0wrexa/interstitial?validity_token=bap03y"
}
}
```
The Cash App payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentMethodInitialization](#schemapaymentmethodinitialization)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» customer_profile_sharing|boolean|false|none|Indicates whether the customer consents to share their Cash App customer profile with Checkout.com.|
|» customer_profile|object|false|read-only|The customer's Cash App profile that they consented to share. Included in the response when `customer_profile_sharing` is enabled.
Cash App releases this profile only once. It's present in the first successful response when you get the Payment Setup after the customer authorizes the payment. Every subsequent response omits it.|
|»» customer_id|string|false|none|Cash App's identifier for the customer. This is not a Checkout.com customer identifier.|
|»» cashtag|string|false|none|The customer's `$Cashtag`.|
|»» reference_id|string|false|none|Cash App's reference for the customer profile.|
|»» full_name|string|false|none|The customer's full name.|
|»» given_name|string|false|none|The customer's given name.|
|»» middle_name|string|false|none|The customer's middle name.|
|»» family_name|string|false|none|The customer's family name.|
|»» suffix|string|false|none|The suffix of the customer's name.|
|»» birth_date|string(date)|false|none|The customer's date of birth.|
|»» address|object|false|none|The customer's address.|
|»»» address_line_1|string|false|none|The first line of the address.|
|»»» address_line_2|string|false|none|The second line of the address.|
|»»» address_line_3|string|false|none|The third line of the address.|
|»»» locality|string|false|none|The address locality, such as the city or town.|
|»»» sublocality|string|false|none|The address sublocality, such as the district or neighborhood.|
|»»» administrative_district_level_1|string|false|none|The address's top-level administrative district, such as the state or province.|
|»»» postal_code|string|false|none|The postal or zip code.|
|»»» country|string|false|none|The address country, in ISO 3166-1 alpha-2 format.|
|»» phone_number|string|false|none|The customer's phone number.|
|»» email_address|string|false|none|The customer's email address.|
|»» customer_since|string(date-time)|false|none|The date and time the customer's Cash App account was created.|
|» reference|string|false|read-only|A reference for the Cash App Pay transaction, returned by the provider.|
|» action|object|false|read-only|The next available action for the payment method.|
|»» type|string|false|none|The type of action.|
|»» redirect_url|string(uri)|false|none|The URL to redirect the customer to so they can authorize the payment with Cash App.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|redirect|
Dana
```json
{
"status": "ready",
"flags": [
"string"
],
"terminal_type": "web",
"os_type": "android"
}
```
The Dana payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» terminal_type|[TerminalType](#schematerminaltype)|false|none|The client-side terminal type. Indicates whether the customer is using a PC browser, mobile browser, or mobile application.|
|» os_type|[OsType](#schemaostype)|false|none|The customer's operating system type. Required when `terminal_type` is not `web`.|
Eps
```json
{
"status": "ready",
"flags": [
"string"
]
}
```
The EPS payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
GCash
```json
{
"status": "ready",
"flags": [
"string"
],
"terminal_type": "web",
"os_type": "android"
}
```
The GCash payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» terminal_type|[TerminalType](#schematerminaltype)|false|none|The client-side terminal type. Indicates whether the customer is using a PC browser, mobile browser, or mobile application.|
|» os_type|[OsType](#schemaostype)|false|none|The customer's operating system type. Required when `terminal_type` is not `web`.|
GooglePay
```json
{
"status": "ready",
"flags": [
"string"
],
"token_data": {
"protocol_version": "string",
"signature": "string",
"signed_message": "string",
"tokenization_key": "string"
},
"token": {
"id": "string",
"expires_on": "2019-08-24T14:15:22Z"
},
"store_for_future_use": true,
"phone": {
"country_code": "+44",
"number": "207 946 0000"
},
"account_holder": {
"type": "individual",
"first_name": "string",
"last_name": "string",
"middle_name": "string",
"company_name": "string",
"account_name_inquiry": true
},
"schemes": [
"accel"
],
"preferred_scheme": "visa"
}
```
The Google Pay payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» token_data|object|false|write-only|none|
|»» protocol_version|string|false|write-only|The encryption and signing scheme used to create this message. If not set, the default is `ECv0`.|
|»» signature|string|false|write-only|The signature that verifies the message came from Google, created using `ECDSA`.|
|»» signed_message|string|false|write-only|A serialized JSON string containing the `encryptedMessage`, `ephemeralPublicKey`, and `tag`. To simplify the signature verification process, this value is serialized.|
|»» tokenization_key|string|false|write-only|The public key provided to the Google API in the `tokenizationSpecification.parameters.gatewayMerchantId` field.|
|» token|object|false|none|The Checkout.com Google Pay token.|
|»» id|string|true|none|The token identifier, prefixed by `tok_`.|
|»» expires_on|string(date-time)|false|none|The date and time the token expires, in ISO 8601 format.|
|» store_for_future_use|boolean|false|write-only|Set to `true` if you intend to reuse the payment credentials in subsequent payments. If set to `false`, a payment instrument will not be included in the payment response.|
|» phone|[PaymentSetupPhone](#schemapaymentsetupphone)|false|none|The customer's phone number.|
|» account_holder|[PaymentSetupAccountHolder](#schemapaymentsetupaccountholder)|false|none|Account holder details for the payment.|
|» schemes|[string]|false|read-only|The list of supported card scheme names.|
|» preferred_scheme|string|false|none|The preferred card scheme to process the payment.|
#### Enumerated Values
|Property|Value|
|---|---|
|preferred_scheme|visa|
|preferred_scheme|mastercard|
Ideal
```json
{
"status": "ready",
"flags": [
"string"
],
"description": "2 t-shirts"
}
```
The iDEAL payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» description|string|false|none|A description of the products or services being paid for. Do not include HTML tags or special characters, as these are rejected by iDEAL.|
KakaoPay
```json
{
"status": "ready",
"flags": [
"string"
],
"terminal_type": "web",
"os_type": "android"
}
```
The KakaoPay payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» terminal_type|[TerminalType](#schematerminaltype)|false|none|The client-side terminal type. Indicates whether the customer is using a PC browser, mobile browser, or mobile application.|
|» os_type|[OsType](#schemaostype)|false|none|The customer's operating system type. Required when `terminal_type` is not `web`.|
Klarna
```json
{
"status": "ready",
"flags": [
"string"
],
"initialization": "disabled",
"action": {
"type": "sdk",
"client_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ewogICJzZXNzaW9uX2lkIiA6ICIw",
"session_id": "0b1d9815-165e-42e2-8867-35bc03789e00"
},
"account_holder": {
"name": "string"
},
"iban": "DE89370400440532013000"
}
```
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentMethodInitialization](#schemapaymentmethodinitialization)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|The Klarna payment method's details and configuration.|
|» action|object|false|read-only|The next available action for the payment method.|
|»» type|string|false|none|The type of action.|
|»» client_token|string|false|none|The client token for the Klarna SDK.|
|»» session_id|string|false|none|The session ID.|
|» account_holder|[KlarnaAccountHolder](#schemaklarnaaccountholder)|false|read-only|The account holder details returned by Klarna after the shopper completes verification.|
|» iban|string|false|read-only|The IBAN of the account used to complete Klarna verification.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|sdk|
KlarnaAccountHolder
```json
{
"name": "string"
}
```
The account holder details returned by Klarna after the shopper completes verification.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|false|none|The full name of the account holder.|
Knet
```json
{
"status": "ready",
"flags": [
"string"
],
"language": "en"
}
```
The KNET payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» language|string|false|none|The customer's preferred language, as an ISO 639-1 code. For example, the language selected on your site, if the issuer's site supports it.
- `ar` - Arabic
- `en` - English|
#### Enumerated Values
|Property|Value|
|---|---|
|language|en|
|language|ar|
MBWay
```json
{
"status": "ready",
"flags": [
"string"
]
}
```
The MBWay payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
MobilePay
```json
{
"status": "ready",
"flags": [
"string"
]
}
```
The MobilePay payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
Multibanco
```json
{
"status": "ready",
"flags": [
"string"
],
"account_holder_name": "string"
}
```
The Multibanco payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» account_holder_name|string|false|none|The account holder's name.|
Octopus
```json
{
"status": "ready",
"flags": [
"string"
]
}
```
The Octopus payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
OrderItem
```json
{
"name": "Battery Power Pack",
"quantity": 1,
"unit_price": 1000,
"total_amount": 1000,
"reference": "BA67A",
"discount_amount": 150,
"url": "https://example.com/products/my-item",
"image_url": "https://example.com/products/my-item/image",
"type": "digital"
}
```
A line item from the customer's order.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|false|none|The descriptive name of the line item.|
|quantity|integer|false|none|The quantity of the line item.|
|unit_price|number|false|none|The unit price of the line item, in minor currency units.|
|total_amount|number|false|none|The total cost of the line item, in minor currency units.
Include any tax and discounts applied, using the formula: `value = (quantity x unit_price) - discount_amount`.|
|reference|string|false|none|The line item reference or product stock keeping unit (SKU).|
|discount_amount|number|false|none|The discount applied to each invoice line item.|
|url|string|false|none|Link to the line item's product page.|
|image_url|string|false|none|Link to the item image to show in the order confirmation.|
|type|string|false|none|The item type. For example, physical or digital.|
OsType
```json
"android"
```
The customer's operating system type. Required when `terminal_type` is not `web`.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The customer's operating system type. Required when `terminal_type` is not `web`.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|android|
|*anonymous*|ios|
P24
```json
{
"status": "ready",
"flags": [
"string"
],
"account_holder": {
"name": "string",
"email": "user@example.com"
}
}
```
The P24 (Przelewy24) payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» account_holder|object|false|none|The account holder's details.|
|»» name|string|false|none|The account holder's name.|
|»» email|string(email)|false|none|The account holder's email address.|
PayByBank
```json
{
"status": "ready",
"flags": [
"string"
],
"bank_id": "ob-natwest",
"action": {
"type": "select_bank",
"banks": [
{
"bank_id": "ob-natwest",
"display_name": "NatWest",
"logo_url": "https://cdn.token.io/banks/natwest.png",
"available": true
}
]
}
}
```
The Pay by Bank (Open Banking) payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» bank_id|string|false|none|The identifier of the bank the customer has selected for the payment.|
|» action|object|false|read-only|The next available action for the payment method.|
|»» type|string|false|none|The type of action.|
|»» banks|[object]|false|none|The list of banks available for the customer to select.|
|»»» bank_id|string|false|none|The unique identifier of the bank.|
|»»» display_name|string|false|none|The display name of the bank.|
|»»» logo_url|string|false|none|The URL of the bank's logo.|
|»»» available|boolean|false|none|Whether the bank is currently available for selection.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|select_bank|
PaymentMethodFlags
```json
[
"string"
]
```
The list of error codes or indicators that highlight missing or invalid information.
### Properties
*None*
PaymentMethodInitialization
```json
{
"initialization": "disabled"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|initialization|string|false|none|The initialization state of the payment method.
When you create a Payment Setup, this defaults to `disabled`.|
#### Enumerated Values
|Property|Value|
|---|---|
|initialization|disabled|
|initialization|enabled|
PaymentMethodStatus
```json
"ready"
```
The payment method status.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|read-only|The payment method status.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|unavailable|
|*anonymous*|action_required|
|*anonymous*|ready|
|*anonymous*|initialization_required|
|*anonymous*|invalid|
PaymentSetup
```json
{
"id": "string",
"processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
"amount": 10000,
"currency": "GBP",
"presentment_details": {
"amount": 110,
"currency": "EUR"
},
"payment_type": "regular",
"reference": "REF-0987-475",
"description": "Set of 3 t-shirts",
"payment_methods": {
"auto_confirm": "card",
"instrument": {
"status": "ready",
"flags": [
"string"
],
"id": "src_wmlfc3zttb4uzmk6snpwb43jbi",
"type": "bacs",
"action": {
"type": "set_instrument"
}
},
"klarna": {
"status": "ready",
"flags": [
"string"
],
"initialization": "disabled",
"action": {
"type": "sdk",
"client_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ewogICJzZXNzaW9uX2lkIiA6ICIw",
"session_id": "0b1d9815-165e-42e2-8867-35bc03789e00"
},
"account_holder": {
"name": "string"
},
"iban": "DE89370400440532013000"
},
"stcpay": {
"status": "ready",
"flags": [
"string"
],
"initialization": "disabled",
"otp": "123456",
"action": {
"type": "otp"
}
},
"tabby": {
"status": "ready",
"flags": [
"string"
],
"initialization": "disabled",
"payment_types": [
"pay_later"
]
},
"bizum": {
"status": "ready",
"flags": [
"string"
]
},
"paynow": {
"status": "ready",
"flags": [
"string"
]
},
"qpay": {
"status": "ready",
"flags": [
"string"
],
"national_id": "21234567890",
"description": "string"
},
"eps": {
"status": "ready",
"flags": [
"string"
]
},
"ideal": {
"status": "ready",
"flags": [
"string"
],
"description": "2 t-shirts"
},
"knet": {
"status": "ready",
"flags": [
"string"
],
"language": "en"
},
"bancontact": {
"status": "ready",
"flags": [
"string"
],
"account_holder_name": "string"
},
"benefit": {
"status": "ready",
"flags": [
"string"
]
},
"blik": {
"status": "ready",
"flags": [
"string"
],
"partner_code": "999111"
},
"vipps": {
"status": "ready",
"flags": [
"string"
]
},
"twint": {
"status": "ready",
"flags": [
"string"
]
},
"alipay_cn": {
"status": "ready",
"flags": [
"string"
],
"terminal_type": "web",
"os_type": "android"
},
"alipay_hk": {
"status": "ready",
"flags": [
"string"
],
"terminal_type": "web",
"os_type": "android"
},
"gcash": {
"status": "ready",
"flags": [
"string"
],
"terminal_type": "web",
"os_type": "android"
},
"tng": {
"status": "ready",
"flags": [
"string"
],
"terminal_type": "web",
"os_type": "android"
},
"dana": {
"status": "ready",
"flags": [
"string"
],
"terminal_type": "web",
"os_type": "android"
},
"mobilepay": {
"status": "ready",
"flags": [
"string"
]
},
"tamara": {
"status": "ready",
"flags": [
"string"
],
"initialization": "disabled",
"risk_assessment": {
"premium_customer": false,
"risk_score": 42,
"order_count_last24h": 0,
"linked_device_count": 2
}
},
"mbway": {
"status": "ready",
"flags": [
"string"
]
},
"multibanco": {
"status": "ready",
"flags": [
"string"
],
"account_holder_name": "string"
},
"wechatpay": {
"status": "ready",
"flags": [
"string"
]
},
"kakaopay": {
"status": "ready",
"flags": [
"string"
],
"terminal_type": "web",
"os_type": "android"
},
"truemoney": {
"status": "ready",
"flags": [
"string"
],
"terminal_type": "web",
"os_type": "android"
},
"octopus": {
"status": "ready",
"flags": [
"string"
]
},
"p24": {
"status": "ready",
"flags": [
"string"
],
"account_holder": {
"name": "string",
"email": "user@example.com"
}
},
"alma": {
"status": "ready",
"flags": [
"string"
]
},
"swish": {
"status": "ready",
"flags": [
"string"
],
"billing_descriptor": "string",
"account_holder": {
"first_name": "John",
"last_name": "Smith"
}
},
"sequra": {
"status": "ready",
"flags": [
"string"
]
},
"ach": {
"status": "ready",
"flags": [
"string"
],
"account_type": "savings",
"account_holder": {
"type": "individual",
"first_name": "string",
"last_name": "string",
"company_name": "string",
"date_of_birth": "string",
"identification": {
"type": "string",
"issuing_country": "string",
"number": "string"
}
},
"account_number": "string",
"bank_code": "stringst",
"country": "st"
},
"sepa": {
"status": "ready",
"flags": [
"string"
],
"account_holder": {
"type": "individual",
"first_name": "string",
"last_name": "string",
"company_name": "string"
},
"account_number": "string",
"country": "st",
"currency": "string",
"mandate": {
"id": "string",
"type": "core",
"date_of_signature": "2019-08-24"
}
},
"bacs": {
"status": "ready",
"flags": [
"string"
],
"initialization": "disabled",
"instrument_id": "src_wkq7552u245upl5h75x24554xy",
"account_holder": {
"type": "individual",
"first_name": "string",
"last_name": "string",
"company_name": "string",
"email": "john.smith@example.com"
},
"account_number": "string",
"bank_code": "string",
"country": "st",
"currency": "string",
"allow_partial_match": false
},
"paybybank": {
"status": "ready",
"flags": [
"string"
],
"bank_id": "ob-natwest",
"action": {
"type": "select_bank",
"banks": [
{
"bank_id": "ob-natwest",
"display_name": "NatWest",
"logo_url": "https://cdn.token.io/banks/natwest.png",
"available": true
}
]
}
},
"paypal": {
"status": "ready",
"flags": [
"string"
],
"initialization": "disabled",
"user_action": "pay_now",
"brand_name": "Acme Corporation",
"shipping_preference": "no_shipping",
"action": {
"type": "sdk",
"order_id": "dd4b1a85-31de-404b-99f4-f143f8ba35ba"
}
},
"cashapp": {
"status": "ready",
"flags": [
"string"
],
"initialization": "disabled",
"customer_profile_sharing": true,
"customer_profile": {
"customer_id": "CST_AYVkuLzfsRqEhf4OyQFxQNv22m7IjNFjO6f2J5CDE2nxAC4-21wJ2H8_2kvsdIsDZMN4",
"cashtag": "$CASHTAG_C_TOKEN",
"reference_id": "value",
"full_name": "John Middle Doe",
"given_name": "John",
"middle_name": "Middle",
"family_name": "Doe",
"suffix": "Jr.",
"birth_date": "1990-01-01",
"address": {
"address_line_1": "123 Main St",
"address_line_2": "string",
"address_line_3": "string",
"locality": "Springfield",
"sublocality": "string",
"administrative_district_level_1": "IL",
"postal_code": "62701",
"country": "US"
},
"phone_number": "5555555555",
"email_address": "cash@cash.com",
"customer_since": "1970-01-18T12:46:04.8Z"
},
"reference": "ORDER-99",
"action": {
"type": "redirect",
"redirect_url": "https://sandbox.api.cash.app/customer-request/v1/requests/GRR_f5xg6wrxhtv3p4w24g0wrexa/interstitial?validity_token=bap03y"
}
},
"googlepay": {
"status": "ready",
"flags": [
"string"
],
"token_data": {
"protocol_version": "string",
"signature": "string",
"signed_message": "string",
"tokenization_key": "string"
},
"token": {
"id": "string",
"expires_on": "2019-08-24T14:15:22Z"
},
"store_for_future_use": true,
"phone": {
"country_code": "+44",
"number": "207 946 0000"
},
"account_holder": {
"type": "individual",
"first_name": "string",
"last_name": "string",
"middle_name": "string",
"company_name": "string",
"account_name_inquiry": true
},
"schemes": [
"accel"
],
"preferred_scheme": "visa"
},
"applepay": {
"status": "ready",
"flags": [
"string"
],
"token_data": {
"version": "string",
"data": "string",
"signature": "string",
"header": {
"ephemeral_public_key": "string",
"public_key_hash": "string",
"transaction_id": "string"
}
},
"token": {
"id": "string",
"expires_on": "2019-08-24T14:15:22Z"
},
"store_for_future_use": true,
"phone": {
"country_code": "+44",
"number": "207 946 0000"
},
"account_holder": {
"type": "individual",
"first_name": "string",
"last_name": "string",
"middle_name": "string",
"company_name": "string",
"account_name_inquiry": true
},
"schemes": [
"accel"
],
"preferred_scheme": "visa"
},
"card": {
"status": "ready",
"flags": [
"string"
],
"token": {
"id": "string"
},
"details": {
"number": "string",
"last4": "string",
"bin": "string",
"scheme": "string",
"expiry_month": 0,
"expiry_year": 0,
"name": "string",
"cvv": "string",
"stored": true,
"expires_on": "2019-08-24T14:15:22Z",
"allow_update": true
},
"store_for_future_use": true,
"phone": {
"country_code": "+44",
"number": "207 946 0000"
},
"account_holder": {
"type": "individual",
"first_name": "string",
"last_name": "string",
"middle_name": "string",
"company_name": "string",
"account_name_inquiry": true
},
"schemes": [
"accel"
],
"preferred_scheme": "visa"
},
"stablecoin": {
"status": "ready",
"flags": [
"string"
]
}
},
"available_payment_methods": [
"card",
"klarna",
"stcpay",
"stablecoin"
],
"settings": {
"success_url": "https://example.com/payments/success",
"failure_url": "https://example.com/payments/fail",
"capture": true,
"excluded_payment_methods": [
"card",
"klarna",
"stcpay"
]
},
"risk": {
"enabled": true
},
"customer": {
"country": "GB",
"id": "cus_123456789",
"email": {
"address": "johnsmith@example.com",
"verified": true
},
"name": "John Smith",
"tax_number": "GB123456789",
"phone": {
"country_code": "+44",
"number": "207 946 0000"
},
"device": {
"locale": "en_GB",
"fingerprint": "fp_abc123xyz",
"ipv4": "203.0.113.0",
"ipv6": "2001:db8:85a3::8a2e:370:7334",
"client": "web",
"os": "android"
},
"merchant_account": {
"id": "1234",
"registration_date": "2023-05-01",
"last_modified": "2023-05-01",
"returning_customer": true,
"first_transaction_date": "2023-09-15",
"last_transaction_date": "2025-03-28",
"total_order_count": 6,
"last_payment_amount": 55.99
}
},
"order": {
"items": [
{
"name": "Battery Power Pack",
"quantity": 1,
"unit_price": 1000,
"total_amount": 1000,
"reference": "BA67A",
"discount_amount": 150,
"url": "https://example.com/products/my-item",
"image_url": "https://example.com/products/my-item/image",
"type": "digital"
}
],
"shipping": {
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@example.com",
"phone": {
"country_code": "+44",
"number": "207 946 0000"
},
"address": {
"address_line1": "10 Canterbury Road",
"address_line2": "Flat 2",
"city": "London",
"state": "Greater London",
"zip": "NE1 1KO",
"country": "GB"
},
"method": "string",
"delay": 3
},
"sub_merchants": [
{
"id": "SUB12345",
"product_category": "Electronics",
"number_of_sales": 500,
"registration_date": "2023-01-15"
}
],
"invoice_id": "inv_123456789",
"shipping_amount": 5,
"discount_amount": 10,
"tax_amount": 2,
"tipping_amount": 2,
"surcharge_amount": 2,
"amount_allocations": [
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4",
"amount": 1000,
"reference": "ORD-5023-4E89",
"commission": {
"amount": 1000,
"percentage": 1.125
}
}
]
},
"billing": {
"address": {
"address_line1": "10 Canterbury Road",
"address_line2": "Flat 2",
"city": "London",
"state": "Greater London",
"zip": "NE1 1KO",
"country": "GB"
}
},
"industry": {
"airline": [
{
"ticket": {
"number": "0742464639523",
"issue_date": "2025-05-01",
"issuing_carrier_code": "042",
"travel_package_indicator": "A",
"travel_agency_name": "Checkout Travel Agents",
"travel_agency_code": "91114362"
},
"passengers": [
{
"first_name": "John",
"last_name": "Smith",
"date_of_birth": "1990-10-31",
"address": {
"country": "GB"
}
}
],
"flight_leg_details": [
{
"flight_number": "BA1483",
"carrier_code": "BA",
"class_of_travelling": "W",
"departure_airport": "LHR",
"departure_date": "2025-10-13",
"departure_time": "18:30",
"arrival_airport": "JFK",
"stop_over_code": "X",
"fare_basis_code": "WUP14B"
}
],
"total_number_of_passengers": 1,
"travel_type": "international",
"trip_type": "one_way",
"refundable": true,
"delivery_recipient": "jane.smith@example.com",
"ancillaries": "extra_baggage",
"insurance": {
"type": "travel",
"company": "AXA",
"price": {
"amount": 500,
"currency": "SAR"
}
}
}
],
"accommodation": [
{
"name": "Checkout Lodge",
"booking_reference": "REF9083748",
"check_in_date": "2025-04-11",
"check_out_date": "2025-04-18",
"address": {
"address_line1": "123 High Street",
"city": "London",
"state": "Greater London",
"country": "GB",
"zip": "NE1 1CK"
},
"number_of_rooms": 2,
"guests": [
{
"first_name": "John",
"last_name": "Smith",
"date_of_birth": "1970-03-19"
}
],
"room": [
{
"rate": 42.3,
"number_of_nights": 5,
"type": "deluxe"
}
],
"total_number_of_guests": 2,
"refundable": true,
"delivery_recipient": "jane.smith@example.com",
"host": {
"registration_date": "2020-01-01",
"total_reservation_count": 150
}
}
]
},
"account_funding_transaction": {
"enabled": true,
"purpose": "financial_services",
"sender": {
"date_of_birth": "2000-01-01",
"reference": "0fc88634-78c1-4286-9cb6-6ca358730c8c",
"identification": {
"type": "passport",
"number": "1234567890",
"issuing_country": "US"
}
},
"recipient": {
"date_of_birth": "2000-01-01",
"account_number": "string",
"first_name": "string",
"last_name": "string",
"address": {
"address_line1": "10 Canterbury Road",
"address_line2": "Flat 2",
"city": "London",
"state": "Greater London",
"zip": "NE1 1KO",
"country": "GB"
}
}
},
"terminal": {
"id": "12345678",
"local_date_time": "2026-05-26T13:05:14+01:00"
},
"billing_descriptor": {
"name": "Checkout.com",
"city": "London",
"reference": "Payment for order 123456"
},
"metadata": {
"property1": "string",
"property2": "string"
},
"latest_payment": {
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"requested_on": "2019-08-24T14:15:22Z",
"source": {
"type": "card",
"id": "src_nwd3m4in3hkuddfpjsaevunhdy",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"expiry_month": 6,
"expiry_year": 2025,
"name": "Bruce Wayne",
"scheme": "VISA",
"scheme_local": "Cartes_Bancaires",
"local_schemes": [
"cartes_bancaires",
"visa"
],
"last4": "9996",
"fingerprint": "F639CAB2745BEE4140BF86DF6B6D6",
"bin": "45434748",
"card_type": "CREDIT",
"card_category": "CONSUMER",
"card_wallet_type": "applepay",
"issuer": "GOTHAM STATE BANK",
"issuer_country": "US",
"product_id": "F",
"product_type": "CLASSIC",
"avs_check": "S",
"cvv_check": "Y",
"payment_account_reference": "EUNIX9AX7THOOJIEJ2AP6OOFAHGH4",
"encrypted_card_number": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz...",
"account_update_status": "card_updated",
"account_update_failure_code": "VAU009",
"account_holder": {}
},
"destination": {
"type": "bank_account",
"id": "string"
},
"amount": 6540,
"amount_requested": 6540,
"currency": "USD",
"payment_type": "Recurring",
"payment_plan": {
"amount_variability": "Variable",
"days_between_payments": 28,
"total_number_of_payments": 5,
"current_payment_number": 3,
"expiry": "20251031",
"name": "Subscription 1234",
"start_date": "20260507",
"amount": 1234
},
"reference": "ORD-5023-4E89",
"description": "Set of 3 masks",
"approved": true,
"expires_on": "string",
"status": "Authorized",
"balances": {
"total_authorized": 6540,
"total_voided": 0,
"available_to_void": 6540,
"total_captured": 0,
"available_to_capture": 6540,
"total_refunded": 0,
"available_to_refund": 0
},
"3ds": {
"downgraded": false,
"enrolled": "Y",
"signature_valid": "Y",
"authentication_response": "Y",
"authentication_status_reason": "string",
"cryptogram": "hv8mUFzPzRZoCAAAAAEQBDMAAAA=",
"xid": "MDAwMDAwMDAwMDAwMDAwMzIyNzY=",
"eci": "string",
"version": "2.1.0",
"exemption": "low_value",
"exemption_applied": "string",
"challenged": true,
"upgrade_reason": "sca_retry",
"trusted_listing": {
"status": "Y",
"source": "01"
}
},
"authentication": {
"experience": "3ds"
},
"risk": {
"flagged": true,
"score": 22
},
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "brucewayne@gmail.com",
"name": "Bruce Wayne",
"summary": {
"registration_date": "2023-05-01",
"first_transaction_date": "2023-07-01",
"last_payment_date": "2023-08-01",
"total_order_count": 15,
"last_payment_amount": 500,
"is_premium_customer": true,
"is_returning_customer": true,
"lifetime_value": 500
}
},
"billing_descriptor": {
"name": "SUPERHEROES.COM",
"city": "GOTHAM",
"reference": "string",
"local_descriptors": [
{
"name": "漢字",
"character_set": "kanji"
}
]
},
"shipping": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"payment_ip": "90.197.169.245",
"sender": {
"type": "individual",
"reference": "8285282045818",
"first_name": "John",
"last_name": "Jones",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"amount_allocations": [
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4",
"amount": 1000,
"reference": "ORD-5023-4E89",
"commission": {
"amount": 1000,
"percentage": 1.125
}
}
],
"recipient": {
"dob": "1985-05-15",
"account_number": "5555554444",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"zip": "SW1A",
"first_name": "John",
"last_name": "Jones"
},
"processing": {
"preferred_scheme": "cartes_bancaires",
"app_id": "com.iap.linker_portal",
"airline_data": [
{
"ticket": {
"number": "045-21351455613",
"issue_date": "2023-05-20",
"issuing_carrier_code": "AI",
"travel_package_indicator": "B",
"travel_agency_name": "World Tours",
"travel_agency_code": "01"
},
"passenger": [
{
"first_name": "John",
"last_name": "White",
"date_of_birth": "1990-05-26",
"address": {
"country": "US"
}
}
],
"flight_leg_details": [
{
"flight_number": "101",
"carrier_code": "BA",
"class_of_travelling": "J",
"departure_airport": "LHR",
"departure_date": "2023-06-19",
"departure_time": "15:30",
"arrival_airport": "LAX",
"stop_over_code": "x",
"fare_basis_code": "SPRSVR"
}
]
}
],
"accommodation_data": [
{
"name": "The Sea View Hotel",
"booking_reference": "HOTEL123",
"check_in_date": "2023-06-20",
"check_out_date": "2023-06-23",
"address": {
"address_line1": "123 Beach Road",
"zip": "10001"
},
"state": "FL",
"country": "USA",
"city": "Los Angeles",
"number_of_rooms": 2,
"guests": [
{
"first_name": "Jane",
"last_name": "Doe",
"date_of_birth": "1985-07-14"
}
],
"room": [
{
"rate": "70",
"number_of_nights_at_room_rate": "3"
}
],
"property_phone": [
{
"country_code": "44",
"number": "7123456789"
}
],
"customer_service_phone": [
{
"country_code": "44",
"number": "7123456789"
}
]
}
],
"partner_customer_id": "2102209000001106125F8",
"partner_payment_id": "440644309099499894406",
"partner_code": "999111",
"failure_code": "partner_error",
"partner_response_code": "ER_WRONG_TICKET",
"tax_amount": 1000,
"locale": "en-US",
"retrieval_reference_number": "909913440644",
"partner_order_id": "string",
"partner_status": "string",
"partner_transaction_id": "string",
"partner_error_codes": [
"string"
],
"partner_merchant_advice_code": "24",
"partner_error_message": "string",
"partner_authorization_code": "string",
"partner_authorization_response_code": "string",
"partner_fraud_status": "string",
"pan_type_processed": "fpan",
"fallback_source_used": false,
"custom_payment_method_ids": [
"string"
],
"aft": true,
"merchant_category_code": "5311",
"scheme_merchant_id": "123456",
"scheme": "ACCEL",
"scheme_transaction_link_id": "string"
},
"items": [
{
"type": "digital",
"sub_type": "stablecoin",
"name": "Necklace",
"quantity": 2,
"unit_price": 50,
"reference": "858818ac",
"commodity_code": "DEF123",
"unit_of_measure": "metres",
"total_amount": 29000,
"tax_rate": 2000,
"tax_amount": 1000,
"tax_exempt": true,
"discount_amount": 1000,
"wxpay_goods_id": "1001",
"url": "string",
"image_url": "string",
"service_ends_on": "2025-01-01",
"purchase_country": "GB",
"foreign_retailer_amount": 200
}
],
"metadata": {
"coupon_code": "NY2018",
"partner_id": 123989
},
"eci": "06",
"scheme_id": "488341541494658",
"actions": [
{
"id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
"type": "Authorization",
"response_code": "10000",
"response_summary": "Approved"
}
],
"retry": {
"enabled": true,
"attempts_made": 0,
"max_attempts": 6,
"ends_on": "2019-08-24T14:15:22Z",
"next_attempt_on": "2019-08-24T14:15:22Z"
},
"cko_network_token_available": false,
"instruction": {
"purpose": "financial_services"
},
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
},
"actions": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/actions"
},
"authorize": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/authorizations"
},
"refund": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/refund"
}
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|read-only|none|
|processing_channel_id|string|true|none|The processing channel to use for the payment.|
|amount|number|true|none|The payment amount, in the minor currency unit.|
|currency|string|true|none|The currency of the payment, as a three-letter ISO currency code.|
|presentment_details|[PaymentSetupPresentmentDetails](#schemapaymentsetuppresentmentdetails)|false|none|The amount and currency to present to the customer, when the settlement
currency differs from the customer-facing currency.|
|payment_type|string|false|none|The type of payment.
You must provide this field for card payments in which the cardholder is not present. For example, if the transaction is a recurring payment, or a mail order/telephone order (MOTO) payment.|
|reference|string|false|none|A reference you can use to identify the payment. For example, an order number.|
|description|string|false|none|A description of the payment.|
|payment_methods|object|false|none|The payment methods that are enabled on your account and available for use.|
|» auto_confirm|string|false|none|The payment method that automatically confirms the payment when it is ready.|
|» instrument|[PaymentSetupInstrument](#schemapaymentsetupinstrument)|false|none|The instrument payment method's details and configuration.|
|» klarna|[Klarna](#schemaklarna)|false|none|none|
|» stcpay|[StcPay](#schemastcpay)|false|none|The stc pay payment method's details and configuration.|
|» tabby|[Tabby](#schematabby)|false|none|The Tabby payment method's details and configuration.|
|» bizum|[Bizum](#schemabizum)|false|read-only|The Bizum payment method's details and configuration.|
|» paynow|[PayNow](#schemapaynow)|false|read-only|The PayNow payment method's details and configuration.|
|» qpay|[Qpay](#schemaqpay)|false|none|The QPay payment method's details and configuration.|
|» eps|[Eps](#schemaeps)|false|read-only|The EPS payment method's details and configuration.|
|» ideal|[Ideal](#schemaideal)|false|none|The iDEAL payment method's details and configuration.|
|» knet|[Knet](#schemaknet)|false|none|The KNET payment method's details and configuration.|
|» bancontact|[Bancontact](#schemabancontact)|false|none|The Bancontact payment method's details and configuration.|
|» benefit|[Benefit](#schemabenefit)|false|read-only|The Benefit payment method's details and configuration.|
|» blik|[Blik](#schemablik)|false|none|The Blik payment method's details and configuration.|
|» vipps|[Vipps](#schemavipps)|false|read-only|The Vipps payment method's details and configuration.|
|» twint|[Twint](#schematwint)|false|read-only|The Twint payment method's details and configuration.|
|» alipay_cn|[AlipayCn](#schemaalipaycn)|false|none|The Alipay CN payment method's details and configuration.|
|» alipay_hk|[AlipayHK](#schemaalipayhk)|false|none|The Alipay HK payment method's details and configuration.|
|» gcash|[GCash](#schemagcash)|false|none|The GCash payment method's details and configuration.|
|» tng|[Tng](#schematng)|false|none|The TNG payment method's details and configuration.|
|» dana|[Dana](#schemadana)|false|none|The Dana payment method's details and configuration.|
|» mobilepay|[MobilePay](#schemamobilepay)|false|read-only|The MobilePay payment method's details and configuration.|
|» tamara|[Tamara](#schematamara)|false|none|The Tamara payment method's details and configuration.|
|» mbway|[MBWay](#schemambway)|false|read-only|The MBWay payment method's details and configuration.|
|» multibanco|[Multibanco](#schemamultibanco)|false|none|The Multibanco payment method's details and configuration.|
|» wechatpay|[WeChatPay](#schemawechatpay)|false|read-only|The WeChatPay payment method's details and configuration.|
|» kakaopay|[KakaoPay](#schemakakaopay)|false|none|The KakaoPay payment method's details and configuration.|
|» truemoney|[TrueMoney](#schematruemoney)|false|none|The TrueMoney payment method's details and configuration.|
|» octopus|[Octopus](#schemaoctopus)|false|read-only|The Octopus payment method's details and configuration.|
|» p24|[P24](#schemap24)|false|none|The P24 (Przelewy24) payment method's details and configuration.|
|» alma|[Alma](#schemaalma)|false|none|The Alma payment method's details and configuration.|
|» swish|[Swish](#schemaswish)|false|none|The Swish payment method's details and configuration.|
|» sequra|[Sequra](#schemasequra)|false|none|The Sequra payment method's details and configuration.|
|» ach|[Ach](#schemaach)|false|none|The ACH payment method's details and configuration.|
|» sepa|[Sepa](#schemasepa)|false|none|The SEPA payment method's details and configuration.|
|» bacs|[Bacs](#schemabacs)|false|none|The Bacs payment method's details and configuration.|
|» paybybank|[PayByBank](#schemapaybybank)|false|none|The Pay by Bank (Open Banking) payment method's details and configuration.|
|» paypal|[PayPal](#schemapaypal)|false|none|The PayPal payment method's details and configuration.|
|» cashapp|[CashApp](#schemacashapp)|false|none|The Cash App payment method's details and configuration.|
|» googlepay|[GooglePay](#schemagooglepay)|false|none|The Google Pay payment method's details and configuration.|
|» applepay|[ApplePay](#schemaapplepay)|false|none|The Apple Pay payment method's details and configuration.|
|» card|[Card](#schemacard)|false|none|The Card payment method's details and configuration.|
|» stablecoin|[Stablecoin](#schemastablecoin)|false|none|The Stablecoin payment method's details and configuration.|
|available_payment_methods|[string]|false|read-only|An ordered list of available payment method names. The order indicates
the recommended presentation priority, with the first item being the
highest priority.|
|settings|object|false|none|Settings for the Payment Setup.|
|» success_url|string(uri)|false|none|The URL to redirect the customer to, if the payment is successful.
For payment methods with a redirect, this value overrides the default success redirect URL configured on your account.|
|» failure_url|string(uri)|false|none|The URL to redirect the customer to, if the payment is unsuccessful.
For payment methods with a redirect, this value overrides the default failure redirect URL configured on your account.|
|» capture|boolean|false|none|Indicates whether to capture the payment immediately.|
|» excluded_payment_methods|[string]|false|none|The list of payment methods excluded from the Payment Setup.|
|risk|object|false|none|Risk assessment settings for the Payment Setup.|
|» enabled|boolean|false|none|Indicates whether a risk assessment should be performed.|
|customer|object|false|none|The customer's details.|
|» country|string|false|none|The two-letter ISO country code of the customer for this payment.|
|» id|string|false|none|The unique identifier of the customer.|
|» email|object|false|none|Details of the customer's email.|
|»» address|string|false|none|The customer's email address.|
|»» verified|boolean|false|none|Specifies whether the customer's email address is verified.|
|» name|string|false|none|The customer's full name.|
|» tax_number|string|false|none|The customer's tax identification number.|
|» phone|[PaymentSetupPhone](#schemapaymentsetupphone)|false|none|The customer's phone number.|
|» device|object|false|none|Details of the customer's device.|
|»» locale|string|false|none|The locale of the device.|
|»» fingerprint|string|false|none|A unique identifier for the customer's device.|
|»» ipv4|string|false|none|The customer's device IPv4 address, used by some payment methods for risk and eligibility checks.|
|»» ipv6|string|false|none|The customer's device IPv6 address, used by some payment methods for risk and eligibility checks.|
|»» client|string|false|none|The type of client the customer uses to initiate the payment.|
|»» os|string|false|none|The operating system of the customer's device.|
|» merchant_account|[PaymentSetupMerchantAccount](#schemapaymentsetupmerchantaccount)|false|none|Details of the account the customer holds with the merchant.|
|order|object|false|none|The customer's order details.|
|» items|[allOf]|false|none|A list of items in the order.|
|» shipping|[PaymentSetupShipping](#schemapaymentsetupshipping)|false|none|The customer's shipping details.|
|» sub_merchants|[allOf]|false|none|The details of the sub-merchants.|
|» invoice_id|string|false|none|The unique identifier for the invoice.|
|» shipping_amount|integer|false|none|The total shipping amount for the order.|
|» discount_amount|integer|false|none|The discount amount the merchant applied to the transaction.|
|» tax_amount|integer|false|none|The total tax amount for the order.|
|» tipping_amount|integer(int64)|false|none|The total tipping amount for the order.|
|» surcharge_amount|integer(int64)|false|none|The total surcharge amount for the order.|
|» amount_allocations|[allOf]|false|none|The sub-entities that the payment is being processed on behalf of.|
|billing|[PaymentSetupBilling](#schemapaymentsetupbilling)|false|none|The billing details for the payment.|
|industry|object|false|none|Industry-specific information.|
|» airline|[allOf]|false|none|none|
|» accommodation|[allOf]|false|none|none|
|account_funding_transaction|[PaymentSetupAccountFundingTransaction](#schemapaymentsetupaccountfundingtransaction)|false|none|Account funding transaction details for the payment.|
|terminal|[PaymentSetupTerminal](#schemapaymentsetupterminal)|false|none|Terminal details.|
|billing_descriptor|[PaymentSetupBillingDescriptor](#schemapaymentsetupbillingdescriptor)|false|none|The billing descriptor for payment.|
|metadata|object|false|none|A set of key/value pairs you can attach to a payment. It can be useful for storing additional information about the payment.|
|» **additionalProperties**|any|false|none|none|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»» *anonymous*|string|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»» *anonymous*|number|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»» *anonymous*|boolean|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|latest_payment|[PaymentDetails](#schemapaymentdetails)|false|read-only|The latest [payment](https://api-reference.checkout.com/tag/payments/GET/payments/%7Bid%7D.responses.200.id) for this setup. Returned after a successful confirmation, including auto-confirm during setup creation.|
#### Enumerated Values
|Property|Value|
|---|---|
|payment_type|regular|
|payment_type|recurring|
|payment_type|moto|
|payment_type|installment|
|payment_type|pay_later|
|payment_type|unscheduled|
|client|web|
|client|mobile_web|
|client|app|
|os|android|
|os|ios|
PaymentSetupAccommodation
```json
{
"name": "Checkout Lodge",
"booking_reference": "REF9083748",
"check_in_date": "2025-04-11",
"check_out_date": "2025-04-18",
"address": {
"address_line1": "123 High Street",
"city": "London",
"state": "Greater London",
"country": "GB",
"zip": "NE1 1CK"
},
"number_of_rooms": 2,
"guests": [
{
"first_name": "John",
"last_name": "Smith",
"date_of_birth": "1970-03-19"
}
],
"room": [
{
"rate": 42.3,
"number_of_nights": 5,
"type": "deluxe"
}
],
"total_number_of_guests": 2,
"refundable": true,
"delivery_recipient": "jane.smith@example.com",
"host": {
"registration_date": "2020-01-01",
"total_reservation_count": 150
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|false|none|For lodging, contains the lodging name that appears on the
storefront/customer receipts. For cruise, contains the ship name booked for the cruise.|
|booking_reference|string|false|none|A unique identifier for the booking.|
|check_in_date|string(date)|false|none|For lodging bookings, the customer's check-in date.
For cruise bookings, the cruise departure date. Also referred to as the sail date.|
|check_out_date|string(date)|false|none|For lodging bookings, the customer's check-out date.
For cruise bookings, the cruise return date.|
|address|object|false|none|The accommodation's address.|
|» address_line1|string|false|none|The first line of the address.|
|» city|string|false|none|The address city.|
|» state|string|false|none|The address state or county.|
|» country|string|false|none|The address country, in ISO 3166-1 alpha-2 format.|
|» zip|string|false|none|The zip code or postal code.|
|number_of_rooms|integer|false|none|The total number of rooms booked for the accommodation.|
|guests|[object]|false|none|The list of guests staying at the accommodation.|
|» first_name|string|false|none|The guest's first name.|
|» last_name|string|false|none|The guest's last name.|
|» date_of_birth|string(date)|false|none|The guest's date of birth.|
|room|[object]|false|none|The list of rooms booked by the customer.|
|» rate|number|false|none|The rate or cost of the room per day.|
|» number_of_nights|integer|false|none|The number of nights the room is booked for.|
|» type|string|false|none|The room class or type booked. For example, `deluxe`.|
|total_number_of_guests|integer|false|none|The total number of guests on the booking.|
|refundable|boolean|false|none|Specifies whether the booking is refundable.|
|delivery_recipient|string|false|none|The recipient the booking confirmation is delivered to.|
|host|object|false|none|Details about the host of the accommodation.|
|» registration_date|string(date)|false|none|The date the host registered.|
|» total_reservation_count|integer|false|none|The total number of reservations the host has received.|
PaymentSetupAccountFundingTransaction
```json
{
"enabled": true,
"purpose": "financial_services",
"sender": {
"date_of_birth": "2000-01-01",
"reference": "0fc88634-78c1-4286-9cb6-6ca358730c8c",
"identification": {
"type": "passport",
"number": "1234567890",
"issuing_country": "US"
}
},
"recipient": {
"date_of_birth": "2000-01-01",
"account_number": "string",
"first_name": "string",
"last_name": "string",
"address": {
"address_line1": "10 Canterbury Road",
"address_line2": "Flat 2",
"city": "London",
"state": "Greater London",
"zip": "NE1 1KO",
"country": "GB"
}
}
}
```
Account funding transaction details for the payment.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|enabled|boolean|false|none|Whether to process this payment as an account funding transaction.|
|purpose|string|false|none|Specifies the purpose of the account funding transaction.|
|sender|object|false|none|Account funding transaction sender details.|
|» date_of_birth|string(date)|false|none|Date of birth of the sender (yyyy-mm-dd).|
|» reference|string|false|none|The unique reference for the sender of the payment.|
|» identification|object|false|none|Sender identification details.|
|»» type|string|false|none|The type of identification used to identify the sender.|
|»» number|string|false|none|The identification number.|
|»» issuing_country|string|false|none|The two-letter ISO country code of the country that issued the identification|
|recipient|object|false|none|Account funding transaction recipient details.|
|» date_of_birth|string(date)|false|none|Date of birth of the recipient (yyyy-mm-dd).|
|» account_number|string|false|none|Any identifier like part of the PAN (first six digits and last four digits), an IBAN, an internal account number, or a phone number related to the primary recipient's account|
|» first_name|string|false|none|The recipient's first name.|
|» last_name|string|false|none|The recipient's last name.|
|» address|[PaymentSetupAddress](#schemapaymentsetupaddress)|false|none|A physical address.|
#### Enumerated Values
|Property|Value|
|---|---|
|purpose|donations|
|purpose|education|
|purpose|emergency_need|
|purpose|expatriation|
|purpose|family_support|
|purpose|financial_services|
|purpose|gifts|
|purpose|income|
|purpose|insurance|
|purpose|investment|
|purpose|it_services|
|purpose|leisure|
|purpose|loan_payment|
|purpose|medical_treatment|
|purpose|other|
|purpose|pension|
|purpose|royalties|
|purpose|savings|
|purpose|travel_and_tourism|
|type|passport|
|type|driving_license|
|type|national_id|
PaymentSetupAccountHolder
```json
{
"type": "individual",
"first_name": "string",
"last_name": "string",
"middle_name": "string",
"company_name": "string",
"account_name_inquiry": true
}
```
Account holder details for the payment.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|false|none|The card account holder type.|
|first_name|string|false|none|The card account holder's first name.|
|last_name|string|false|none|The card account holder's last name.|
|middle_name|string|false|none|The card account holder's middle name.|
|company_name|string|false|none|The card account holder's company name.|
|account_name_inquiry|boolean|false|none|Indicates whether the ANI (account name inquiry) check is performed with the card scheme (Visa or Mastercard).|
#### Enumerated Values
|Property|Value|
|---|---|
|type|individual|
|type|government|
|type|corporate|
PaymentSetupAddress
```json
{
"address_line1": "10 Canterbury Road",
"address_line2": "Flat 2",
"city": "London",
"state": "Greater London",
"zip": "NE1 1KO",
"country": "GB"
}
```
A physical address.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|address_line1|string|false|none|The first line of the address.|
|address_line2|string|false|none|The second line of the address.|
|city|string|false|none|The address city.|
|state|string|false|none|The address state or county.|
|zip|string|false|none|The postal or zip code.|
|country|string|false|none|The address country, in ISO 3166-1 alpha-2 format.|
PaymentSetupAirline
```json
{
"ticket": {
"number": "0742464639523",
"issue_date": "2025-05-01",
"issuing_carrier_code": "042",
"travel_package_indicator": "A",
"travel_agency_name": "Checkout Travel Agents",
"travel_agency_code": "91114362"
},
"passengers": [
{
"first_name": "John",
"last_name": "Smith",
"date_of_birth": "1990-10-31",
"address": {
"country": "GB"
}
}
],
"flight_leg_details": [
{
"flight_number": "BA1483",
"carrier_code": "BA",
"class_of_travelling": "W",
"departure_airport": "LHR",
"departure_date": "2025-10-13",
"departure_time": "18:30",
"arrival_airport": "JFK",
"stop_over_code": "X",
"fare_basis_code": "WUP14B"
}
],
"total_number_of_passengers": 1,
"travel_type": "international",
"trip_type": "one_way",
"refundable": true,
"delivery_recipient": "jane.smith@example.com",
"ancillaries": "extra_baggage",
"insurance": {
"type": "travel",
"company": "AXA",
"price": {
"amount": 500,
"currency": "SAR"
}
}
}
```
Details about the airline ticket and flights the customer booked.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|ticket|object|false|none|Details about the airline ticket.|
|» number|string|false|none|The ticket's unique identifier.|
|» issue_date|string(date)|false|none|The date the airline ticket was issued.|
|» issuing_carrier_code|string|false|none|The carrier code of the ticket issuer.|
|» travel_package_indicator|string|false|none|The travel package indicator, as one of the following codes:
- `A` - Airline flight reservation
- `B` - Car rental and airline reservation
- `C` - Car rental reservation
- `N` - Unknown|
|» travel_agency_name|string|false|none|The name of the travel agency.|
|» travel_agency_code|string|false|none|The IATA or ARC unique identifier for the travel agency that issues the ticket.|
|passengers|[object]|false|none|The list of passengers on the flight.|
|» first_name|string|false|none|The passenger's first name.|
|» last_name|string|false|none|The passenger's last name.|
|» date_of_birth|string(date)|false|none|The passenger's date of birth.|
|» address|object|false|none|Details about the passenger's address.|
|»» country|string|false|none|The two-letter ISO country code of the passenger's country of residence.|
|flight_leg_details|[allOf]|false|none|The list of flight legs booked by the customer.|
|total_number_of_passengers|integer|false|none|The total number of passengers on the booking.|
|travel_type|string|false|none|The type of travel. For example, `domestic` or `international`.|
|trip_type|string|false|none|The type of trip. For example, `one_way` or `round_trip`.|
|refundable|boolean|false|none|Specifies whether the booking is refundable.|
|delivery_recipient|string|false|none|The recipient the ticket is delivered to.|
|ancillaries|string|false|none|Any additional add-ons purchased with the booking. For example, `extra_baggage`.|
|insurance|object|false|none|Details about the travel insurance purchased with the booking.|
|» type|string|false|none|The type of insurance.|
|» company|string|false|none|The name of the insurance company.|
|» price|object|false|none|The price of the insurance.|
|»» amount|number|false|none|The insurance amount, in the minor currency unit.|
|»» currency|string|false|none|The currency of the insurance amount, as a three-letter ISO currency code.|
PaymentSetupAmountAllocation
```json
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4",
"amount": 1000,
"reference": "ORD-5023-4E89",
"commission": {
"amount": 1000,
"percentage": 1.125
}
}
```
Amount Allocations
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|true|none|The id of the sub-entity.|
|amount|integer(int64)|true|none|The split amount - this will be credited to your sub-entity's currency account. The sum of all split amounts must be equal to the payment amount.
The amount must be provided in the minor currency unit.|
|reference|string|false|none|A reference you can later use to identify this split, such as an order number.|
|commission|object|false|none|Commission you'd like to collect from this split - this will be credited to your currency account. The commission cannot exceed the split amount.
Commission = (`amount` * `commission.percentage`) + `commission.amount`|
|» amount|integer(int64)|false|none|Optional fixed amount of commission to collect.
The amount must be provided in the minor currency unit.|
|» percentage|number|false|none|Optional percentage of commission to collect.
Supports up to 8 decimal places.|
PaymentSetupBilling
```json
{
"address": {
"address_line1": "10 Canterbury Road",
"address_line2": "Flat 2",
"city": "London",
"state": "Greater London",
"zip": "NE1 1KO",
"country": "GB"
}
}
```
The billing details for the payment.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|address|[PaymentSetupAddress](#schemapaymentsetupaddress)|false|none|A physical address.|
PaymentSetupBillingDescriptor
```json
{
"name": "Checkout.com",
"city": "London",
"reference": "Payment for order 123456"
}
```
The billing descriptor for payment.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|false|none|A dynamic description of the payment.|
|city|string|false|none|The city from which the payment was made.|
|reference|string|false|none|The reference shown on the statement.|
PaymentSetupFlightLegDetails
```json
{
"flight_number": "BA1483",
"carrier_code": "BA",
"class_of_travelling": "W",
"departure_airport": "LHR",
"departure_date": "2025-10-13",
"departure_time": "18:30",
"arrival_airport": "JFK",
"stop_over_code": "X",
"fare_basis_code": "WUP14B"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|flight_number|string|false|none|The flight identifier.|
|carrier_code|string|false|none|The IATA 2-letter accounting code (PAX) that identifies the carrier. Required if the airline data includes leg details.|
|class_of_travelling|string|false|none|A one-letter identifier for the travel class. For example:
- `F` - First class
- `J` - Business class
- `W` - Premium economy class
- `Y` - Economy class|
|departure_airport|string|false|none|The IATA three-letter airport code for the departure airport. Required if the airline data includes leg details.|
|departure_date|string(date)|false|none|The date of the scheduled take-off.|
|departure_time|string|false|none|The time of the scheduled take-off.|
|arrival_airport|string|false|none|The IATA three-letter airport code for the destination airport. Required if the airline data includes leg details.|
|stop_over_code|string|false|none|A one-letter code that indicates whether the passenger is entitled to make a stopover. Specify `O` or a blank space if the passenger is entitled. Specify `X` if the passenger is not entitled.|
|fare_basis_code|string|false|none|The alphanumeric fare basis code.|
PaymentSetupInstrument
```json
{
"status": "ready",
"flags": [
"string"
],
"id": "src_wmlfc3zttb4uzmk6snpwb43jbi",
"type": "bacs",
"action": {
"type": "set_instrument"
}
}
```
The instrument payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» id|string|false|none|The unique identifier of the selected instrument.|
|» type|string|false|read-only|The type of the instrument.|
|» action|object|false|read-only|The next available action for the payment method.|
|»» type|string|false|none|The type of action.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|set_instrument|
PaymentSetupMerchantAccount
```json
{
"id": "1234",
"registration_date": "2023-05-01",
"last_modified": "2023-05-01",
"returning_customer": true,
"first_transaction_date": "2023-09-15",
"last_transaction_date": "2025-03-28",
"total_order_count": 6,
"last_payment_amount": 55.99
}
```
Details of the account the customer holds with the merchant.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The merchant's unique identifier for the customer's account.|
|registration_date|string(date)|false|none|The date the customer registered their account with the merchant.|
|last_modified|string(date)|false|none|The date the customer's account with the merchant was last modified.|
|returning_customer|boolean|false|none|Specifies if the customer is a returning customer.|
|first_transaction_date|string(date)|false|none|The date of the customer's first transaction.|
|last_transaction_date|string(date)|false|none|The date of the customer's most recent transaction.|
|total_order_count|integer|false|none|The total number of orders made by the customer.|
|last_payment_amount|number|false|none|The payment amount of the customer's most recent transaction.|
PaymentSetupPaymentMethod
```json
{
"status": "ready",
"flags": [
"string"
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|status|[PaymentMethodStatus](#schemapaymentmethodstatus)|false|none|The payment method status.|
|flags|[PaymentMethodFlags](#schemapaymentmethodflags)|false|none|The list of error codes or indicators that highlight missing or invalid information.|
PaymentSetupPhone
```json
{
"country_code": "+44",
"number": "207 946 0000"
}
```
The customer's phone number.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|country_code|string|false|none|The phone number's href="https://www.checkout.com/docs/resources/codes/country-codes"
target="_blank">international country calling code.|
|number|string|false|none|The phone number.|
PaymentSetupPresentmentDetails
```json
{
"amount": 110,
"currency": "EUR"
}
```
The amount and currency to present to the customer, when the settlement
currency differs from the customer-facing currency.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|amount|integer(int64)|false|none|The presentment amount, in the minor currency unit.|
|currency|string|false|none|The presentment currency, as a three-letter ISO currency code.|
PaymentSetupResponse
```json
{
"id": "string",
"processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
"amount": 10000,
"currency": "GBP",
"presentment_details": {
"amount": 110,
"currency": "EUR"
},
"payment_type": "regular",
"reference": "REF-0987-475",
"description": "Set of 3 t-shirts",
"payment_methods": {
"auto_confirm": "card",
"instrument": {
"status": "ready",
"flags": [
"string"
],
"id": "src_wmlfc3zttb4uzmk6snpwb43jbi",
"type": "bacs",
"action": {
"type": "set_instrument"
}
},
"klarna": {
"status": "ready",
"flags": [
"string"
],
"initialization": "disabled",
"action": {
"type": "sdk",
"client_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ewogICJzZXNzaW9uX2lkIiA6ICIw",
"session_id": "0b1d9815-165e-42e2-8867-35bc03789e00"
},
"account_holder": {
"name": "string"
},
"iban": "DE89370400440532013000"
},
"stcpay": {
"status": "ready",
"flags": [
"string"
],
"initialization": "disabled",
"otp": "123456",
"action": {
"type": "otp"
}
},
"tabby": {
"status": "ready",
"flags": [
"string"
],
"initialization": "disabled",
"payment_types": [
"pay_later"
]
},
"bizum": {
"status": "ready",
"flags": [
"string"
]
},
"paynow": {
"status": "ready",
"flags": [
"string"
]
},
"qpay": {
"status": "ready",
"flags": [
"string"
],
"national_id": "21234567890",
"description": "string"
},
"eps": {
"status": "ready",
"flags": [
"string"
]
},
"ideal": {
"status": "ready",
"flags": [
"string"
],
"description": "2 t-shirts"
},
"knet": {
"status": "ready",
"flags": [
"string"
],
"language": "en"
},
"bancontact": {
"status": "ready",
"flags": [
"string"
],
"account_holder_name": "string"
},
"benefit": {
"status": "ready",
"flags": [
"string"
]
},
"blik": {
"status": "ready",
"flags": [
"string"
],
"partner_code": "999111"
},
"vipps": {
"status": "ready",
"flags": [
"string"
]
},
"twint": {
"status": "ready",
"flags": [
"string"
]
},
"alipay_cn": {
"status": "ready",
"flags": [
"string"
],
"terminal_type": "web",
"os_type": "android"
},
"alipay_hk": {
"status": "ready",
"flags": [
"string"
],
"terminal_type": "web",
"os_type": "android"
},
"gcash": {
"status": "ready",
"flags": [
"string"
],
"terminal_type": "web",
"os_type": "android"
},
"tng": {
"status": "ready",
"flags": [
"string"
],
"terminal_type": "web",
"os_type": "android"
},
"dana": {
"status": "ready",
"flags": [
"string"
],
"terminal_type": "web",
"os_type": "android"
},
"mobilepay": {
"status": "ready",
"flags": [
"string"
]
},
"tamara": {
"status": "ready",
"flags": [
"string"
],
"initialization": "disabled",
"risk_assessment": {
"premium_customer": false,
"risk_score": 42,
"order_count_last24h": 0,
"linked_device_count": 2
}
},
"mbway": {
"status": "ready",
"flags": [
"string"
]
},
"multibanco": {
"status": "ready",
"flags": [
"string"
],
"account_holder_name": "string"
},
"wechatpay": {
"status": "ready",
"flags": [
"string"
]
},
"kakaopay": {
"status": "ready",
"flags": [
"string"
],
"terminal_type": "web",
"os_type": "android"
},
"truemoney": {
"status": "ready",
"flags": [
"string"
],
"terminal_type": "web",
"os_type": "android"
},
"octopus": {
"status": "ready",
"flags": [
"string"
]
},
"p24": {
"status": "ready",
"flags": [
"string"
],
"account_holder": {
"name": "string",
"email": "user@example.com"
}
},
"alma": {
"status": "ready",
"flags": [
"string"
]
},
"swish": {
"status": "ready",
"flags": [
"string"
],
"billing_descriptor": "string",
"account_holder": {
"first_name": "John",
"last_name": "Smith"
}
},
"sequra": {
"status": "ready",
"flags": [
"string"
]
},
"ach": {
"status": "ready",
"flags": [
"string"
],
"account_type": "savings",
"account_holder": {
"type": "individual",
"first_name": "string",
"last_name": "string",
"company_name": "string",
"date_of_birth": "string",
"identification": {
"type": "string",
"issuing_country": "string",
"number": "string"
}
},
"account_number": "string",
"bank_code": "stringst",
"country": "st"
},
"sepa": {
"status": "ready",
"flags": [
"string"
],
"account_holder": {
"type": "individual",
"first_name": "string",
"last_name": "string",
"company_name": "string"
},
"account_number": "string",
"country": "st",
"currency": "string",
"mandate": {
"id": "string",
"type": "core",
"date_of_signature": "2019-08-24"
}
},
"bacs": {
"status": "ready",
"flags": [
"string"
],
"initialization": "disabled",
"instrument_id": "src_wkq7552u245upl5h75x24554xy",
"account_holder": {
"type": "individual",
"first_name": "string",
"last_name": "string",
"company_name": "string",
"email": "john.smith@example.com"
},
"account_number": "string",
"bank_code": "string",
"country": "st",
"currency": "string",
"allow_partial_match": false
},
"paybybank": {
"status": "ready",
"flags": [
"string"
],
"bank_id": "ob-natwest",
"action": {
"type": "select_bank",
"banks": [
{
"bank_id": "ob-natwest",
"display_name": "NatWest",
"logo_url": "https://cdn.token.io/banks/natwest.png",
"available": true
}
]
}
},
"paypal": {
"status": "ready",
"flags": [
"string"
],
"initialization": "disabled",
"user_action": "pay_now",
"brand_name": "Acme Corporation",
"shipping_preference": "no_shipping",
"action": {
"type": "sdk",
"order_id": "dd4b1a85-31de-404b-99f4-f143f8ba35ba"
}
},
"cashapp": {
"status": "ready",
"flags": [
"string"
],
"initialization": "disabled",
"customer_profile_sharing": true,
"customer_profile": {
"customer_id": "CST_AYVkuLzfsRqEhf4OyQFxQNv22m7IjNFjO6f2J5CDE2nxAC4-21wJ2H8_2kvsdIsDZMN4",
"cashtag": "$CASHTAG_C_TOKEN",
"reference_id": "value",
"full_name": "John Middle Doe",
"given_name": "John",
"middle_name": "Middle",
"family_name": "Doe",
"suffix": "Jr.",
"birth_date": "1990-01-01",
"address": {
"address_line_1": "123 Main St",
"address_line_2": "string",
"address_line_3": "string",
"locality": "Springfield",
"sublocality": "string",
"administrative_district_level_1": "IL",
"postal_code": "62701",
"country": "US"
},
"phone_number": "5555555555",
"email_address": "cash@cash.com",
"customer_since": "1970-01-18T12:46:04.8Z"
},
"reference": "ORDER-99",
"action": {
"type": "redirect",
"redirect_url": "https://sandbox.api.cash.app/customer-request/v1/requests/GRR_f5xg6wrxhtv3p4w24g0wrexa/interstitial?validity_token=bap03y"
}
},
"googlepay": {
"status": "ready",
"flags": [
"string"
],
"token_data": {
"protocol_version": "string",
"signature": "string",
"signed_message": "string",
"tokenization_key": "string"
},
"token": {
"id": "string",
"expires_on": "2019-08-24T14:15:22Z"
},
"store_for_future_use": true,
"phone": {
"country_code": "+44",
"number": "207 946 0000"
},
"account_holder": {
"type": "individual",
"first_name": "string",
"last_name": "string",
"middle_name": "string",
"company_name": "string",
"account_name_inquiry": true
},
"schemes": [
"accel"
],
"preferred_scheme": "visa"
},
"applepay": {
"status": "ready",
"flags": [
"string"
],
"token_data": {
"version": "string",
"data": "string",
"signature": "string",
"header": {
"ephemeral_public_key": "string",
"public_key_hash": "string",
"transaction_id": "string"
}
},
"token": {
"id": "string",
"expires_on": "2019-08-24T14:15:22Z"
},
"store_for_future_use": true,
"phone": {
"country_code": "+44",
"number": "207 946 0000"
},
"account_holder": {
"type": "individual",
"first_name": "string",
"last_name": "string",
"middle_name": "string",
"company_name": "string",
"account_name_inquiry": true
},
"schemes": [
"accel"
],
"preferred_scheme": "visa"
},
"card": {
"status": "ready",
"flags": [
"string"
],
"token": {
"id": "string"
},
"details": {
"number": "string",
"last4": "string",
"bin": "string",
"scheme": "string",
"expiry_month": 0,
"expiry_year": 0,
"name": "string",
"cvv": "string",
"stored": true,
"expires_on": "2019-08-24T14:15:22Z",
"allow_update": true
},
"store_for_future_use": true,
"phone": {
"country_code": "+44",
"number": "207 946 0000"
},
"account_holder": {
"type": "individual",
"first_name": "string",
"last_name": "string",
"middle_name": "string",
"company_name": "string",
"account_name_inquiry": true
},
"schemes": [
"accel"
],
"preferred_scheme": "visa"
},
"stablecoin": {
"status": "ready",
"flags": [
"string"
]
}
},
"available_payment_methods": [
"card",
"klarna",
"stcpay",
"stablecoin"
],
"settings": {
"success_url": "https://example.com/payments/success",
"failure_url": "https://example.com/payments/fail",
"capture": true,
"excluded_payment_methods": [
"card",
"klarna",
"stcpay"
]
},
"risk": {
"enabled": true
},
"customer": {
"country": "GB",
"id": "cus_123456789",
"email": {
"address": "johnsmith@example.com",
"verified": true
},
"name": "John Smith",
"tax_number": "GB123456789",
"phone": {
"country_code": "+44",
"number": "207 946 0000"
},
"device": {
"locale": "en_GB",
"fingerprint": "fp_abc123xyz",
"ipv4": "203.0.113.0",
"ipv6": "2001:db8:85a3::8a2e:370:7334",
"client": "web",
"os": "android"
},
"merchant_account": {
"id": "1234",
"registration_date": "2023-05-01",
"last_modified": "2023-05-01",
"returning_customer": true,
"first_transaction_date": "2023-09-15",
"last_transaction_date": "2025-03-28",
"total_order_count": 6,
"last_payment_amount": 55.99
}
},
"order": {
"items": [
{
"name": "Battery Power Pack",
"quantity": 1,
"unit_price": 1000,
"total_amount": 1000,
"reference": "BA67A",
"discount_amount": 150,
"url": "https://example.com/products/my-item",
"image_url": "https://example.com/products/my-item/image",
"type": "digital"
}
],
"shipping": {
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@example.com",
"phone": {
"country_code": "+44",
"number": "207 946 0000"
},
"address": {
"address_line1": "10 Canterbury Road",
"address_line2": "Flat 2",
"city": "London",
"state": "Greater London",
"zip": "NE1 1KO",
"country": "GB"
},
"method": "string",
"delay": 3
},
"sub_merchants": [
{
"id": "SUB12345",
"product_category": "Electronics",
"number_of_sales": 500,
"registration_date": "2023-01-15"
}
],
"invoice_id": "inv_123456789",
"shipping_amount": 5,
"discount_amount": 10,
"tax_amount": 2,
"tipping_amount": 2,
"surcharge_amount": 2,
"amount_allocations": [
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4",
"amount": 1000,
"reference": "ORD-5023-4E89",
"commission": {
"amount": 1000,
"percentage": 1.125
}
}
]
},
"billing": {
"address": {
"address_line1": "10 Canterbury Road",
"address_line2": "Flat 2",
"city": "London",
"state": "Greater London",
"zip": "NE1 1KO",
"country": "GB"
}
},
"industry": {
"airline": [
{
"ticket": {
"number": "0742464639523",
"issue_date": "2025-05-01",
"issuing_carrier_code": "042",
"travel_package_indicator": "A",
"travel_agency_name": "Checkout Travel Agents",
"travel_agency_code": "91114362"
},
"passengers": [
{
"first_name": "John",
"last_name": "Smith",
"date_of_birth": "1990-10-31",
"address": {
"country": "GB"
}
}
],
"flight_leg_details": [
{
"flight_number": "BA1483",
"carrier_code": "BA",
"class_of_travelling": "W",
"departure_airport": "LHR",
"departure_date": "2025-10-13",
"departure_time": "18:30",
"arrival_airport": "JFK",
"stop_over_code": "X",
"fare_basis_code": "WUP14B"
}
],
"total_number_of_passengers": 1,
"travel_type": "international",
"trip_type": "one_way",
"refundable": true,
"delivery_recipient": "jane.smith@example.com",
"ancillaries": "extra_baggage",
"insurance": {
"type": "travel",
"company": "AXA",
"price": {
"amount": 500,
"currency": "SAR"
}
}
}
],
"accommodation": [
{
"name": "Checkout Lodge",
"booking_reference": "REF9083748",
"check_in_date": "2025-04-11",
"check_out_date": "2025-04-18",
"address": {
"address_line1": "123 High Street",
"city": "London",
"state": "Greater London",
"country": "GB",
"zip": "NE1 1CK"
},
"number_of_rooms": 2,
"guests": [
{
"first_name": "John",
"last_name": "Smith",
"date_of_birth": "1970-03-19"
}
],
"room": [
{
"rate": 42.3,
"number_of_nights": 5,
"type": "deluxe"
}
],
"total_number_of_guests": 2,
"refundable": true,
"delivery_recipient": "jane.smith@example.com",
"host": {
"registration_date": "2020-01-01",
"total_reservation_count": 150
}
}
]
},
"account_funding_transaction": {
"enabled": true,
"purpose": "financial_services",
"sender": {
"date_of_birth": "2000-01-01",
"reference": "0fc88634-78c1-4286-9cb6-6ca358730c8c",
"identification": {
"type": "passport",
"number": "1234567890",
"issuing_country": "US"
}
},
"recipient": {
"date_of_birth": "2000-01-01",
"account_number": "string",
"first_name": "string",
"last_name": "string",
"address": {
"address_line1": "10 Canterbury Road",
"address_line2": "Flat 2",
"city": "London",
"state": "Greater London",
"zip": "NE1 1KO",
"country": "GB"
}
}
},
"terminal": {
"id": "12345678",
"local_date_time": "2026-05-26T13:05:14+01:00"
},
"billing_descriptor": {
"name": "Checkout.com",
"city": "London",
"reference": "Payment for order 123456"
},
"metadata": {
"property1": "string",
"property2": "string"
},
"latest_payment": {
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"requested_on": "2019-08-24T14:15:22Z",
"source": {
"type": "card",
"id": "src_nwd3m4in3hkuddfpjsaevunhdy",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"expiry_month": 6,
"expiry_year": 2025,
"name": "Bruce Wayne",
"scheme": "VISA",
"scheme_local": "Cartes_Bancaires",
"local_schemes": [
"cartes_bancaires",
"visa"
],
"last4": "9996",
"fingerprint": "F639CAB2745BEE4140BF86DF6B6D6",
"bin": "45434748",
"card_type": "CREDIT",
"card_category": "CONSUMER",
"card_wallet_type": "applepay",
"issuer": "GOTHAM STATE BANK",
"issuer_country": "US",
"product_id": "F",
"product_type": "CLASSIC",
"avs_check": "S",
"cvv_check": "Y",
"payment_account_reference": "EUNIX9AX7THOOJIEJ2AP6OOFAHGH4",
"encrypted_card_number": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz...",
"account_update_status": "card_updated",
"account_update_failure_code": "VAU009",
"account_holder": {}
},
"destination": {
"type": "bank_account",
"id": "string"
},
"amount": 6540,
"amount_requested": 6540,
"currency": "USD",
"payment_type": "Recurring",
"payment_plan": {
"amount_variability": "Variable",
"days_between_payments": 28,
"total_number_of_payments": 5,
"current_payment_number": 3,
"expiry": "20251031",
"name": "Subscription 1234",
"start_date": "20260507",
"amount": 1234
},
"reference": "ORD-5023-4E89",
"description": "Set of 3 masks",
"approved": true,
"expires_on": "string",
"status": "Authorized",
"balances": {
"total_authorized": 6540,
"total_voided": 0,
"available_to_void": 6540,
"total_captured": 0,
"available_to_capture": 6540,
"total_refunded": 0,
"available_to_refund": 0
},
"3ds": {
"downgraded": false,
"enrolled": "Y",
"signature_valid": "Y",
"authentication_response": "Y",
"authentication_status_reason": "string",
"cryptogram": "hv8mUFzPzRZoCAAAAAEQBDMAAAA=",
"xid": "MDAwMDAwMDAwMDAwMDAwMzIyNzY=",
"eci": "string",
"version": "2.1.0",
"exemption": "low_value",
"exemption_applied": "string",
"challenged": true,
"upgrade_reason": "sca_retry",
"trusted_listing": {
"status": "Y",
"source": "01"
}
},
"authentication": {
"experience": "3ds"
},
"risk": {
"flagged": true,
"score": 22
},
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "brucewayne@gmail.com",
"name": "Bruce Wayne",
"summary": {
"registration_date": "2023-05-01",
"first_transaction_date": "2023-07-01",
"last_payment_date": "2023-08-01",
"total_order_count": 15,
"last_payment_amount": 500,
"is_premium_customer": true,
"is_returning_customer": true,
"lifetime_value": 500
}
},
"billing_descriptor": {
"name": "SUPERHEROES.COM",
"city": "GOTHAM",
"reference": "string",
"local_descriptors": [
{
"name": "漢字",
"character_set": "kanji"
}
]
},
"shipping": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"payment_ip": "90.197.169.245",
"sender": {
"type": "individual",
"reference": "8285282045818",
"first_name": "John",
"last_name": "Jones",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"amount_allocations": [
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4",
"amount": 1000,
"reference": "ORD-5023-4E89",
"commission": {
"amount": 1000,
"percentage": 1.125
}
}
],
"recipient": {
"dob": "1985-05-15",
"account_number": "5555554444",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"zip": "SW1A",
"first_name": "John",
"last_name": "Jones"
},
"processing": {
"preferred_scheme": "cartes_bancaires",
"app_id": "com.iap.linker_portal",
"airline_data": [
{
"ticket": {
"number": "045-21351455613",
"issue_date": "2023-05-20",
"issuing_carrier_code": "AI",
"travel_package_indicator": "B",
"travel_agency_name": "World Tours",
"travel_agency_code": "01"
},
"passenger": [
{
"first_name": "John",
"last_name": "White",
"date_of_birth": "1990-05-26",
"address": {
"country": "US"
}
}
],
"flight_leg_details": [
{
"flight_number": "101",
"carrier_code": "BA",
"class_of_travelling": "J",
"departure_airport": "LHR",
"departure_date": "2023-06-19",
"departure_time": "15:30",
"arrival_airport": "LAX",
"stop_over_code": "x",
"fare_basis_code": "SPRSVR"
}
]
}
],
"accommodation_data": [
{
"name": "The Sea View Hotel",
"booking_reference": "HOTEL123",
"check_in_date": "2023-06-20",
"check_out_date": "2023-06-23",
"address": {
"address_line1": "123 Beach Road",
"zip": "10001"
},
"state": "FL",
"country": "USA",
"city": "Los Angeles",
"number_of_rooms": 2,
"guests": [
{
"first_name": "Jane",
"last_name": "Doe",
"date_of_birth": "1985-07-14"
}
],
"room": [
{
"rate": "70",
"number_of_nights_at_room_rate": "3"
}
],
"property_phone": [
{
"country_code": "44",
"number": "7123456789"
}
],
"customer_service_phone": [
{
"country_code": "44",
"number": "7123456789"
}
]
}
],
"partner_customer_id": "2102209000001106125F8",
"partner_payment_id": "440644309099499894406",
"partner_code": "999111",
"failure_code": "partner_error",
"partner_response_code": "ER_WRONG_TICKET",
"tax_amount": 1000,
"locale": "en-US",
"retrieval_reference_number": "909913440644",
"partner_order_id": "string",
"partner_status": "string",
"partner_transaction_id": "string",
"partner_error_codes": [
"string"
],
"partner_merchant_advice_code": "24",
"partner_error_message": "string",
"partner_authorization_code": "string",
"partner_authorization_response_code": "string",
"partner_fraud_status": "string",
"pan_type_processed": "fpan",
"fallback_source_used": false,
"custom_payment_method_ids": [
"string"
],
"aft": true,
"merchant_category_code": "5311",
"scheme_merchant_id": "123456",
"scheme": "ACCEL",
"scheme_transaction_link_id": "string"
},
"items": [
{
"type": "digital",
"sub_type": "stablecoin",
"name": "Necklace",
"quantity": 2,
"unit_price": 50,
"reference": "858818ac",
"commodity_code": "DEF123",
"unit_of_measure": "metres",
"total_amount": 29000,
"tax_rate": 2000,
"tax_amount": 1000,
"tax_exempt": true,
"discount_amount": 1000,
"wxpay_goods_id": "1001",
"url": "string",
"image_url": "string",
"service_ends_on": "2025-01-01",
"purchase_country": "GB",
"foreign_retailer_amount": 200
}
],
"metadata": {
"coupon_code": "NY2018",
"partner_id": 123989
},
"eci": "06",
"scheme_id": "488341541494658",
"actions": [
{
"id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
"type": "Authorization",
"response_code": "10000",
"response_summary": "Approved"
}
],
"retry": {
"enabled": true,
"attempts_made": 0,
"max_attempts": 6,
"ends_on": "2019-08-24T14:15:22Z",
"next_attempt_on": "2019-08-24T14:15:22Z"
},
"cko_network_token_available": false,
"instruction": {
"purpose": "financial_services"
},
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
},
"actions": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/actions"
},
"authorize": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/authorizations"
},
"refund": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/refund"
}
}
}
}
```
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetup](#schemapaymentsetup)|false|none|none|
PaymentSetupShipping
```json
{
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@example.com",
"phone": {
"country_code": "+44",
"number": "207 946 0000"
},
"address": {
"address_line1": "10 Canterbury Road",
"address_line2": "Flat 2",
"city": "London",
"state": "Greater London",
"zip": "NE1 1KO",
"country": "GB"
},
"method": "string",
"delay": 3
}
```
The customer's shipping details.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|first_name|string|false|none|The customer's first name.|
|last_name|string|false|none|The customer's last name.|
|email|string|false|none|The customer's email address.|
|phone|[PaymentSetupPhone](#schemapaymentsetupphone)|false|none|The customer's phone number.|
|address|[PaymentSetupAddress](#schemapaymentsetupaddress)|false|none|A physical address.|
|method|string|false|none|The shipping method the customer selected.
For more information on which values you can specify, refer to the payment method's external API reference.|
|delay|integer|false|none|The number of days between the order date and the expected delivery date.|
PaymentSetupSubMerchant
```json
{
"id": "SUB12345",
"product_category": "Electronics",
"number_of_sales": 500,
"registration_date": "2023-01-15"
}
```
Details about a sub-merchant in the order.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The unique identifier for the sub-merchant.|
|product_category|string|false|none|The product category for the sub-merchant.|
|number_of_sales|integer|false|none|The number of orders the sub-merchant has processed.|
|registration_date|string(date)|false|none|The date the sub-merchant was registered.|
PaymentSetupTerminal
```json
{
"id": "12345678",
"local_date_time": "2026-05-26T13:05:14+01:00"
}
```
Terminal details.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|Terminal identifier.|
|local_date_time|string(date-time)|false|none|The local date and time on the terminal, in ISO 8601 format.|
PaymentSetupValidationError
```json
{
"request_id": "0HL80RJLS76I7",
"error_type": "request_invalid",
"error_codes": [
"amount_required"
]
}
```
The validation errors flagged with the request.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|request_id|string|false|none|The unique identifier of the flagged request.|
|error_type|string|false|none|The type of error flagged.|
|error_codes|[string]|false|none|The error codes returned by the failed request.|
PayNow
```json
{
"status": "ready",
"flags": [
"string"
]
}
```
The PayNow payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
PayPal
```json
{
"status": "ready",
"flags": [
"string"
],
"initialization": "disabled",
"user_action": "pay_now",
"brand_name": "Acme Corporation",
"shipping_preference": "no_shipping",
"action": {
"type": "sdk",
"order_id": "dd4b1a85-31de-404b-99f4-f143f8ba35ba"
}
}
```
The PayPal payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentMethodInitialization](#schemapaymentmethodinitialization)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» user_action|string|false|none|The user action for the PayPal widget.
- `pay_now` - After the customer clicks the PayPal button, the customer is redirected to a page to enter payment details and immediately directed to finalize the payment.
- `continue` - After the customer clicks the PayPal button, the customer is redirected to a page to enter payment details and then redirected back to the merchant's site to review and finalize the payment.|
|» brand_name|string|false|none|The brand name to display in the PayPal checkout experience.|
|» shipping_preference|string|false|none|Where to obtain the shipping information.
- `no_shipping` - Redacts the shipping address from the PayPal pages.
- `get_from_file` - Obtains the shipping address from the customer's PayPal account.
- `set_provided_address` - Uses the shipping address provided by the merchant.|
|» action|object|false|read-only|The next available action for the payment method.|
|»» type|string|false|none|The type of action.|
|»» order_id|string|false|none|The PayPal order ID to use with the PayPal SDK.|
#### Enumerated Values
|Property|Value|
|---|---|
|user_action|pay_now|
|user_action|continue|
|shipping_preference|no_shipping|
|shipping_preference|get_from_file|
|shipping_preference|set_provided_address|
|type|sdk|
Qpay
```json
{
"status": "ready",
"flags": [
"string"
],
"national_id": "21234567890",
"description": "string"
}
```
The QPay payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» national_id|string|false|write-only|The Qatari national ID. Must start with 2 or 3, followed by 10 digits.|
|» description|string|false|none|A description of the payment order. Alphanumeric characters only.|
Sepa
```json
{
"status": "ready",
"flags": [
"string"
],
"account_holder": {
"type": "individual",
"first_name": "string",
"last_name": "string",
"company_name": "string"
},
"account_number": "string",
"country": "st",
"currency": "string",
"mandate": {
"id": "string",
"type": "core",
"date_of_signature": "2019-08-24"
}
}
```
The SEPA payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» account_holder|object|false|none|The account holder details.|
|»» type|string|false|none|The type of account holder.|
|»» first_name|string|false|none|The first name of the account holder.|
|»» last_name|string|false|none|The last name of the account holder.|
|»» company_name|string|false|none|The legal name of a registered company that holds the account.|
|» account_number|string|false|write-only|The account holder's IBAN.|
|» country|string|false|none|The account's country, as an ISO 3166-1 alpha-2 code.|
|» currency|string|false|none|The account holder's account currency.|
|» mandate|object|false|none|The mandate details.|
|»» id|string|false|none|The ID of the mandate.|
|»» type|string|false|none|The type of mandate.|
|»» date_of_signature|string(date)|false|none|The date the mandate was signed.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|individual|
|type|corporate|
|type|core|
|type|b2b|
Sequra
```json
{
"status": "ready",
"flags": [
"string"
]
}
```
The Sequra payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
Stablecoin
```json
{
"status": "ready",
"flags": [
"string"
]
}
```
The Stablecoin payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
StcPay
```json
{
"status": "ready",
"flags": [
"string"
],
"initialization": "disabled",
"otp": "123456",
"action": {
"type": "otp"
}
}
```
The stc pay payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentMethodInitialization](#schemapaymentmethodinitialization)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» otp|string|false|write-only|The one-time password (OTP) for stc pay.|
|» action|object|false|read-only|The next available action for the payment method.|
|»» type|string|false|none|The type of action.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|otp|
Swish
```json
{
"status": "ready",
"flags": [
"string"
],
"billing_descriptor": "string",
"account_holder": {
"first_name": "John",
"last_name": "Smith"
}
}
```
The Swish payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» billing_descriptor|string|false|none|A description that appears on the customer's billing statement.|
|» account_holder|object|false|none|The account holder's details.|
|»» first_name|string|false|none|The account holder's first name.|
|»» last_name|string|false|none|The account holder's last name.|
Tabby
```json
{
"status": "ready",
"flags": [
"string"
],
"initialization": "disabled",
"payment_types": [
"pay_later"
]
}
```
The Tabby payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentMethodInitialization](#schemapaymentmethodinitialization)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» payment_types|[string]|false|none|The available payment types for Tabby (For example, `installments`).|
Tamara
```json
{
"status": "ready",
"flags": [
"string"
],
"initialization": "disabled",
"risk_assessment": {
"premium_customer": false,
"risk_score": 42,
"order_count_last24h": 0,
"linked_device_count": 2
}
}
```
The Tamara payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentMethodInitialization](#schemapaymentmethodinitialization)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» risk_assessment|object|false|none|Risk signals about the customer, forwarded to Tamara with the payment.|
|»» premium_customer|boolean|false|none|Specifies whether the customer is a premium customer.|
|»» risk_score|integer|false|none|The customer's risk score.|
|»» order_count_last24h|integer|false|none|The number of orders the customer has made in the last 24 hours.|
|»» linked_device_count|integer|false|none|The number of devices linked to the customer.|
TerminalType
```json
"web"
```
The client-side terminal type. Indicates whether the customer is using a PC browser, mobile browser, or mobile application.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The client-side terminal type. Indicates whether the customer is using a PC browser, mobile browser, or mobile application.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|web|
|*anonymous*|wap|
|*anonymous*|app|
Tng
```json
{
"status": "ready",
"flags": [
"string"
],
"terminal_type": "web",
"os_type": "android"
}
```
The TNG payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» terminal_type|[TerminalType](#schematerminaltype)|false|none|The client-side terminal type. Indicates whether the customer is using a PC browser, mobile browser, or mobile application.|
|» os_type|[OsType](#schemaostype)|false|none|The customer's operating system type. Required when `terminal_type` is not `web`.|
TrueMoney
```json
{
"status": "ready",
"flags": [
"string"
],
"terminal_type": "web",
"os_type": "android"
}
```
The TrueMoney payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» terminal_type|[TerminalType](#schematerminaltype)|false|none|The client-side terminal type. Indicates whether the customer is using a PC browser, mobile browser, or mobile application.|
|» os_type|[OsType](#schemaostype)|false|none|The customer's operating system type. Required when `terminal_type` is not `web`.|
Twint
```json
{
"status": "ready",
"flags": [
"string"
]
}
```
The Twint payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
Vipps
```json
{
"status": "ready",
"flags": [
"string"
]
}
```
The Vipps payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
WeChatPay
```json
{
"status": "ready",
"flags": [
"string"
]
}
```
The WeChatPay payment method's details and configuration.
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSetupPaymentMethod](#schemapaymentsetuppaymentmethod)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
Shipping
```json
{
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@example.com",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"from_address_zip": "123456",
"timeframe": "SameDay",
"method": "BillingAddress",
"delay": 5
}
```
The shipping details.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|first_name|string|false|none|The first name of the person receiving the goods or the service.|
|last_name|string|false|none|The last name of the person receiving the goods or the service.|
|email|string|false|none|The email address associated with the shipping order.|
|address|[Address](#schemaaddress)|false|none|The shipping address.|
|phone|[PhoneNumber](#schemaphonenumber)|false|none|The phone number associated with the shipping address.|
|from_address_zip|string|false|none|The postal code or zip code of the location being shipped from.|
|timeframe|string|false|none|Indicates the merchandise delivery timeframe. The following values will be supported by Checkout.com, otherwise your specific value will be passed through to the provider.|
|method|string|false|none|Indicates the shipping method chosen for the transaction. The following values will be supported by Checkout.com, otherwise your specific value will be passed through to the provider.|
|delay|integer|false|none|The number of days by which the shipping is delayed.|
#### Enumerated Values
|Property|Value|
|---|---|
|timeframe|ElectronicDelivery|
|timeframe|SameDay|
|timeframe|Overnight|
|timeframe|TwoDayOrMore|
|method|Digital|
|method|PickUp|
|method|BillingAddress|
|method|OtherAddress|
Subscription
```json
{
"id": "string"
}
```
Subscription
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The ID or reference linking a series of recurring payments together.|
TrackingInfo
```json
{
"return_shipping_company": "DHL US",
"return_tracking_number": "GM275322484009027685",
"return_tracking_uri": "https://example.com/tracking/GM275322484009027685",
"shipping_company": "DHL US",
"tracking_number": "GM275322484009027685",
"tracking_uri": "https://example.com/tracking/GM275322484009027685"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|return_shipping_company|string|false|none|Name of the shipping company for the return shipment (as specific as possible).|
|return_tracking_number|string|false|none|Tracking number for the return shipment.|
|return_tracking_uri|string|false|none|URL where the customer can track the return shipment.|
|shipping_company|string|false|none|Name of the shipping company (as specific as possible)|
|tracking_number|string|false|none|Tracking number for the shipment.|
|tracking_uri|string|false|none|URI where the customer can track their shipment.|
TrustedListing
```json
{
"status": "Y",
"source": "01"
}
```
TrustedListing
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|status|string|false|none|Enables the communication of trusted beneficiary status between the Access Control Server (ACS), the Directory Server (DS), and the 3D Secure (3DS) Requestor.
• Y = 3DS Requestor is allowlisted by cardholder
• N = 3DS Requestor is not allowlisted by cardholder
• E = Not eligible as determined by issuer
• P = Pending confirmation by cardholder
• R = Cardholder rejected
• U = Allowlist status unknown, unavailable, or does not apply|
|source|string|false|none|The system setting trusted beneficiary status
• 01 = 3DS Server
• 02 = DS
• 03 = ACS
• 80-99 = DS-specific values
|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Y|
|status|N|
|status|E|
|status|P|
|status|R|
|status|U|
UnreferencedRefundRequest
```json
{
"source": {
"type": "currency_account",
"id": "stringstringstringstringstrin"
},
"destination": {
"type": "string",
"token": "stringstringstringstringstring",
"account_holder": {
"type": "individual",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"billing_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "str",
"zip": "string",
"country": "st"
},
"phone": {
"country_code": "string",
"number": "string"
},
"identification": {
"type": "passport",
"number": "string",
"issuing_country": "st",
"date_of_expiry": "stringstri"
},
"email": "string",
"date_of_birth": "stringstri",
"country_of_birth": "st"
}
},
"instruction": {
"funds_transfer_type": "string",
"purpose": "family_support"
},
"amount": 1,
"currency": "GBP",
"payment_type": "UnreferencedRefund",
"processing_channel_id": "string",
"reference": "string",
"metadata": {
"coupon_code": "NY2018",
"partner_id": 123989
},
"previous_payment_id": "pay_fun26akvvjjerahhctaq2uzhu4",
"segment": {
"brand": "Acme Corporation",
"business_category": "Inward Payments",
"market": "UK"
},
"processing": {
"processing_speed": "fast"
}
}
```
Unreferenced Refund
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|source|object|true|none|The source of the unreferenced refund.|
|» type|string|true|none|The unreferenced refund source type.|
|» id|string|true|none|The ID of the currency account that will fund the unreferenced refund.|
|destination|[UnreferencedRefundRequestDestination](#schemaunreferencedrefundrequestdestination)|true|none|The destination of the unreferenced refund.|
|instruction|object|false|none|Additional details about the unreferenced refund instruction.|
|» funds_transfer_type|string|false|none|**Required** if `processing.processing_speed` is `fast`.
Value of this field should be based on the destination card scheme:
- For Visa, use `MI`
- For Mastercard, use `C60`|
|» purpose|string|false|none|The purpose of the unreferenced refund.
This field is required if the card's `issuer_country` is one of:
- `AR` (Argentina)
- `BD` (Bangladesh)
- `CL` (Chile)
- `CO` (Colombia)
- `EG` (Egypt)
- `IN` (India)
- `MX` (Mexico)
To view a card's `issuer_country`, [retrieve the card's metadata](https://api-reference.checkout.com/#operation/requestCardMetadata!c=200&path=issuer_country&t=response).|
|amount|any|true|none|The amount in minor currency|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[Amount](#schemaamount)|false|none|The amount in the minor currency.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|number|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|currency|string|true|none|The three-letter ISO currency code of the payment.
|
|payment_type|string|true|none|The type of the payment|
|processing_channel_id|string|true|none|The processing channel identifier|
|reference|string|false|none|An internal reference you can later use to identify this payment|
|metadata|object|false|none|A set of key-value pairs that you can attach to the refund request. It can be useful for storing additional information in a structured format. **Note**: This object only allows one level of depth, so cannot accept non-primitive data types such as objects or arrays.|
|previous_payment_id|string|false|none|The previous related payment identifier. This could be the ID of the payment that you want to refund.|
|segment|[Segment](#schemasegment)|false|none|The dimension details about business segment for payment request. At least one dimension required.|
|processing|object|false|none|Returns information related to the processing of the payment.|
|» processing_speed|string|false|none|The speed at which the unreferenced refund is processed.
Only applicable for unreferenced refunds.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|currency_account|
|purpose|family_support|
|purpose|expatriation|
|purpose|travel_and_tourism|
|purpose|education|
|purpose|medical_treatment|
|purpose|emergency_need|
|purpose|leisure|
|purpose|savings|
|purpose|gifts|
|purpose|donations|
|purpose|financial_services|
|purpose|it_services|
|purpose|investment|
|purpose|insurance|
|purpose|loan_payment|
|purpose|pension|
|purpose|royalties|
|purpose|other|
|purpose|income|
|payment_type|UnreferencedRefund|
|processing_speed|fast|
VoidAcceptedResponse
```json
{
"action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
"reference": "ORD-5023-4E89",
"_links": {
"payment": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
}
}
}
```
Void response
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|action_id|[ActionId](#schemaactionid)|true|none|The unique identifier for the void action|
|reference|string|false|none|Your reference for the void request|
|_links|object|false|read-only|The links related to the void|
|» payment|[Link](#schemalink)|true|none|none|
VoidRequest
```json
{
"amount": 6540,
"reference": "ORD-5023-4E89",
"metadata": {
"coupon_code": "NY2018",
"partner_id": 123989
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|amount|integer(int64)|false|none|The amount to void. If not specified, the full payment amount will be voided.|
|reference|string|false|none|A reference you can later use to identify this void request.
For Amex, the string limit is 30 characters.|
|metadata|object|false|none|A set of key-value pairs to attach to the authorization request. You can use this to store additional information in a structured format.
The `metadata` object only supports primitive data types. Objects and arrays are not supported.|
BankPayout
```json
{
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"requested_on": "2023-08-24T14:15:22Z",
"destination": {
"type": "bank_account",
"id": "src_4pakgjwmv5re5m5ivqohsqpxnm",
"bank_code": "123-456",
"branch_code": "6443",
"iban": "HU93116000060000000012345676",
"country": "GB",
"account_holder": {
"first_name": "Jia",
"last_name": "Tsang"
}
},
"amount": 10000,
"currency": "GBP",
"reference": "ORD-5023-4E89",
"billing_descriptor": {
"reference": "BANK-REF"
},
"status": "Pending",
"processing_channel_id": "pc_vxt6yftthv4e5flqak6w2i7rim",
"sender": {
"first_name": "Ali",
"last_name": "Farid"
},
"actions": [
{
"type": "Return",
"processed_on": "2023-08-24T14:15:25.3448464+00:00",
"status": "Returned"
},
{
"id": "act_m4wvaqkqdzferpgpw32ykoxvuq",
"type": "Payout",
"processed_on": "2023-08-24T14:15:23.3448464+00:00",
"status": "Approved",
"response_code": "10000",
"response_summary": "Approved"
},
{
"id": "act_4crmhihaknzuvhjclvxu7bni24",
"type": "Payout",
"processed_on": "2023-08-24T14:15:22.3448464+00:00",
"status": "Pending",
"reference": "fd45gyh7-6y74-3gt6-bb3d-fd167854bc3c"
}
]
}
```
Bank payout
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The unique identifier of the payout.|
|requested_on|string|false|none|The UTC date and time the payment was requested, in ISO 8601 format.|
|destination|object|false|none|The destination of the payout.|
|» type|string|false|none|The payout destination type.|
|» id|string|false|none|The unique identifier of the payment instrument.|
|» bank_code|string|false|none|The code that identifies the bank.|
|» branch_code|string|false|none|The code that identifies the bank branch.|
|» iban|string|false|none|The International Bank Account Number (IBAN) of the account.|
|» country|string|false|none|The country where the account is based, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes).|
|» account_holder|object|false|none|The account holder's details.|
|»» first_name|string|false|none|The account holder's first name.|
|»» last_name|string|false|none|The account holder's last name.|
|amount|number|false|none|The original payout amount.|
|currency|string|false|none|The currency of the payout, as a [three-letter ISO currency code](https://www.checkout.com/docs/developer-resources/codes/currency-codes).|
|reference|string|false|none|The reference for the payout.|
|billing_descriptor|object|false|none|The billing descriptor details.|
|» reference|string|false|none|The reference displayed on the payout recipient's bank statement.|
|status|string|false|none|The status of the payout.|
|processing_channel_id|string|false|none|The unique identifier of the processing channel that was used for the payout.|
|sender|object|false|none|The payout sender's details.|
|» first_name|string|false|none|The sender's first name.|
|» last_name|string|false|none|The sender's last name.|
|actions|[object]|false|none|none|
|» id|string|false|none|The unique identifier of the payment action.|
|» type|string|false|none|The type of action.|
|» processed_on|string(date-time)|false|none|The date and time the action was processed.|
|» response_code|string|false|none|The response code.|
|» response_summary|string|false|none|The response summary.|
|» reference|string|false|none|The reference for the payout.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|Payout|
|type|Return|
BankPayoutResponse
```json
{
"data": [
{
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"requested_on": "2023-08-24T14:15:22Z",
"destination": {
"type": "bank_account",
"id": "src_4pakgjwmv5re5m5ivqohsqpxnm",
"bank_code": "123-456",
"branch_code": "6443",
"iban": "HU93116000060000000012345676",
"country": "GB",
"account_holder": {
"first_name": "Jia",
"last_name": "Tsang"
}
},
"amount": 10000,
"currency": "GBP",
"reference": "ORD-5023-4E89",
"billing_descriptor": {
"reference": "BANK-REF"
},
"status": "Pending",
"processing_channel_id": "pc_vxt6yftthv4e5flqak6w2i7rim",
"sender": {
"first_name": "Ali",
"last_name": "Farid"
},
"actions": [
{
"type": "Return",
"processed_on": "2023-08-24T14:15:25.3448464+00:00",
"status": "Returned"
},
{
"id": "act_m4wvaqkqdzferpgpw32ykoxvuq",
"type": "Payout",
"processed_on": "2023-08-24T14:15:23.3448464+00:00",
"status": "Approved",
"response_code": "10000",
"response_summary": "Approved"
},
{
"id": "act_4crmhihaknzuvhjclvxu7bni24",
"type": "Payout",
"processed_on": "2023-08-24T14:15:22.3448464+00:00",
"status": "Pending",
"reference": "fd45gyh7-6y74-3gt6-bb3d-fd167854bc3c"
}
]
}
],
"_links": {
"next": {
"href": "https://{prefix}.api.checkout.com/payments/search/nGd7-altGkOfSl3fJptLxA?token=MTc0MDUwMjE2MjQxOCxlN2NiNTdmYy04MDA5LTQ3YmMtOTYzNi0zNDEyOWRmZTkwZTI"
}
}
}
```
Bank payout response
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|data|[anyOf]|false|none|none|
|_links|[Links](#schemalinks)|false|none|Links related to the search.|
CardPayout
```json
{
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"requested_on": "2023-08-24T14:15:22Z",
"destination": {
"type": "card",
"id": "ca_y3oqhf46pyzuxjbcn2giaqnb44",
"expiry_year": "2024",
"expiry_month": "04",
"account_holder": {
"first_name": "Jia",
"last_name": "Tsang"
},
"scheme": "Visa",
"last4": "1212",
"issuer": "issuer",
"issuer_country": "issuer"
},
"amount": 10000,
"currency": "GBP",
"reference": "ORD-5023-4E89",
"billing_descriptor": {
"reference": "CARD-REF"
},
"status": "Paid",
"processing_channel_id": "pc_vxt6yftthv4e5flqak6w2i7rim",
"sender": {
"type": "individual",
"first_name": "Ali",
"last_name": "Farid"
},
"metadata": {},
"actions": [
{
"id": "act_obwnktnk6i2e5bcp5i7xq673se",
"type": "Payout",
"processed_on": "2023-08-24T14:15:23.3448464+00:00",
"status": "Approved",
"response_code": "10000",
"response_summary": "Approved",
"sanction_screening": "Pass",
"processing": {
"acquirer_reference_number": "232810098064"
}
},
{
"id": "act_rdqbtrhinozuza3wbnhi3n7noa",
"type": "Payout",
"processed_on": "2023-08-24T14:15:22.3448464+00:00",
"status": "Pending",
"reference": "fd45gyh7-6y74-3gt6-bb3d-fd167854bc3c"
}
]
}
```
Card payout
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The unique identifier of the payout.|
|requested_on|string|false|none|The UTC date and time the payment was requested, in ISO 8601 format.|
|destination|object|false|none|The destination of the payout.|
|» type|string|false|none|The payout destination type.|
|» id|string|false|none|The unique identifier of the payment source.|
|» expiry_year|string|false|none|The card expiration year.|
|» expiry_month|string|false|none|The card expiration month.|
|» account_holder|object|false|none|The account holder's details.|
|»» first_name|string|false|none|The account holder's first name.
This field is only returned if `destination.account_holder.type` is `individual`.|
|»» last_name|string|false|none|The account holder's last name.
This field is only returned if `destination.account_holder.type` is `individual`.|
|» scheme|string|false|none|The card scheme.|
|» last4|string|false|none|The last four digits of the card number.|
|» issuer|string|false|none|The issuer name.|
|» issuer_country|string|false|none|The issuer country, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes).|
|amount|number|false|none|The original payout amount.|
|currency|string|false|none|The currency of the payout, as a [three-letter ISO currency code](https://www.checkout.com/docs/developer-resources/codes/currency-codes).|
|reference|string|false|none|The reference for the payout.|
|billing_descriptor|object|false|none|The billing descriptor details.|
|» reference|string|false|none|The reference displayed on the payout recipient's bank statement.|
|status|string|false|none|The status of the payout.|
|processing_channel_id|string|false|none|The unique identifier of the processing channel that was used for the payout.|
|sender|object|false|none|The payout sender's details.|
|» type|string|false|none|The sender type.
This field is only returned for payout requests for some [funds transfer types](https://www.checkout.com/docs/payments/request-payouts/card-payouts#Fund_Transfer_Types).|
|» first_name|string|false|none|The sender's first name.
This field is only returned if `sender.type` is `individual`.|
|» last_name|string|false|none|The sender's last name.
This field is only returned if `sender.type` is `individual`.|
|metadata|object|false|none|A set of key-value pairs attached to the payout, used to store additional information.|
|actions|[object]|false|none|none|
|» id|string|false|none|The unique identifier of the payment action.|
|» type|string|false|none|The type of action.|
|» processed_on|string(date-time)|false|none|The date and time the action was processed.|
|» processing|object|false|none|none|
|»» acquirer_reference_number|string|false|none|A unique identifier for the payout that is submitted to the card scheme during processing.|
|» response_code|string|false|none|The response code.|
|» response_summary|string|false|none|The response summary.|
|» reference|string|false|none|The reference for the payout.|
|» sanction_screening|string|false|none|The outcome of sanction screening.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|Payout|
CardPayoutResponse
```json
{
"data": [
{
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"requested_on": "2023-08-24T14:15:22Z",
"destination": {
"type": "card",
"id": "ca_y3oqhf46pyzuxjbcn2giaqnb44",
"expiry_year": "2024",
"expiry_month": "04",
"account_holder": {
"first_name": "Jia",
"last_name": "Tsang"
},
"scheme": "Visa",
"last4": "1212",
"issuer": "issuer",
"issuer_country": "issuer"
},
"amount": 10000,
"currency": "GBP",
"reference": "ORD-5023-4E89",
"billing_descriptor": {
"reference": "CARD-REF"
},
"status": "Paid",
"processing_channel_id": "pc_vxt6yftthv4e5flqak6w2i7rim",
"sender": {
"type": "individual",
"first_name": "Ali",
"last_name": "Farid"
},
"metadata": {},
"actions": [
{
"id": "act_obwnktnk6i2e5bcp5i7xq673se",
"type": "Payout",
"processed_on": "2023-08-24T14:15:23.3448464+00:00",
"status": "Approved",
"response_code": "10000",
"response_summary": "Approved",
"sanction_screening": "Pass",
"processing": {
"acquirer_reference_number": "232810098064"
}
},
{
"id": "act_rdqbtrhinozuza3wbnhi3n7noa",
"type": "Payout",
"processed_on": "2023-08-24T14:15:22.3448464+00:00",
"status": "Pending",
"reference": "fd45gyh7-6y74-3gt6-bb3d-fd167854bc3c"
}
]
}
],
"_links": {
"next": {
"href": "https://{prefix}.api.checkout.com/payments/search/nGd7-altGkOfSl3fJptLxA?token=MTc0MDUwMjE2MjQxOCxlN2NiNTdmYy04MDA5LTQ3YmMtOTYzNi0zNDEyOWRmZTkwZTI"
}
}
}
```
Card payout response
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|data|[anyOf]|false|none|none|
|_links|[Links](#schemalinks)|false|none|Links related to the search.|
Links
```json
{
"next": {
"href": "https://{prefix}.api.checkout.com/payments/search/nGd7-altGkOfSl3fJptLxA?token=MTc0MDUwMjE2MjQxOCxlN2NiNTdmYy04MDA5LTQ3YmMtOTYzNi0zNDEyOWRmZTkwZTI"
}
}
```
Links
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|next|[Link](#schemalink)|false|none|A link to the next page of results, if the search returned more results than the value specified in `limit`.
Pagination links expire after 24 hours. If you attempt to access the link after this time, you receive a `404 Not Found` response code.|
Payin
```json
{
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"requested_on": "2023-08-24T14:15:22Z",
"source": {
"type": "card",
"expiry_month": "04",
"expiry_year": "2024",
"name": "Jia Tsang",
"scheme": "Visa",
"local_schemes": [
"cartes bancaires"
],
"last4": "3131",
"fingerprint": "B16D9C2EF0C861A8825C9BD59CCE9171D84EBC45E89CC792B5D1D2D0DDE3DAB7",
"bin": "313131",
"card_type": "credit",
"card_wallet_type": "googlepay",
"issuer": "GE CAPITAL FINANCIAL, INC",
"issuer_country": "US",
"avs_check": "G"
},
"amount": 10000,
"amount_requested": 10000,
"currency": "GBP",
"payment_type": "regular",
"processing_channel_id": "pc_vxt6yftthv4e5flqak6w2i7rim",
"reference": "ORD-5023-4E89",
"status": "captured",
"balances": {
"total_authorized": 200,
"total_captured": 150,
"total_refunded": 50
},
"3ds": {
"eci": "02",
"version": "2.1.0"
},
"risk": {
"flagged": false,
"score": "22"
},
"customer": {
"email": "jia.tsang@checkout.com",
"name": "Jia Tsang"
},
"billing_descriptor": {
"name": "Purchase",
"city": "London"
},
"metadata": {},
"actions": [
{
"id": "act_egiv5753bwmexj6ip3tlpog6gq",
"type": "Dispute",
"processed_on": "2023-08-25T14:15:24Z",
"status": "Evidence Required",
"amount": 1310,
"reason_code": "13.1"
},
{
"id": "act_i3cd3w3lcooexmyrtlgulk3d7a",
"type": "Capture",
"processed_on": "2023-08-24T14:15:26Z",
"status": "Approved",
"amount": 1310,
"auth_code": "983647",
"response_code": "10000",
"response_summary": "Approved",
"reference": "REF-7HR-IYW",
"processing": {
"acquirer_reference_number": "25651432189281252509653"
}
},
{
"id": "act_2uwlm6xyeszerhroqhfnotmiwu",
"type": "Authorization",
"processed_on": "2023-08-24T14:15:25Z",
"status": "Approved",
"amount": 1310,
"auth_code": "983647",
"response_code": "10000",
"response_summary": "Approved",
"reference": "REF-7HR-IYW",
"processing": {
"acquirer_reference_number": "25651432189281252509653"
}
},
{
"id": "act_mscwxewzdldefh2rbbnhm6aeqi",
"type": "Authorization",
"processed_on": "2023-08-24T14:15:24Z",
"status": "Pending",
"amount": 1310,
"reference": "REF-7HR-IYW"
},
{
"id": "act_qocmjw6skb4u3c4wd3avpot64y",
"type": "Authentication",
"processed_on": "2023-08-24T14:15:34Z",
"status": "Approved",
"authentication_experience": "3ds",
"authentication_transaction_id": "f05af960-f718-428d-b856-068f6cb9a3b4"
},
{
"id": "act_qocmjw6skb4u3c4wd3avpot64y",
"type": "Authentication",
"processed_on": "2023-08-24T14:15:22Z",
"status": "Pending",
"reference": "REF-7HR-IYW"
}
]
}
```
Payin
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The unique identifier of the payment.|
|requested_on|string|false|none|The UTC date and time the payment was requested, in ISO 8601 format.|
|source|object|false|none|The source of the payment.|
|» type|string|false|none|The payment source type.
For payment request sources that result in a card token, this will be `card`. For example, a token or source ID.|
|» expiry_month|string|false|none|The card expiration month.|
|» expiry_year|string|false|none|The card expiration year.|
|» name|string|false|none|The cardholder's name.|
|» scheme|string|false|none|The card scheme.|
|» local_schemes|[string]|false|none|The local co-branded card scheme.|
|» last4|string|false|none|The last four digits of the card number.|
|» fingerprint|string|false|none|The card's unique fingerprint.
You can use the card fingerprint to compare cards across customers.|
|» bin|string|false|none|The card issuer's Bank Identification Number (BIN).|
|» card_type|string|false|none|The card type.|
|» card_wallet_type|string|false|none|The card wallet type.|
|» issuer|string|false|none|The card issuer.|
|» issuer_country|string|false|none|The issuer country, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes).|
|» avs_check|string|false|none|The result of the Address Verification System (AVS) check.|
|amount|number|false|none|The original payment amount.|
|amount_requested|number|false|none|The full amount from the original authorization, if a partial authorization was requested.|
|currency|string|false|none|The currency of the payment, as a [three-letter ISO currency code](https://www.checkout.com/docs/developer-resources/codes/currency-codes).|
|payment_type|string|false|none|The type of payment.
This field is returned for card payments where the cardholder was not present. For example, recurring payments or mail order / telephone order (MOTO) payments.|
|processing_channel_id|string|false|none|The unique identifier of the processing channel that was used for the payment.|
|reference|string|false|none|The reference for the payment.|
|status|string|false|none|The status of the payment.|
|balances|object|false|none|The payment's balances.|
|» total_authorized|number|false|none|The total amount that was authorized.|
|» total_captured|number|false|none|The total amount that was captured.|
|» total_refunded|number|false|none|The total amount that was refunded.|
|3ds|object|false|none|Details relating to payments processed with 3D Secure (3DS).|
|» eci|string|false|none|The Electronic Commerce Indicator (ECI).|
|» version|string|false|none|The version of 3DS that was used for authentication.|
|risk|object|false|none|The payment's risk assessment results.|
|» flagged|boolean|false|none|Specifies whether the payment was flagged by a risk check.|
|» score|string|false|none|The risk score calculated by our Fraud Detection engine.
This field is only returned if sufficient data was provided to Fraud Detection.|
|customer|object|false|none|The customer linked to the payment.|
|» email|string|false|none|The customer's email address.|
|» name|string|false|none|The customer's name.|
|billing_descriptor|object|false|none|An optional description displayed on the customer's statement identifying a purchase.
Applies to card payments only.|
|» name|string|false|none|The reference displayed on the customer's bank statement.|
|» city|string|false|none|The city from which the payment originated.|
|metadata|object|false|none|A set of key-value pairs attached to the payout, used to store additional information.|
|actions|[object]|false|none|none|
|» id|string|false|none|The unique identifier of the payment action, including authentication and disputes.|
|» type|string|false|none|The type of action.|
|» status|string|false|none|The action outcome.|
|» processed_on|string(date-time)|false|none|The date and time the action was processed.|
|» amount|integer|false|none|The action amount in minor currency units.|
|» auth_code|string|false|none|The issuer authorization code for cards.|
|» response_code|string|false|none|The response code.|
|» response_summary|string|false|none|The response summary.|
|» reference|string|false|none|Your reference for the action.|
|» processing|object|false|none|none|
|»» acquirer_reference_number|string|false|none|A unique identifier for the capture that is submitted to the card scheme during processing.|
|» fraud_score|string|false|none|The risk score calculated by our Fraud Detection engine. This field is only returned if sufficient data was provided to Fraud Detection.|
|» response_status_reason|string|false|none|The reason for the response status. This is only available as a result of a 3DS2 authentication.|
|» authentication_experience|string|false|none|The authentication type used.|
|» reason_code|string|false|none|The reason code provided by the card scheme. This only applies to disputes.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|Authentication|
|type|Authorization|
|type|Card Verification|
|type|Void|
|type|Capture|
|type|Partial Capture|
|type|Partial Refund|
|type|Refund|
|type|Cancelation|
|type|Request|
|type|Pending|
|type|Dispute|
PayinResponse
```json
{
"data": [
{
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"requested_on": "2023-08-24T14:15:22Z",
"source": {
"type": "card",
"expiry_month": "04",
"expiry_year": "2024",
"name": "Jia Tsang",
"scheme": "Visa",
"local_schemes": [
"cartes bancaires"
],
"last4": "3131",
"fingerprint": "B16D9C2EF0C861A8825C9BD59CCE9171D84EBC45E89CC792B5D1D2D0DDE3DAB7",
"bin": "313131",
"card_type": "credit",
"card_wallet_type": "googlepay",
"issuer": "GE CAPITAL FINANCIAL, INC",
"issuer_country": "US",
"avs_check": "G"
},
"amount": 10000,
"amount_requested": 10000,
"currency": "GBP",
"payment_type": "regular",
"processing_channel_id": "pc_vxt6yftthv4e5flqak6w2i7rim",
"reference": "ORD-5023-4E89",
"status": "captured",
"balances": {
"total_authorized": 200,
"total_captured": 150,
"total_refunded": 50
},
"3ds": {
"eci": "02",
"version": "2.1.0"
},
"risk": {
"flagged": false,
"score": "22"
},
"customer": {
"email": "jia.tsang@checkout.com",
"name": "Jia Tsang"
},
"billing_descriptor": {
"name": "Purchase",
"city": "London"
},
"metadata": {},
"actions": [
{
"id": "act_egiv5753bwmexj6ip3tlpog6gq",
"type": "Dispute",
"processed_on": "2023-08-25T14:15:24Z",
"status": "Evidence Required",
"amount": 1310,
"reason_code": "13.1"
},
{
"id": "act_i3cd3w3lcooexmyrtlgulk3d7a",
"type": "Capture",
"processed_on": "2023-08-24T14:15:26Z",
"status": "Approved",
"amount": 1310,
"auth_code": "983647",
"response_code": "10000",
"response_summary": "Approved",
"reference": "REF-7HR-IYW",
"processing": {
"acquirer_reference_number": "25651432189281252509653"
}
},
{
"id": "act_2uwlm6xyeszerhroqhfnotmiwu",
"type": "Authorization",
"processed_on": "2023-08-24T14:15:25Z",
"status": "Approved",
"amount": 1310,
"auth_code": "983647",
"response_code": "10000",
"response_summary": "Approved",
"reference": "REF-7HR-IYW",
"processing": {
"acquirer_reference_number": "25651432189281252509653"
}
},
{
"id": "act_mscwxewzdldefh2rbbnhm6aeqi",
"type": "Authorization",
"processed_on": "2023-08-24T14:15:24Z",
"status": "Pending",
"amount": 1310,
"reference": "REF-7HR-IYW"
},
{
"id": "act_qocmjw6skb4u3c4wd3avpot64y",
"type": "Authentication",
"processed_on": "2023-08-24T14:15:34Z",
"status": "Approved",
"authentication_experience": "3ds",
"authentication_transaction_id": "f05af960-f718-428d-b856-068f6cb9a3b4"
},
{
"id": "act_qocmjw6skb4u3c4wd3avpot64y",
"type": "Authentication",
"processed_on": "2023-08-24T14:15:22Z",
"status": "Pending",
"reference": "REF-7HR-IYW"
}
]
}
],
"_links": {
"next": {
"href": "https://{prefix}.api.checkout.com/payments/search/nGd7-altGkOfSl3fJptLxA?token=MTc0MDUwMjE2MjQxOCxlN2NiNTdmYy04MDA5LTQ3YmMtOTYzNi0zNDEyOWRmZTkwZTI"
}
}
}
```
Payin response
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|data|[anyOf]|false|none|none|
|_links|[Links](#schemalinks)|false|none|Links related to the search.|
SearchError
```json
{
"request_id": "0HL80RJLS76I7",
"error_type": "request_invalid",
"error_codes": [
"unknown_attribute"
]
}
```
Search error
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|request_id|string|false|none|none|
|error_type|string|false|none|none|
|error_codes|[string]|false|none|none|
SearchRequest
```json
{
"query": "id:'pay_mbabizu24mvu3mela5njyhpit4'",
"limit": 10,
"from": "2023-08-24T14:15:22Z",
"to": "2023-08-24T14:15:22Z"
}
```
Search request
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|query|string|false|none|The query string.
For more information on how to build out your query, see the Search and filter payments documentation.|
|limit|integer|false|none|The number of results to return per page.|
|from|string|false|none|The UTC date and time for the query start in ISO 8601 format. Required if `to` is provided.|
|to|string|false|none|The UTC date and time for the query end in ISO 8601 format. Required if `from` is provided.|
CreateAndSubmitPaymentSessionsActionRequiredResponse
```json
{
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"status": "Action Required",
"type": "alipay_cn",
"action": {},
"payment_session_id": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ",
"payment_session_secret": "pss_9823241e-2cec-4c98-b23d-7b29ow4e2e34"
}
```
Response for an action required payment session payment.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[PaymentId](#schemapaymentid)|true|none|The payment identifier.|
|status|string|true|none|The payment's status.|
|type|[PaymentInterfacesPaymentMethod](#schemapaymentinterfacespaymentmethod)|true|none|The payment method name.|
|action|object|true|none|Instruction for further payment action.|
|payment_session_id|[PaymentSessionId](#schemapaymentsessionid)|true|none|The Payment Sessions unique identifier|
|payment_session_secret|[PaymentSessionSecret](#schemapaymentsessionsecret)|true|none|The secret used by Flow to authenticate payment session requests.
Do not log or store this value.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Action Required|
CreateAndSubmitPaymentSessionsProcessedResponse
```json
{
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"status": "Approved",
"type": "alipay_cn",
"payment_session_id": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ",
"payment_session_secret": "pss_9823241e-2cec-4c98-b23d-7b29ow4e2e34"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[PaymentId](#schemapaymentid)|true|none|The payment identifier.|
|status|string|true|none|The payment's status.|
|type|[PaymentInterfacesPaymentMethod](#schemapaymentinterfacespaymentmethod)|true|none|The payment method name.|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[CreateAndSubmitPaymentSessionsProcessedResponseStatusApproved](#schemacreateandsubmitpaymentsessionsprocessedresponsestatusapproved)|false|none|Response for an approved payment session payment.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[CreateAndSubmitPaymentSessionsProcessedResponseStatusDeclined](#schemacreateandsubmitpaymentsessionsprocessedresponsestatusdeclined)|false|none|Response for a declined payment session payment.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Approved|
|status|Declined|
CreateAndSubmitPaymentSessionsProcessedResponseStatusApproved
```json
{
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"status": "Approved",
"type": "alipay_cn",
"payment_session_id": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ",
"payment_session_secret": "pss_9823241e-2cec-4c98-b23d-7b29ow4e2e34"
}
```
Approved
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[PaymentId](#schemapaymentid)|true|none|The payment identifier.|
|status|string|true|none|The payment was approved.|
|type|[PaymentInterfacesPaymentMethod](#schemapaymentinterfacespaymentmethod)|true|none|The payment method name.|
|payment_session_id|[PaymentSessionId](#schemapaymentsessionid)|true|none|The Payment Sessions unique identifier|
|payment_session_secret|[PaymentSessionSecret](#schemapaymentsessionsecret)|true|none|The secret used by Flow to authenticate payment session requests.
Do not log or store this value.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Approved|
CreateAndSubmitPaymentSessionsProcessedResponseStatusDeclined
```json
{
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"status": "Declined",
"type": "alipay_cn",
"decline_reason": "string"
}
```
Declined
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[PaymentId](#schemapaymentid)|true|none|The payment identifier.|
|status|string|true|none|The payment was declined.|
|type|[PaymentInterfacesPaymentMethod](#schemapaymentinterfacespaymentmethod)|true|none|The payment method name.|
|decline_reason|string|true|none|The reason for the payment decline.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Declined|
CreateAndSubmitPaymentSessionsRequest
```json
{
"session_data": "string",
"amount": 1000,
"currency": "USD",
"payment_type": "Regular",
"authorization_type": "Estimated",
"billing": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"billing_descriptor": {
"name": "string",
"city": "string",
"reference": "string"
},
"reference": "ORD-123A",
"description": "Payment for gold necklace",
"customer": {
"email": "jia.tsang@example.com",
"name": "Jia Tsang",
"id": "string",
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"tax_number": "string",
"summary": {
"registration_date": "2023-05-01",
"first_transaction_date": "2023-07-01",
"last_payment_date": "2023-08-01",
"total_order_count": 15,
"last_payment_amount": 500,
"is_premium_customer": true,
"is_returning_customer": true,
"lifetime_value": 500
}
},
"shipping": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"recipient": {
"dob": "1985-05-15",
"account_number": "5555554444",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"first_name": "Jia",
"last_name": "Tsang"
},
"processing": {
"aft": true,
"discount_amount": 0,
"shipping_amount": 300,
"tax_amount": 3000,
"invoice_id": "string",
"brand_name": "string",
"locale": "en-US",
"partner_customer_risk_data": {
"key": "string",
"value": "string"
},
"custom_payment_method_ids": [
"string"
],
"airline_data": [
{
"ticket": {
"number": "045-21351455613",
"issue_date": "2023-05-20",
"issuing_carrier_code": "AI",
"travel_package_indicator": "B",
"travel_agency_name": "World Tours",
"travel_agency_code": "01"
},
"passenger": [
{
"first_name": "John",
"last_name": "White",
"date_of_birth": "1990-05-26",
"address": {
"country": "US"
}
}
],
"flight_leg_details": [
{
"flight_number": "101",
"carrier_code": "BA",
"class_of_travelling": "J",
"departure_airport": "LHR",
"departure_date": "2023-06-19",
"departure_time": "15:30",
"arrival_airport": "LAX",
"stop_over_code": "x",
"fare_basis_code": "SPRSVR"
}
]
}
],
"accommodation_data": [
{
"name": "The Sea View Hotel",
"booking_reference": "HOTEL123",
"check_in_date": "2023-06-20",
"check_out_date": "2023-06-23",
"address": {
"address_line1": "123 Beach Road",
"zip": "10001"
},
"state": "FL",
"country": "USA",
"city": "Los Angeles",
"number_of_rooms": 2,
"guests": [
{
"first_name": "Jane",
"last_name": "Doe",
"date_of_birth": "1985-07-14"
}
],
"room": [
{
"rate": "70",
"number_of_nights_at_room_rate": "3"
}
]
}
],
"order_id": "123456789",
"surcharge_amount": 200,
"duty_amount": 0,
"shipping_tax_amount": 100,
"affiliate_id": "string",
"affiliate_url": "www.mycrypto.com",
"purchase_country": "string",
"merchant_initiated_reason": "Delayed_charge",
"campaign_id": 0,
"original_order_amount": 10,
"receipt_id": "10",
"merchant_callback_url": "string",
"line_of_business": "Flights",
"pan_preference": "fpan",
"provision_network_token": true,
"reconciliation_id": "4123495123",
"aggregator": {
"sub_merchant_id": "9cf70789ba90123",
"aggregator_id_visa": "10012345",
"aggregator_id_mc": "00000123456"
}
},
"instruction": {
"purpose": "donations"
},
"processing_channel_id": "string",
"items": [
{
"reference": "string",
"commodity_code": "string",
"unit_of_measure": "string",
"total_amount": 1000,
"tax_amount": 1000,
"discount_amount": 1000,
"url": "string",
"image_url": "string",
"name": "Gold Necklace",
"quantity": 1,
"unit_price": 1000
}
],
"amount_allocations": [
{
"id": "string",
"amount": 1,
"reference": "ORD-123A",
"commission": {
"amount": 10,
"percentage": 12.5
}
}
],
"risk": {
"enabled": false
},
"display_name": "string",
"success_url": "https://example.com/payments/success",
"failure_url": "https://example.com/payments/failure",
"metadata": {
"coupon_code": "NY2018"
},
"locale": "ar",
"3ds": {
"enabled": "false",
"challenge_indicator": "no_preference",
"allow_upgrade": true,
"exemption": "low_value"
},
"sender": {},
"capture": true,
"capture_on": "2024-01-01T09:15:30Z",
"payment_plan": {
"amount_variability": "Variable",
"days_between_payments": 28,
"total_number_of_payments": 5,
"current_payment_number": 3,
"expiry": "20251031",
"name": "Subscription 1234",
"start_date": "20260507",
"amount": 1234
}
}
```
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» session_data|[PaymentSessionsSessionData](#schemapaymentsessionssessiondata)|true|none|A unique token representing the additional customer data captured by Flow, as received from the handleSubmit callback.
Do not log or store this value.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[CreatePaymentSessionsBaseRequest](#schemacreatepaymentsessionsbaserequest)|false|none|none|
CreatePaymentSessionsBaseRequest
```json
{
"amount": 1000,
"currency": "USD",
"payment_type": "Regular",
"authorization_type": "Estimated",
"billing": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"billing_descriptor": {
"name": "string",
"city": "string",
"reference": "string"
},
"reference": "ORD-123A",
"description": "Payment for gold necklace",
"customer": {
"email": "jia.tsang@example.com",
"name": "Jia Tsang",
"id": "string",
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"tax_number": "string",
"summary": {
"registration_date": "2023-05-01",
"first_transaction_date": "2023-07-01",
"last_payment_date": "2023-08-01",
"total_order_count": 15,
"last_payment_amount": 500,
"is_premium_customer": true,
"is_returning_customer": true,
"lifetime_value": 500
}
},
"shipping": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"recipient": {
"dob": "1985-05-15",
"account_number": "5555554444",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"first_name": "Jia",
"last_name": "Tsang"
},
"processing": {
"aft": true,
"discount_amount": 0,
"shipping_amount": 300,
"tax_amount": 3000,
"invoice_id": "string",
"brand_name": "string",
"locale": "en-US",
"partner_customer_risk_data": {
"key": "string",
"value": "string"
},
"custom_payment_method_ids": [
"string"
],
"airline_data": [
{
"ticket": {
"number": "045-21351455613",
"issue_date": "2023-05-20",
"issuing_carrier_code": "AI",
"travel_package_indicator": "B",
"travel_agency_name": "World Tours",
"travel_agency_code": "01"
},
"passenger": [
{
"first_name": "John",
"last_name": "White",
"date_of_birth": "1990-05-26",
"address": {
"country": "US"
}
}
],
"flight_leg_details": [
{
"flight_number": "101",
"carrier_code": "BA",
"class_of_travelling": "J",
"departure_airport": "LHR",
"departure_date": "2023-06-19",
"departure_time": "15:30",
"arrival_airport": "LAX",
"stop_over_code": "x",
"fare_basis_code": "SPRSVR"
}
]
}
],
"accommodation_data": [
{
"name": "The Sea View Hotel",
"booking_reference": "HOTEL123",
"check_in_date": "2023-06-20",
"check_out_date": "2023-06-23",
"address": {
"address_line1": "123 Beach Road",
"zip": "10001"
},
"state": "FL",
"country": "USA",
"city": "Los Angeles",
"number_of_rooms": 2,
"guests": [
{
"first_name": "Jane",
"last_name": "Doe",
"date_of_birth": "1985-07-14"
}
],
"room": [
{
"rate": "70",
"number_of_nights_at_room_rate": "3"
}
]
}
],
"order_id": "123456789",
"surcharge_amount": 200,
"duty_amount": 0,
"shipping_tax_amount": 100,
"affiliate_id": "string",
"affiliate_url": "www.mycrypto.com",
"purchase_country": "string",
"merchant_initiated_reason": "Delayed_charge",
"campaign_id": 0,
"original_order_amount": 10,
"receipt_id": "10",
"merchant_callback_url": "string",
"line_of_business": "Flights",
"pan_preference": "fpan",
"provision_network_token": true,
"reconciliation_id": "4123495123",
"aggregator": {
"sub_merchant_id": "9cf70789ba90123",
"aggregator_id_visa": "10012345",
"aggregator_id_mc": "00000123456"
}
},
"instruction": {
"purpose": "donations"
},
"processing_channel_id": "string",
"items": [
{
"reference": "string",
"commodity_code": "string",
"unit_of_measure": "string",
"total_amount": 1000,
"tax_amount": 1000,
"discount_amount": 1000,
"url": "string",
"image_url": "string",
"name": "Gold Necklace",
"quantity": 1,
"unit_price": 1000
}
],
"amount_allocations": [
{
"id": "string",
"amount": 1,
"reference": "ORD-123A",
"commission": {
"amount": 10,
"percentage": 12.5
}
}
],
"risk": {
"enabled": false
},
"display_name": "string",
"success_url": "https://example.com/payments/success",
"failure_url": "https://example.com/payments/failure",
"metadata": {
"coupon_code": "NY2018"
},
"locale": "ar",
"3ds": {
"enabled": "false",
"challenge_indicator": "no_preference",
"allow_upgrade": true,
"exemption": "low_value"
},
"sender": {},
"capture": true,
"capture_on": "2024-01-01T09:15:30Z",
"payment_plan": {
"amount_variability": "Variable",
"days_between_payments": 28,
"total_number_of_payments": 5,
"current_payment_number": 3,
"expiry": "20251031",
"name": "Subscription 1234",
"start_date": "20260507",
"amount": 1234
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|amount|[PaymentSessionsAmount](#schemapaymentsessionsamount)|true|none|The payment amount. Provide a value of `0` to perform a card verification.
The amount must be provided in the minor currency unit.|
|currency|[PaymentSessionCurrency](#schemapaymentsessioncurrency)|true|none|The three-letter ISO currency code.|
|payment_type|[PaymentSessionPaymentType](#schemapaymentsessionpaymenttype)|false|none|Must be specified for card-not-present (CNP) payments. For example, a recurring mail order / telephone order (MOTO) payment.|
|authorization_type|string|false|none|The authorization type.|
|billing|[PaymentSessionBilling](#schemapaymentsessionbilling)|true|none|The billing details.|
|billing_descriptor|[PaymentSessionsBillingDescriptor](#schemapaymentsessionsbillingdescriptor)|false|none|A description of the purchase, which is displayed on the customer's statement.|
|reference|[PaymentInterfacesReference](#schemapaymentinterfacesreference)|false|none|A reference you can use to identify the payment. For example, an order number.
- For Amex payments, this must be at most 30 characters.
- For Benefit payments, the reference must be a unique alphanumeric value.
- For iDEAL payments, the reference is required and must be an alphanumeric value with a 35-character limit.|
|description|string|false|none|A description for the payment.|
|customer|[PaymentSessionCustomer](#schemapaymentsessioncustomer)|false|none|The customer's details. Required if `source.type` is `tamara`.|
|shipping|[PaymentSessionShipping](#schemapaymentsessionshipping)|false|none|The shipping details|
|recipient|[PaymentInterfacesRecipient](#schemapaymentinterfacesrecipient)|false|none|Information about the recipient of the payment's funds. Applies to Account Funding Transactions, and VISA or Mastercard domestic UK transactions processed by financial institutions.|
|processing|[PaymentInterfacesProcessing](#schemapaymentinterfacesprocessing)|false|none|Use the processing object to influence or override the data sent during card processing|
|instruction|object|false|none|Details about the payment instruction.|
|» purpose|[Purpose](#schemapurpose)|false|none|The purpose of the payment.
This field might be required for AFT transactions depending on the card's `issuer_country`. To view a card's `issuer_country`, [retrieve the card's metadata](https://api-reference.checkout.com/#operation/requestCardMetadata!c=200&path=issuer_country&t=response).
See the [AFT documentation page](https://www.checkout.com/docs/payments/manage-payments/perform-an-account-funding-transaction) for more details.|
|processing_channel_id|[PaymentSessionProcessingChannelId](#schemapaymentsessionprocessingchannelid)|false|none|The processing channel to use for the payment.|
|items|[PaymentSessionsItems](#schemapaymentsessionsitems)|false|none|The line items in the order.|
|amount_allocations|[object]|false|none|The sub-entities that the payment is being processed on behalf of.|
|» id|string|true|none|The sub-entity's ID.|
|» amount|integer|true|none|The split amount, in minor currency units. The sum of all split amounts must be equal to the payment amount. The split amount will be credited to your sub-entity's currency account.|
|» reference|string|false|none|A reference you can use to identify the split. For example, an order number.|
|» commission|object|false|none|The commission you'd like to collect from the split, calculated using the formula: `commission = (amount * commission.percentage) + commission.amount`. The commission cannot exceed the split amount. Commission will be credited to your currency account.|
|»» amount|integer|false|none|An optional commission to collect, as a fixed amount in minor currency units.|
|»» percentage|number|false|none|An optional commission to collect, as a percentage value with up to eight decimal places.|
|risk|object|false|none|Configures the risk assessment performed during payment processing.|
|» enabled|boolean|true|none|Specifies whether to perform a risk assessment.|
|display_name|string|false|none|The merchant's display name.|
|success_url|[PaymentSessionsSuccessUrl](#schemapaymentsessionssuccessurl)|true|none|Overrides the default success redirect URL configured on your account, for payment methods that require a redirect.|
|failure_url|[PaymentSessionsFailureUrl](#schemapaymentsessionsfailureurl)|true|none|Overrides the default failure redirect URL configured on your account, for payment methods that require a redirect.|
|metadata|[PaymentSessionMetadata](#schemapaymentsessionmetadata)|false|none|Allows you to store additional information about a transaction with custom fields and up to five user-defined fields, which can be used for reporting purposes. You can supply fields of type `string`, `number`, and `boolean` within the `metadata` object. Arrays and objects are not supported.
You can provide up to 18 metadata fields per API call, but the value of each field must not exceed 255 characters in length.
You can also reference [`metadata` properties](https://www.checkout.com/docs/business-operations/prevent-fraud/understand-fraud-detection#Metadata) in your custom rules for Fraud Detection. For example, `$coupon_code = '1234'`.|
|locale|string|false|none|Creates a translated version of the page in the specified language.|
|3ds|[PaymentSessions3DS](#schemapaymentsessions3ds)|false|none|none|
|sender|[PaymentInterfacesSender](#schemapaymentinterfacessender)|false|none|The sender of the payment.|
|capture|[PaymentSessionCaptureFlag](#schemapaymentsessioncaptureflag)|false|none|Specifies whether to capture the payment, if applicable.|
|capture_on|[PaymentSessionCaptureOn](#schemapaymentsessioncaptureon)|false|none|A timestamp specifying when to capture the payment, as an ISO 8601 code. If a value is provided, `capture` is automatically set to `true`.|
|payment_plan|[PaymentSessionPaymentPlanRecurring](#schemapaymentsessionpaymentplanrecurring)|false|none|The information to process a recurring payment request. To be used when the payment_type is Recurring.|
#### Enumerated Values
|Property|Value|
|---|---|
|authorization_type|Final|
|authorization_type|Estimated|
|locale|ar|
|locale|da-DK|
|locale|de-DE|
|locale|el|
|locale|en-GB|
|locale|es-ES|
|locale|fi-FI|
|locale|fil-PH|
|locale|fr-FR|
|locale|hi-IN|
|locale|id-ID|
|locale|it-IT|
|locale|ja-JP|
|locale|ko-KR|
|locale|ms-MY|
|locale|nb-NO|
|locale|nl-NL|
|locale|pt-PT|
|locale|sv-SE|
|locale|th-TH|
|locale|vi-VN|
|locale|zh-CN|
|locale|zh-HK|
|locale|zh-TW|
CreatePaymentSessionsRequest
```json
{
"amount": 1000,
"currency": "USD",
"payment_type": "Regular",
"authorization_type": "Estimated",
"billing": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"billing_descriptor": {
"name": "string",
"city": "string",
"reference": "string"
},
"reference": "ORD-123A",
"description": "Payment for gold necklace",
"customer": {
"email": "jia.tsang@example.com",
"name": "Jia Tsang",
"id": "string",
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"tax_number": "string",
"summary": {
"registration_date": "2023-05-01",
"first_transaction_date": "2023-07-01",
"last_payment_date": "2023-08-01",
"total_order_count": 15,
"last_payment_amount": 500,
"is_premium_customer": true,
"is_returning_customer": true,
"lifetime_value": 500
}
},
"shipping": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"recipient": {
"dob": "1985-05-15",
"account_number": "5555554444",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"first_name": "Jia",
"last_name": "Tsang"
},
"processing": {
"aft": true,
"discount_amount": 0,
"shipping_amount": 300,
"tax_amount": 3000,
"invoice_id": "string",
"brand_name": "string",
"locale": "en-US",
"partner_customer_risk_data": {
"key": "string",
"value": "string"
},
"custom_payment_method_ids": [
"string"
],
"airline_data": [
{
"ticket": {
"number": "045-21351455613",
"issue_date": "2023-05-20",
"issuing_carrier_code": "AI",
"travel_package_indicator": "B",
"travel_agency_name": "World Tours",
"travel_agency_code": "01"
},
"passenger": [
{
"first_name": "John",
"last_name": "White",
"date_of_birth": "1990-05-26",
"address": {
"country": "US"
}
}
],
"flight_leg_details": [
{
"flight_number": "101",
"carrier_code": "BA",
"class_of_travelling": "J",
"departure_airport": "LHR",
"departure_date": "2023-06-19",
"departure_time": "15:30",
"arrival_airport": "LAX",
"stop_over_code": "x",
"fare_basis_code": "SPRSVR"
}
]
}
],
"accommodation_data": [
{
"name": "The Sea View Hotel",
"booking_reference": "HOTEL123",
"check_in_date": "2023-06-20",
"check_out_date": "2023-06-23",
"address": {
"address_line1": "123 Beach Road",
"zip": "10001"
},
"state": "FL",
"country": "USA",
"city": "Los Angeles",
"number_of_rooms": 2,
"guests": [
{
"first_name": "Jane",
"last_name": "Doe",
"date_of_birth": "1985-07-14"
}
],
"room": [
{
"rate": "70",
"number_of_nights_at_room_rate": "3"
}
]
}
],
"order_id": "123456789",
"surcharge_amount": 200,
"duty_amount": 0,
"shipping_tax_amount": 100,
"affiliate_id": "string",
"affiliate_url": "www.mycrypto.com",
"purchase_country": "string",
"merchant_initiated_reason": "Delayed_charge",
"campaign_id": 0,
"original_order_amount": 10,
"receipt_id": "10",
"merchant_callback_url": "string",
"line_of_business": "Flights",
"pan_preference": "fpan",
"provision_network_token": true,
"reconciliation_id": "4123495123",
"aggregator": {
"sub_merchant_id": "9cf70789ba90123",
"aggregator_id_visa": "10012345",
"aggregator_id_mc": "00000123456"
}
},
"instruction": {
"purpose": "donations"
},
"processing_channel_id": "string",
"items": [
{
"reference": "string",
"commodity_code": "string",
"unit_of_measure": "string",
"total_amount": 1000,
"tax_amount": 1000,
"discount_amount": 1000,
"url": "string",
"image_url": "string",
"name": "Gold Necklace",
"quantity": 1,
"unit_price": 1000
}
],
"amount_allocations": [
{
"id": "string",
"amount": 1,
"reference": "ORD-123A",
"commission": {
"amount": 10,
"percentage": 12.5
}
}
],
"risk": {
"enabled": false
},
"display_name": "string",
"success_url": "https://example.com/payments/success",
"failure_url": "https://example.com/payments/failure",
"metadata": {
"coupon_code": "NY2018"
},
"locale": "ar",
"3ds": {
"enabled": "false",
"challenge_indicator": "no_preference",
"allow_upgrade": true,
"exemption": "low_value"
},
"sender": {},
"capture": true,
"capture_on": "2024-01-01T09:15:30Z",
"payment_plan": {
"amount_variability": "Variable",
"days_between_payments": 28,
"total_number_of_payments": 5,
"current_payment_number": 3,
"expiry": "20251031",
"name": "Subscription 1234",
"start_date": "20260507",
"amount": 1234
},
"expires_on": "2024-01-01T09:15:30Z",
"enabled_payment_methods": [
"card",
"applepay",
"googlepay"
],
"disabled_payment_methods": [
"eps",
"ideal",
"knet"
],
"payment_method_configuration": {
"applepay": {
"store_payment_details": "disabled",
"account_holder": {},
"total_type": "pending"
},
"card": {
"store_payment_details": "disabled",
"account_holder": {}
},
"googlepay": {
"store_payment_details": "disabled",
"account_holder": {},
"total_price_status": "estimated"
},
"stored_card": {
"customer_id": "string",
"instrument_ids": [
"string"
],
"default_instrument_id": "string"
}
},
"customer_retry": {
"max_attempts": 2
},
"ip_address": "90.197.169.245"
}
```
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[CreatePaymentSessionsBaseRequest](#schemacreatepaymentsessionsbaserequest)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» expires_on|string(date-time)|false|none|A timestamp specifying when the `PaymentSession` should expire, as an ISO 8601 code. If no value is provided, expiry is set to 24 hours after the `PaymentSession` is created. You cannot set the session expiry to more than 60 days after the `PaymentSession` is created.|
|» enabled_payment_methods|[PaymentInterfacesPaymentMethods](#schemapaymentinterfacespaymentmethods)|false|none|Specifies which payment method options to present to the customer.
The values in this field override any equivalent values in `disabled_payment_methods`.|
|» disabled_payment_methods|[PaymentInterfacesPaymentMethods](#schemapaymentinterfacespaymentmethods)|false|none|Specifies which payment method options to not present to the customer.
If you specify the same payment method in this field and in `enabled_payment_methods`, the `disabled_payment_methods` value will be overridden.
Any payment method options not explicitly specified in this field will be presented to the customer by default.|
|» payment_method_configuration|any|false|none|none|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»» *anonymous*|[PaymentSessionsPaymentMethodConfigurationBase](#schemapaymentsessionspaymentmethodconfigurationbase)|false|none|Configurations for payment method-specific settings.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»» *anonymous*|object|false|none|none|
|»»» applepay|object|false|none|none|
|»»»» account_holder|object|false|none|The account holder's details.|
|»»»» total_type|string|false|none|The [type](https://developer.apple.com/documentation/applepayontheweb/applepaylineitemtype) of the Apple Pay payment [total line item](https://developer.apple.com/documentation/applepayontheweb/applepaypaymentrequest/total).|
|»»» card|object|false|none|none|
|»»»» account_holder|object|false|none|The account holder's details.|
|»»» googlepay|object|false|none|none|
|»»»» account_holder|object|false|none|The account holder's details.|
|»»»» total_price_status|string|false|none|The status of the Google Pay payment [total price](https://developers.google.com/pay/api/web/reference/request-objects#TransactionInfo).|
|»»» stored_card|object|false|none|Configuration options specific to stored card payments.|
|»»»» customer_id|string|false|none|The unique identifier for an existing [customer](https://api-reference.checkout.com/#tag/Customers). Enables the stored card payment method if the customer has one or more payment instruments stored.
This value takes precedence over `payment_method_configuration.stored_card.instrument_ids` when choosing the stored cards to present to the customer.|
|»»»» instrument_ids|[string]|false|none|The unique identifiers for card instruments. Enables stored card payment method if any exists.
The first valid payment instrument in the list is shown to the customer as the default option.
Alternatively, you can specify a default payment instrument by providing its ID in the `payment_method_configuration.stored_card.default_instrument_id` field.|
|»»»» default_instrument_id|string|false|none|The unique identifier for the payment instrument to present to the customer as the default option.|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» customer_retry|object|false|none|Configuration for asynchronous retries.|
|»» max_attempts|integer|true|none|The maximum number of authorization retry attempts, excluding the initial authorization.|
|» ip_address|[IPAddress](#schemaipaddress)|false|none|The Customers IP address. Only IPv4 and IPv6 addresses are accepted.|
#### Enumerated Values
|Property|Value|
|---|---|
|total_type|pending|
|total_type|final|
|total_price_status|estimated|
|total_price_status|final|
CreatePaymentSessionsResponse
```json
{
"id": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ",
"payment_session_token": "string",
"payment_session_secret": "pss_9823241e-2cec-4c98-b23d-7b29ow4e2e34",
"_links": {
"self": {
"href": "https://{prefix}.api.sandbox.checkout.com/payment-sessions/ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[PaymentSessionId](#schemapaymentsessionid)|true|none|The Payment Sessions unique identifier|
|payment_session_token|string|true|none|A unique token representing the payment session, which you must provide when you initialize [Flow](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/get-started-with-flow#Step_2:_Initialize_and_mount_Flow_).
Do not log or store this value.|
|payment_session_secret|[PaymentSessionSecret](#schemapaymentsessionsecret)|true|none|The secret used by Flow to authenticate payment session requests.
Do not log or store this value.|
|_links|object|true|none|The links related to the Payment Session.|
|» self|object|true|none|The URI of the Payment Session.|
|»» href|string|true|none|The link URL|
PaymentSessionsRateLimitedResponse
```json
{
"request_id": "string",
"error_type": "string",
"error_codes": [
"string"
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|request_id|string|true|none|none|
|error_type|string|true|none|none|
|error_codes|[string]|true|none|none|
PaymentSessionsValidationErrorResponse
```json
{
"request_id": "string",
"error_type": "string",
"error_codes": [
"string"
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|request_id|string|true|none|none|
|error_type|string|true|none|none|
|error_codes|[string]|true|none|none|
PaymentSessionBilling
```json
{
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
}
```
The billing details.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|address|[Address](#schemaaddress)|true|none|The billing address.|
|phone|[PaymentInterfacesPhoneNumber](#schemapaymentinterfacesphonenumber)|false|none|The phone number associated with the billing address|
PaymentSessionCaptureFlag
```json
true
```
Specifies whether to capture the payment, if applicable.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|boolean|false|none|Specifies whether to capture the payment, if applicable.|
PaymentSessionCaptureOn
```json
"2024-01-01T09:15:30Z"
```
A timestamp specifying when to capture the payment, as an ISO 8601 code. If a value is provided, `capture` is automatically set to `true`.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string(date-time)|false|none|A timestamp specifying when to capture the payment, as an ISO 8601 code. If a value is provided, `capture` is automatically set to `true`.|
PaymentSessionCurrency
```json
"USD"
```
The three-letter ISO currency code.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The three-letter ISO currency code.|
PaymentSessionCustomer
```json
{
"email": "jia.tsang@example.com",
"name": "Jia Tsang",
"id": "string",
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"tax_number": "string",
"summary": {
"registration_date": "2023-05-01",
"first_transaction_date": "2023-07-01",
"last_payment_date": "2023-08-01",
"total_order_count": 15,
"last_payment_amount": 500,
"is_premium_customer": true,
"is_returning_customer": true,
"lifetime_value": 500
}
}
```
The customer's details. Required if `source.type` is `tamara`.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|email|string(email)|false|none|The customer's email address. Required if `source.type` is `tamara`.|
|name|string|false|none|The customer's name. Required if `source.type` is `tamara`.|
|id|string|false|none|The unique identifier for an existing customer.|
|phone|[PaymentInterfacesPhoneNumber](#schemapaymentinterfacesphonenumber)|false|none|The customer's phone number. Required if `source.type` is `tamara`.|
|tax_number|string|false|none|The customer's value-added tax (VAT) registration number.|
|summary|[PaymentInterfacesCustomerSummary](#schemapaymentinterfacescustomersummary)|false|none|Summary of the customer's transaction history.
Used for risk assessment when `source.type` is `Tamara`|
PaymentSessionId
```json
"ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ"
```
The Payment Sessions unique identifier
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The Payment Sessions unique identifier|
```json
{
"coupon_code": "NY2018"
}
```
Allows you to store additional information about a transaction with custom fields and up to five user-defined fields, which can be used for reporting purposes. You can supply fields of type `string`, `number`, and `boolean` within the `metadata` object. Arrays and objects are not supported.
You can provide up to 18 metadata fields per API call, but the value of each field must not exceed 255 characters in length.
You can also reference [`metadata` properties](https://www.checkout.com/docs/business-operations/prevent-fraud/understand-fraud-detection#Metadata) in your custom rules for Fraud Detection. For example, `$coupon_code = '1234'`.
### Properties
*None*
PaymentSessionPaymentPlanRecurring
```json
{
"amount_variability": "Variable",
"days_between_payments": 28,
"total_number_of_payments": 5,
"current_payment_number": 3,
"expiry": "20251031",
"name": "Subscription 1234",
"start_date": "20260507",
"amount": 1234
}
```
The information to process a recurring payment request. To be used when the payment_type is Recurring.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|amount_variability|string|false|none|Specifies whether the amount is fixed or variable for each recurrence.|
|days_between_payments|integer|false|none|Indicates the minimum number of days between payments.|
|total_number_of_payments|integer|false|none|Indicates the agreed total number of payments.|
|current_payment_number|integer|false|none|The number of the current installment payment.|
|expiry|string|false|none|The date after which no further payments will be performed, in the format YYYYMMDD.|
|name|string|false|none|The name of the payment plan.
Required when `source.type` is `blik`. For Blik merchant-initiated requests using an external `partner_agreement_id`, this value is used as the Blik Alias Label.|
|start_date|string|false|none|The date on which the first payment will be taken, in `YYYYMMDD` format.
Required when `source.type` is `blik` and the recurring agreement is created without an initial payment (`amount` set to `0`).|
|amount|integer|false|none|The amount to charge for each payment in the plan, in the [minor currency unit](https://www.checkout.com/docs/resources/calculating-the-amount).
Required when `source.type` is `blik`, `payment_plan.amount_variability` is `Fixed`, and the recurring agreement is created without an initial payment (`amount` set to `0`).|
#### Enumerated Values
|Property|Value|
|---|---|
|amount_variability|Fixed|
|amount_variability|Variable|
PaymentSessionPaymentType
```json
"Regular"
```
Must be specified for card-not-present (CNP) payments. For example, a recurring mail order / telephone order (MOTO) payment.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|Must be specified for card-not-present (CNP) payments. For example, a recurring mail order / telephone order (MOTO) payment.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|Regular|
|*anonymous*|Recurring|
|*anonymous*|MOTO|
|*anonymous*|Installment|
|*anonymous*|Unscheduled|
PaymentSessionProcessingChannelId
```json
"string"
```
The processing channel to use for the payment.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The processing channel to use for the payment.|
PaymentSessions3DS
```json
{
"enabled": "false",
"challenge_indicator": "no_preference",
"allow_upgrade": true,
"exemption": "low_value"
}
```
### Properties
anyOf - discriminator: PaymentSessions3DSIntegrated.enabled
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSessions3DSIntegrated](#schemapaymentsessions3dsintegrated)|false|none|none|
or
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSessions3DSThirdParty](#schemapaymentsessions3dsthirdparty)|false|none|Required information to process a payment that has been 3DS authenticated using a Third Party provider|
PaymentSessions3DSAccountInfo
```json
{
"purchase_count": 10,
"account_age": "no_account",
"add_card_attempts": 10,
"shipping_address_age": "this_transaction",
"account_name_matches_shipping_name": true,
"suspicious_account_activity": true,
"transactions_today": 10,
"authentication_method": "no_authentication",
"cardholder_account_age_indicator": "no_account",
"account_change": "2019-08-24T14:15:22Z",
"account_change_indicator": "this_transaction",
"account_date": "2019-08-24T14:15:22Z",
"account_password_change": "2019-08-24T14:15:22Z",
"account_password_change_indicator": "no_change",
"transactions_per_year": 2,
"payment_account_age": "2019-08-24T14:15:22Z",
"shipping_address_usage": "2019-08-24T14:15:22Z",
"account_type": "not_applicable",
"account_id": "string"
}
```
AccountInfo
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|purchase_count|number|false|none|The number of purchases with this cardholder's account during the last six months|
|account_age|string|false|none|The length of time that the payment account was enrolled in the cardholder's account|
|add_card_attempts|number|false|none|The number of _Add Card_ attempts in the last 24 hours|
|shipping_address_age|string|false|none|Indicates when the shipping address for this transaction was first used|
|account_name_matches_shipping_name|boolean|false|none|Indicates if the cardholder name on the account is identical to the shipping name used for this transaction|
|suspicious_account_activity|boolean|false|none|Indicates whether suspicious activity on the cardholder account has been observed|
|transactions_today|number|false|none|The number of transactions (successful and abandoned) for the cardholder account across all payment accounts in the previous 24 hours|
|authentication_method|string|false|none|Information about how the cardholder was authenticated before or during the transaction|
|cardholder_account_age_indicator|string|false|none|The length of time the cardholder has held the account with the 3DS Requestor|
|account_change|string(date-time)|false|none|The UTC date and time the cardholder’s account with the 3DS Requestor was last changed, in ISO 8601 format.
Changes that affect this value include:
- updating the billing or shipping address
- adding a new payment account
- adding a new user|
|account_change_indicator|string|false|none|The amount of time since the cardholder’s account information with the 3DS Requestor was last changed.
Changes that affect this value include:
- updating the billing or shipping address
- adding a new payment account
- adding a new user|
|account_date|string(date-time)|false|none|The UTC date and time the cardholder opened the account with the 3DS Requestor, in ISO 8601 format.|
|account_password_change|string(date-time)|false|none|The UTC date and time the cardholder’s account with the 3DS Requestor was last reset or had a password change, in ISO 8601 format.|
|account_password_change_indicator|string|false|none|The amount of time since the cardholder’s account with the 3DS Requestor was last reset or had a password change.|
|transactions_per_year|integer|false|none|The number of transactions associated with the cardholder's account with the 3DS Requestor in the previous year. This value includes both successful and abandoned transactions, across all payment accounts.
Set this value to `999` if the number of transactions is `1000` or greater.|
|payment_account_age|string(date-time)|false|none|The UTC date and time the payment account was enrolled in the cardholder’s account with the 3DS Requestor, in ISO 8601 format.|
|shipping_address_usage|string(date-time)|false|none|The UTC date and time the shipping address used for the transaction was first used with the 3DS Requestor, in ISO 8601 format.|
|account_type|string|false|none|The type of account, in the case of a card product with multiple accounts.|
|account_id|string|false|none|Additional information about the account optionally provided by the 3DS Requestor|
#### Enumerated Values
|Property|Value|
|---|---|
|account_age|no_account|
|account_age|created_during_transaction|
|account_age|less_than_thirty_days|
|account_age|thirty_to_sixty_days|
|account_age|more_than_sixty_days|
|shipping_address_age|this_transaction|
|shipping_address_age|less_than_thirty_days|
|shipping_address_age|thirty_to_sixty_days|
|shipping_address_age|more_than_sixty_days|
|authentication_method|no_authentication|
|authentication_method|own_credentials|
|authentication_method|federated_id|
|authentication_method|issuer_credentials|
|authentication_method|third_party_authentication|
|authentication_method|fido|
|cardholder_account_age_indicator|no_account|
|cardholder_account_age_indicator|this_transaction|
|cardholder_account_age_indicator|less_than_thirty_days|
|cardholder_account_age_indicator|thirty_to_sixty_days|
|cardholder_account_age_indicator|more_than_sixty_days|
|account_change_indicator|this_transaction|
|account_change_indicator|less_than_thirty_days|
|account_change_indicator|thirty_to_sixty_days|
|account_change_indicator|more_than_sixty_days|
|account_password_change_indicator|no_change|
|account_password_change_indicator|this_transaction|
|account_password_change_indicator|less_than_thirty_days|
|account_password_change_indicator|thirty_to_sixty_days|
|account_password_change_indicator|more_than_sixty_days|
|account_type|not_applicable|
|account_type|credit|
|account_type|debit|
PaymentSessions3DSIntegrated
```json
{
"enabled": "false",
"challenge_indicator": "no_preference",
"allow_upgrade": true,
"exemption": "low_value"
}
```
Integrated authentication
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|enabled|string|true|none|Whether to process this payment as a 3D Secure payment. Payments where `merchant_initiated` is `true` will be processed as 3DS Requestor Initiated.|
|challenge_indicator|string|false|none|Indicates the preference for whether or not a 3DS challenge should be performed. The customer’s bank has the final say on whether or not the customer receives the challenge.|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSessions3DSIntegratedNonEnabled](#schemapaymentsessions3dsintegratednonenabled)|false|none|3DS authentication not enabled|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentSessions3DSIntegratedEnabled](#schemapaymentsessions3dsintegratedenabled)|false|none|3DS authentication enabled|
#### Enumerated Values
|Property|Value|
|---|---|
|enabled|true|
|enabled|false|
|challenge_indicator|no_preference|
|challenge_indicator|no_challenge_requested|
|challenge_indicator|challenge_requested|
|challenge_indicator|challenge_requested_mandate|
PaymentSessions3DSIntegratedEnabled
```json
{
"enabled": "true",
"challenge_indicator": "no_preference",
"attempt_n3d": true,
"exemption": "low_value",
"account_info": {
"purchase_count": 10,
"account_age": "no_account",
"add_card_attempts": 10,
"shipping_address_age": "this_transaction",
"account_name_matches_shipping_name": true,
"suspicious_account_activity": true,
"transactions_today": 10,
"authentication_method": "no_authentication",
"cardholder_account_age_indicator": "no_account",
"account_change": "2019-08-24T14:15:22Z",
"account_change_indicator": "this_transaction",
"account_date": "2019-08-24T14:15:22Z",
"account_password_change": "2019-08-24T14:15:22Z",
"account_password_change_indicator": "no_change",
"transactions_per_year": 2,
"payment_account_age": "2019-08-24T14:15:22Z",
"shipping_address_usage": "2019-08-24T14:15:22Z",
"account_type": "not_applicable",
"account_id": "string"
}
}
```
true
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|enabled|string|true|none|Whether to process this payment as a 3D Secure payment. Payments where `merchant_initiated` is `true` will be processed as 3DS Requestor Initiated.|
|challenge_indicator|string|false|none|Indicates the preference for whether or not a 3DS challenge should be performed. The customer’s bank has the final say on whether or not the customer receives the challenge.|
|attempt_n3d|boolean|false|none|Applies only when `3ds.enabled` is set to `true`. Set to `true` to attempt the payment without 3DS when the issuer, card, or network doesn’t support 3DS.|
|exemption|string|false|none|Specifies an exemption reason so that the payment is not processed using 3D Secure authentication. Learn more about exemptions in our SCA compliance guide|
|account_info|[PaymentSessions3DSAccountInfo](#schemapaymentsessions3dsaccountinfo)|false|none|Additional information about the cardholder's account|
#### Enumerated Values
|Property|Value|
|---|---|
|enabled|true|
|challenge_indicator|no_preference|
|challenge_indicator|no_challenge_requested|
|challenge_indicator|challenge_requested|
|challenge_indicator|challenge_requested_mandate|
|exemption|low_value|
|exemption|trusted_listing|
|exemption|trusted_listing_prompt|
|exemption|transaction_risk_assessment|
|exemption|data_share|
PaymentSessions3DSIntegratedNonEnabled
```json
{
"enabled": "false",
"challenge_indicator": "no_preference",
"allow_upgrade": true,
"exemption": "low_value"
}
```
false
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|enabled|string|true|none|Whether to process this payment as a 3D Secure payment. Payments where `merchant_initiated` is `true` will be processed as 3DS Requestor Initiated.|
|challenge_indicator|string|false|none|Indicates the preference for whether or not a 3DS challenge should be performed. The customer’s bank has the final say on whether or not the customer receives the challenge.|
|allow_upgrade|boolean|false|none|Indicates whether to process this payment as 3D Secure if the authorization was soft declined due to 3DS authentication required. For processing channels created before October 12, 2022, the value will default to `false`.|
|exemption|string|false|none|Specifies an exemption reason so that the payment is not processed using 3D Secure authentication. Learn more about exemptions in our SCA compliance guide|
#### Enumerated Values
|Property|Value|
|---|---|
|enabled|false|
|challenge_indicator|no_preference|
|challenge_indicator|no_challenge_requested|
|challenge_indicator|challenge_requested|
|challenge_indicator|challenge_requested_mandate|
|exemption|low_value|
|exemption|trusted_listing|
|exemption|trusted_listing_prompt|
|exemption|transaction_risk_assessment|
|exemption|3ds_outage|
|exemption|sca_delegation|
|exemption|out_of_sca_scope|
|exemption|low_risk_program|
|exemption|recurring_operation|
|exemption|data_share|
|exemption|other|
PaymentSessions3DSThirdParty
```json
{
"enabled": true,
"eci": "05",
"cryptogram": "AgAAAAAAAIR8CQrXcIhbQAAAAAA=",
"xid": "MDAwMDAwMDAwMDAwMDAwMzIyNzY=",
"version": "2.0.1",
"exemption": "low_value"
}
```
Third party authentication
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|enabled|boolean|true|none|Whether to process this payment as a 3D Secure payment|
|eci|string|true|none|The Electronic Commerce Indicator security level associated with the 3D Secure enrollment result. Required if using a third-party merchant plug-in (MPI)|
|cryptogram|string|true|none|A Base64 encoded cryptographic identifier (CAVV) used by the card schemes to validate the cardholder authentication result (3D Secure). Required if using an external MPI|
|xid|string|true|none|The 3D Secure transaction identifier. Required if using an external MPI with 3D Secure 2.X.X and a Mastercard card, or with 3D Secure 1.X.X for any supported card scheme|
|version|string|true|none|Indicates the version of 3D Secure that was used for authentication. Defaults to 1.0.0 if not provided|
|exemption|string|false|none|Specifies an exemption reason so that the payment is not processed using 3D Secure authentication. Learn more about exemptions in our SCA compliance guide|
#### Enumerated Values
|Property|Value|
|---|---|
|enabled|true|
|exemption|low_value|
|exemption|secure_corporate_payment|
|exemption|trusted_listing|
|exemption|transaction_risk_assessment|
|exemption|3ds_outage|
|exemption|sca_delegation|
|exemption|out_of_sca_scope|
|exemption|other|
|exemption|low_risk_program|
|exemption|recurring_operation|
01_PaymentSessionRequest_AccountHolderIndividual
```json
{
"type": "individual",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"account_name_inquiry": true
}
```
individual
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The account holder type.|
|first_name|string|true|none|The account holder's first name.
The combination of `first_name`, `middle_name`, and `last_name` should exceed 3 letters in length.
This must be a valid legal name. The following formats for the `first_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors):
- a single character
- all non-alphabetic characters|
|middle_name|string|false|none|The account holder's middle name.
The combination of `first_name`, `middle_name`, and `last_name` should exceed 3 letters in length.
This field is required if the `issuer_country` value returned in the [card metadata](https://api-reference.checkout.com/#operation/requestCardMetadata!c=200&path=issuer_country&t=response) response is `ZA`.|
|last_name|string|true|none|The account holder's last name.
The combination of `first_name`, `middle_name`, and `last_name` should exceed 3 letters in length.
This must be a valid legal name. The following formats for the `last_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors):
- a single character
- all non-alphabetic characters|
|account_name_inquiry|boolean|false|none|Specifies whether to perform an account name inquiry (ANI) check with the scheme.
This is only valid for Visa and Mastercard payments.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|individual|
02_PaymentSessionRequest_AccountHolderCorporate
```json
{
"type": "corporate",
"company_name": "string",
"account_name_inquiry": true
}
```
corporate
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The account holder type.|
|company_name|string|true|none|The account holder's company name.
This must be a valid legal name. The following formats for the `company_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors):
- a single character
- all non-alphabetic characters|
|account_name_inquiry|boolean|false|none|Specifies whether to perform an account name inquiry (ANI) check with the scheme.
This is only valid for Visa and Mastercard payments.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|corporate|
03_PaymentSessionRequest_AccountHolderGovernment
```json
{
"type": "government",
"company_name": "string",
"account_name_inquiry": true
}
```
government
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The account holder type.|
|company_name|string|true|none|The account holder's company name.
This must be a valid legal name. The following formats for the `company_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors):
- a single character
- all non-alphabetic characters|
|account_name_inquiry|boolean|false|none|Specifies whether to perform an account name inquiry (ANI) check with the scheme.
This is only valid for Visa and Mastercard payments.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|government|
PaymentSessionsAmount
```json
1000
```
The payment amount. Provide a value of `0` to perform a card verification.
The amount must be provided in the minor currency unit.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|integer|false|none|The payment amount. Provide a value of `0` to perform a card verification.
The amount must be provided in the minor currency unit.|
PaymentSessionsBillingDescriptor
```json
{
"name": "string",
"city": "string",
"reference": "string"
}
```
A description of the purchase, which is displayed on the customer's statement.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|true|none|A description for the payment, which will be displayed on the customer's card statement. Only applicable for card payments.|
|city|string|true|none|The city from which the payment originated. Only applicable for card payments.|
|reference|string|false|none|The reference to display on the customer's bank statement. Required for payouts to bank accounts.|
PaymentSessionSecret
```json
"pss_9823241e-2cec-4c98-b23d-7b29ow4e2e34"
```
The secret used by Flow to authenticate payment session requests.
Do not log or store this value.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The secret used by Flow to authenticate payment session requests.
Do not log or store this value.|
PaymentSessionsFailureUrl
```json
"https://example.com/payments/failure"
```
Overrides the default failure redirect URL configured on your account, for payment methods that require a redirect.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string(uri)|false|none|Overrides the default failure redirect URL configured on your account, for payment methods that require a redirect.|
PaymentSessionShipping
```json
{
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
}
```
The shipping details
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|address|[Address](#schemaaddress)|false|none|The shipping address|
|phone|[PaymentInterfacesPhoneNumber](#schemapaymentinterfacesphonenumber)|false|none|The phone number associated with the shipping address.|
PaymentSessionsItems
```json
[
{
"reference": "string",
"commodity_code": "string",
"unit_of_measure": "string",
"total_amount": 1000,
"tax_amount": 1000,
"discount_amount": 1000,
"url": "string",
"image_url": "string",
"name": "Gold Necklace",
"quantity": 1,
"unit_price": 1000
}
]
```
The line items in the order.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|false|none|The item reference or product stock keeping unit (SKU).|
|commodity_code|string|false|none|A code identifying a commodity for value-added tax (VAT) purposes.|
|unit_of_measure|string|false|none|The unit in which the item is measured, as a Unit of Measure (UoM) code.|
|total_amount|integer|false|none|The total cost of the line item, in minor currency units. The value should include any tax and discounts applied using the formula: `value = (quantity x unit_price) - discount_amount`.|
|tax_amount|integer|false|none|The total amount of sales tax or value-added tax (VAT) on the total purchase amount. Tax should be included in the total purchase amount.|
|discount_amount|integer|false|none|The discount applied to each invoice line item.|
|url|string|false|none|Link to the line item's product page.|
|image_url|string|false|none|Link to the line item's product image.|
|name|string|true|none|The descriptive name of the line item.|
|quantity|integer|true|none|The number of line items.|
|unit_price|integer|true|none|The unit price of the item, in minor currency units.|
PaymentSessionsPaymentMethodConfigurationBase
```json
{
"applepay": {
"store_payment_details": "disabled"
},
"card": {
"store_payment_details": "disabled"
},
"googlepay": {
"store_payment_details": "disabled"
}
}
```
Configurations for payment method-specific settings.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|applepay|object|false|none|Configuration options specific to Apple Pay payments.|
|» store_payment_details|[PaymentSessionsStorePaymentDetails](#schemapaymentsessionsstorepaymentdetails)|false|none|Specifies whether you intend to store the cardholder's payment details.
If you set this field to `enabled`, you must:
- have obtained consent from the cardholder to store their payment details
- provide a customer ID or email address in the request
If the request's `payment_type` is set to one of the following values, you do not need to provide this field:
- `Installment`
- `Recurring`
- `Unscheduled`|
|card|object|false|none|Configuration options specific to card payments.|
|» store_payment_details|[PaymentSessionsStorePaymentDetailsCard](#schemapaymentsessionsstorepaymentdetailscard)|false|none|Specifies whether you intend to store the cardholder's payment details.
If you set this field to `enabled` or `collect_consent`, you must:
- Have obtained consent from the cardholder to store their payment details
- Provide `customer.id` or `customer.email` in the request
You do not need to provide this field if `payment_type` is set to one of the following values:
- `Installment`
- `Recurring`
- `Unscheduled`|
|googlepay|object|false|none|Configuration options specific to Google Pay payments.|
|» store_payment_details|[PaymentSessionsStorePaymentDetails](#schemapaymentsessionsstorepaymentdetails)|false|none|Specifies whether you intend to store the cardholder's payment details.
If you set this field to `enabled`, you must:
- have obtained consent from the cardholder to store their payment details
- provide a customer ID or email address in the request
If the request's `payment_type` is set to one of the following values, you do not need to provide this field:
- `Installment`
- `Recurring`
- `Unscheduled`|
PaymentSessionsSessionData
```json
"string"
```
A unique token representing the additional customer data captured by Flow, as received from the handleSubmit callback.
Do not log or store this value.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|A unique token representing the additional customer data captured by Flow, as received from the handleSubmit callback.
Do not log or store this value.|
PaymentSessionsStorePaymentDetails
```json
"disabled"
```
Specifies whether you intend to store the cardholder's payment details.
If you set this field to `enabled`, you must:
- have obtained consent from the cardholder to store their payment details
- provide a customer ID or email address in the request
If the request's `payment_type` is set to one of the following values, you do not need to provide this field:
- `Installment`
- `Recurring`
- `Unscheduled`
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|Specifies whether you intend to store the cardholder's payment details.
If you set this field to `enabled`, you must:
- have obtained consent from the cardholder to store their payment details
- provide a customer ID or email address in the request
If the request's `payment_type` is set to one of the following values, you do not need to provide this field:
- `Installment`
- `Recurring`
- `Unscheduled`|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|disabled|
|*anonymous*|enabled|
PaymentSessionsStorePaymentDetailsCard
```json
"disabled"
```
Specifies whether you intend to store the cardholder's payment details.
If you set this field to `enabled` or `collect_consent`, you must:
- Have obtained consent from the cardholder to store their payment details
- Provide `customer.id` or `customer.email` in the request
You do not need to provide this field if `payment_type` is set to one of the following values:
- `Installment`
- `Recurring`
- `Unscheduled`
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|Specifies whether you intend to store the cardholder's payment details.
If you set this field to `enabled` or `collect_consent`, you must:
- Have obtained consent from the cardholder to store their payment details
- Provide `customer.id` or `customer.email` in the request
You do not need to provide this field if `payment_type` is set to one of the following values:
- `Installment`
- `Recurring`
- `Unscheduled`|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|disabled|
|*anonymous*|enabled|
|*anonymous*|collect_consent|
PaymentSessionsSuccessUrl
```json
"https://example.com/payments/success"
```
Overrides the default success redirect URL configured on your account, for payment methods that require a redirect.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string(uri)|false|none|Overrides the default success redirect URL configured on your account, for payment methods that require a redirect.|
SubmitPaymentSessionsActionRequiredResponse
```json
{
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"status": "Action Required",
"type": "alipay_cn",
"action": {}
}
```
Response for an action required payment session payment.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[PaymentId](#schemapaymentid)|true|none|The payment identifier.|
|status|string|true|none|The payment's status.|
|type|[PaymentInterfacesPaymentMethod](#schemapaymentinterfacespaymentmethod)|true|none|The payment method name.|
|action|object|true|none|Instruction for further payment action.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Action Required|
SubmitPaymentSessionsProcessedResponse
```json
{
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"status": "Approved",
"type": "alipay_cn"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[PaymentId](#schemapaymentid)|true|none|The payment identifier.|
|status|string|true|none|The payment's status.|
|type|[PaymentInterfacesPaymentMethod](#schemapaymentinterfacespaymentmethod)|true|none|The payment method name.|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[SubmitPaymentSessionsProcessedResponseStatusApproved](#schemasubmitpaymentsessionsprocessedresponsestatusapproved)|false|none|Response for an approved payment session payment.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[SubmitPaymentSessionsProcessedResponseStatusDeclined](#schemasubmitpaymentsessionsprocessedresponsestatusdeclined)|false|none|Response for a declined payment session payment.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Approved|
|status|Declined|
SubmitPaymentSessionsProcessedResponseStatusApproved
```json
{
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"status": "Approved",
"type": "alipay_cn"
}
```
Approved
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[PaymentId](#schemapaymentid)|true|none|The payment identifier.|
|status|string|true|none|The payment was approved.|
|type|[PaymentInterfacesPaymentMethod](#schemapaymentinterfacespaymentmethod)|true|none|The payment method name.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Approved|
SubmitPaymentSessionsProcessedResponseStatusDeclined
```json
{
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"status": "Declined",
"type": "alipay_cn",
"decline_reason": "string"
}
```
Declined
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[PaymentId](#schemapaymentid)|true|none|The payment identifier.|
|status|string|true|none|The payment was declined.|
|type|[PaymentInterfacesPaymentMethod](#schemapaymentinterfacespaymentmethod)|true|none|The payment method name.|
|decline_reason|string|true|none|The reason for the payment decline.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Declined|
SubmitPaymentSessionsRequest
```json
{
"session_data": "string",
"amount": 1000,
"currency": "USD",
"billing": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"success_url": "https://example.com/payments/success",
"failure_url": "https://example.com/payments/failure",
"payment_type": "Regular",
"billing_descriptor": {
"name": "string",
"city": "string",
"reference": "string"
},
"reference": "ORD-123A",
"customer": {
"email": "jia.tsang@example.com",
"name": "Jia Tsang",
"id": "string",
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"tax_number": "string",
"summary": {
"registration_date": "2023-05-01",
"first_transaction_date": "2023-07-01",
"last_payment_date": "2023-08-01",
"total_order_count": 15,
"last_payment_amount": 500,
"is_premium_customer": true,
"is_returning_customer": true,
"lifetime_value": 500
}
},
"shipping": {
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"items": [
{
"reference": "string",
"commodity_code": "string",
"unit_of_measure": "string",
"total_amount": 1000,
"tax_amount": 1000,
"discount_amount": 1000,
"url": "string",
"image_url": "string",
"name": "Gold Necklace",
"quantity": 1,
"unit_price": 1000
}
],
"amount_allocations": [
{
"id": "string",
"amount": 1,
"reference": "ORD-123A",
"commission": {
"amount": 10,
"percentage": 12.5
}
}
],
"3ds": {
"enabled": "false",
"challenge_indicator": "no_preference",
"allow_upgrade": true,
"exemption": "low_value"
},
"ip_address": "90.197.169.245",
"payment_method_configuration": {
"applepay": {
"store_payment_details": "disabled"
},
"card": {
"store_payment_details": "disabled"
},
"googlepay": {
"store_payment_details": "disabled"
}
},
"recipient": {
"dob": "1985-05-15",
"account_number": "5555554444",
"address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"first_name": "Jia",
"last_name": "Tsang"
},
"instruction": {
"purpose": "donations"
},
"processing_channel_id": "string",
"metadata": {
"coupon_code": "NY2018"
},
"sender": {},
"capture": true,
"capture_on": "2024-01-01T09:15:30Z",
"processing": {
"pan_preference": "fpan",
"provision_network_token": true
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|session_data|[PaymentSessionsSessionData](#schemapaymentsessionssessiondata)|true|none|A unique token representing the additional customer data captured by Flow, as received from the handleSubmit callback.
Do not log or store this value.|
|amount|[PaymentSessionsAmount](#schemapaymentsessionsamount)|false|none|The payment amount. Provide a value of `0` to perform a card verification.
The amount must be provided in the minor currency unit.|
|currency|[PaymentSessionCurrency](#schemapaymentsessioncurrency)|false|none|The three-letter ISO currency code.|
|billing|[PaymentSessionBilling](#schemapaymentsessionbilling)|false|none|The billing details.|
|success_url|[PaymentSessionsSuccessUrl](#schemapaymentsessionssuccessurl)|false|none|Overrides the default success redirect URL configured on your account, for payment methods that require a redirect.|
|failure_url|[PaymentSessionsFailureUrl](#schemapaymentsessionsfailureurl)|false|none|Overrides the default failure redirect URL configured on your account, for payment methods that require a redirect.|
|payment_type|[PaymentSessionPaymentType](#schemapaymentsessionpaymenttype)|false|none|Must be specified for card-not-present (CNP) payments. For example, a recurring mail order / telephone order (MOTO) payment.|
|billing_descriptor|[PaymentSessionsBillingDescriptor](#schemapaymentsessionsbillingdescriptor)|false|none|A description of the purchase, which is displayed on the customer's statement.|
|reference|[PaymentInterfacesReference](#schemapaymentinterfacesreference)|false|none|A reference you can use to identify the payment. For example, an order number.
- For Amex payments, this must be at most 30 characters.
- For Benefit payments, the reference must be a unique alphanumeric value.
- For iDEAL payments, the reference is required and must be an alphanumeric value with a 35-character limit.|
|customer|[PaymentSessionCustomer](#schemapaymentsessioncustomer)|false|none|The customer's details.|
|shipping|[PaymentSessionShipping](#schemapaymentsessionshipping)|false|none|The shipping details|
|items|[PaymentSessionsItems](#schemapaymentsessionsitems)|false|none|The line items in the order.|
|amount_allocations|[object]|false|none|The sub-entities that the payment is being processed on behalf of.|
|» id|string|true|none|The sub-entity's ID.|
|» amount|integer|true|none|The split amount, in minor currency units. The sum of all split amounts must be equal to the payment amount. The split amount will be credited to your sub-entity's currency account.|
|» reference|string|false|none|A reference you can use to identify the split. For example, an order number.|
|» commission|object|false|none|The commission you'd like to collect from the split, calculated using the formula: `commission = (amount * commission.percentage) + commission.amount`. The commission cannot exceed the split amount. Commission will be credited to your currency account.|
|»» amount|integer|false|none|An optional commission to collect, as a fixed amount in minor currency units.|
|»» percentage|number|false|none|An optional commission to collect, as a percentage value with up to eight decimal places.|
|3ds|[PaymentSessions3DS](#schemapaymentsessions3ds)|false|none|none|
|ip_address|[IPAddress](#schemaipaddress)|false|none|The Customer's IP address. Only IPv4 and IPv6 addresses are accepted.|
|payment_method_configuration|[PaymentSessionsPaymentMethodConfigurationBase](#schemapaymentsessionspaymentmethodconfigurationbase)|false|none|Configurations for payment method-specific settings.|
|recipient|[PaymentInterfacesRecipient](#schemapaymentinterfacesrecipient)|false|none|Information about the recipient of the payment's funds. Applies to Account Funding Transactions, and VISA or Mastercard domestic UK transactions processed by financial institutions.|
|instruction|object|false|none|Details about the payment instruction.|
|» purpose|[Purpose](#schemapurpose)|false|none|The purpose of the payment.
This field might be required for AFT transactions depending on the card's `issuer_country`. To view a card's `issuer_country`, [retrieve the card's metadata](https://api-reference.checkout.com/#operation/requestCardMetadata!c=200&path=issuer_country&t=response).
See the [AFT documentation page](https://www.checkout.com/docs/payments/manage-payments/perform-an-account-funding-transaction) for more details.|
|processing_channel_id|[PaymentSessionProcessingChannelId](#schemapaymentsessionprocessingchannelid)|false|none|The processing channel to use for the payment.|
|metadata|[PaymentSessionMetadata](#schemapaymentsessionmetadata)|false|none|Allows you to store additional information about a transaction with custom fields and up to five user-defined fields, which can be used for reporting purposes. You can supply fields of type `string`, `number`, and `boolean` within the `metadata` object. Arrays and objects are not supported.
You can provide up to 18 metadata fields per API call, but the value of each field must not exceed 255 characters in length.
You can also reference [`metadata` properties](https://www.checkout.com/docs/business-operations/prevent-fraud/understand-fraud-detection#Metadata) in your custom rules for Fraud Detection. For example, `$coupon_code = '1234'`.|
|sender|[PaymentInterfacesSender](#schemapaymentinterfacessender)|false|none|The sender of the payment.|
|capture|[PaymentSessionCaptureFlag](#schemapaymentsessioncaptureflag)|false|none|Specifies whether to capture the payment, if applicable.|
|capture_on|[PaymentSessionCaptureOn](#schemapaymentsessioncaptureon)|false|none|A timestamp specifying when to capture the payment, as an ISO 8601 code. If a value is provided, `capture` is automatically set to `true`.|
|processing|[PaymentInterfacesProcessingBase](#schemapaymentinterfacesprocessingbase)|false|none|Use the processing object to influence or override the data sent during card processing|
PhoneNumber
```json
{
"country_code": "+1",
"number": "415 555 2671"
}
```
A phone number
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|country_code|string|false|none|The international country calling code. Required if `source.type` is `tamara`.|
|number|string|false|none|The phone number. Required if `source.type` is `tamara`.|
BusinessDetailsCompany
```json
{
"legal_name": "The Online Retailer",
"trading_name": "Online Retail Co",
"registered_address": {
"address_line1": "444 Test Avenue",
"city": "Anytown",
"zip": "67890-1234",
"country": "US",
"state": "FL"
},
"principal_address": {
"address_line1": "123 Anywhere St.",
"city": "Anytown",
"zip": "12345-6789",
"country": "US",
"address_line2": "Apt. 456",
"state": "AL"
},
"status": "active",
"additional_trading_names": [
"Online Retail"
]
}
```
Company
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|status|string|false|read-only|The status of the business details. This describes the data in this response, not the sub-entity's own status. A suspended sub-entity can still have `active` business details.
`active` means the values are live. `pending` means a change has been submitted and is still under review, so the values shown are the ones you submitted, not the ones currently in effect.
Read-only on input. You can send a response body back unchanged in a `PUT` request, and this field is ignored.|
|legal_name|string|true|none|The legal name of the sub-entity.|
|trading_name|string|true|none|The trading name of the sub-entity, also known as the 'Doing Business As' name.|
|additional_trading_names|[string]|false|none|The collection of additional trading names for the sub-entity.|
|» Trading name|string|false|none|An additional trading name of the sub-entity.|
|registered_address|object|true|none|The registered address of the company.|
|» address_line1|string|true|none|The first line of the address.|
|» address_line2|string¦null|false|none|The second line of the address.|
|» city|string|true|none|The address city.|
|» state|string|false|none|The address state. Required for addresses in the US and France, and optional elsewhere. For US addresses, provide the two-letter ISO 3166-2 code. For French addresses, provide the department the address is in.|
|» zip|string¦null|true|none|The address ZIP code or postal code. Required, but can be `null` for countries that do not use postal codes.|
|» country|string(iso-3166-1-alpha-2)|true|none|The two-letter ISO 3166-1 alpha-2 country code. Returned by the `GET` request, and required when you submit an address, but you cannot change the sub-entity's country.
For more information, see Country codes.|
|principal_address|object|true|none|The primary location of the company where business is performed.|
|» address_line1|string|true|none|The first line of the address.|
|» address_line2|string¦null|false|none|The second line of the address.|
|» city|string|true|none|The address city.|
|» state|string|false|none|The address state. Required for addresses in the US and France, and optional elsewhere. For US addresses, provide the two-letter ISO 3166-2 code. For French addresses, provide the department the address is in.|
|» zip|string¦null|true|none|The address ZIP code or postal code. Required, but can be `null` for countries that do not use postal codes.|
|» country|string(iso-3166-1-alpha-2)|true|none|The two-letter ISO 3166-1 alpha-2 country code. Returned by the `GET` request, and required when you submit an address, but you cannot change the sub-entity's country.
For more information, see Country codes.|
|documents|object|false|none|Supporting documents for the change you submit. Each document is required only when you change the fields it supports, and is not requested otherwise. A document already on file satisfies the requirement, so you do not need to upload a new one.
Documents are not returned for `active` business details. For `pending` business details, the documents submitted with the change are returned.|
|» company_verification|object|false|none|A document certified by a power of attorney within the last three months.
Required when you change `legal_name`, `trading_name`, or `additional_trading_names`. If you change any of those fields without providing this document, the request fails with a `422` error that names the missing document.|
|»» type|string|true|none|The type of document used for company verification.|
|»» front|string|true|none|The ID of the front side of the document.|
|» proof_of_principal_address|object|false|none|Proof of the principal place of business.
Required when you change `principal_address`. The registered office and the principal place of business are different, so this document does not cover a change to `registered_address`.|
|»» type|string|true|none|The type of document used for principal address verification.|
|»» front|string|true|none|The ID of the front side of the document.|
|» proof_of_registered_address|object|false|none|Proof of the registered address of the company.
Required when you change `registered_address`. If you change both addresses, provide this document and `proof_of_principal_address`.|
|»» type|string|true|none|The type of document used for registered address verification.|
|»» front|string|true|none|The ID of the front side of the document.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|active|
|status|pending|
|type|incorporation_document|
|type|proof_of_address|
|type|proof_of_address|
BusinessDetailsSoleTrader
```json
{
"trading_name": "The Online Retailer",
"principal_address": {
"address_line1": "123 Anywhere St.",
"city": "Anytown",
"zip": "12345-6789",
"country": "US",
"address_line2": "Apt. 456",
"state": "AL"
},
"status": "active",
"additional_trading_names": [
"Online Retailer Co"
]
}
```
Sole trader
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|status|string|false|read-only|The status of the business details. This describes the data in this response, not the sub-entity's own status. A suspended sub-entity can still have `active` business details.
`active` means the values are live. `pending` means a change has been submitted and is still under review, so the values shown are the ones you submitted, not the ones currently in effect.
Read-only on input. You can send a response body back unchanged in a `PUT` request, and this field is ignored.|
|trading_name|string|true|none|The trading name of the sub-entity, also known as the 'Doing Business As' name.|
|additional_trading_names|[string]|false|none|The collection of additional trading names for the sub-entity.|
|» Trading name|string|false|none|An additional trading name of the sub-entity.|
|principal_address|object|true|none|The primary location where the sole trader performs business.|
|» address_line1|string|true|none|The first line of the address.|
|» address_line2|string¦null|false|none|The second line of the address.|
|» city|string|true|none|The address city.|
|» state|string|false|none|The address state. Required for addresses in the US and France, and optional elsewhere. For US addresses, provide the two-letter ISO 3166-2 code. For French addresses, provide the department the address is in.|
|» zip|string¦null|true|none|The address ZIP code or postal code. Required, but can be `null` for countries that do not use postal codes.|
|» country|string(iso-3166-1-alpha-2)|true|none|The two-letter ISO 3166-1 alpha-2 country code. Returned by the `GET` request, and required when you submit an address, but you cannot change the sub-entity's country.
For more information, see Country codes.|
|documents|object|false|none|Supporting documents for the change you submit. Each document is required only when you change the fields it supports, and is not requested otherwise. A document already on file satisfies the requirement, so you do not need to upload a new one.
Documents are not returned for `active` business details. For `pending` business details, the documents submitted with the change are returned.|
|» company_verification|object|false|none|A document certified by a power of attorney within the last three months.
Required when you change `trading_name` or `additional_trading_names`. If you change either of those fields without providing this document, the request fails with a `422` error that names the missing document.|
|»» type|string|true|none|The type of document used for company verification.|
|»» front|string|true|none|The ID of the front side of the document.|
|» proof_of_principal_address|object|false|none|Proof of the principal place of business.
Required when you change `principal_address`. If you change this field without providing this document, the request fails with a `422` error that names the missing document.|
|»» type|string|true|none|The type of document used for principal address verification.|
|»» front|string|true|none|The ID of the front side of the document.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|active|
|status|pending|
|type|incorporation_document|
|type|proof_of_address|
EEACompanyFull2-0
```json
{
"reference": "string",
"status": "string",
"is_draft": true,
"profile": {
"urls": [
"http://example.com"
],
"mccs": [
"string"
],
"default_holding_currency": null,
"holding_currencies": [
"EUR"
]
},
"contact_details": {
"phone": {
"number": 10000000
},
"email_addresses": {
"primary": null
},
"invitee": {
"email": null
}
},
"capabilities": {},
"requirements_due": [
{
"field": "string",
"reason": "string"
}
],
"instruments": [
{}
],
"company": {
"legal_name": "string",
"trading_name": "string",
"business_registration_number": "string",
"principal_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
},
"registered_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
},
"representatives": [
{
"id": "stringstringstringstringstring",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"date_of_birth": {
"day": 1,
"month": 1,
"year": 1900
},
"phone": {
"number": 10000000
},
"address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
},
"place_of_birth": {
"country": "st"
},
"roles": [
"ubo"
],
"documents": {
"identity_verification": {
"type": "passport",
"front": "stringstringstringstringstrings",
"back": "stringstringstringstringstrings"
}
}
}
],
"financial_details": {
"annual_processing_volume": 0,
"average_transaction_value": 0,
"highest_transaction_value": 0,
"currency": "EUR"
},
"business_type": "general_partnership",
"date_of_incorporation": {
"day": 1,
"month": 1,
"year": 1500
}
},
"documents": {
"company_verification": {
"type": "incorporation_document",
"front": "stringstringstringstringstrings"
},
"bank_verification": {
"type": "bank_statement",
"front": "stringstringstringstringstrings"
},
"financial_verification": {
"type": "financial_statement",
"front": "stringstringstringstringstrings"
}
}
}
```
EEA Company - Full (2.0)
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|true|none|A unique reference you can later use to identify the sub-entity.|
|status|string|false|read-only|none|
|is_draft|boolean|false|write-only|Specifies whether the sub-entity details are in draft.
Marking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.|
|profile|object|true|none|Information about the profile of the sub-entity, primarily regarding the products/services offered.|
|» urls|[string]|true|none|A collection of website URLs the sub-entity accepts payments on.|
|»» Company website URL|string(uri)|false|none|The URL of the company's website.|
|» mccs|[any]|true|none|Select the categories that most closely describe the business|
|»» Merchant category code|number|false|none|The merchant category code (4-digit ISO 18245).|
|» default_holding_currency|any|false|none|The default holding currency code (iso-4217)|
|» holding_currencies|[string]|false|none|Incoming funds are held in your selected currencies|
|»» Currency|string|false|none|The currency code (iso-4217)|
|contact_details|object|true|none|Contact details of this sub-entity.|
|» phone|object|true|none|The phone number of the sub-entity.|
|»» number|any|true|none|The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)|
|» email_addresses|object|true|none|Email addresses for this sub-entity.|
|»» primary|any|true|none|The main email address for this sub-entity.|
|» invitee|object|false|none|The details of the user responsible for onboarding the sub-entity.|
|»» email|any|false|none|The main email address for this sub-entity.|
|capabilities|object|false|read-only|The capabilities of the entity.|
|requirements_due|[object]|false|read-only|List of requirements due in order to be onboarded.|
|» Requirements due entry|object|false|read-only|A list of fields which require attention|
|»» field|string|false|none|The field that is needs to be addressed.|
|»» reason|string|false|none|The reason behind the field needing attention.|
|instruments|[object]|false|read-only|none|
|company|object|true|none|Information about the company represented by the sub-entity.|
|» legal_name|string|true|none|The legal name of the sub-entity.|
|» trading_name|string|true|none|The trading name of the sub-entity, also referred to as 'doing business as'.|
|» business_registration_number|number|true|none|The sub-entity's Business Registration Number. This can be a Commercial Registration or Ministry of Commerce certificate number, or any other equivalent registration number. For sub-entities based in France, this must be a SIRET number.|
|» principal_address|object|true|none|The primary location of the company where business is performed.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» registered_address|object|true|none|The registered address of the company.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» representatives|[object]|true|none|Information about representatives of this company.|
|»» Representative|object|false|none|Information about representatives of this company.|
|»»» id|number|false|none|The representative's id.|
|»»» first_name|string|true|none|The representative's first name.|
|»»» middle_name|string|false|none|The representative's middle name. Required if appears in official docs|
|»»» last_name|string|true|none|The representative's last name.|
|»»» date_of_birth|object|true|none|The date of birth of the person according to the Gregorian calendar.|
|»»»» day|integer|true|none|The calendar day of the month they were born.|
|»»»» month|integer|true|none|The month of the year they were born.|
|»»»» year|integer|true|none|The year they were born.|
|»»» phone|object|false|none|The phone number of the sub-entity.|
|»»»» number|any|true|none|The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)|
|»»» address|object|true|none|The representative's address.|
|»»»» address_line1|string|true|none|The first line of the address.|
|»»»» address_line2|number|false|none|The second line of the address.|
|»»»» city|string|true|none|The address city.|
|»»»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»»»» zip|string|true|none|The address zip/postal code.|
|»»»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|»»» place_of_birth|object|true|none|The place of birth of the person.|
|»»»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|»»» roles|[string]|true|none|The individual's roles within the company|
|»»»» Representative Role|string|false|none|The representative's roles within the company|
|»»» documents|object|true|none|A legal document used to verify identity|
|»»»» identity_verification|object|true|none|The document to use to confirm the individual's identity.|
|»»»»» type|string|true|none|The type of document used for identity verification|
|»»»»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|»»»»» back|string|false|none|The ID of the back side of the document as represented within Checkout.com systems.|
|» financial_details|object|true|none|Seller financial questions and supporting documents.|
|»» annual_processing_volume|integer|true|none|The estimated annual processing volume. In minor units without decimals.|
|»» average_transaction_value|integer|true|none|The expected average transaction value. In minor units without decimals.|
|»» highest_transaction_value|integer|true|none|The expected highest transaction value. In minor units without decimals.|
|»» currency|string|false|none|The currency used for the processing details provided.|
|» business_type|string|true|none|The legal type of the company|
|» date_of_incorporation|object|false|none|The date the company was incorporated.|
|»» day|integer|false|none|The day of the month the company was incorporated.|
|»» month|integer|true|none|The month the company was incorporated.|
|»» year|integer|true|none|The year the company was incorporated.|
|documents|object|true|none|The documents used to support the identity of a company.|
|» company_verification|object|true|none|Certified by a power of attorney within the last 3 months|
|»» type|string|true|none|The type of document used for company verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» bank_verification|object|false|none|A document showing transactions from last 3 months|
|»» type|string|true|none|The type of document being used as bank verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» financial_verification|object|false|none|Financial statement document becomes mandatory depending on the answer provided for annual_processing_volume. The status of your sub-entity will change to requirements_due stating when this is necessary.|
|»» type|string|true|none|The type of the file.|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
#### Enumerated Values
|Property|Value|
|---|---|
|Currency|AED|
|Currency|AUD|
|Currency|CAD|
|Currency|CHF|
|Currency|CZK|
|Currency|DKK|
|Currency|EUR|
|Currency|GBP|
|Currency|HKD|
|Currency|JPY|
|Currency|NOK|
|Currency|NZD|
|Currency|PLN|
|Currency|RON|
|Currency|SEK|
|Currency|SGD|
|Currency|USD|
|Currency|ZAR|
|Representative Role|ubo|
|Representative Role|legal_representative|
|type|passport|
|type|national_identity_card|
|type|driving_license|
|type|citizen_card|
|type|residence_permit|
|type|electoral_id|
|currency|EUR|
|business_type|general_partnership|
|business_type|limited_partnership|
|business_type|public_limited_company|
|business_type|limited_company|
|business_type|professional_association|
|business_type|unincorporated_association|
|business_type|auto_entrepreneur|
|type|incorporation_document|
|type|bank_statement|
|type|financial_statement|
EEACompanyFull3-0
```json
{
"reference": "string",
"status": "string",
"is_draft": true,
"profile": {
"urls": [
"http://example.com"
],
"mccs": [
"string"
],
"default_holding_currency": null,
"holding_currencies": [
"EUR"
]
},
"contact_details": {
"phone": {
"country_code": "GR",
"number": "string"
},
"email_addresses": {
"primary": null
},
"invitee": {
"email": null
}
},
"capabilities": {},
"requirements_due": [
{
"field": "string",
"reason": "string",
"message": "string"
}
],
"company": {
"legal_name": "string",
"trading_name": "string",
"business_registration_number": "string",
"date_of_incorporation": {
"day": 1,
"month": 1,
"year": 1500
},
"regulatory_licence_number": "string",
"principal_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
},
"registered_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
},
"representatives": [
{
"id": "stringstringstringstringstring",
"individual": {
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"date_of_birth": {
"day": 1,
"month": 1,
"year": 1900
},
"place_of_birth": {
"country": "st"
},
"national_id_number": "stringstr",
"email_address": null,
"phone": {
"country_code": "AF",
"number": "string"
},
"address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
}
},
"company_position": "ceo",
"roles": [
"ubo"
],
"ownership_percentage": 25,
"documents": {
"identity_verification": {
"type": "passport",
"front": "stringstringstringstringstrings",
"back": "stringstringstringstringstrings"
},
"certified_authorised_signatory": {
"type": "power_of_attorney",
"front": "stringstringstringstringstrings"
}
}
}
],
"business_type": "individual_or_sole_proprietorship"
},
"processing_details": {
"settlement_country": "st",
"target_countries": [
"st"
],
"annual_processing_volume": 0,
"average_transaction_value": 0,
"highest_transaction_value": 0,
"currency": "EUR"
},
"documents": {
"company_verification": {
"type": "incorporation_document",
"front": "stringstringstringstringstrings"
},
"articles_of_association": {
"type": "memorandum_of_association",
"front": "stringstringstringstringstrings"
},
"bank_verification": {
"type": "bank_statement",
"front": "stringstringstringstringstrings"
},
"shareholder_structure": {
"type": "certified_shareholder_structure",
"front": "stringstringstringstringstrings"
},
"proof_of_legality": {
"type": "proof_of_legality",
"front": "stringstringstringstringstrings"
},
"proof_of_principal_address": {
"type": "proof_of_address",
"front": "stringstringstringstringstrings"
},
"additional_document1": {
"front": "stringstringstringstringstrings"
},
"additional_document2": {
"front": "stringstringstringstringstrings"
},
"additional_document3": {
"front": "stringstringstringstringstrings"
}
}
}
```
EEA Company - Full (3.0)
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|true|none|A unique reference you can later use to identify the sub-entity.|
|status|string|false|read-only|none|
|is_draft|boolean|false|write-only|Specifies whether the sub-entity details are in draft.
Marking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.|
|profile|object|true|none|Information about the profile of the sub-entity, primarily regarding the products/services offered.|
|» urls|[string]|true|none|A collection of website URLs the sub-entity accepts payments on.|
|»» Company website URL|string(uri)|false|none|The URL of the company's website.|
|» mccs|[any]|true|none|Select the categories that most closely describe the business|
|»» Merchant category code|number|false|none|The merchant category code (4-digit ISO 18245).|
|» default_holding_currency|any|true|none|The default holding currency code (iso-4217)|
|» holding_currencies|[string]|true|none|Incoming funds are held in your selected currencies|
|»» Currency|string|false|none|The currency code (iso-4217)|
|contact_details|object|false|none|Contact details of this sub-entity.|
|» phone|object|false|none|Phone number|
|»» country_code|string|true|none|The country code (iso-3166-1 alpha-2) where the phone number is registered|
|»» number|string|true|none|The phone number without the country calling code|
|» email_addresses|object|false|none|Email addresses for this sub-entity.|
|»» primary|any|true|none|The main email address for this sub-entity.|
|» invitee|object|false|none|The details of the user responsible for onboarding the sub-entity.|
|»» email|any|false|none|The main email address for this sub-entity.|
|capabilities|object|false|read-only|The capabilities of the entity.|
|requirements_due|[object]|false|read-only|List of requirements due in order to be onboarded.|
|» Requirements due entry|object|false|read-only|A list of fields which require attention|
|»» field|string|false|none|The field that is needs to be addressed.|
|»» reason|string|false|none|The reason behind the field needing attention.|
|»» message|string|false|none|A more descriptive message.|
|company|object|true|none|Information about the company represented by the sub-entity.|
|» legal_name|string|true|none|The legal name of the sub-entity.|
|» trading_name|string|true|none|The trading name of the sub-entity, also referred to as 'doing business as'.|
|» business_registration_number|number|true|none|The sub-entity's Business Registration Number. This can be a Commercial Registration or Ministry of Commerce certificate number, or any other equivalent registration number. For sub-entities based in France, this must be a SIRET number.|
|» date_of_incorporation|object|true|none|The date the company was incorporated.|
|»» day|integer|false|none|The day of the month the company was incorporated.|
|»» month|integer|true|none|The month the company was incorporated.|
|»» year|integer|true|none|The year the company was incorporated.|
|» regulatory_licence_number|number|false|none|The regulatory licence number of the company.|
|» principal_address|object|true|none|The primary location of the company where business is performed.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» registered_address|object|true|none|The registered address of the company.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» representatives|[oneOf]|true|none|Information about representatives of this company.|
|»» Representative|object|false|none|none|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»»» *anonymous*|object|false|none|Personal information about the individual representing the sub-entity.|
|»»»» id|number|false|none|The representative's id.|
|»»»» individual|object|true|none|Information about the individual representing the sub-entity.|
|»»»»» first_name|string|true|none|The representative's first name.|
|»»»»» middle_name|string|false|none|The representative's middle name. Required if appears in official docs|
|»»»»» last_name|string|true|none|The representative's last name.|
|»»»»» date_of_birth|object|true|none|The date of birth of the person according to the Gregorian calendar.|
|»»»»»» day|integer|true|none|The calendar day of the month they were born.|
|»»»»»» month|integer|true|none|The month of the year they were born.|
|»»»»»» year|integer|true|none|The year they were born.|
|»»»»» place_of_birth|object|true|none|The place of birth of the person.|
|»»»»»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|»»»»» national_id_number|number|false|none|Social security number (SSN) or Individual Taxpayer Identification Number (ITIN) for non-US citizens|
|»»»»» email_address|any|false|none|The main email address for this sub-entity.|
|»»»»» phone|object|false|none|Phone number|
|»»»»»» country_code|string|true|none|The country code (iso-3166-1 alpha-2) where the phone number is registered|
|»»»»»» number|string|true|none|The phone number without the country calling code|
|»»»»» address|object|true|none|The representative's address.|
|»»»»»» address_line1|string|true|none|The first line of the address.|
|»»»»»» address_line2|number|false|none|The second line of the address.|
|»»»»»» city|string|true|none|The address city.|
|»»»»»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»»»»»» zip|string|true|none|The address zip/postal code.|
|»»»»»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|»»»» company_position|string|false|none|The position of the representative within the company.|
|»»»» roles|[string]|true|none|The individual's roles within the company|
|»»»»» Representative Role|string|false|none|The representative's role|
|»»»» ownership_percentage|integer|false|none|The percentage ownership of the UBO or controlling company (required when over 25%)|
|»»»» documents|object|false|none|Verification documents for the individual representative|
|»»»»» identity_verification|object|false|none|The document to use to confirm the individual's identity.|
|»»»»»» type|string|true|none|The type of document used for identity verification|
|»»»»»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|»»»»»» back|string|false|none|The ID of the back side of the document as represented within Checkout.com systems.|
|»»»»» certified_authorised_signatory|object|false|none|Required when the legal representative or other role owner is not registered on certificate of incorporation|
|»»»»»» type|string|true|none|The type of document.|
|»»»»»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»»» *anonymous*|object|false|none|Information about the controlling company|
|»»»» id|number|false|none|The representative's id.|
|»»»» company|object|true|none|none|
|»»»»» legal_name|string|true|none|The legal name of the sub-entity.|
|»»»»» trading_name|string|true|none|The trading name of the sub-entity, also referred to as 'doing business as'.|
|»»»»» registered_address|object|true|none|The representative's address.|
|»»»»»» address_line1|string|false|none|The first line of the address.|
|»»»»»» address_line2|number|false|none|The second line of the address.|
|»»»»»» city|string|false|none|The address city.|
|»»»»»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»»»»»» zip|string|false|none|The address zip/postal code.|
|»»»»»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|»»»» ownership_percentage|integer|false|none|The percentage ownership of the UBO or controlling company (required when over 25%)|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» business_type|string|true|none|The legal type of the company|
|processing_details|object|true|none|none|
|» settlement_country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2) where the settlement bank account is located|
|» target_countries|[string]|true|none|Target country codes (iso-3166-1 alpha-2) with more than 10% expected volume processing with Checkout|
|»» Country|string(iso-3166-1-alpha-2)|false|none|The country code (iso-3166-1 alpha-2)|
|» annual_processing_volume|integer|true|none|The estimated annual processing volume. In minor units without decimals.|
|» average_transaction_value|integer|true|none|The expected average transaction value. In minor units without decimals.|
|» highest_transaction_value|integer|true|none|The expected highest transaction value. In minor units without decimals.|
|» currency|string|true|none|The currency used for the processing details provided.|
|documents|object|true|none|The documents used to support the verification of company details.|
|» company_verification|object|true|none|Certified by a power of attorney within the last 3 months|
|»» type|string|true|none|The type of document used for company verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» articles_of_association|object|true|none|Memorandum or Articles of Association document|
|»» type|string|true|none|The type of document used for company verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» bank_verification|object|true|none|A document showing transactions from last 3 months|
|»» type|string|true|none|The type of document being used as bank verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» shareholder_structure|object|true|none|Shareholder structure chart (including % of shares) certified by a competent authority individual and dated within last 3 months|
|»» type|string|true|none|The type of document.|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» proof_of_legality|object|false|none|A regulatory licence document required for the company to operate (when applicable)|
|»» type|string|true|none|The type of document used for proof of legality|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» proof_of_principal_address|object|false|none|Proof of principal place of business|
|»» type|string|true|none|The type of document being used as address verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» additional_document1|object|false|none|Additional space for documents to be provided when requested|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» additional_document2|object|false|none|Additional space for documents to be provided when requested|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» additional_document3|object|false|none|Additional space for documents to be provided when requested|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
#### Enumerated Values
|Property|Value|
|---|---|
|Currency|AED|
|Currency|AUD|
|Currency|CAD|
|Currency|CHF|
|Currency|CZK|
|Currency|DKK|
|Currency|EUR|
|Currency|GBP|
|Currency|HKD|
|Currency|JPY|
|Currency|NOK|
|Currency|NZD|
|Currency|PLN|
|Currency|RON|
|Currency|SEK|
|Currency|SGD|
|Currency|USD|
|Currency|ZAR|
|country_code|GR|
|country_code|NL|
|country_code|BE|
|country_code|FR|
|country_code|ES|
|country_code|PT|
|country_code|LU|
|country_code|IE|
|country_code|IS|
|country_code|MT|
|country_code|CY|
|country_code|FI|
|country_code|BG|
|country_code|HU|
|country_code|LT|
|country_code|LV|
|country_code|EE|
|country_code|AD|
|country_code|HR|
|country_code|SI|
|country_code|IT|
|country_code|RO|
|country_code|CZ|
|country_code|SK|
|country_code|LI|
|country_code|AT|
|country_code|DK|
|country_code|SE|
|country_code|NO|
|country_code|PL|
|country_code|DE|
|country_code|AF|
|country_code|AL|
|country_code|DZ|
|country_code|AS|
|country_code|AD|
|country_code|AO|
|country_code|AI|
|country_code|AG|
|country_code|AR|
|country_code|AM|
|country_code|AW|
|country_code|AU|
|country_code|AT|
|country_code|AZ|
|country_code|BS|
|country_code|BH|
|country_code|BD|
|country_code|BB|
|country_code|BY|
|country_code|BE|
|country_code|BZ|
|country_code|BJ|
|country_code|BM|
|country_code|BT|
|country_code|BO|
|country_code|BA|
|country_code|BW|
|country_code|BR|
|country_code|BN|
|country_code|BG|
|country_code|BF|
|country_code|BI|
|country_code|CV|
|country_code|KH|
|country_code|CM|
|country_code|CA|
|country_code|KY|
|country_code|CF|
|country_code|TD|
|country_code|CL|
|country_code|CN|
|country_code|CO|
|country_code|KM|
|country_code|CD|
|country_code|CG|
|country_code|CK|
|country_code|CR|
|country_code|HR|
|country_code|CU|
|country_code|CW|
|country_code|CY|
|country_code|CZ|
|country_code|DK|
|country_code|DJ|
|country_code|DM|
|country_code|DO|
|country_code|EC|
|country_code|EG|
|country_code|SV|
|country_code|GQ|
|country_code|ER|
|country_code|EE|
|country_code|SZ|
|country_code|ET|
|country_code|FO|
|country_code|FJ|
|country_code|FI|
|country_code|FR|
|country_code|GF|
|country_code|PF|
|country_code|GA|
|country_code|GM|
|country_code|GE|
|country_code|DE|
|country_code|GH|
|country_code|GI|
|country_code|GR|
|country_code|GL|
|country_code|GD|
|country_code|GP|
|country_code|GU|
|country_code|GT|
|country_code|GG|
|country_code|GN|
|country_code|GW|
|country_code|GY|
|country_code|HT|
|country_code|HN|
|country_code|HK|
|country_code|HU|
|country_code|IS|
|country_code|IN|
|country_code|ID|
|country_code|IR|
|country_code|IQ|
|country_code|IE|
|country_code|IM|
|country_code|IL|
|country_code|IT|
|country_code|JM|
|country_code|JP|
|country_code|JE|
|country_code|JO|
|country_code|KZ|
|country_code|KE|
|country_code|KI|
|country_code|KP|
|country_code|KR|
|country_code|KW|
|country_code|KG|
|country_code|LA|
|country_code|LV|
|country_code|LB|
|country_code|LS|
|country_code|LR|
|country_code|LY|
|country_code|LI|
|country_code|LT|
|country_code|LU|
|country_code|MO|
|country_code|MG|
|country_code|MW|
|country_code|MY|
|country_code|MV|
|country_code|ML|
|country_code|MT|
|country_code|MH|
|country_code|MQ|
|country_code|MR|
|country_code|MU|
|country_code|MX|
|country_code|FM|
|country_code|MD|
|country_code|MC|
|country_code|MN|
|country_code|ME|
|country_code|MS|
|country_code|MA|
|country_code|MZ|
|country_code|MM|
|country_code|NA|
|country_code|NR|
|country_code|NP|
|country_code|NL|
|country_code|NC|
|country_code|NZ|
|country_code|NI|
|country_code|NE|
|country_code|NG|
|country_code|NU|
|country_code|NF|
|country_code|MK|
|country_code|MP|
|country_code|NO|
|country_code|OM|
|country_code|PK|
|country_code|PW|
|country_code|PA|
|country_code|PG|
|country_code|PY|
|country_code|PE|
|country_code|PH|
|country_code|PL|
|country_code|PT|
|country_code|PR|
|country_code|QA|
|country_code|RE|
|country_code|RO|
|country_code|RU|
|country_code|RW|
|country_code|BL|
|country_code|SH|
|country_code|KN|
|country_code|LC|
|country_code|PM|
|country_code|VC|
|country_code|WS|
|country_code|SM|
|country_code|ST|
|country_code|SA|
|country_code|SN|
|country_code|RS|
|country_code|SC|
|country_code|SL|
|country_code|SG|
|country_code|BQ|
|country_code|SX|
|country_code|SK|
|country_code|SI|
|country_code|SB|
|country_code|SO|
|country_code|ZA|
|country_code|GS|
|country_code|SS|
|country_code|ES|
|country_code|LK|
|country_code|SD|
|country_code|SR|
|country_code|SE|
|country_code|CH|
|country_code|SY|
|country_code|TW|
|country_code|TJ|
|country_code|TZ|
|country_code|TH|
|country_code|TL|
|country_code|TG|
|country_code|TK|
|country_code|TO|
|country_code|TT|
|country_code|TN|
|country_code|TR|
|country_code|TM|
|country_code|TC|
|country_code|TV|
|country_code|UG|
|country_code|UA|
|country_code|AE|
|country_code|GB|
|country_code|US|
|country_code|UY|
|country_code|UZ|
|country_code|VU|
|country_code|VA|
|country_code|VE|
|country_code|VN|
|country_code|VG|
|country_code|VI|
|country_code|WF|
|country_code|EH|
|country_code|YE|
|country_code|ZM|
|country_code|ZW|
|company_position|ceo|
|company_position|cfo|
|company_position|coo|
|company_position|managing_member|
|company_position|general_partner|
|company_position|president|
|company_position|vice_president|
|company_position|treasurer|
|company_position|other_senior_management|
|company_position|other_executive_officer|
|company_position|other_non_executive_non_senior|
|Representative Role|ubo|
|Representative Role|legal_representative|
|Representative Role|authorised_signatory|
|Representative Role|control_person|
|type|passport|
|type|national_identity_card|
|type|driving_license|
|type|citizen_card|
|type|residence_permit|
|type|electoral_id|
|type|power_of_attorney|
|business_type|individual_or_sole_proprietorship|
|business_type|limited_company|
|business_type|public_limited_company|
|business_type|limited_partnership|
|business_type|general_partnership|
|business_type|government_agency|
|business_type|non_profit_entity|
|business_type|trust|
|business_type|club_or_society|
|business_type|unincorporated_association|
|currency|EUR|
|type|incorporation_document|
|type|memorandum_of_association|
|type|articles_of_association|
|type|bank_statement|
|type|certified_shareholder_structure|
|type|proof_of_legality|
|type|proof_of_address|
EEACompanyLite2-0
```json
{
"reference": "string",
"status": "string",
"is_draft": true,
"profile": {
"urls": [
"http://example.com"
],
"mccs": [
"string"
]
},
"contact_details": {
"phone": {
"number": 10000000
},
"email_addresses": {
"primary": null
},
"invitee": {
"email": null
}
},
"capabilities": {},
"requirements_due": [
{
"field": "string",
"reason": "string"
}
],
"instruments": [
{}
],
"company": {
"legal_name": "string",
"trading_name": "string",
"business_registration_number": "string",
"principal_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
},
"registered_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
},
"representatives": [
{
"id": "stringstringstringstringstring",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"documents": {
"identity_verification": {
"type": "passport",
"front": "stringstringstringstringstrings",
"back": "stringstringstringstringstrings"
}
},
"date_of_birth": {
"day": 1,
"month": 1,
"year": 1900
},
"phone": {
"number": 10000000
},
"address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
},
"place_of_birth": {
"country": "st"
},
"roles": [
"ubo"
]
}
],
"financial_details": {
"annual_processing_volume": 0,
"average_transaction_value": 0,
"highest_transaction_value": 0,
"currency": "EUR"
},
"business_type": "general_partnership"
},
"documents": {
"company_verification": {
"type": "incorporation_document",
"front": "stringstringstringstringstrings"
},
"bank_verification": {
"type": "bank_statement",
"front": "stringstringstringstringstrings"
},
"financial_verification": {
"type": "financial_statement",
"front": "stringstringstringstringstrings"
}
}
}
```
EEA Company - Lite (2.0)
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|true|none|A unique reference you can later use to identify the sub-entity.|
|status|string|false|read-only|none|
|is_draft|boolean|false|write-only|Specifies whether the sub-entity details are in draft.
Marking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.|
|profile|object|true|none|Information about the profile of the sub-entity, primarily regarding the products/services offered.|
|» urls|[string]|true|none|A collection of website URLs the sub-entity accepts payments on.|
|»» Company website URL|string(uri)|false|none|The URL of the company's website.|
|» mccs|[any]|true|none|Select the categories that most closely describe the business|
|»» Merchant category code|number|false|none|The merchant category code (4-digit ISO 18245).|
|contact_details|object|true|none|Contact details of this sub-entity.|
|» phone|object|true|none|The phone number of the sub-entity.|
|»» number|any|true|none|The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)|
|» email_addresses|object|true|none|Email addresses for this sub-entity.|
|»» primary|any|true|none|The main email address for this sub-entity.|
|» invitee|object|false|none|The details of the user responsible for onboarding the sub-entity.|
|»» email|any|false|none|The main email address for this sub-entity.|
|capabilities|object|false|read-only|The capabilities of the entity.|
|requirements_due|[object]|false|read-only|List of requirements due in order to be onboarded.|
|» Requirements due entry|object|false|read-only|A list of fields which require attention|
|»» field|string|false|none|The field that is needs to be addressed.|
|»» reason|string|false|none|The reason behind the field needing attention.|
|instruments|[object]|false|read-only|none|
|company|object|true|none|none|
|» legal_name|string|true|none|The legal name of the sub-entity.|
|» trading_name|string|true|none|The trading name of the sub-entity, also referred to as 'doing business as'.|
|» business_registration_number|number|false|none|The sub-entity's Business Registration Number. This can be a Commercial Registration or Ministry of Commerce certificate number, or any other equivalent registration number. For sub-entities based in France, this must be a SIRET number.|
|» principal_address|object|true|none|The primary location of the company where business is performed.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» registered_address|object|true|none|The registered address of the company.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» representatives|[object]|true|none|Information about representatives of this company.|
|»» Representative|object|false|none|Information about representatives of this company.|
|»»» id|number|false|none|The representative's id.|
|»»» first_name|string|true|none|The representative's first name.|
|»»» middle_name|string|false|none|The representative's middle name. Required if appears in official docs|
|»»» last_name|string|true|none|The representative's last name.|
|»»» documents|object|false|none|A legal document used to verify identity|
|»»»» identity_verification|object|true|none|The document to use to confirm the individual's identity.|
|»»»»» type|string|true|none|The type of document used for identity verification|
|»»»»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|»»»»» back|string|false|none|The ID of the back side of the document as represented within Checkout.com systems.|
|»»» date_of_birth|object|false|none|The date of birth of the person according to the Gregorian calendar.|
|»»»» day|integer|true|none|The calendar day of the month they were born.|
|»»»» month|integer|true|none|The month of the year they were born.|
|»»»» year|integer|true|none|The year they were born.|
|»»» phone|object|false|none|The phone number of the sub-entity.|
|»»»» number|any|true|none|The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)|
|»»» address|object|true|none|The representative's address.|
|»»»» address_line1|string|false|none|The first line of the address.|
|»»»» address_line2|number|false|none|The second line of the address.|
|»»»» city|string|false|none|The address city.|
|»»»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»»»» zip|string|false|none|The address zip/postal code.|
|»»»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|»»» place_of_birth|object|false|none|The place of birth of the person.|
|»»»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|»»» roles|[string]|false|none|The individual's roles within the company|
|»»»» Representative Role|string|false|none|The representative's roles within the company|
|» financial_details|object|false|none|Seller financial questions and supporting documents.|
|»» annual_processing_volume|integer|false|none|The estimated annual processing volume. In minor units without decimals.|
|»» average_transaction_value|integer|false|none|The expected average transaction value. In minor units without decimals.|
|»» highest_transaction_value|integer|false|none|The expected highest transaction value. In minor units without decimals.|
|»» currency|string|false|none|The currency used for the processing details provided.|
|» business_type|string|false|none|The legal type of the company|
|documents|object|false|none|The documents used to support the identity of a company.|
|» company_verification|object|false|none|Certified by a power of attorney within the last 3 months|
|»» type|string|true|none|The type of document used for company verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» bank_verification|object|false|none|A document showing transactions from last 3 months|
|»» type|string|true|none|The type of document being used as bank verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» financial_verification|object|false|none|Financial statement document becomes mandatory depending on the answer provided for annual_processing_volume. The status of your sub-entity will change to requirements_due stating when this is necessary.|
|»» type|string|true|none|The type of the file.|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|passport|
|type|national_identity_card|
|type|driving_license|
|type|citizen_card|
|type|residence_permit|
|type|electoral_id|
|Representative Role|ubo|
|Representative Role|legal_representative|
|currency|EUR|
|business_type|general_partnership|
|business_type|limited_partnership|
|business_type|public_limited_company|
|business_type|limited_company|
|business_type|professional_association|
|business_type|unincorporated_association|
|business_type|auto_entrepreneur|
|type|incorporation_document|
|type|bank_statement|
|type|financial_statement|
EEASoleTraderFull2-0
```json
{
"reference": "string",
"status": "string",
"is_draft": true,
"profile": {
"urls": [
"http://example.com"
],
"mccs": [
"string"
],
"default_holding_currency": null,
"holding_currencies": [
"EUR"
]
},
"contact_details": {
"phone": {
"number": 10000000
},
"email_addresses": {
"primary": null
},
"invitee": {
"email": null
}
},
"capabilities": {},
"requirements_due": [
{
"field": "string",
"reason": "string"
}
],
"instruments": [
{}
],
"individual": {
"trading_name": "string",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"date_of_birth": {
"day": 1,
"month": 1,
"year": 1900
},
"registered_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
},
"place_of_birth": {
"country": "st"
}
},
"documents": {
"identity_verification": {
"type": "passport",
"front": "stringstringstringstringstrings",
"back": "stringstringstringstringstrings"
}
}
}
```
EEA Sole Trader - Full (2.0)
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|true|none|A unique reference you can later use to identify the sub-entity.|
|status|string|false|read-only|none|
|is_draft|boolean|false|write-only|Specifies whether the sub-entity details are in draft.
Marking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.|
|profile|object|true|none|Information about the profile of the sub-entity, primarily regarding the products/services offered.|
|» urls|[string]|true|none|A collection of website URLs the sub-entity accepts payments on.|
|»» Company website URL|string(uri)|false|none|The URL of the company's website.|
|» mccs|[any]|true|none|Select the categories that most closely describe the business|
|»» Merchant category code|number|false|none|The merchant category code (4-digit ISO 18245).|
|» default_holding_currency|any|false|none|The default holding currency code (iso-4217)|
|» holding_currencies|array|false|none|Incoming funds are held in your selected currencies|
|»» Currency|string|false|none|The currency code (iso-4217)|
|contact_details|object|true|none|Contact details of this sub-entity.|
|» phone|object|true|none|The phone number of the sub-entity.|
|»» number|any|true|none|The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)|
|» email_addresses|object|true|none|Email addresses for this sub-entity.|
|»» primary|any|true|none|The main email address for this sub-entity.|
|» invitee|object|false|none|The details of the user responsible for onboarding the sub-entity.|
|»» email|any|false|none|The main email address for this sub-entity.|
|capabilities|object|false|read-only|The capabilities of the entity.|
|requirements_due|[object]|false|read-only|List of requirements due in order to be onboarded.|
|» Requirements due entry|object|false|read-only|A list of fields which require attention|
|»» field|string|false|none|The field that is needs to be addressed.|
|»» reason|string|false|none|The reason behind the field needing attention.|
|instruments|[object]|false|read-only|none|
|individual|object|true|none|Information about the individual represented by the sub-entity.|
|» trading_name|string|true|none|The trading name of the sub-entity, also referred to as 'doing business as'.|
|» first_name|string|true|none|The representative's first name.|
|» middle_name|string|false|none|The representative's middle name. Required if appears in official docs|
|» last_name|string|true|none|The representative's last name.|
|» date_of_birth|object|true|none|The date of birth of the person according to the Gregorian calendar.|
|»» day|integer|true|none|The calendar day of the month they were born.|
|»» month|integer|true|none|The month of the year they were born.|
|»» year|integer|true|none|The year they were born.|
|» registered_address|object|true|none|The registered address of the company.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» place_of_birth|object|true|none|The place of birth of the person.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|documents|object|true|none|A legal document used to verify identity.|
|» identity_verification|object|true|none|The document to use to confirm the individual's identity.|
|»» type|string|true|none|The type of document used for identity verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|»» back|string|false|none|The ID of the back side of the document as represented within Checkout.com systems.|
#### Enumerated Values
|Property|Value|
|---|---|
|Currency|AED|
|Currency|AUD|
|Currency|CAD|
|Currency|CHF|
|Currency|CZK|
|Currency|DKK|
|Currency|EUR|
|Currency|GBP|
|Currency|HKD|
|Currency|JPY|
|Currency|NOK|
|Currency|NZD|
|Currency|PLN|
|Currency|RON|
|Currency|SEK|
|Currency|SGD|
|Currency|USD|
|Currency|ZAR|
|type|passport|
|type|national_identity_card|
|type|driving_license|
|type|citizen_card|
|type|residence_permit|
|type|electoral_id|
EEASoleTraderFull3-0
```json
{
"reference": "string",
"status": "string",
"is_draft": true,
"profile": {
"urls": [
"http://example.com"
],
"mccs": [
"string"
],
"default_holding_currency": null,
"holding_currencies": [
"EUR"
]
},
"contact_details": {
"phone": {
"country_code": "GR",
"number": "string"
},
"email_addresses": {
"primary": null
},
"invitee": {
"email": null
}
},
"capabilities": {},
"requirements_due": [
{
"field": "string",
"reason": "string",
"message": "string"
}
],
"company": {
"trading_name": "string",
"date_of_incorporation": {
"day": 1,
"month": 1,
"year": 1500
},
"principal_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
},
"representatives": [
{
"id": "stringstringstringstringstring",
"individual": {
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"date_of_birth": {
"day": 1,
"month": 1,
"year": 1900
},
"place_of_birth": {
"country": "st"
},
"national_id_number": "stringstr",
"email_address": null,
"phone": {
"country_code": "AF",
"number": "string"
},
"address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
}
},
"roles": [
"ubo"
],
"documents": {
"identity_verification": {
"type": "passport",
"front": "stringstringstringstringstrings",
"back": "stringstringstringstringstrings"
},
"proof_of_residential_address": {
"type": "proof_of_address",
"front": "stringstringstringstringstrings"
},
"proof_of_registration": {
"type": "extract_from_trade_register",
"front": "stringstringstringstringstrings"
}
}
}
],
"business_type": "individual_or_sole_proprietorship"
},
"processing_details": {
"settlement_country": "st",
"target_countries": [
"st"
],
"annual_processing_volume": 0,
"average_transaction_value": 0,
"highest_transaction_value": 0,
"currency": "EUR"
},
"documents": {
"bank_verification": {
"type": "bank_statement",
"front": "stringstringstringstringstrings"
},
"additional_document1": {
"front": "stringstringstringstringstrings"
},
"additional_document2": {
"front": "stringstringstringstringstrings"
},
"additional_document3": {
"front": "stringstringstringstringstrings"
}
}
}
```
EEA Sole Trader - Full (3.0)
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|true|none|A unique reference you can later use to identify the sub-entity.|
|status|string|false|read-only|none|
|is_draft|boolean|false|write-only|Specifies whether the sub-entity details are in draft.
Marking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.|
|profile|object|true|none|Information about the profile of the sub-entity, primarily regarding the products/services offered.|
|» urls|[string]|true|none|A collection of website URLs the sub-entity accepts payments on.|
|»» Company website URL|string(uri)|false|none|The URL of the company's website.|
|» mccs|[any]|true|none|Select the categories that most closely describe the business|
|»» Merchant category code|number|false|none|The merchant category code (4-digit ISO 18245).|
|» default_holding_currency|any|true|none|The default holding currency code (iso-4217)|
|» holding_currencies|[string]|true|none|Incoming funds are held in your selected currencies|
|»» Currency|string|false|none|The currency code (iso-4217)|
|contact_details|object|true|none|Contact details of this sub-entity.|
|» phone|object|false|none|Phone number|
|»» country_code|string|true|none|The country code (iso-3166-1 alpha-2) where the phone number is registered|
|»» number|string|true|none|The phone number without the country calling code|
|» email_addresses|object|false|none|Email addresses for this sub-entity.|
|»» primary|any|true|none|The main email address for this sub-entity.|
|» invitee|object|false|none|The details of the user responsible for onboarding the sub-entity.|
|»» email|any|false|none|The main email address for this sub-entity.|
|capabilities|object|false|read-only|The capabilities of the entity.|
|requirements_due|[object]|false|read-only|List of requirements due in order to be onboarded.|
|» Requirements due entry|object|false|read-only|A list of fields which require attention|
|»» field|string|false|none|The field that is needs to be addressed.|
|»» reason|string|false|none|The reason behind the field needing attention.|
|»» message|string|false|none|A more descriptive message.|
|company|object|true|none|Information about the sole trader's business.|
|» trading_name|string|true|none|The trading name of the sub-entity, also referred to as 'doing business as'.|
|» date_of_incorporation|object|true|none|The date the company was incorporated.|
|»» day|integer|false|none|The day of the month the company was incorporated.|
|»» month|integer|true|none|The month the company was incorporated.|
|»» year|integer|true|none|The year the company was incorporated.|
|» principal_address|object|true|none|The primary location where business is performed.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» representatives|[object]|true|none|Information about representatives of this company.|
|»» Person of Interest|object|false|none|Personal information about the individual representing the sub-entity.|
|»»» id|number|false|none|The representative's id.|
|»»» individual|object|true|none|Information about the individual representing the sub-entity.|
|»»»» first_name|string|true|none|The representative's first name.|
|»»»» middle_name|string|false|none|The representative's middle name. Required if appears in official docs|
|»»»» last_name|string|true|none|The representative's last name.|
|»»»» date_of_birth|object|true|none|The date of birth of the person according to the Gregorian calendar.|
|»»»»» day|integer|true|none|The calendar day of the month they were born.|
|»»»»» month|integer|true|none|The month of the year they were born.|
|»»»»» year|integer|true|none|The year they were born.|
|»»»» place_of_birth|object|true|none|The place of birth of the person.|
|»»»»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|»»»» national_id_number|number|false|none|Social security number (SSN) or Individual Taxpayer Identification Number (ITIN) for non-US citizens|
|»»»» email_address|any|false|none|The representative's personal email address.|
|»»»» phone|object|false|none|Phone number|
|»»»»» country_code|string|true|none|The country code (iso-3166-1 alpha-2) where the phone number is registered|
|»»»»» number|string|true|none|The phone number without the country calling code|
|»»»» address|object|true|none|The representative's address.|
|»»»»» address_line1|string|true|none|The first line of the address.|
|»»»»» address_line2|number|false|none|The second line of the address.|
|»»»»» city|string|true|none|The address city.|
|»»»»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»»»»» zip|string|true|none|The address zip/postal code.|
|»»»»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|»»» roles|[string]|true|none|The individual's roles within the company|
|»»»» Representative Role|string|false|none|The representative's role|
|»»» documents|object|true|none|Verification documents for the individual representative|
|»»»» identity_verification|object|true|none|The document to use to confirm the individual's identity.|
|»»»»» type|string|true|none|The type of document used for identity verification|
|»»»»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|»»»»» back|string|false|none|The ID of the back side of the document as represented within Checkout.com systems.|
|»»»» proof_of_residential_address|object|true|none|Proof of residential address of the representative|
|»»»»» type|string|true|none|The type of document being used as address verification|
|»»»»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|»»»» proof_of_registration|object|true|none|Proof of sole traders registration e.g. extract from a trade register|
|»»»»» type|string|true|none|The type of document being used as proof of registration|
|»»»»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» business_type|string|true|none|The legal type of the company|
|processing_details|object|true|none|none|
|» settlement_country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2) where the settlement bank account is located|
|» target_countries|[string]|true|none|Target country codes (iso-3166-1 alpha-2) with more than 10% expected volume processing with Checkout|
|»» Country|string(iso-3166-1-alpha-2)|false|none|The country code (iso-3166-1 alpha-2)|
|» annual_processing_volume|integer|true|none|The estimated annual processing volume. In minor units without decimals.|
|» average_transaction_value|integer|true|none|The expected average transaction value. In minor units without decimals.|
|» highest_transaction_value|integer|true|none|The expected highest transaction value. In minor units without decimals.|
|» currency|string|true|none|The currency used for the processing details provided.|
|documents|object|true|none|The documents used to support the verification of business details.|
|» bank_verification|object|true|none|A document showing transactions from last 3 months|
|»» type|string|true|none|The type of document being used as bank verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» additional_document1|object|false|none|Additional space for documents to be provided when requested|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» additional_document2|object|false|none|Additional space for documents to be provided when requested|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» additional_document3|object|false|none|Additional space for documents to be provided when requested|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
#### Enumerated Values
|Property|Value|
|---|---|
|Currency|AED|
|Currency|AUD|
|Currency|CAD|
|Currency|CHF|
|Currency|CZK|
|Currency|DKK|
|Currency|EUR|
|Currency|GBP|
|Currency|HKD|
|Currency|JPY|
|Currency|NOK|
|Currency|NZD|
|Currency|PLN|
|Currency|RON|
|Currency|SEK|
|Currency|SGD|
|Currency|USD|
|Currency|ZAR|
|country_code|GR|
|country_code|NL|
|country_code|BE|
|country_code|FR|
|country_code|ES|
|country_code|PT|
|country_code|LU|
|country_code|IE|
|country_code|IS|
|country_code|MT|
|country_code|CY|
|country_code|FI|
|country_code|BG|
|country_code|HU|
|country_code|LT|
|country_code|LV|
|country_code|EE|
|country_code|AD|
|country_code|HR|
|country_code|SI|
|country_code|IT|
|country_code|RO|
|country_code|CZ|
|country_code|SK|
|country_code|LI|
|country_code|AT|
|country_code|DK|
|country_code|SE|
|country_code|NO|
|country_code|PL|
|country_code|DE|
|country_code|AF|
|country_code|AL|
|country_code|DZ|
|country_code|AS|
|country_code|AD|
|country_code|AO|
|country_code|AI|
|country_code|AG|
|country_code|AR|
|country_code|AM|
|country_code|AW|
|country_code|AU|
|country_code|AT|
|country_code|AZ|
|country_code|BS|
|country_code|BH|
|country_code|BD|
|country_code|BB|
|country_code|BY|
|country_code|BE|
|country_code|BZ|
|country_code|BJ|
|country_code|BM|
|country_code|BT|
|country_code|BO|
|country_code|BA|
|country_code|BW|
|country_code|BR|
|country_code|BN|
|country_code|BG|
|country_code|BF|
|country_code|BI|
|country_code|CV|
|country_code|KH|
|country_code|CM|
|country_code|CA|
|country_code|KY|
|country_code|CF|
|country_code|TD|
|country_code|CL|
|country_code|CN|
|country_code|CO|
|country_code|KM|
|country_code|CD|
|country_code|CG|
|country_code|CK|
|country_code|CR|
|country_code|HR|
|country_code|CU|
|country_code|CW|
|country_code|CY|
|country_code|CZ|
|country_code|DK|
|country_code|DJ|
|country_code|DM|
|country_code|DO|
|country_code|EC|
|country_code|EG|
|country_code|SV|
|country_code|GQ|
|country_code|ER|
|country_code|EE|
|country_code|SZ|
|country_code|ET|
|country_code|FO|
|country_code|FJ|
|country_code|FI|
|country_code|FR|
|country_code|GF|
|country_code|PF|
|country_code|GA|
|country_code|GM|
|country_code|GE|
|country_code|DE|
|country_code|GH|
|country_code|GI|
|country_code|GR|
|country_code|GL|
|country_code|GD|
|country_code|GP|
|country_code|GU|
|country_code|GT|
|country_code|GG|
|country_code|GN|
|country_code|GW|
|country_code|GY|
|country_code|HT|
|country_code|HN|
|country_code|HK|
|country_code|HU|
|country_code|IS|
|country_code|IN|
|country_code|ID|
|country_code|IR|
|country_code|IQ|
|country_code|IE|
|country_code|IM|
|country_code|IL|
|country_code|IT|
|country_code|JM|
|country_code|JP|
|country_code|JE|
|country_code|JO|
|country_code|KZ|
|country_code|KE|
|country_code|KI|
|country_code|KP|
|country_code|KR|
|country_code|KW|
|country_code|KG|
|country_code|LA|
|country_code|LV|
|country_code|LB|
|country_code|LS|
|country_code|LR|
|country_code|LY|
|country_code|LI|
|country_code|LT|
|country_code|LU|
|country_code|MO|
|country_code|MG|
|country_code|MW|
|country_code|MY|
|country_code|MV|
|country_code|ML|
|country_code|MT|
|country_code|MH|
|country_code|MQ|
|country_code|MR|
|country_code|MU|
|country_code|MX|
|country_code|FM|
|country_code|MD|
|country_code|MC|
|country_code|MN|
|country_code|ME|
|country_code|MS|
|country_code|MA|
|country_code|MZ|
|country_code|MM|
|country_code|NA|
|country_code|NR|
|country_code|NP|
|country_code|NL|
|country_code|NC|
|country_code|NZ|
|country_code|NI|
|country_code|NE|
|country_code|NG|
|country_code|NU|
|country_code|NF|
|country_code|MK|
|country_code|MP|
|country_code|NO|
|country_code|OM|
|country_code|PK|
|country_code|PW|
|country_code|PA|
|country_code|PG|
|country_code|PY|
|country_code|PE|
|country_code|PH|
|country_code|PL|
|country_code|PT|
|country_code|PR|
|country_code|QA|
|country_code|RE|
|country_code|RO|
|country_code|RU|
|country_code|RW|
|country_code|BL|
|country_code|SH|
|country_code|KN|
|country_code|LC|
|country_code|PM|
|country_code|VC|
|country_code|WS|
|country_code|SM|
|country_code|ST|
|country_code|SA|
|country_code|SN|
|country_code|RS|
|country_code|SC|
|country_code|SL|
|country_code|SG|
|country_code|BQ|
|country_code|SX|
|country_code|SK|
|country_code|SI|
|country_code|SB|
|country_code|SO|
|country_code|ZA|
|country_code|GS|
|country_code|SS|
|country_code|ES|
|country_code|LK|
|country_code|SD|
|country_code|SR|
|country_code|SE|
|country_code|CH|
|country_code|SY|
|country_code|TW|
|country_code|TJ|
|country_code|TZ|
|country_code|TH|
|country_code|TL|
|country_code|TG|
|country_code|TK|
|country_code|TO|
|country_code|TT|
|country_code|TN|
|country_code|TR|
|country_code|TM|
|country_code|TC|
|country_code|TV|
|country_code|UG|
|country_code|UA|
|country_code|AE|
|country_code|GB|
|country_code|US|
|country_code|UY|
|country_code|UZ|
|country_code|VU|
|country_code|VA|
|country_code|VE|
|country_code|VN|
|country_code|VG|
|country_code|VI|
|country_code|WF|
|country_code|EH|
|country_code|YE|
|country_code|ZM|
|country_code|ZW|
|Representative Role|ubo|
|type|passport|
|type|national_identity_card|
|type|driving_license|
|type|citizen_card|
|type|residence_permit|
|type|electoral_id|
|type|proof_of_address|
|type|extract_from_trade_register|
|type|other|
|business_type|individual_or_sole_proprietorship|
|business_type|limited_company|
|business_type|public_limited_company|
|business_type|limited_partnership|
|business_type|general_partnership|
|business_type|government_agency|
|business_type|non_profit_entity|
|business_type|trust|
|business_type|club_or_society|
|business_type|unincorporated_association|
|currency|EUR|
|type|bank_statement|
EEASoleTraderLite2-0
```json
{
"reference": "string",
"status": "string",
"is_draft": true,
"profile": {
"urls": [
"http://example.com"
],
"mccs": [
"string"
]
},
"contact_details": {
"phone": {
"number": 10000000
},
"email_addresses": {
"primary": null
},
"invitee": {
"email": null
}
},
"capabilities": {},
"requirements_due": [
{
"field": "string",
"reason": "string"
}
],
"instruments": [
{}
],
"documents": {
"identity_verification": {
"type": "passport",
"front": "stringstringstringstringstrings",
"back": "stringstringstringstringstrings"
}
},
"individual": {
"trading_name": "string",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"registered_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
},
"date_of_birth": {
"day": 1,
"month": 1,
"year": 1900
},
"place_of_birth": {
"country": "st"
}
}
}
```
EEA Sole Trader - Lite (2.0)
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|true|none|A unique reference you can later use to identify the sub-entity.|
|status|string|false|read-only|none|
|is_draft|boolean|false|write-only|Specifies whether the sub-entity details are in draft.
Marking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.|
|profile|object|true|none|Information about the profile of the sub-entity, primarily regarding the products/services offered.|
|» urls|[string]|true|none|A collection of website URLs the sub-entity accepts payments on.|
|»» Company website URL|string(uri)|false|none|The URL of the company's website.|
|» mccs|[any]|true|none|Select the categories that most closely describe the business|
|»» Merchant category code|number|false|none|The merchant category code (4-digit ISO 18245).|
|contact_details|object|true|none|Contact details of this sub-entity.|
|» phone|object|true|none|The phone number of the sub-entity.|
|»» number|any|true|none|The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)|
|» email_addresses|object|true|none|Email addresses for this sub-entity.|
|»» primary|any|true|none|The main email address for this sub-entity.|
|» invitee|object|false|none|The details of the user responsible for onboarding the sub-entity.|
|»» email|any|false|none|The main email address for this sub-entity.|
|capabilities|object|false|read-only|The capabilities of the entity.|
|requirements_due|[object]|false|read-only|List of requirements due in order to be onboarded.|
|» Requirements due entry|object|false|read-only|A list of fields which require attention|
|»» field|string|false|none|The field that is needs to be addressed.|
|»» reason|string|false|none|The reason behind the field needing attention.|
|instruments|[object]|false|read-only|none|
|documents|object|false|none|A legal document used to verify identity.|
|» identity_verification|object|true|none|The document to use to confirm the individual's identity.|
|»» type|string|true|none|The type of document used for identity verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|»» back|string|false|none|The ID of the back side of the document as represented within Checkout.com systems.|
|individual|object|true|none|Information about the individual represented by the sub-entity.|
|» trading_name|string|true|none|The trading name of the sub-entity, also referred to as 'doing business as'.|
|» first_name|string|true|none|The representative's first name.|
|» middle_name|string|false|none|The representative's middle name. Required if appears in official docs|
|» last_name|string|true|none|The representative's last name.|
|» registered_address|object|true|none|The registered address of the company.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» date_of_birth|object|true|none|The date of birth of the person according to the Gregorian calendar.|
|»» day|integer|true|none|The calendar day of the month they were born.|
|»» month|integer|true|none|The month of the year they were born.|
|»» year|integer|true|none|The year they were born.|
|» place_of_birth|object|true|none|The place of birth of the person.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
#### Enumerated Values
|Property|Value|
|---|---|
|type|passport|
|type|national_identity_card|
|type|driving_license|
|type|citizen_card|
|type|residence_permit|
|type|electoral_id|
EntityBasicResponseV2
```json
{
"id": "ent_wxglze3wwywujg4nna5fb7ldli",
"reference": "superhero1234",
"capabilities": {
"payments": {
"enabled": false,
"available": true
},
"payouts": {
"enabled": false,
"available": true
},
"issuing": {
"enabled": false,
"available": true
}
},
"requirements_due": [
{
"field": "individual.identification.document",
"reason": "required"
}
]
}
```
Basic response
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The unique identifier of the entity.|
|reference|string|false|none|A unique reference you can later use to identify this entity.|
|capabilities|[EntityCapabilities](#schemaentitycapabilities)|false|none|none|
|requirements_due|[[EntityRequirementV2](#schemaentityrequirementv2)]|false|none|The requirements still due for this entity to unlock capabilities.|
EntityBasicResponseV3
```json
{
"id": "ent_wxglze3wwywujg4nna5fb7ldli",
"reference": "superhero1234",
"requirements_due": [
{
"field": "individual.identification.document",
"reason": "required",
"message": "required"
}
]
}
```
Basic response
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The unique identifier of the entity.|
|reference|string|false|none|A unique reference you can later use to identify this entity.|
|requirements_due|[[EntityRequirementV3](#schemaentityrequirementv3)]|false|none|The requirements still due for this entity to unlock capabilities.|
EntityBasicResponseWithLinksV2
```json
{
"id": "ent_wxglze3wwywujg4nna5fb7ldli",
"reference": "superhero1234",
"capabilities": {
"payments": {
"enabled": false,
"available": true
},
"payouts": {
"enabled": false,
"available": true
},
"issuing": {
"enabled": false,
"available": true
}
},
"requirements_due": [
{
"field": "individual.identification.document",
"reason": "required"
}
],
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli"
}
}
}
```
Company - Platform (2.0)
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[EntityBasicResponseV2](#schemaentitybasicresponsev2)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[EntityLinks](#schemaentitylinks)|false|none|none|
EntityBasicResponseWithLinksV3
```json
{
"id": "ent_wxglze3wwywujg4nna5fb7ldli",
"reference": "superhero1234",
"requirements_due": [
{
"field": "individual.identification.document",
"reason": "required",
"message": "required"
}
],
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli"
}
}
}
```
Company - Platform (3.0)
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[EntityBasicResponseV3](#schemaentitybasicresponsev3)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[EntityLinks](#schemaentitylinks)|false|none|none|
EntityCapabilities
```json
{
"payments": {
"enabled": false,
"available": true
},
"payouts": {
"enabled": false,
"available": true
},
"issuing": {
"enabled": false,
"available": true
}
}
```
Capabilities
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|payments|object|false|none|Payment related capabilities of an entity.|
|» available|boolean|false|none|True if payments are available to the entity.|
|» enabled|boolean|false|none|True if payments are enabled.|
|payouts|object|false|none|Payout related capabilities of an entity.|
|» available|boolean|false|none|True if payouts are available to the entity.|
|» enabled|boolean|false|none|True if payouts are enabled.|
|issuing|object|false|none|Issuing related capabilities of an entity.|
|» available|boolean|false|none|True if issuing is available to the entity.|
|» enabled|boolean|false|none|True if issuing is enabled.|
EntityLinks
```json
{
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli"
}
}
}
```
Links
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|_links|object|false|none|none|
|» **additionalProperties**|[Link](#schemalink)|false|none|none|
EntityRequirementDetails
```json
{
"id": "req_5wmacwhrhbzhqkhx5hlqmzje44",
"resource": "ent_wxglze3wwywujg4nna5fb7ldli",
"resource_type": "company",
"reason": "periodic_review",
"priority": "high",
"deadline": "2026-06-01T00:00:00Z",
"urn": "urn:object:company#ent_wxglze3wwywujg4nna5fb7ldli#field:legal-name",
"field_path": "company.legal_name",
"field_urn": "urn:field:companies/legal-name",
"metadata": {
"purpose": "company_verification"
},
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli/requirements/req_5wmacwhrhbzhqkhx5hlqmzje44"
}
},
"message": "Please confirm your legal company name.",
"_schema": {}
}
```
Requirement details
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[EntityRequirementListItem](#schemaentityrequirementlistitem)|false|none|A pending requirement that the sub-entity must resolve to remain compliant or unlock capabilities.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» message|string|false|none|A user-facing explanation of what is needed to resolve the requirement.|
|» _schema|object¦null|false|none|JSON Schema that the value supplied to `PUT /accounts/entities/{id}/requirements/{requirementId}` must conform to. The shape varies by requirement type (for example: an identity document upload, a free-text response, or a structured object). Validate the value client-side against this schema before submitting. May be `null` if no schema is registered for the requirement's field.|
EntityRequirementListItem
```json
{
"id": "req_5wmacwhrhbzhqkhx5hlqmzje44",
"resource": "ent_wxglze3wwywujg4nna5fb7ldli",
"resource_type": "company",
"reason": "periodic_review",
"priority": "high",
"deadline": "2026-06-01T00:00:00Z",
"urn": "urn:object:company#ent_wxglze3wwywujg4nna5fb7ldli#field:legal-name",
"field_path": "company.legal_name",
"field_urn": "urn:field:companies/legal-name",
"metadata": {
"purpose": "company_verification"
},
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli/requirements/req_5wmacwhrhbzhqkhx5hlqmzje44"
}
}
}
```
Requirement summary
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The unique identifier of the requirement.|
|resource|string|false|none|The ID of the resource (sub-entity or representative) the requirement applies to.|
|resource_type|string|false|none|The type of resource the requirement applies to derived from the resource's URN. Common values include `company`, `individual`, and `representative`. Defaults to `entity` if the URN cannot be parsed.|
|reason|string|false|none|The reason the requirement was raised.|
|priority|string|false|none|Priority level of this requirement. "high" by default, "critical" if deadline is within 7 days.|
|deadline|string(date-time)|false|none|The date and time, in ISO 8601 UTC format, by which the requirement must be resolved.|
|urn|string|false|none|The schema-registry URN identifying the field this requirement applies to. Format: `urn:object:{resource_type}#{resource_id}#field:{field_name}`.|
|field_path|string¦null|false|none|Dot-notation path of the field on the resource that needs to be supplied or updated. May be `null` for ad-hoc requirements (such as additional documents or free-text responses) that do not map to a specific field on the entity.|
|field_urn|string¦null|false|none|The schema-registry URN of the field, from the public mapping definition. May be `null` if no mapping exists.|
|metadata|object¦null|false|none|Optional metadata from the property mapping definition. Shape varies by requirement.|
|_links|object|false|none|Links to related resources.|
|» **additionalProperties**|[Link](#schemalink)|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|reason|periodic_review|
|reason|attestation|
|priority|high|
|priority|critical|
EntityRequirementListResponse
```json
{
"data": [
{
"id": "req_5wmacwhrhbzhqkhx5hlqmzje44",
"resource": "ent_wxglze3wwywujg4nna5fb7ldli",
"resource_type": "company",
"reason": "periodic_review",
"priority": "high",
"deadline": "2026-06-01T00:00:00Z",
"urn": "urn:object:company#ent_wxglze3wwywujg4nna5fb7ldli#field:legal-name",
"field_path": "company.legal_name",
"field_urn": "urn:field:companies/legal-name",
"metadata": {
"purpose": "company_verification"
},
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli/requirements/req_5wmacwhrhbzhqkhx5hlqmzje44"
}
}
}
]
}
```
Requirements list
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|data|[[EntityRequirementListItem](#schemaentityrequirementlistitem)]|false|none|The list of pending requirements for the sub-entity. Empty when no requirements are outstanding.|
EntityRequirementUpdateRequest
```json
{
"value": {
"file_id": "file_6lbss42ezvoufcb2beo76rvwly"
}
}
```
Resolve requirement request
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|value|any|true|none|The response to the requirement. The expected shape depends on the requirement and is defined by the JSON Schema returned in the requirement details response. Common shapes include a file reference (for document uploads), a primitive value, or a structured object.|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|object|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[any]|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|number|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|boolean|false|none|none|
EntityRequirementUpdateResponse
```json
{
"id": "req_5wmacwhrhbzhqkhx5hlqmzje44",
"status": "processing",
"submitted_at": "2026-05-05T10:15:30Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli/requirements/req_5wmacwhrhbzhqkhx5hlqmzje44"
},
"collection": {
"href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli/requirements"
}
}
}
```
Resolve requirement response
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The unique identifier of the requirement.|
|status|string|false|none|Processing status of the submitted response. While the response is processing, the requirement is no longer retrievable via the GET endpoints; if validation fails downstream the requirement may reappear.|
|submitted_at|string(date-time)|false|none|The date and time, in ISO 8601 UTC format, the response was accepted.|
|_links|object|false|none|none|
|» **additionalProperties**|[Link](#schemalink)|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|status|processing|
EntityRequirementV2
```json
{
"field": "individual.identification.document",
"reason": "required"
}
```
Requirement
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|field|string|false|none|The name of the field required.|
|reason|string|false|none|The reason the field is required.|
EntityRequirementV3
```json
{
"field": "individual.identification.document",
"reason": "required",
"message": "required"
}
```
Requirement
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|field|string|false|none|The name of the field required.|
|reason|string|false|none|The reason the field is required.|
|message|string|false|none|An additional text field for requirement reasoning.|
GBCompanyFull2-0
```json
{
"reference": "string",
"status": "string",
"is_draft": true,
"profile": {
"urls": [
"http://example.com"
],
"mccs": [
"string"
],
"default_holding_currency": null,
"holding_currencies": [
"GBP"
]
},
"contact_details": {
"phone": {
"number": 10000000
},
"email_addresses": {
"primary": null
},
"invitee": {
"email": null
}
},
"capabilities": {},
"requirements_due": [
{
"field": "string",
"reason": "string"
}
],
"instruments": [
{}
],
"company": {
"legal_name": "string",
"trading_name": "string",
"business_registration_number": "stringst",
"principal_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
},
"registered_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
},
"representatives": [
{
"id": "stringstringstringstringstring",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"documents": {
"identity_verification": {
"type": "passport",
"front": "stringstringstringstringstrings",
"back": "stringstringstringstringstrings"
}
},
"date_of_birth": {
"day": 1,
"month": 1,
"year": 1900
},
"phone": {
"number": 10000000
},
"address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
},
"roles": [
"ubo"
]
}
],
"date_of_incorporation": {
"day": 1,
"month": 1,
"year": 1500
}
},
"documents": {
"company_verification": {
"type": "incorporation_document",
"front": "stringstringstringstringstrings"
}
}
}
```
GB Company - Full (2.0)
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|true|none|A unique reference you can later use to identify the sub-entity.|
|status|string|false|read-only|none|
|is_draft|boolean|false|write-only|Specifies whether the sub-entity details are in draft.
Marking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.|
|profile|object|true|none|Information about the profile of the sub-entity, primarily regarding the products/services offered.|
|» urls|[string]|true|none|A collection of website URLs the sub-entity accepts payments on.|
|»» Company website URL|string(uri)|false|none|The URL of the company's website.|
|» mccs|[any]|true|none|Select the categories that most closely describe the business|
|»» Merchant category code|number|false|none|The merchant category code (4-digit ISO 18245).|
|» default_holding_currency|any|false|none|The default holding currency code (iso-4217)|
|» holding_currencies|array|false|none|Incoming funds are held in your selected currencies|
|»» Currency|string|false|none|The currency code (iso-4217)|
|contact_details|object|true|none|Contact details of this sub-entity.|
|» phone|object|true|none|The phone number of the sub-entity.|
|»» number|any|true|none|The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)|
|» email_addresses|object|true|none|Email addresses for this sub-entity.|
|»» primary|any|true|none|The main email address for this sub-entity.|
|» invitee|object|false|none|The details of the user responsible for onboarding the sub-entity.|
|»» email|any|false|none|The main email address for this sub-entity.|
|capabilities|object|false|read-only|The capabilities of the entity.|
|requirements_due|[object]|false|read-only|List of requirements due in order to be onboarded.|
|» Requirements due entry|object|false|read-only|A list of fields which require attention|
|»» field|string|false|none|The field that is needs to be addressed.|
|»» reason|string|false|none|The reason behind the field needing attention.|
|instruments|[object]|false|read-only|none|
|company|object|true|none|Information about the company represented by the sub-entity.|
|» legal_name|string|true|none|The legal name of the sub-entity.|
|» trading_name|string|true|none|The trading name of the sub-entity, also referred to as 'doing business as'.|
|» business_registration_number|number|true|none|The sub-entity's Business Registration Number. This can be a Commercial Registration or Ministry of Commerce certificate number, or any other equivalent registration number.|
|» principal_address|object|true|none|The primary location of the company where business is performed.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» registered_address|object|true|none|The registered address of the company.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» representatives|[object]|true|none|Information about representatives of this company.|
|»» Representative|object|false|none|Information about representatives of this company.|
|»»» id|number|false|none|The representative's id.|
|»»» first_name|string|true|none|The representative's first name.|
|»»» middle_name|string|false|none|The representative's middle name. Required if appears in official docs|
|»»» last_name|string|true|none|The representative's last name.|
|»»» documents|object|false|none|A legal document used to verify identity|
|»»»» identity_verification|object|true|none|The document to use to confirm the individual's identity.|
|»»»»» type|string|true|none|The type of document used for identity verification|
|»»»»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|»»»»» back|string|false|none|The ID of the back side of the document as represented within Checkout.com systems.|
|»»» date_of_birth|object|true|none|The date of birth of the person according to the Gregorian calendar.|
|»»»» day|integer|true|none|The calendar day of the month they were born.|
|»»»» month|integer|true|none|The month of the year they were born.|
|»»»» year|integer|true|none|The year they were born.|
|»»» phone|object|false|none|The phone number of the sub-entity.|
|»»»» number|any|true|none|The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)|
|»»» address|object|true|none|The representative's address.|
|»»»» address_line1|string|false|none|The first line of the address.|
|»»»» address_line2|number|false|none|The second line of the address.|
|»»»» city|string|false|none|The address city.|
|»»»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»»»» zip|string|false|none|The address zip/postal code.|
|»»»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|»»» roles|[string]|true|none|The individual's roles within the company|
|»»»» Representative Role|string|false|none|The representative's roles within the company|
|» date_of_incorporation|object|false|none|The date the company was incorporated.|
|»» day|integer|false|none|The day of the month the company was incorporated.|
|»» month|integer|true|none|The month the company was incorporated.|
|»» year|integer|true|none|The year the company was incorporated.|
|documents|object|false|none|The documents used to support the verification of company details.|
|» company_verification|object|true|none|Certified by a power of attorney within the last 3 months|
|»» type|string|true|none|The type of document used for company verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
#### Enumerated Values
|Property|Value|
|---|---|
|Currency|AED|
|Currency|AUD|
|Currency|CAD|
|Currency|CHF|
|Currency|CZK|
|Currency|DKK|
|Currency|EUR|
|Currency|GBP|
|Currency|HKD|
|Currency|JPY|
|Currency|KWD|
|Currency|NOK|
|Currency|NZD|
|Currency|PLN|
|Currency|RON|
|Currency|SEK|
|Currency|SGD|
|Currency|USD|
|Currency|ZAR|
|type|passport|
|type|national_identity_card|
|type|driving_license|
|type|citizen_card|
|type|residence_permit|
|type|electoral_id|
|Representative Role|ubo|
|Representative Role|authorised_signatory|
|type|incorporation_document|
GBCompanyFull3-0
```json
{
"reference": "string",
"status": "string",
"is_draft": true,
"profile": {
"urls": [
"http://example.com"
],
"mccs": [
"string"
],
"default_holding_currency": null,
"holding_currencies": [
"GBP"
]
},
"contact_details": {
"phone": {
"country_code": "GI",
"number": "strings"
},
"email_addresses": {
"primary": null
},
"invitee": {
"email": null
}
},
"capabilities": {},
"requirements_due": [
{
"field": "string",
"reason": "string",
"message": "string"
}
],
"company": {
"legal_name": "string",
"trading_name": "string",
"business_registration_number": "stringst",
"date_of_incorporation": {
"day": 1,
"month": 1,
"year": 1500
},
"principal_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
},
"registered_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
},
"representatives": [
{
"id": "stringstringstringstringstring",
"individual": {
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"date_of_birth": {
"day": 1,
"month": 1,
"year": 1900
},
"place_of_birth": {
"country": "st"
},
"national_id_number": "stringstr",
"email_address": null,
"phone": {
"country_code": "AF",
"number": "string"
},
"address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
}
},
"company_position": "ceo",
"roles": [
"ubo"
],
"ownership_percentage": 25,
"documents": {
"identity_verification": {
"type": "passport",
"front": "stringstringstringstringstrings",
"back": "stringstringstringstringstrings"
},
"certified_authorised_signatory": {
"type": "power_of_attorney",
"front": "stringstringstringstringstrings"
}
}
}
],
"business_type": "individual_or_sole_proprietorship"
},
"processing_details": {
"settlement_country": "st",
"target_countries": [
"st"
],
"annual_processing_volume": 0,
"average_transaction_value": 0,
"highest_transaction_value": 0,
"currency": "GBP"
},
"documents": {
"company_verification": {
"type": "incorporation_document",
"front": "stringstringstringstringstrings"
},
"articles_of_association": {
"type": "memorandum_of_association",
"front": "stringstringstringstringstrings"
},
"bank_verification": {
"type": "bank_statement",
"front": "stringstringstringstringstrings"
},
"shareholder_structure": {
"type": "certified_shareholder_structure",
"front": "stringstringstringstringstrings"
},
"proof_of_legality": {
"type": "proof_of_legality",
"front": "stringstringstringstringstrings"
},
"proof_of_principal_address": {
"type": "proof_of_address",
"front": "stringstringstringstringstrings"
},
"additional_document1": {
"front": "stringstringstringstringstrings"
},
"additional_document2": {
"front": "stringstringstringstringstrings"
},
"additional_document3": {
"front": "stringstringstringstringstrings"
}
}
}
```
GB Company - Full (3.0)
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|true|none|A unique reference you can later use to identify the sub-entity.|
|status|string|false|read-only|none|
|is_draft|boolean|false|write-only|Specifies whether the sub-entity details are in draft.
Marking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.|
|profile|object|true|none|Information about the profile of the sub-entity, primarily regarding the products/services offered.|
|» urls|[string]|true|none|A collection of website URLs the sub-entity accepts payments on.|
|»» Company website URL|string(uri)|false|none|The URL of the company's website.|
|» mccs|[any]|true|none|Select the categories that most closely describe the business|
|»» Merchant category code|number|false|none|The merchant category code (4-digit ISO 18245).|
|» default_holding_currency|any|true|none|The default holding currency code (iso-4217)|
|» holding_currencies|[string]|true|none|Incoming funds are held in your selected currencies|
|»» Currency|string|false|none|The currency code (iso-4217)|
|contact_details|object|true|none|Contact details of this sub-entity.|
|» phone|object|false|none|Phone number|
|»» country_code|string|true|none|The country code (iso-3166-1 alpha-2) where the phone number is registered|
|»» number|string|true|none|The phone number without the country calling code|
|» email_addresses|object|false|none|Email addresses for this sub-entity.|
|»» primary|any|true|none|The main email address for this sub-entity.|
|» invitee|object|false|none|The details of the user responsible for onboarding the sub-entity.|
|»» email|any|false|none|The main email address for this sub-entity.|
|capabilities|object|false|read-only|The capabilities of the entity.|
|requirements_due|[object]|false|read-only|List of requirements due in order to be onboarded.|
|» Requirements due entry|object|false|read-only|A list of fields which require attention|
|»» field|string|false|none|The field that is needs to be addressed.|
|»» reason|string|false|none|The reason behind the field needing attention.|
|»» message|string|false|none|A more descriptive message.|
|company|object|true|none|Information about the company represented by the sub-entity.|
|» legal_name|string|true|none|The legal name of the sub-entity.|
|» trading_name|string|true|none|The trading name of the sub-entity, also referred to as 'doing business as'.|
|» business_registration_number|number|true|none|The sub-entity's Business Registration Number. This can be a Commercial Registration or Ministry of Commerce certificate number, or any other equivalent registration number.|
|» date_of_incorporation|object|true|none|The date the company was incorporated.|
|»» day|integer|false|none|The day of the month the company was incorporated.|
|»» month|integer|true|none|The month the company was incorporated.|
|»» year|integer|true|none|The year the company was incorporated.|
|» principal_address|object|true|none|The primary location of the company where business is performed.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» registered_address|object|true|none|The registered address of the company.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» representatives|[oneOf]|true|none|Information about representatives of this company.|
|»» Representative|object|false|none|none|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»»» *anonymous*|object|false|none|Personal information about the individual representing the sub-entity.|
|»»»» id|number|false|none|The representative's id.|
|»»»» individual|object|true|none|Information about the individual representing the sub-entity.|
|»»»»» first_name|string|true|none|The representative's first name.|
|»»»»» middle_name|string|false|none|The representative's middle name. Required if appears in official docs|
|»»»»» last_name|string|true|none|The representative's last name.|
|»»»»» date_of_birth|object|true|none|The date of birth of the person according to the Gregorian calendar.|
|»»»»»» day|integer|true|none|The calendar day of the month they were born.|
|»»»»»» month|integer|true|none|The month of the year they were born.|
|»»»»»» year|integer|true|none|The year they were born.|
|»»»»» place_of_birth|object|true|none|The place of birth of the person.|
|»»»»»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|»»»»» national_id_number|number|false|none|Social security number (SSN) or Individual Taxpayer Identification Number (ITIN) for non-US citizens|
|»»»»» email_address|any|false|none|The main email address for this sub-entity.|
|»»»»» phone|object|false|none|Phone number|
|»»»»»» country_code|string|true|none|The country code (iso-3166-1 alpha-2) where the phone number is registered|
|»»»»»» number|string|true|none|The phone number without the country calling code|
|»»»»» address|object|true|none|The representative's address.|
|»»»»»» address_line1|string|true|none|The first line of the address.|
|»»»»»» address_line2|number|false|none|The second line of the address.|
|»»»»»» city|string|true|none|The address city.|
|»»»»»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»»»»»» zip|string|true|none|The address zip/postal code.|
|»»»»»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|»»»» company_position|string|false|none|The position of the representative within the company.|
|»»»» roles|[string]|true|none|The individual's roles within the company|
|»»»»» Representative Role|string|false|none|The representative's role|
|»»»» ownership_percentage|integer|false|none|The percentage ownership of the UBO or controlling company (required when over 25%)|
|»»»» documents|object|false|none|Verification documents for the individual representative|
|»»»»» identity_verification|object|false|none|The document to use to confirm the individual's identity.|
|»»»»»» type|string|true|none|The type of document used for identity verification|
|»»»»»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|»»»»»» back|string|false|none|The ID of the back side of the document as represented within Checkout.com systems.|
|»»»»» certified_authorised_signatory|object|false|none|Required when the legal representative or other role owner is not registered on certificate of incorporation|
|»»»»»» type|string|true|none|The type of document.|
|»»»»»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»»» *anonymous*|object|false|none|Information about the controlling company|
|»»»» id|number|false|none|The representative's id.|
|»»»» company|object|true|none|none|
|»»»»» legal_name|string|true|none|The legal name of the sub-entity.|
|»»»»» trading_name|string|true|none|The trading name of the sub-entity, also referred to as 'doing business as'.|
|»»»»» registered_address|object|true|none|The representative's address.|
|»»»»»» address_line1|string|false|none|The first line of the address.|
|»»»»»» address_line2|number|false|none|The second line of the address.|
|»»»»»» city|string|false|none|The address city.|
|»»»»»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»»»»»» zip|string|false|none|The address zip/postal code.|
|»»»»»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|»»»» ownership_percentage|integer|false|none|The percentage ownership of the UBO or controlling company (required when over 25%)|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» business_type|string|true|none|The legal type of the company|
|processing_details|object|true|none|Seller processing details.|
|» settlement_country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2) where the settlement bank account is located|
|» target_countries|[string]|true|none|Target country codes (iso-3166-1 alpha-2) with more than 10% expected volume processing with Checkout|
|»» Country|string(iso-3166-1-alpha-2)|false|none|The country code (iso-3166-1 alpha-2)|
|» annual_processing_volume|integer|true|none|The estimated annual processing volume. In minor units without decimals.|
|» average_transaction_value|integer|true|none|The expected average transaction value. In minor units without decimals.|
|» highest_transaction_value|integer|true|none|The expected highest transaction value. In minor units without decimals.|
|» currency|string|true|none|The currency used for the processing details provided.|
|documents|object|true|none|The documents used to support the verification of company details.|
|» company_verification|object|false|none|Certified by a power of attorney within the last 3 months|
|»» type|string|true|none|The type of document used for company verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» articles_of_association|object|true|none|Memorandum or Articles of Association document|
|»» type|string|true|none|The type of document used for company verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» bank_verification|object|false|none|A document showing transactions from last 3 months|
|»» type|string|true|none|The type of document being used as bank verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» shareholder_structure|object|true|none|Shareholder structure chart (including % of shares) certified by a competent authority individual and dated within last 3 months|
|»» type|string|true|none|The type of document.|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» proof_of_legality|object|false|none|A regulatory licence document required for the company to operate (when applicable)|
|»» type|string|true|none|The type of document used for proof of legality|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» proof_of_principal_address|object|false|none|Proof of principal place of business|
|»» type|string|true|none|The type of document being used as address verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» additional_document1|object|false|none|Additional space for documents to be provided when requested|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» additional_document2|object|false|none|Additional space for documents to be provided when requested|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» additional_document3|object|false|none|Additional space for documents to be provided when requested|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
#### Enumerated Values
|Property|Value|
|---|---|
|Currency|AED|
|Currency|AUD|
|Currency|CAD|
|Currency|CHF|
|Currency|CZK|
|Currency|DKK|
|Currency|EUR|
|Currency|GBP|
|Currency|HKD|
|Currency|JPY|
|Currency|KWD|
|Currency|NOK|
|Currency|NZD|
|Currency|PLN|
|Currency|RON|
|Currency|SEK|
|Currency|SGD|
|Currency|USD|
|Currency|ZAR|
|country_code|GI|
|country_code|CH|
|country_code|GG|
|country_code|IM|
|country_code|JE|
|country_code|GB|
|country_code|AF|
|country_code|AL|
|country_code|DZ|
|country_code|AS|
|country_code|AD|
|country_code|AO|
|country_code|AI|
|country_code|AG|
|country_code|AR|
|country_code|AM|
|country_code|AW|
|country_code|AU|
|country_code|AT|
|country_code|AZ|
|country_code|BS|
|country_code|BH|
|country_code|BD|
|country_code|BB|
|country_code|BY|
|country_code|BE|
|country_code|BZ|
|country_code|BJ|
|country_code|BM|
|country_code|BT|
|country_code|BO|
|country_code|BA|
|country_code|BW|
|country_code|BR|
|country_code|BN|
|country_code|BG|
|country_code|BF|
|country_code|BI|
|country_code|CV|
|country_code|KH|
|country_code|CM|
|country_code|CA|
|country_code|KY|
|country_code|CF|
|country_code|TD|
|country_code|CL|
|country_code|CN|
|country_code|CO|
|country_code|KM|
|country_code|CD|
|country_code|CG|
|country_code|CK|
|country_code|CR|
|country_code|HR|
|country_code|CU|
|country_code|CW|
|country_code|CY|
|country_code|CZ|
|country_code|DK|
|country_code|DJ|
|country_code|DM|
|country_code|DO|
|country_code|EC|
|country_code|EG|
|country_code|SV|
|country_code|GQ|
|country_code|ER|
|country_code|EE|
|country_code|SZ|
|country_code|ET|
|country_code|FO|
|country_code|FJ|
|country_code|FI|
|country_code|FR|
|country_code|GF|
|country_code|PF|
|country_code|GA|
|country_code|GM|
|country_code|GE|
|country_code|DE|
|country_code|GH|
|country_code|GI|
|country_code|GR|
|country_code|GL|
|country_code|GD|
|country_code|GP|
|country_code|GU|
|country_code|GT|
|country_code|GG|
|country_code|GN|
|country_code|GW|
|country_code|GY|
|country_code|HT|
|country_code|HN|
|country_code|HK|
|country_code|HU|
|country_code|IS|
|country_code|IN|
|country_code|ID|
|country_code|IR|
|country_code|IQ|
|country_code|IE|
|country_code|IM|
|country_code|IL|
|country_code|IT|
|country_code|JM|
|country_code|JP|
|country_code|JE|
|country_code|JO|
|country_code|KZ|
|country_code|KE|
|country_code|KI|
|country_code|KP|
|country_code|KR|
|country_code|KW|
|country_code|KG|
|country_code|LA|
|country_code|LV|
|country_code|LB|
|country_code|LS|
|country_code|LR|
|country_code|LY|
|country_code|LI|
|country_code|LT|
|country_code|LU|
|country_code|MO|
|country_code|MG|
|country_code|MW|
|country_code|MY|
|country_code|MV|
|country_code|ML|
|country_code|MT|
|country_code|MH|
|country_code|MQ|
|country_code|MR|
|country_code|MU|
|country_code|MX|
|country_code|FM|
|country_code|MD|
|country_code|MC|
|country_code|MN|
|country_code|ME|
|country_code|MS|
|country_code|MA|
|country_code|MZ|
|country_code|MM|
|country_code|NA|
|country_code|NR|
|country_code|NP|
|country_code|NL|
|country_code|NC|
|country_code|NZ|
|country_code|NI|
|country_code|NE|
|country_code|NG|
|country_code|NU|
|country_code|NF|
|country_code|MK|
|country_code|MP|
|country_code|NO|
|country_code|OM|
|country_code|PK|
|country_code|PW|
|country_code|PA|
|country_code|PG|
|country_code|PY|
|country_code|PE|
|country_code|PH|
|country_code|PL|
|country_code|PT|
|country_code|PR|
|country_code|QA|
|country_code|RE|
|country_code|RO|
|country_code|RU|
|country_code|RW|
|country_code|BL|
|country_code|SH|
|country_code|KN|
|country_code|LC|
|country_code|SX|
|country_code|PM|
|country_code|VC|
|country_code|WS|
|country_code|SM|
|country_code|ST|
|country_code|SA|
|country_code|SN|
|country_code|RS|
|country_code|SC|
|country_code|SL|
|country_code|SG|
|country_code|BQ|
|country_code|SK|
|country_code|SI|
|country_code|SB|
|country_code|SO|
|country_code|ZA|
|country_code|GS|
|country_code|SS|
|country_code|ES|
|country_code|LK|
|country_code|SD|
|country_code|SR|
|country_code|SE|
|country_code|CH|
|country_code|SY|
|country_code|TW|
|country_code|TJ|
|country_code|TZ|
|country_code|TH|
|country_code|TL|
|country_code|TG|
|country_code|TK|
|country_code|TO|
|country_code|TT|
|country_code|TN|
|country_code|TR|
|country_code|TM|
|country_code|TC|
|country_code|TV|
|country_code|UG|
|country_code|UA|
|country_code|AE|
|country_code|GB|
|country_code|US|
|country_code|UY|
|country_code|UZ|
|country_code|VU|
|country_code|VA|
|country_code|VE|
|country_code|VN|
|country_code|VG|
|country_code|VI|
|country_code|WF|
|country_code|EH|
|country_code|YE|
|country_code|ZM|
|country_code|ZW|
|company_position|ceo|
|company_position|cfo|
|company_position|coo|
|company_position|managing_member|
|company_position|general_partner|
|company_position|president|
|company_position|vice_president|
|company_position|treasurer|
|company_position|other_senior_management|
|company_position|other_executive_officer|
|company_position|other_non_executive_non_senior|
|Representative Role|ubo|
|Representative Role|authorised_signatory|
|Representative Role|director|
|Representative Role|control_person|
|type|passport|
|type|national_identity_card|
|type|driving_license|
|type|citizen_card|
|type|residence_permit|
|type|electoral_id|
|type|power_of_attorney|
|business_type|individual_or_sole_proprietorship|
|business_type|limited_company|
|business_type|public_limited_company|
|business_type|limited_partnership|
|business_type|general_partnership|
|business_type|scottish_limited_partnership|
|business_type|government_agency|
|business_type|non_profit_entity|
|business_type|trust|
|business_type|club_or_society|
|business_type|unincorporated_association|
|currency|GBP|
|type|incorporation_document|
|type|memorandum_of_association|
|type|articles_of_association|
|type|bank_statement|
|type|certified_shareholder_structure|
|type|proof_of_legality|
|type|proof_of_address|
GBCompanyLite2-0
```json
{
"reference": "string",
"status": "string",
"is_draft": true,
"profile": {
"urls": [
"http://example.com"
],
"mccs": [
"string"
]
},
"contact_details": {
"phone": {
"number": 10000000
},
"email_addresses": {
"primary": null
},
"invitee": {
"email": null
}
},
"capabilities": {},
"requirements_due": [
{
"field": "string",
"reason": "string"
}
],
"instruments": [
{}
],
"company": {
"legal_name": "string",
"trading_name": "string",
"business_registration_number": "stringst",
"principal_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
},
"registered_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
},
"representatives": [
{
"id": "stringstringstringstringstring",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"documents": {
"identity_verification": {
"type": "passport",
"front": "stringstringstringstringstrings",
"back": "stringstringstringstringstrings"
}
},
"date_of_birth": {
"day": 1,
"month": 1,
"year": 1900
},
"phone": {
"number": 10000000
},
"address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
},
"roles": [
"ubo"
]
}
]
},
"documents": {
"company_verification": {
"type": "incorporation_document",
"front": "stringstringstringstringstrings"
}
}
}
```
GB Company - Lite (2.0)
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|true|none|A unique reference you can later use to identify the sub-entity.|
|status|string|false|read-only|none|
|is_draft|boolean|false|write-only|Specifies whether the sub-entity details are in draft.
Marking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.|
|profile|object|true|none|Information about the profile of the sub-entity, primarily regarding the products/services offered.|
|» urls|[string]|true|none|A collection of website URLs the sub-entity accepts payments on.|
|»» Company website URL|string(uri)|false|none|The URL of the company's website.|
|» mccs|[any]|true|none|Select the categories that most closely describe the business|
|»» Merchant category code|number|false|none|The merchant category code (4-digit ISO 18245).|
|contact_details|object|true|none|Contact details of this sub-entity.|
|» phone|object|true|none|The phone number of the sub-entity.|
|»» number|any|true|none|The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)|
|» email_addresses|object|true|none|Email addresses for this sub-entity.|
|»» primary|any|true|none|The main email address for this sub-entity.|
|» invitee|object|false|none|The details of the user responsible for onboarding the sub-entity.|
|»» email|any|false|none|The main email address for this sub-entity.|
|capabilities|object|false|read-only|The capabilities of the entity.|
|requirements_due|[object]|false|read-only|List of requirements due in order to be onboarded.|
|» Requirements due entry|object|false|read-only|A list of fields which require attention|
|»» field|string|false|none|The field that is needs to be addressed.|
|»» reason|string|false|none|The reason behind the field needing attention.|
|instruments|[object]|false|read-only|none|
|company|object|true|none|none|
|» legal_name|string|true|none|The legal name of the sub-entity.|
|» trading_name|string|true|none|The trading name of the sub-entity, also referred to as 'doing business as'.|
|» business_registration_number|number|false|none|The sub-entity's Business Registration Number. This can be a Commercial Registration or Ministry of Commerce certificate number, or any other equivalent registration number.|
|» principal_address|object|true|none|The primary location of the company where business is performed.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» registered_address|object|true|none|The registered address of the company.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» representatives|[object]|true|none|Information about representatives of this company.|
|»» Representative|object|false|none|Information about representatives of this company.|
|»»» id|number|false|none|The representative's id.|
|»»» first_name|string|true|none|The representative's first name.|
|»»» middle_name|string|false|none|The representative's middle name. Required if appears in official docs|
|»»» last_name|string|true|none|The representative's last name.|
|»»» documents|object|false|none|A legal document used to verify identity|
|»»»» identity_verification|object|true|none|The document to use to confirm the individual's identity.|
|»»»»» type|string|true|none|The type of document used for identity verification|
|»»»»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|»»»»» back|string|false|none|The ID of the back side of the document as represented within Checkout.com systems.|
|»»» date_of_birth|object|false|none|The date of birth of the person according to the Gregorian calendar.|
|»»»» day|integer|true|none|The calendar day of the month they were born.|
|»»»» month|integer|true|none|The month of the year they were born.|
|»»»» year|integer|true|none|The year they were born.|
|»»» phone|object|false|none|The phone number of the sub-entity.|
|»»»» number|any|true|none|The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)|
|»»» address|object|true|none|The representative's address.|
|»»»» address_line1|string|false|none|The first line of the address.|
|»»»» address_line2|number|false|none|The second line of the address.|
|»»»» city|string|false|none|The address city.|
|»»»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»»»» zip|string|false|none|The address zip/postal code.|
|»»»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|»»» roles|[string]|true|none|The individual's roles within the company|
|»»»» Representative Role|string|false|none|The representative's roles within the company|
|documents|object|false|none|none|
|» company_verification|object|false|none|Certified by a power of attorney within the last 3 months|
|»» type|string|true|none|The type of document used for company verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|passport|
|type|national_identity_card|
|type|driving_license|
|type|citizen_card|
|type|residence_permit|
|type|electoral_id|
|Representative Role|ubo|
|Representative Role|authorised_signatory|
|type|incorporation_document|
GBSoleTraderFull2-0
```json
{
"reference": "string",
"status": "string",
"is_draft": true,
"profile": {
"urls": [
"http://example.com"
],
"mccs": [
"string"
],
"default_holding_currency": null,
"holding_currencies": [
"GBP"
]
},
"contact_details": {
"phone": {
"number": 10000000
},
"email_addresses": {
"primary": null
},
"invitee": {
"email": null
}
},
"capabilities": {},
"requirements_due": [
{
"field": "string",
"reason": "string"
}
],
"instruments": [
{}
],
"individual": {
"trading_name": "string",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"date_of_birth": {
"day": 1,
"month": 1,
"year": 1900
},
"registered_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
}
},
"documents": {
"identity_verification": {
"type": "passport",
"front": "stringstringstringstringstrings",
"back": "stringstringstringstringstrings"
}
}
}
```
GB Sole Trader - Full (2.0)
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|true|none|A unique reference you can later use to identify the sub-entity.|
|status|string|false|read-only|none|
|is_draft|boolean|false|write-only|Specifies whether the sub-entity details are in draft.
Marking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.|
|profile|object|true|none|Information about the profile of the sub-entity, primarily regarding the products/services offered.|
|» urls|[string]|true|none|A collection of website URLs the sub-entity accepts payments on.|
|»» Company website URL|string(uri)|false|none|The URL of the company's website.|
|» mccs|[any]|true|none|Select the categories that most closely describe the business|
|»» Merchant category code|number|false|none|The merchant category code (4-digit ISO 18245).|
|» default_holding_currency|any|false|none|The default holding currency code (iso-4217)|
|» holding_currencies|array|false|none|Incoming funds are held in your selected currencies|
|»» Currency|string|false|none|The currency code (iso-4217)|
|contact_details|object|true|none|Contact details of this sub-entity.|
|» phone|object|true|none|The phone number of the sub-entity.|
|»» number|any|true|none|The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)|
|» email_addresses|object|true|none|Email addresses for this sub-entity.|
|»» primary|any|true|none|The main email address for this sub-entity.|
|» invitee|object|false|none|The details of the user responsible for onboarding the sub-entity.|
|»» email|any|false|none|The main email address for this sub-entity.|
|capabilities|object|false|read-only|The capabilities of the entity.|
|requirements_due|[object]|false|read-only|List of requirements due in order to be onboarded.|
|» Requirements due entry|object|false|read-only|A list of fields which require attention|
|»» field|string|false|none|The field that is needs to be addressed.|
|»» reason|string|false|none|The reason behind the field needing attention.|
|instruments|[object]|false|read-only|none|
|individual|object|true|none|Information about the individual represented by the sub-entity.|
|» trading_name|string|true|none|The trading name of the sub-entity, also referred to as 'doing business as'.|
|» first_name|string|true|none|The representative's first name.|
|» middle_name|string|false|none|The representative's middle name. Required if appears in official docs|
|» last_name|string|true|none|The representative's last name.|
|» date_of_birth|object|true|none|The date of birth of the person according to the Gregorian calendar.|
|»» day|integer|true|none|The calendar day of the month they were born.|
|»» month|integer|true|none|The month of the year they were born.|
|»» year|integer|true|none|The year they were born.|
|» registered_address|object|true|none|The registered address of the company.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|documents|object|false|none|A legal document used to verify identity.|
|» identity_verification|object|true|none|The document to use to confirm the individual's identity.|
|»» type|string|true|none|The type of document used for identity verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|»» back|string|false|none|The ID of the back side of the document as represented within Checkout.com systems.|
#### Enumerated Values
|Property|Value|
|---|---|
|Currency|AED|
|Currency|AUD|
|Currency|CAD|
|Currency|CHF|
|Currency|CZK|
|Currency|DKK|
|Currency|EUR|
|Currency|GBP|
|Currency|HKD|
|Currency|JPY|
|Currency|KWD|
|Currency|NOK|
|Currency|NZD|
|Currency|PLN|
|Currency|RON|
|Currency|SEK|
|Currency|SGD|
|Currency|USD|
|Currency|ZAR|
|type|passport|
|type|national_identity_card|
|type|driving_license|
|type|citizen_card|
|type|residence_permit|
|type|electoral_id|
GBSoleTraderFull3-0
```json
{
"reference": "string",
"status": "string",
"is_draft": true,
"profile": {
"urls": [
"http://example.com"
],
"mccs": [
"string"
],
"default_holding_currency": null,
"holding_currencies": [
"GBP"
]
},
"contact_details": {
"phone": {
"country_code": "GI",
"number": "strings"
},
"email_addresses": {
"primary": null
},
"invitee": {
"email": null
}
},
"capabilities": {},
"requirements_due": [
{
"field": "string",
"reason": "string",
"message": "string"
}
],
"company": {
"trading_name": "string",
"date_of_incorporation": {
"day": 1,
"month": 1,
"year": 1500
},
"principal_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
},
"representatives": [
{
"id": "stringstringstringstringstring",
"individual": {
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"date_of_birth": {
"day": 1,
"month": 1,
"year": 1900
},
"place_of_birth": {
"country": "st"
},
"national_id_number": "stringstr",
"email_address": null,
"phone": {
"country_code": "AF",
"number": "string"
},
"address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
}
},
"roles": [
"ubo"
],
"documents": {
"identity_verification": {
"type": "passport",
"front": "stringstringstringstringstrings",
"back": "stringstringstringstringstrings"
}
}
}
],
"business_type": "individual_or_sole_proprietorship"
},
"processing_details": {
"settlement_country": "st",
"target_countries": [
"st"
],
"annual_processing_volume": 0,
"average_transaction_value": 0,
"highest_transaction_value": 0,
"currency": "GBP"
},
"documents": {
"bank_verification": {
"type": "bank_statement",
"front": "stringstringstringstringstrings"
},
"additional_document1": {
"front": "stringstringstringstringstrings"
},
"additional_document2": {
"front": "stringstringstringstringstrings"
},
"additional_document3": {
"front": "stringstringstringstringstrings"
}
}
}
```
GB Sole Trader - Full (3.0)
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|true|none|A unique reference you can later use to identify the sub-entity.|
|status|string|false|read-only|none|
|is_draft|boolean|false|write-only|Specifies whether the sub-entity details are in draft.
Marking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.|
|profile|object|true|none|Information about the profile of the sub-entity, primarily regarding the products/services offered.|
|» urls|[string]|true|none|A collection of website URLs the sub-entity accepts payments on.|
|»» Company website URL|string(uri)|false|none|The URL of the company's website.|
|» mccs|[any]|true|none|Select the categories that most closely describe the business|
|»» Merchant category code|number|false|none|The merchant category code (4-digit ISO 18245).|
|» default_holding_currency|any|true|none|The default holding currency code (iso-4217)|
|» holding_currencies|[string]|true|none|Incoming funds are held in your selected currencies|
|»» Currency|string|false|none|The currency code (iso-4217)|
|contact_details|object|true|none|Contact details of this sub-entity.|
|» phone|object|false|none|Phone number|
|»» country_code|string|true|none|The country code (iso-3166-1 alpha-2) where the phone number is registered|
|»» number|string|true|none|The phone number without the country calling code|
|» email_addresses|object|false|none|Email addresses for this sub-entity.|
|»» primary|any|true|none|The main email address for this sub-entity.|
|» invitee|object|false|none|The details of the user responsible for onboarding the sub-entity.|
|»» email|any|false|none|The main email address for this sub-entity.|
|capabilities|object|false|read-only|The capabilities of the entity.|
|requirements_due|[object]|false|read-only|List of requirements due in order to be onboarded.|
|» Requirements due entry|object|false|read-only|A list of fields which require attention|
|»» field|string|false|none|The field that is needs to be addressed.|
|»» reason|string|false|none|The reason behind the field needing attention.|
|»» message|string|false|none|A more descriptive message.|
|company|object|true|none|Information about the sole trader's business.|
|» trading_name|string|true|none|The trading name of the sub-entity, also referred to as 'doing business as'.|
|» date_of_incorporation|object|true|none|The date the company was incorporated.|
|»» day|integer|false|none|The day of the month the company was incorporated.|
|»» month|integer|true|none|The month the company was incorporated.|
|»» year|integer|true|none|The year the company was incorporated.|
|» principal_address|object|true|none|The primary location where business is performed.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» representatives|[object]|true|none|Information about representatives of this company.|
|»» Person of Interest|object|false|none|Personal information about the individual representing the sub-entity.|
|»»» id|number|false|none|The representative's id.|
|»»» individual|object|true|none|Information about the individual representing the sub-entity.|
|»»»» first_name|string|true|none|The representative's first name.|
|»»»» middle_name|string|false|none|The representative's middle name. Required if appears in official docs|
|»»»» last_name|string|true|none|The representative's last name.|
|»»»» date_of_birth|object|true|none|The date of birth of the person according to the Gregorian calendar.|
|»»»»» day|integer|true|none|The calendar day of the month they were born.|
|»»»»» month|integer|true|none|The month of the year they were born.|
|»»»»» year|integer|true|none|The year they were born.|
|»»»» place_of_birth|object|true|none|The place of birth of the person.|
|»»»»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|»»»» national_id_number|number|false|none|Social security number (SSN) or Individual Taxpayer Identification Number (ITIN) for non-US citizens|
|»»»» email_address|any|false|none|The representative's personal email address.|
|»»»» phone|object|false|none|Phone number|
|»»»»» country_code|string|true|none|The country code (iso-3166-1 alpha-2) where the phone number is registered|
|»»»»» number|string|true|none|The phone number without the country calling code|
|»»»» address|object|true|none|The representative's address.|
|»»»»» address_line1|string|true|none|The first line of the address.|
|»»»»» address_line2|number|false|none|The second line of the address.|
|»»»»» city|string|true|none|The address city.|
|»»»»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»»»»» zip|string|true|none|The address zip/postal code.|
|»»»»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|»»» roles|[string]|true|none|The individual's roles within the company|
|»»»» Representative Role|string|false|none|The representative's role|
|»»» documents|object|true|none|Verification documents for the individual representative|
|»»»» identity_verification|object|true|none|The document to use to confirm the individual's identity.|
|»»»»» type|string|true|none|The type of document used for identity verification|
|»»»»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|»»»»» back|string|false|none|The ID of the back side of the document as represented within Checkout.com systems.|
|» business_type|string|true|none|The legal type of the company|
|processing_details|object|true|none|Seller processing details.|
|» settlement_country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2) where the settlement bank account is located|
|» target_countries|[string]|true|none|Target country codes (iso-3166-1 alpha-2) with more than 10% expected volume processing with Checkout|
|»» Country|string(iso-3166-1-alpha-2)|false|none|The country code (iso-3166-1 alpha-2)|
|» annual_processing_volume|integer|true|none|The estimated annual processing volume. In minor units without decimals.|
|» average_transaction_value|integer|true|none|The expected average transaction value. In minor units without decimals.|
|» highest_transaction_value|integer|true|none|The expected highest transaction value. In minor units without decimals.|
|» currency|string|true|none|The currency used for the processing details provided.|
|documents|object|true|none|The documents used to support the verification of business details.|
|» bank_verification|object|true|none|A document showing transactions from last 3 months|
|»» type|string|true|none|The type of document being used as bank verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» additional_document1|object|false|none|Additional space for documents to be provided when requested|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» additional_document2|object|false|none|Additional space for documents to be provided when requested|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» additional_document3|object|false|none|Additional space for documents to be provided when requested|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
#### Enumerated Values
|Property|Value|
|---|---|
|Currency|AED|
|Currency|AUD|
|Currency|CAD|
|Currency|CHF|
|Currency|CZK|
|Currency|DKK|
|Currency|EUR|
|Currency|GBP|
|Currency|HKD|
|Currency|JPY|
|Currency|KWD|
|Currency|NOK|
|Currency|NZD|
|Currency|PLN|
|Currency|RON|
|Currency|SEK|
|Currency|SGD|
|Currency|USD|
|Currency|ZAR|
|country_code|GI|
|country_code|CH|
|country_code|GG|
|country_code|IM|
|country_code|JE|
|country_code|GB|
|country_code|AF|
|country_code|AL|
|country_code|DZ|
|country_code|AS|
|country_code|AD|
|country_code|AO|
|country_code|AI|
|country_code|AG|
|country_code|AR|
|country_code|AM|
|country_code|AW|
|country_code|AU|
|country_code|AT|
|country_code|AZ|
|country_code|BS|
|country_code|BH|
|country_code|BD|
|country_code|BB|
|country_code|BY|
|country_code|BE|
|country_code|BZ|
|country_code|BJ|
|country_code|BM|
|country_code|BT|
|country_code|BO|
|country_code|BA|
|country_code|BW|
|country_code|BR|
|country_code|BN|
|country_code|BG|
|country_code|BF|
|country_code|BI|
|country_code|CV|
|country_code|KH|
|country_code|CM|
|country_code|CA|
|country_code|KY|
|country_code|CF|
|country_code|TD|
|country_code|CL|
|country_code|CN|
|country_code|CO|
|country_code|KM|
|country_code|CD|
|country_code|CG|
|country_code|CK|
|country_code|CR|
|country_code|HR|
|country_code|CU|
|country_code|CW|
|country_code|CY|
|country_code|CZ|
|country_code|DK|
|country_code|DJ|
|country_code|DM|
|country_code|DO|
|country_code|EC|
|country_code|EG|
|country_code|SV|
|country_code|GQ|
|country_code|ER|
|country_code|EE|
|country_code|SZ|
|country_code|ET|
|country_code|FO|
|country_code|FJ|
|country_code|FI|
|country_code|FR|
|country_code|GF|
|country_code|PF|
|country_code|GA|
|country_code|GM|
|country_code|GE|
|country_code|DE|
|country_code|GH|
|country_code|GI|
|country_code|GR|
|country_code|GL|
|country_code|GD|
|country_code|GP|
|country_code|GU|
|country_code|GT|
|country_code|GG|
|country_code|GN|
|country_code|GW|
|country_code|GY|
|country_code|HT|
|country_code|HN|
|country_code|HK|
|country_code|HU|
|country_code|IS|
|country_code|IN|
|country_code|ID|
|country_code|IR|
|country_code|IQ|
|country_code|IE|
|country_code|IM|
|country_code|IL|
|country_code|IT|
|country_code|JM|
|country_code|JP|
|country_code|JE|
|country_code|JO|
|country_code|KZ|
|country_code|KE|
|country_code|KI|
|country_code|KP|
|country_code|KR|
|country_code|KW|
|country_code|KG|
|country_code|LA|
|country_code|LV|
|country_code|LB|
|country_code|LS|
|country_code|LR|
|country_code|LY|
|country_code|LI|
|country_code|LT|
|country_code|LU|
|country_code|MO|
|country_code|MG|
|country_code|MW|
|country_code|MY|
|country_code|MV|
|country_code|ML|
|country_code|MT|
|country_code|MH|
|country_code|MQ|
|country_code|MR|
|country_code|MU|
|country_code|MX|
|country_code|FM|
|country_code|MD|
|country_code|MC|
|country_code|MN|
|country_code|ME|
|country_code|MS|
|country_code|MA|
|country_code|MZ|
|country_code|MM|
|country_code|NA|
|country_code|NR|
|country_code|NP|
|country_code|NL|
|country_code|NC|
|country_code|NZ|
|country_code|NI|
|country_code|NE|
|country_code|NG|
|country_code|NU|
|country_code|NF|
|country_code|MK|
|country_code|MP|
|country_code|NO|
|country_code|OM|
|country_code|PK|
|country_code|PW|
|country_code|PA|
|country_code|PG|
|country_code|PY|
|country_code|PE|
|country_code|PH|
|country_code|PL|
|country_code|PT|
|country_code|PR|
|country_code|QA|
|country_code|RE|
|country_code|RO|
|country_code|RU|
|country_code|RW|
|country_code|BL|
|country_code|SH|
|country_code|KN|
|country_code|LC|
|country_code|PM|
|country_code|VC|
|country_code|WS|
|country_code|SM|
|country_code|ST|
|country_code|SA|
|country_code|SN|
|country_code|RS|
|country_code|SC|
|country_code|SL|
|country_code|SG|
|country_code|BQ|
|country_code|SX|
|country_code|SK|
|country_code|SI|
|country_code|SB|
|country_code|SO|
|country_code|ZA|
|country_code|GS|
|country_code|SS|
|country_code|ES|
|country_code|LK|
|country_code|SD|
|country_code|SR|
|country_code|SE|
|country_code|CH|
|country_code|SY|
|country_code|TW|
|country_code|TJ|
|country_code|TZ|
|country_code|TH|
|country_code|TL|
|country_code|TG|
|country_code|TK|
|country_code|TO|
|country_code|TT|
|country_code|TN|
|country_code|TR|
|country_code|TM|
|country_code|TC|
|country_code|TV|
|country_code|UG|
|country_code|UA|
|country_code|AE|
|country_code|GB|
|country_code|US|
|country_code|UY|
|country_code|UZ|
|country_code|VU|
|country_code|VA|
|country_code|VE|
|country_code|VN|
|country_code|VG|
|country_code|VI|
|country_code|WF|
|country_code|EH|
|country_code|YE|
|country_code|ZM|
|country_code|ZW|
|Representative Role|ubo|
|type|passport|
|type|national_identity_card|
|type|driving_license|
|type|citizen_card|
|type|residence_permit|
|type|electoral_id|
|business_type|individual_or_sole_proprietorship|
|business_type|limited_company|
|business_type|public_limited_company|
|business_type|limited_partnership|
|business_type|general_partnership|
|business_type|scottish_limited_partnership|
|business_type|government_agency|
|business_type|non_profit_entity|
|business_type|trust|
|business_type|club_or_society|
|business_type|unincorporated_association|
|currency|GBP|
|type|bank_statement|
GBSoleTraderLite2-0
```json
{
"reference": "string",
"status": "string",
"is_draft": true,
"profile": {
"urls": [
"http://example.com"
],
"mccs": [
"string"
]
},
"contact_details": {
"phone": {
"number": 10000000
},
"email_addresses": {
"primary": null
},
"invitee": {
"email": null
}
},
"capabilities": {},
"requirements_due": [
{
"field": "string",
"reason": "string"
}
],
"instruments": [
{}
],
"documents": {
"identity_verification": {
"type": "passport",
"front": "stringstringstringstringstrings",
"back": "stringstringstringstringstrings"
}
},
"individual": {
"trading_name": "string",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"date_of_birth": {
"day": 1,
"month": 1,
"year": 1900
},
"registered_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
}
}
}
```
GB Sole Trader - Lite (2.0)
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|true|none|A unique reference you can later use to identify the sub-entity.|
|status|string|false|read-only|none|
|is_draft|boolean|false|write-only|Specifies whether the sub-entity details are in draft.
Marking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.|
|profile|object|true|none|Information about the profile of the sub-entity, primarily regarding the products/services offered.|
|» urls|[string]|true|none|A collection of website URLs the sub-entity accepts payments on.|
|»» Company website URL|string(uri)|false|none|The URL of the company's website.|
|» mccs|[any]|true|none|Select the categories that most closely describe the business|
|»» Merchant category code|number|false|none|The merchant category code (4-digit ISO 18245).|
|contact_details|object|true|none|Contact details of this sub-entity.|
|» phone|object|true|none|The phone number of the sub-entity.|
|»» number|any|true|none|The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)|
|» email_addresses|object|true|none|Email addresses for this sub-entity.|
|»» primary|any|true|none|The main email address for this sub-entity.|
|» invitee|object|false|none|The details of the user responsible for onboarding the sub-entity.|
|»» email|any|false|none|The main email address for this sub-entity.|
|capabilities|object|false|read-only|The capabilities of the entity.|
|requirements_due|[object]|false|read-only|List of requirements due in order to be onboarded.|
|» Requirements due entry|object|false|read-only|A list of fields which require attention|
|»» field|string|false|none|The field that is needs to be addressed.|
|»» reason|string|false|none|The reason behind the field needing attention.|
|instruments|[object]|false|read-only|none|
|documents|object|false|none|A legal document used to verify identity.|
|» identity_verification|object|true|none|The document to use to confirm the individual's identity.|
|»» type|string|true|none|The type of document used for identity verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|»» back|string|false|none|The ID of the back side of the document as represented within Checkout.com systems.|
|individual|object|true|none|Information about the individual represented by the sub-entity.|
|» trading_name|string|true|none|The trading name of the sub-entity, also referred to as 'doing business as'.|
|» first_name|string|true|none|The representative's first name.|
|» middle_name|string|false|none|The representative's middle name. Required if appears in official docs|
|» last_name|string|true|none|The representative's last name.|
|» date_of_birth|object|false|none|The date of birth of the person according to the Gregorian calendar.|
|»» day|integer|true|none|The calendar day of the month they were born.|
|»» month|integer|true|none|The month of the year they were born.|
|»» year|integer|true|none|The year they were born.|
|» registered_address|object|true|none|The registered address of the company.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
#### Enumerated Values
|Property|Value|
|---|---|
|type|passport|
|type|national_identity_card|
|type|driving_license|
|type|citizen_card|
|type|residence_permit|
|type|electoral_id|
GetScheduleResponse
```json
{
"GBP": {
"recurrence": {
"enabled": true,
"threshold": 100,
"payment_instrument_id": "ppi_w4jelhppmfiufdnatam37wrfc4",
"schedule": {
"frequency": "weekly",
"by_day": [
"monday"
]
}
},
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli"
}
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|GBP|object(ISO 4217)|false|none|The three-letter ISO currency code of the account's currency.|
|» recurrence|object|false|none|Information about how often the schedule takes place.|
|»» enabled|boolean|false|none|Indicates the status of the payout schedule.|
|»» threshold|number|false|none|Minimum available balance on the account to do a payout. If the balance is less than the threshold, then the payout instruction will not send.|
|»» payment_instrument_id|string|false|none|The ID of the platforms payment instrument used for payouts on this schedule.|
|»» schedule|object|false|none|Details about the payout schedule. Required if `enabled` is set to `true`.|
|»»» frequency|string|true|none|Used to indicate how often funds should be paid out to a sub-entity.|
|» _links|object|false|none|none|
|»» **additionalProperties**|[Link](#schemalink)|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|frequency|weekly|
|frequency|daily|
|frequency|monthly|
GetScheduleResponseIsv
```json
{
"GBP": {
"recurrence": {
"enabled": true,
"threshold": 100,
"balance_minimum": 500,
"carry_forward_enabled": true,
"payment_instrument_id": "ppi_w4jelhppmfiufdnatam37wrfc4",
"schedule": {
"frequency": "weekly",
"by_day": [
"monday"
]
}
},
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli"
}
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|GBP|object(ISO 4217)|false|none|The three-letter ISO currency code of the account's currency.|
|» recurrence|object|false|none|Information about how often the payout takes place.|
|»» enabled|boolean|false|none|Indicates whether the payout schedule is enabled.|
|»» threshold|number|false|none|The minimum balance, in the minor units of the schedule's currency, required for a payout to take place. If the sub-entity's available balance is below the `threshold`, Checkout.com does not send the payout instruction. Defaults to `0` if you do not set it.|
|»» balance_minimum|number¦null|false|none|The amount, in the minor units of the schedule's currency, to retain in the sub-entity's available balance. Checkout.com pays out only the funds above the `balance_minimum`, and generates no payout if there are none. Defaults to `0` if you do not set it.|
|»» carry_forward_enabled|boolean¦null|false|none|Indicates whether to carry forward any balance below the configured minimum to the next payout. Always returned for SaaS sellers, and defaults to `false` if you do not set it.|
|»» payment_instrument_id|string|false|none|The ID of the platforms payment instrument used for payouts on this schedule.|
|»» schedule|object|false|none|Details about the payout schedule. Required if `enabled` is set to `true`.|
|»»» frequency|string|true|none|Used to indicate how often funds should be paid out to a sub-entity.|
|» _links|object|false|none|none|
|»» **additionalProperties**|[Link](#schemalink)|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|frequency|weekly|
|frequency|daily|
|frequency|monthly|
```json
{
"data": [
{
"user_id": "usr_eyk754cqieqexfh6u46no5nnha"
}
],
"links": {
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli"
}
}
}
}
```
Sub-entity members response
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|data|[object]|false|none|The list of members of the sub-entity.|
|» Members|object|false|none|none|
|»» user_id|string|false|none|The unique ID used to identify a sub-entity member.|
|links|[EntityLinks](#schemaentitylinks)|false|none|none|
```json
{
"reference": "superhero1234",
"is_draft": true,
"contact_details": {
"invitee": {
"email": "admin@superhero1234.com"
}
}
}
```
Hosted Onboarding Invitation Request
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|true|none|A unique reference you can later use to identify the sub-entity.|
|is_draft|boolean|true|none|Specifies whether the sub-entity details are in draft.
Marking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.|
|contact_details|object|true|none|The contact details of the members invited to onboard the sub-entity|
|» invitee|object|true|none|The details of the user responsible for onboarding the sub-entity.|
|»» email|string(email)|true|none|The email of the user responsible for onboarding the sub-entity.|
```json
{}
```
Reinvite sub-entity member
### Properties
*None*
```json
{}
```
Reinvite sub-entity member
### Properties
*None*
```json
{
"account_number": "12345100",
"routing_number": "026009593",
"account_type": "savings"
}
```
InstrumentDetailsAch
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|account_number|string|true|none|The alphanumeric value that identifies the account.|
|routing_number|string|true|none|The 9-digit American Bankers Association (ABA) routing number that identifies the financial institution.|
|account_type|string|true|none|The type of bank account.|
#### Enumerated Values
|Property|Value|
|---|---|
|account_type|savings|
|account_type|checking|
```json
{
"account_number": "13654567455",
"bank_code": "123-456"
}
```
InstrumentDetailsFasterPayments
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|account_number|string|true|none|The alphanumeric value that identifies the account|
|bank_code|string|true|none|The code that identifies the bank|
```json
{
"iban": "HU93116000060000000012345676",
"swift_bic": "37040044"
}
```
InstrumentDetailsSepa
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|iban|string|true|none|The account's International Bank Account Number (IBAN)|
|swift_bic|string(ISO 9362:2009)|true|none|An 8 or 11 character code that identifies the bank or bank branch|
```json
{
"label": "Peter's Personal Account",
"type": "bank_account",
"currency": "GBP",
"country": "GB",
"default": true,
"document": {
"type": "bank_statement",
"file_id": "file_wxglze3wwywujg4nna5fb7ldli"
},
"instrument_details": {
"account_number": "13654567455",
"bank_code": "123-456"
}
}
```
PaymentInstrumentBankAccount
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PlatformsPaymentInstrument](#schemaplatformspaymentinstrument)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» country|string(ISO 3166-1)|true|none|The account's country, as a two-letter ISO country code|
|» default|boolean|false|none|For ad-hoc payouts, the payment instrument is explicitly specified in the payout request.
For scheduled payouts, the first payment instrument created for a given currency will be used for that currency's payout schedule.
To change the payment instrument associated with a payout schedule, update the payout schedule.
(Deprecated) Specifies whether the payment instrument should be set as the default payout destination.|
|» document|object|true|none|A legal document used to verify the bank account|
|»» type|string|false|none|The document type|
|»» file_id|string|false|none|The file ID of the uploaded document. The document must have been uploaded for the purpose of `"bank_verification"`.|
|» instrument_details|any|true|none|Details of the payment instrument being created.|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»» *anonymous*|[PlatformsInstrumentDetailsFasterPayments](#schemaplatformsinstrumentdetailsfasterpayments)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»» *anonymous*|[PlatformsInstrumentDetailsSepa](#schemaplatformsinstrumentdetailssepa)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»» *anonymous*|[PlatformsInstrumentDetailsAch](#schemaplatformsinstrumentdetailsach)|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|type|bank_statement|
```json
{
"label": "Peter's Personal Account",
"type": "bank_account",
"currency": "GBP",
"instrument_details": {
"token": "tok_4gzeau5o2uqubbk6fufs3m7p54"
}
}
```
card_token
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|card_token|any|false|none|Card Token Request|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PlatformsPaymentInstrument](#schemaplatformspaymentinstrument)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» instrument_details|object|true|none|Details of the payment instrument being created|
|»» token|string|false|none|The token that identifies the card|
```json
{
"label": "Peter's Personal Account",
"type": "bank_account",
"currency": "GBP"
}
```
PaymentInstrumentBase
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|label|string|true|none|A reference that you can use to identify the payment instrument|
|type|string|true|none|The instrument type|
|currency|string(ISO 4217)|true|none|The account's currency, as a 3-letter ISO currency code|
#### Enumerated Values
|Property|Value|
|---|---|
|type|bank_account|
|type|card_token|
```json
{
"type": "bank_account",
"label": "Peter's Personal Account",
"currency": "GBP",
"instrument_details": {}
}
```
PaymentInstrumentCreateRequest
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of instrument|
|label|string|true|none|A reference that you can use to identify the payment instrument|
|currency|string|true|none|The three-letter ISO currency code of the account's currency.|
|instrument_details|object|true|none|Details of the payment instrument being created|
```json
{
"data": [
{
"id": "ppi_qn4nis4k3ykpzzu7cvtuvhqqga",
"status": "verified",
"instrument_id": "src_wmlfc3zyhqzehihu7giusaaawu",
"label": "Peter's Personal Account",
"type": "bank_account",
"currency": "GBP",
"_links": {
"property1": {
"href": "string"
},
"property2": {
"href": "string"
}
}
}
],
"_links": {
"property1": {
"href": "string"
},
"property2": {
"href": "string"
}
}
}
```
PaymentInstrumentQueryResponse
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|data|[[PlatformsPaymentInstrumentRead](#schemaplatformspaymentinstrumentread)]|false|none|none|
|_links|object|false|none|none|
|» **additionalProperties**|[Link](#schemalink)|false|none|none|
```json
{
"id": "ppi_qn4nis4k3ykpzzu7cvtuvhqqga",
"status": "verified",
"instrument_id": "src_wmlfc3zyhqzehihu7giusaaawu",
"label": "Peter's Personal Account",
"type": "bank_account",
"currency": "GBP",
"_links": {
"property1": {
"href": "string"
},
"property2": {
"href": "string"
}
}
}
```
PaymentInstrumentReadResponse
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» id|string|false|none|The ID of the sub-entity's payment instrument.|
|» status|[PlatformsPaymentInstrumentStatus](#schemaplatformspaymentinstrumentstatus)|false|none|The status of your sub-entity's payment instrument. The status indicates the instrument's stage of verification, and whether it can be used for payouts.|
|» instrument_id|string|false|none|The payment instrument's ID. Only available once the instrument status is `verified`.|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PlatformsPaymentInstrument](#schemaplatformspaymentinstrument)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» _links|object|false|none|none|
|»» **additionalProperties**|[Link](#schemalink)|false|none|none|
```json
"verified"
```
Status
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|Status|string|false|none|The status of your sub-entity's payment instrument. The status indicates the instrument's stage of verification, and whether it can be used for payouts.|
#### Enumerated Values
|Property|Value|
|---|---|
|Status|pending|
|Status|verified|
|Status|unverified|
```json
{
"label": "Peter's Personal Account",
"default": true,
"headers": {
"if-match": "Y3Y9MCZydj0w"
}
}
```
PaymentInstrumentUpdateRequest
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|label|string|false|none|A reference that you can use to identify the payment instrument.|
|default|boolean|false|none|For ad-hoc payouts, the payment instrument is explicitly specified in the payout request.
For scheduled payouts, the first payment instrument created for a given currency will be used for that currency's payout schedule.
To change the payment instrument associated with a payout schedule, update the payout schedule.
(Deprecated) Specifies whether the payment instrument should be set as the default payout destination.|
|headers|object|false|none|none|
|» if-match|string|true|none|The payment instrument ETag value|
```json
{
"id": "file_6lbss42ezvoufcb2beo76rvwly",
"status": "invalid",
"status_reasons": [
"InvalidMimeType"
],
"size": 1024,
"mime_type": "application/pdf",
"uploaded_on": "2020-12-01T15:01:01Z",
"purpose": "identity_verification",
"_links": {
"download": {
"href": "https://s3.eu-west-1.amazonaws.com/mp-files-api-clean-prod/ent_ociwguf5a5fe3ndmpnvpnwsi3e/file_6lbss42ezvoufcb2beo76rvwly?X-Amz-Expires=3600&x-amz-security-token=some_token"
},
"self": {
"href": "https://files.checkout.com/files/file_6lbss42ezvoufcb2beo76rvwly"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The ID of the file.|
|status|string|false|none|The current status of the file.|
|status_reasons|[string]|false|none|If `status` is `Invalid`, returns the reasons why the file was invalid. If `status` is any other value, returns `Null`.|
|size|number|false|none|The size of the file in KB.|
|mime_type|string|false|none|The MIME type of the file.|
|uploaded_on|string(date-time)|false|none|The date and time the file was uploaded, in ISO 8601 UTC format.|
|purpose|string|false|none|The purpose of the file, as provided in the initial request.|
|_links|object|false|none|none|
|» **additionalProperties**|[Link](#schemalink)|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|purpose|identity_verification|
|purpose|dispute_evidence|
|purpose|bank_verification|
|purpose|company_verification|
|purpose|financial_verification|
|purpose|tax_verification|
```json
{
"purpose": "identity_verification"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|purpose|string|true|none|The purpose of the file upload.|
#### Enumerated Values
|Property|Value|
|---|---|
|purpose|additional_document|
|purpose|articles_of_association|
|purpose|bank_verification|
|purpose|certified_authorised_signatory|
|purpose|company_ownership|
|purpose|company_verification|
|purpose|financial_verification|
|purpose|identity_verification|
|purpose|proof_of_legality|
|purpose|proof_of_principal_address|
|purpose|shareholder_structure|
|purpose|tax_verification|
|purpose|proof_of_residential_address|
|purpose|proof_of_registration|
```json
{
"id": "file_6lbss42ezvoufcb2beo76rvwly",
"maximum_size_in_bytes": 4194304,
"document_types_for_purpose": [
"image/jpeg",
"image/png",
"image/jpg"
],
"_links": {
"upload": {
"href": "https://s3.eu-west-1.amazonaws.com/mp-files-api-staging-prod/ent_ociwguf5a5fe3ndmpnvpnwsi3e/file_6lbss42ezvoufcb2beo76rvwly?AWSAccessKeyId=ASIX4BFJOBCQFLAMPKU3&Expires=1661355993&x-amz-security-token=some_token"
},
"self": {
"href": "https://files.checkout.com/files/file_6lbss42ezvoufcb2beo76rvwly"
}
}
}
```
File uploaded successfully.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The file identifier.|
|maximum_size_in_bytes|number|false|none|The maximum file size allowed, in bytes.|
|document_types_for_purpose|[string]|false|none|The MIME file types allowed for the document purpose, provided on the initial file upload request.|
|_links|object|false|none|none|
|» upload|object|false|none|Send a data-binary type request to this URL with your file attached. For example:
```
curl --location --request PUT 'https://s3.eu-west-1.amazonaws.com/mp-files-api-staging-prod/ent_ociwguf5a5fe3ndmpnvpnwsi3e/file_6lbss42ezvoufcb2beo76rvwly?AWSAccessKeyId=ASIX4BFJOBCQFLAMPKU3&Expires=1661355993&x-amz-security-token=some_token'
--data-binary '@/C:/Users/Test/test.pdf'
```|
|»» href|string|false|none|none|
|» self|object|false|none|The file information retrieval URL.|
|»» href|string|false|none|none|
ReserveRuleCreateRequest
```json
{
"type": "rolling",
"rolling": {
"percentage": 10,
"holding_duration": {
"weeks": 2
}
},
"valid_from": "2019-08-24T14:15:22Z"
}
```
ReserveRuleCreateRequest
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[ReserveRuleUpdateRequest](#schemareserveruleupdaterequest)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» valid_from|string(date-time)|true|none|The date and time the reserve rule will come into effect. This must be at least 15 minutes in the future.|
ReserveRuleId
```json
"rsv_qn4nis4k3ykpzzu7cvtuvhqqga"
```
ReserveRuleId
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|ReserveRuleId|string|false|none|none|
ReserveRuleQueryResponse
```json
{
"data": [
{
"type": "rolling",
"rolling": {
"percentage": 10,
"holding_duration": {
"weeks": 2
}
},
"valid_from": "2019-08-24T14:15:22Z",
"id": "rsv_qn4nis4k3ykpzzu7cvtuvhqqga",
"_links": {
"property1": {
"href": "string"
},
"property2": {
"href": "string"
}
}
}
],
"_links": {
"property1": {
"href": "string"
},
"property2": {
"href": "string"
}
}
}
```
ReserveRuleQueryResponse
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|data|[[ReserveRuleReadResponse](#schemareserverulereadresponse)]|false|none|none|
|_links|object|false|none|none|
|» **additionalProperties**|[Link](#schemalink)|false|none|none|
ReserveRuleReadResponse
```json
{
"type": "rolling",
"rolling": {
"percentage": 10,
"holding_duration": {
"weeks": 2
}
},
"valid_from": "2019-08-24T14:15:22Z",
"id": "rsv_qn4nis4k3ykpzzu7cvtuvhqqga",
"_links": {
"property1": {
"href": "string"
},
"property2": {
"href": "string"
}
}
}
```
ReserveRuleReadResponse
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[ReserveRuleCreateRequest](#schemareserverulecreaterequest)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» id|[ReserveRuleId](#schemareserveruleid)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» _links|object|false|none|none|
|»» **additionalProperties**|[Link](#schemalink)|false|none|none|
ReserveRuleUpdateRequest
```json
{
"type": "rolling",
"rolling": {
"percentage": 10,
"holding_duration": {
"weeks": 2
}
}
}
```
ReserveRuleUpdateRequest
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|none|
|rolling|[RollingReserveRule](#schemarollingreserverule)|true|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|type|rolling|
ReserveRuleWriteResponse
```json
{
"id": "rsv_qn4nis4k3ykpzzu7cvtuvhqqga",
"_links": {
"self": {
"href": "string"
}
}
}
```
ReserveRuleWriteResponse
### Properties
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» id|[ReserveRuleId](#schemareserveruleid)|false|none|none|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» _links|object|false|none|none|
|»» self|[Link](#schemalink)|false|none|none|
RollingReserveRule
```json
{
"percentage": 10,
"holding_duration": {
"weeks": 2
}
}
```
RollingReserveRule
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|percentage|number|true|none|The percentage of captured funds that will be reserved as a collateral balance.|
|holding_duration|object|true|none|The length of time the collateral balance will be reserved for.|
|» weeks|integer|true|none|none|
ScheduleFrequencyDaily
```json
{
"frequency": "string"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|frequency|string|false|none|Used to indicate how often funds should be paid out to a sub-entity.|
ScheduleFrequencyDailyIsv
```json
{
"frequency": "string"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|frequency|string|false|none|Used to indicate how often funds should be paid out to a sub-entity. For SaaS sellers, a daily schedule runs on working days only (Monday to Friday). Payouts do not take place on weekends. The payout is based on the sub-entity's available balance as of 00:00 in the sub-entity's time zone.|
ScheduleFrequencyMonthly
```json
{
"frequency": "string",
"by_month_day": [
2
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|frequency|string|false|none|Used to indicate how often funds should be paid out to a sub-entity.|
|by_month_day|[integer]|true|none|The day or days of the month the payout should take place.|
ScheduleFrequencyMonthlyIsv
```json
{
"frequency": "string",
"by_month_day": [
1,
15
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|frequency|string|false|none|Used to indicate how often funds should be paid out to a sub-entity. For SaaS sellers, the payout is based on the sub-entity's available balance as of 00:00 in the sub-entity's time zone.|
|by_month_day|[integer]|true|none|The day or days of the month the payout should take place. For SaaS sellers, only the following combinations are supported, in any order: `[1]`, `[15]`, `[1, 15]`, or `[1, 16]`.|
#### Enumerated Values
|Property|Value|
|---|---|
|by_month_day|[1]|
|by_month_day|[15]|
|by_month_day|[1,15]|
|by_month_day|[15,1]|
|by_month_day|[1,16]|
|by_month_day|[16,1]|
ScheduleFrequencyWeekly
```json
{
"frequency": "string",
"by_day": [
"monday"
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|frequency|string|false|none|Used to indicate how often funds should be paid out to a sub-entity.|
|by_day|[string]|true|none|The day or days of the week the payout should take place.|
ScheduleFrequencyWeeklyIsv
```json
{
"frequency": "string",
"by_day": [
"monday"
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|frequency|string|false|none|Used to indicate how often funds should be paid out to a sub-entity. For SaaS sellers, the payout is based on the sub-entity's available balance as of 00:00 in the sub-entity's time zone.|
|by_day|[string]|true|none|The day or days of the week the payout should take place. For SaaS sellers, only working days (Monday to Friday) are supported. Payouts set to take place on weekends are rejected.|
UpdateScheduleRequest
```json
{
"ISO": {
"enabled": true,
"threshold": 100,
"payment_instrument_id": "ppi_w4jelhppmfiufdnatam37wrfc4",
"recurrence": {
"frequency": "weekly",
"by_day": [
"monday"
]
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|ISO|object(ISO 4217)|false|none|The three-letter ISO currency code of the account's currency.|
|» enabled|boolean|false|none|Indicates the status of the payout schedule.|
|» threshold|number|false|none|Minimum available balance on the account to do a payout. If the balance is less than the threshold, then the payout instruction will not send.|
|» payment_instrument_id|string|false|none|The ID of the platforms payment instrument used for payouts on this schedule.|
|» recurrence|object|false|none|Information about how often the schedule takes place.|
|»» frequency|string|true|none|none|
UpdateScheduleRequestIsv
```json
{
"ISO": {
"enabled": true,
"threshold": 100,
"balance_minimum": 500,
"carry_forward_enabled": true,
"payment_instrument_id": "ppi_w4jelhppmfiufdnatam37wrfc4",
"recurrence": {
"frequency": "weekly",
"by_day": [
"monday"
]
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|ISO|object(ISO 4217)|false|none|The three-letter ISO currency code of the account's currency.|
|» enabled|boolean|true|none|Indicates whether the payout schedule is enabled.|
|» threshold|number|false|none|The minimum balance, in the minor units of the schedule's currency, required for a payout to take place. If the sub-entity's available balance is below the `threshold`, Checkout.com does not send the payout instruction. Defaults to `0` if you do not set it.|
|» balance_minimum|number¦null|false|none|The amount, in the minor units of the schedule's currency, to retain in the sub-entity's available balance. Checkout.com pays out only the funds above the `balance_minimum`, and generates no payout otherwise. Defaults to `0` if you do not set it.|
|» carry_forward_enabled|boolean¦null|false|none|Indicates whether to carry forward any balance below the configured minimum to the next payout. Defaults to `false` if you do not set it.|
|» payment_instrument_id|string|false|none|The ID of the platforms payment instrument used as the payout destination. Optional for SaaS sellers. If included, it must reference a verified payment instrument, otherwise the request fails.|
|» recurrence|object|true|none|Information about how often the schedule takes place.|
|»» frequency|string|true|none|none|
USCompanyFull2-0
```json
{
"reference": "string",
"status": "string",
"is_draft": true,
"profile": {
"urls": [
"http://example.com"
],
"mccs": [
"string"
],
"default_holding_currency": null,
"holding_currencies": [
"USD"
]
},
"contact_details": {
"phone": {
"number": 2000000000
},
"email_addresses": {
"primary": null
},
"invitee": {
"email": null
}
},
"capabilities": {},
"requirements_due": [
{
"field": "string",
"reason": "string"
}
],
"instruments": [
{}
],
"company": {
"legal_name": "string",
"trading_name": "string",
"business_registration_number": "stringstr",
"principal_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "AL",
"zip": "string",
"country": "st"
},
"registered_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "AL",
"zip": "string",
"country": "st"
},
"representatives": [
{
"id": "stringstringstringstringstring",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"identification": {
"national_id_number": "stringstr"
},
"date_of_birth": {
"day": 1,
"month": 1,
"year": 1900
},
"phone": {
"number": 10000000
},
"address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
},
"documents": {
"identity_verification": {
"type": "passport",
"front": "stringstringstringstringstrings",
"back": "stringstringstringstringstrings"
}
},
"roles": [
"ubo"
]
}
],
"business_type": "private_corporation",
"financial_details": {
"annual_processing_volume": 0,
"average_transaction_value": 0,
"highest_transaction_value": 0,
"currency": "USD"
},
"date_of_incorporation": {
"day": 1,
"month": 1,
"year": 1500
}
},
"documents": {
"company_verification": {
"type": "incorporation_document",
"front": "stringstringstringstringstrings"
},
"tax_verification": {
"type": "ein_letter",
"front": "stringstringstringstringstrings"
}
}
}
```
US Company - Full (2.0)
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|true|none|A unique reference you can later use to identify the sub-entity.|
|status|string|false|read-only|none|
|is_draft|boolean|false|write-only|Specifies whether the sub-entity details are in draft.
Marking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.|
|profile|object|true|none|Information about the profile of the sub-entity, primarily regarding the products/services offered.|
|» urls|[string]|true|none|A collection of website URLs the sub-entity accepts payments on.|
|»» Company website URL|string(uri)|false|none|The URL of the company's website.|
|» mccs|[any]|true|none|Select the categories that most closely describe the business|
|»» Merchant category code|number|false|none|The merchant category code (4-digit ISO 18245).|
|» default_holding_currency|any|false|none|The default holding currency code (iso-4217)|
|» holding_currencies|array|false|none|Incoming funds are held in your selected currencies|
|»» Currency|string|false|none|The currency code (iso-4217)|
|contact_details|object|true|none|none|
|» phone|object|true|none|none|
|»» number|any|true|none|Include the area code|
|» email_addresses|object|true|none|none|
|»» primary|any|true|none|The main email address for this sub-entity.|
|» invitee|object|false|none|none|
|»» email|any|false|none|The main email address for this sub-entity.|
|capabilities|object|false|read-only|The capabilities of the entity.|
|requirements_due|[object]|false|read-only|List of requirements due in order to be onboarded.|
|» Requirements due entry|object|false|read-only|A list of fields which require attention|
|»» field|string|false|none|The field that is needs to be addressed.|
|»» reason|string|false|none|The reason behind the field needing attention.|
|instruments|[object]|false|read-only|none|
|company|object|true|none|Information about the company represented by the sub-entity.|
|» legal_name|string|true|none|The legal name of the sub-entity.|
|» trading_name|string|true|none|The trading name of the sub-entity, also referred to as 'doing business as'.|
|» business_registration_number|string|true|none|Employer Identification Number (EIN).|
|» principal_address|object|true|none|The primary location of the company where business is performed.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|true|none|The address state. This field is required for addresses based in the US. For US addresses, provide the state as an ISO 3166-1 code.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» registered_address|object|true|none|The registered address of the company.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|true|none|The address state. This field is required for addresses based in the US. For US addresses, provide the state as an ISO 3166-1 code.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» representatives|[object]|true|none|Information about representatives of this company.|
|»» Representative|object|false|none|Information about representatives of this company.|
|»»» id|number|false|none|The representative's id.|
|»»» first_name|string|true|none|The representative's first name.|
|»»» middle_name|string|false|none|The representative's middle name. Required if appears in official docs|
|»»» last_name|string|true|none|The representative's last name.|
|»»» identification|object|true|none|Information about representatives of this company.|
|»»»» national_id_number|number|true|none|Social security number (SSN) or Individual Taxpayer Identification Number (ITIN) for non-US citizens|
|»»» date_of_birth|object|true|none|The date of birth of the person according to the Gregorian calendar.|
|»»»» day|integer|true|none|The calendar day of the month they were born.|
|»»»» month|integer|true|none|The month of the year they were born.|
|»»»» year|integer|true|none|The year they were born.|
|»»» phone|object|false|none|The phone number of the sub-entity.|
|»»»» number|any|true|none|The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)|
|»»» address|object|true|none|The representative's address.|
|»»»» address_line1|string|true|none|The first line of the address.|
|»»»» address_line2|number|false|none|The second line of the address.|
|»»»» city|string|true|none|The address city.|
|»»»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»»»» zip|string|true|none|The address zip/postal code.|
|»»»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|»»» documents|object|false|none|A legal document used to verify identity|
|»»»» identity_verification|object|true|none|The document to use to confirm the individual's identity.|
|»»»»» type|string|true|none|The type of document used for identity verification|
|»»»»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|»»»»» back|string|false|none|The ID of the back side of the document as represented within Checkout.com systems.|
|»»» roles|[string]|true|none|The individual's roles within the company|
|»»»» Representative Role|string|false|none|The representative's roles within the company|
|» business_type|string|true|none|The legal type of the company|
|» financial_details|object|true|none|Seller financial questions and supporting documents.|
|»» annual_processing_volume|integer|true|none|The estimated annual processing volume. In minor units without decimals.|
|»» average_transaction_value|integer|true|none|The expected average transaction value. In minor units without decimals.|
|»» highest_transaction_value|integer|true|none|The expected highest transaction value. In minor units without decimals.|
|»» currency|string|true|none|The currency used for the processing details provided.|
|» date_of_incorporation|object|false|none|The date the company was incorporated.|
|»» day|integer|false|none|The day of the month the company was incorporated.|
|»» month|integer|true|none|The month the company was incorporated.|
|»» year|integer|true|none|The year the company was incorporated.|
|documents|object|false|none|The documents used to support the verification of company details.|
|» company_verification|object|false|none|The document to use to confirm the company's identity.|
|»» type|string|true|none|The type of document being used for company verification.|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» tax_verification|object|false|none|Employer Identification Number document.|
|»» type|string|true|none|The type of document used for tax verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
#### Enumerated Values
|Property|Value|
|---|---|
|Currency|USD|
|state|AL|
|state|AK|
|state|AZ|
|state|AR|
|state|CA|
|state|CO|
|state|CT|
|state|DE|
|state|DC|
|state|FL|
|state|GA|
|state|HI|
|state|ID|
|state|IL|
|state|IN|
|state|IA|
|state|KS|
|state|KY|
|state|LA|
|state|ME|
|state|MD|
|state|MA|
|state|MI|
|state|MN|
|state|MS|
|state|MO|
|state|MT|
|state|NE|
|state|NV|
|state|NH|
|state|NJ|
|state|NM|
|state|NY|
|state|NC|
|state|ND|
|state|OH|
|state|OK|
|state|OR|
|state|PA|
|state|RI|
|state|SC|
|state|SD|
|state|TN|
|state|TX|
|state|UT|
|state|VT|
|state|VA|
|state|WA|
|state|WV|
|state|WI|
|state|WY|
|state|AS|
|state|GU|
|state|MP|
|state|PR|
|state|VI|
|state|UM|
|state|AL|
|state|AK|
|state|AZ|
|state|AR|
|state|CA|
|state|CO|
|state|CT|
|state|DE|
|state|DC|
|state|FL|
|state|GA|
|state|HI|
|state|ID|
|state|IL|
|state|IN|
|state|IA|
|state|KS|
|state|KY|
|state|LA|
|state|ME|
|state|MD|
|state|MA|
|state|MI|
|state|MN|
|state|MS|
|state|MO|
|state|MT|
|state|NE|
|state|NV|
|state|NH|
|state|NJ|
|state|NM|
|state|NY|
|state|NC|
|state|ND|
|state|OH|
|state|OK|
|state|OR|
|state|PA|
|state|RI|
|state|SC|
|state|SD|
|state|TN|
|state|TX|
|state|UT|
|state|VT|
|state|VA|
|state|WA|
|state|WV|
|state|WI|
|state|WY|
|state|AS|
|state|GU|
|state|MP|
|state|PR|
|state|VI|
|state|UM|
|type|passport|
|type|national_identity_card|
|type|driving_license|
|type|citizen_card|
|type|residence_permit|
|type|electoral_id|
|Representative Role|ubo|
|Representative Role|authorised_signatory|
|Representative Role|control_person|
|business_type|private_corporation|
|business_type|publicly_traded_corporation|
|business_type|government_agency|
|business_type|individual_or_sole_proprietorship|
|business_type|limited_liability_corporation|
|business_type|limited_partnership|
|business_type|non_profit_entity|
|business_type|sec_registered_entity|
|business_type|cftc_registered_entity|
|business_type|regulated_financial_institution|
|currency|USD|
|type|incorporation_document|
|type|articles_of_association|
|type|ein_letter|
USCompanyFull3-0
```json
{
"reference": "string",
"status": "string",
"is_draft": true,
"profile": {
"urls": [
"http://example.com"
],
"mccs": [
"string"
],
"default_holding_currency": null,
"holding_currencies": [
"USD"
]
},
"contact_details": {
"phone": {
"country_code": "US",
"number": "stringstri"
},
"email_addresses": {
"primary": null
},
"invitee": {
"email": null
}
},
"capabilities": {},
"requirements_due": [
{
"field": "string",
"reason": "string",
"message": "string"
}
],
"company": {
"legal_name": "string",
"trading_name": "string",
"business_registration_number": "stringstr",
"date_of_incorporation": {
"day": 1,
"month": 1,
"year": 1500
},
"principal_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
},
"registered_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "AL",
"zip": "string",
"country": "st"
},
"representatives": [
{
"id": "stringstringstringstringstring",
"individual": {
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"date_of_birth": {
"day": 1,
"month": 1,
"year": 1900
},
"place_of_birth": {
"country": "st"
},
"national_id_number": "stringstr",
"email_address": null,
"phone": {
"country_code": "AF",
"number": "string"
},
"address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
}
},
"company_position": "ceo",
"roles": [
"ubo"
],
"ownership_percentage": 25,
"documents": {
"identity_verification": {
"type": "passport",
"front": "stringstringstringstringstrings",
"back": "stringstringstringstringstrings"
},
"certified_authorised_signatory": {
"type": "power_of_attorney",
"front": "stringstringstringstringstrings"
}
}
}
],
"business_type": "individual_or_sole_proprietorship"
},
"processing_details": {
"settlement_country": "st",
"target_countries": [
"st"
],
"annual_processing_volume": 0,
"average_transaction_value": 0,
"highest_transaction_value": 0,
"currency": "USD"
},
"documents": {
"tax_verification": {
"type": "ein_letter",
"front": "stringstringstringstringstrings"
},
"company_verification": {
"type": "incorporation_document",
"front": "stringstringstringstringstrings"
},
"articles_of_association": {
"type": "memorandum_of_association",
"front": "stringstringstringstringstrings"
},
"bank_verification": {
"type": "bank_statement",
"front": "stringstringstringstringstrings"
},
"shareholder_structure": {
"type": "certified_shareholder_structure",
"front": "stringstringstringstringstrings"
},
"proof_of_legality": {
"type": "proof_of_legality",
"front": "stringstringstringstringstrings"
},
"proof_of_principal_address": {
"type": "proof_of_address",
"front": "stringstringstringstringstrings"
},
"additional_document1": {
"front": "stringstringstringstringstrings"
},
"additional_document2": {
"front": "stringstringstringstringstrings"
},
"additional_document3": {
"front": "stringstringstringstringstrings"
}
}
}
```
US Company - Full (3.0)
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|true|none|A unique reference you can later use to identify the sub-entity.|
|status|string|false|read-only|none|
|is_draft|boolean|false|write-only|Specifies whether the sub-entity details are in draft.
Marking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.|
|profile|object|true|none|Information about the profile of the sub-entity, primarily regarding the products/services offered.|
|» urls|[string]|true|none|A collection of website URLs the sub-entity accepts payments on.|
|»» Company website URL|string(uri)|false|none|The URL of the company's website.|
|» mccs|[any]|true|none|Select the categories that most closely describe the business|
|»» Merchant category code|number|false|none|The merchant category code (4-digit ISO 18245).|
|» default_holding_currency|any|true|none|The default holding currency code (iso-4217)|
|» holding_currencies|[string]|true|none|Incoming funds are held in your selected currencies|
|»» Currency|string|false|none|The currency code (iso-4217)|
|contact_details|object|true|none|Contact details of this sub-entity.|
|» phone|object|false|none|Phone number|
|»» country_code|string|true|none|The country code (iso-3166-1 alpha-2) where the phone number is registered|
|»» number|string|true|none|The phone number without the country calling code|
|» email_addresses|object|false|none|Email addresses for this sub-entity.|
|»» primary|any|true|none|The main email address for this sub-entity.|
|» invitee|object|false|none|The details of the user responsible for onboarding the sub-entity.|
|»» email|any|false|none|The main email address for this sub-entity.|
|capabilities|object|false|read-only|The capabilities of the entity.|
|requirements_due|[object]|false|read-only|List of requirements due in order to be onboarded.|
|» Requirements due entry|object|false|read-only|A list of fields which require attention|
|»» field|string|false|none|The field that is needs to be addressed.|
|»» reason|string|false|none|The reason behind the field needing attention.|
|»» message|string|false|none|A more descriptive message.|
|company|object|true|none|Information about the company represented by the sub-entity.|
|» legal_name|string|true|none|The legal name of the sub-entity.|
|» trading_name|string|true|none|The trading name of the sub-entity, also referred to as 'doing business as'.|
|» business_registration_number|number|true|none|The sub-entity's Business Registration Number.
This can be a Commercial Registration number, a Ministry of Commerce certificate number, or an equivalent registration number.|
|» date_of_incorporation|object|true|none|The date the company was incorporated.|
|»» day|integer|false|none|The day of the month the company was incorporated.|
|»» month|integer|true|none|The month the company was incorporated.|
|»» year|integer|true|none|The year the company was incorporated.|
|» principal_address|object|true|none|The primary location of the company where business is performed.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» registered_address|object|true|none|The registered address of the company.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|true|none|The address state. This field is required for addresses based in the US. For US addresses, provide the state as an ISO 3166-1 code.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» representatives|[oneOf]|true|none|Information about representatives of this company.|
|»» Representative|object|false|none|Personal information about the individual representing the sub-entity.|
|»»» id|number|false|none|The representative's id.|
|»»» individual|object|true|none|Information about the individual representing the sub-entity.|
|»»»» first_name|string|true|none|The representative's first name.|
|»»»» middle_name|string|false|none|The representative's middle name. Required if appears in official docs|
|»»»» last_name|string|true|none|The representative's last name.|
|»»»» date_of_birth|object|true|none|The date of birth of the person according to the Gregorian calendar.|
|»»»»» day|integer|true|none|The calendar day of the month they were born.|
|»»»»» month|integer|true|none|The month of the year they were born.|
|»»»»» year|integer|true|none|The year they were born.|
|»»»» place_of_birth|object|true|none|The place of birth of the person.|
|»»»»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|»»»» national_id_number|number|false|none|Social security number (SSN) or Individual Taxpayer Identification Number (ITIN) for non-US citizens|
|»»»» email_address|any|false|none|The main email address for this sub-entity.|
|»»»» phone|object|false|none|Phone number|
|»»»»» country_code|string|true|none|The country code (iso-3166-1 alpha-2) where the phone number is registered|
|»»»»» number|string|true|none|The phone number without the country calling code|
|»»»» address|object|true|none|The representative's address.|
|»»»»» address_line1|string|true|none|The first line of the address.|
|»»»»» address_line2|number|false|none|The second line of the address.|
|»»»»» city|string|true|none|The address city.|
|»»»»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»»»»» zip|string|true|none|The address zip/postal code.|
|»»»»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|»»» company_position|string|false|none|The position of the representative within the company.|
|»»» roles|[string]|true|none|The individual's roles within the company|
|»»»» Representative Role|string|false|none|The representative's role|
|»»» ownership_percentage|integer|false|none|The percentage ownership of the UBO or controlling company (required when over 25%)|
|»»» documents|object|false|none|Verification documents for the individual representative|
|»»»» identity_verification|object|false|none|The document to use to confirm the individual's identity.|
|»»»»» type|string|true|none|The type of document used for identity verification|
|»»»»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|»»»»» back|string|false|none|The ID of the back side of the document as represented within Checkout.com systems.|
|»»»» certified_authorised_signatory|object|false|none|Required when the legal representative or other role owner is not registered on certificate of incorporation|
|»»»»» type|string|true|none|The type of document.|
|»»»»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» business_type|string|true|none|The legal type of the company|
|processing_details|object|true|none|Seller processing details.|
|» settlement_country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2) where the settlement bank account is located|
|» target_countries|[string]|true|none|Target country codes (iso-3166-1 alpha-2) with more than 10% expected volume processing with Checkout|
|»» Country|string(iso-3166-1-alpha-2)|false|none|The country code (iso-3166-1 alpha-2)|
|» annual_processing_volume|integer|true|none|The estimated annual processing volume. In minor units without decimals.|
|» average_transaction_value|integer|true|none|The expected average transaction value. In minor units without decimals.|
|» highest_transaction_value|integer|true|none|The expected highest transaction value. In minor units without decimals.|
|» currency|string|true|none|The currency used for the processing details provided.|
|documents|object|true|none|The documents used to support the verification of company details.|
|» tax_verification|object|false|none|Employer Identification Number document.|
|»» type|string|true|none|The type of document used for tax verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» company_verification|object|false|none|Certified by a power of attorney within the last 3 months|
|»» type|string|true|none|The type of document used for company verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» articles_of_association|object|false|none|Memorandum or Articles of Association document|
|»» type|string|true|none|The type of document used for company verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» bank_verification|object|false|none|A document showing transactions from last 3 months|
|»» type|string|true|none|The type of document being used as bank verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» shareholder_structure|object|false|none|Shareholder structure chart (including % of shares) certified by a competent authority individual and dated within last 3 months|
|»» type|string|true|none|The type of document.|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» proof_of_legality|object|false|none|A regulatory licence document required for the company to operate (when applicable)|
|»» type|string|true|none|The type of document used for proof of legality|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» proof_of_principal_address|object|false|none|Proof of principal place of business|
|»» type|string|true|none|The type of document being used as address verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» additional_document1|object|false|none|Additional space for documents to be provided when requested|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» additional_document2|object|false|none|Additional space for documents to be provided when requested|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» additional_document3|object|false|none|Additional space for documents to be provided when requested|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
#### Enumerated Values
|Property|Value|
|---|---|
|Currency|USD|
|country_code|US|
|state|AL|
|state|AK|
|state|AZ|
|state|AR|
|state|CA|
|state|CO|
|state|CT|
|state|DE|
|state|DC|
|state|FL|
|state|GA|
|state|HI|
|state|ID|
|state|IL|
|state|IN|
|state|IA|
|state|KS|
|state|KY|
|state|LA|
|state|ME|
|state|MD|
|state|MA|
|state|MI|
|state|MN|
|state|MS|
|state|MO|
|state|MT|
|state|NE|
|state|NV|
|state|NH|
|state|NJ|
|state|NM|
|state|NY|
|state|NC|
|state|ND|
|state|OH|
|state|OK|
|state|OR|
|state|PA|
|state|RI|
|state|SC|
|state|SD|
|state|TN|
|state|TX|
|state|UT|
|state|VT|
|state|VA|
|state|WA|
|state|WV|
|state|WI|
|state|WY|
|state|AS|
|state|GU|
|state|MP|
|state|PR|
|state|VI|
|state|UM|
|country_code|AF|
|country_code|AL|
|country_code|DZ|
|country_code|AS|
|country_code|AD|
|country_code|AO|
|country_code|AI|
|country_code|AG|
|country_code|AR|
|country_code|AM|
|country_code|AW|
|country_code|AU|
|country_code|AT|
|country_code|AZ|
|country_code|BS|
|country_code|BH|
|country_code|BD|
|country_code|BB|
|country_code|BY|
|country_code|BE|
|country_code|BZ|
|country_code|BJ|
|country_code|BM|
|country_code|BT|
|country_code|BO|
|country_code|BA|
|country_code|BW|
|country_code|BR|
|country_code|BN|
|country_code|BG|
|country_code|BF|
|country_code|BI|
|country_code|CV|
|country_code|KH|
|country_code|CM|
|country_code|CA|
|country_code|KY|
|country_code|CF|
|country_code|TD|
|country_code|CL|
|country_code|CN|
|country_code|CO|
|country_code|KM|
|country_code|CD|
|country_code|CG|
|country_code|CK|
|country_code|CR|
|country_code|HR|
|country_code|CU|
|country_code|CW|
|country_code|CY|
|country_code|CZ|
|country_code|DK|
|country_code|DJ|
|country_code|DM|
|country_code|DO|
|country_code|EC|
|country_code|EG|
|country_code|SV|
|country_code|GQ|
|country_code|ER|
|country_code|EE|
|country_code|SZ|
|country_code|ET|
|country_code|FO|
|country_code|FJ|
|country_code|FI|
|country_code|FR|
|country_code|GF|
|country_code|PF|
|country_code|GA|
|country_code|GM|
|country_code|GE|
|country_code|DE|
|country_code|GH|
|country_code|GI|
|country_code|GR|
|country_code|GL|
|country_code|GD|
|country_code|GP|
|country_code|GU|
|country_code|GT|
|country_code|GG|
|country_code|GN|
|country_code|GW|
|country_code|GY|
|country_code|HT|
|country_code|HN|
|country_code|HK|
|country_code|HU|
|country_code|IS|
|country_code|IN|
|country_code|ID|
|country_code|IR|
|country_code|IQ|
|country_code|IE|
|country_code|IM|
|country_code|IL|
|country_code|IT|
|country_code|JM|
|country_code|JP|
|country_code|JE|
|country_code|JO|
|country_code|KZ|
|country_code|KE|
|country_code|KI|
|country_code|KP|
|country_code|KR|
|country_code|KW|
|country_code|KG|
|country_code|LA|
|country_code|LV|
|country_code|LB|
|country_code|LS|
|country_code|LR|
|country_code|LY|
|country_code|LI|
|country_code|LT|
|country_code|LU|
|country_code|MO|
|country_code|MG|
|country_code|MW|
|country_code|MY|
|country_code|MV|
|country_code|ML|
|country_code|MT|
|country_code|MH|
|country_code|MQ|
|country_code|MR|
|country_code|MU|
|country_code|MX|
|country_code|FM|
|country_code|MD|
|country_code|MC|
|country_code|MN|
|country_code|ME|
|country_code|MS|
|country_code|MA|
|country_code|MZ|
|country_code|MM|
|country_code|NA|
|country_code|NR|
|country_code|NP|
|country_code|NL|
|country_code|NC|
|country_code|NZ|
|country_code|NI|
|country_code|NE|
|country_code|NG|
|country_code|NU|
|country_code|NF|
|country_code|MK|
|country_code|MP|
|country_code|NO|
|country_code|OM|
|country_code|PK|
|country_code|PW|
|country_code|PA|
|country_code|PG|
|country_code|PY|
|country_code|PE|
|country_code|PH|
|country_code|PL|
|country_code|PT|
|country_code|PR|
|country_code|QA|
|country_code|RE|
|country_code|RO|
|country_code|RU|
|country_code|RW|
|country_code|BL|
|country_code|SH|
|country_code|KN|
|country_code|LC|
|country_code|PM|
|country_code|VC|
|country_code|WS|
|country_code|SM|
|country_code|ST|
|country_code|SA|
|country_code|SN|
|country_code|RS|
|country_code|SC|
|country_code|SL|
|country_code|SG|
|country_code|BQ|
|country_code|SX|
|country_code|SK|
|country_code|SI|
|country_code|SB|
|country_code|SO|
|country_code|ZA|
|country_code|GS|
|country_code|SS|
|country_code|ES|
|country_code|LK|
|country_code|SD|
|country_code|SR|
|country_code|SE|
|country_code|CH|
|country_code|SY|
|country_code|TW|
|country_code|TJ|
|country_code|TZ|
|country_code|TH|
|country_code|TL|
|country_code|TG|
|country_code|TK|
|country_code|TO|
|country_code|TT|
|country_code|TN|
|country_code|TR|
|country_code|TM|
|country_code|TC|
|country_code|TV|
|country_code|UG|
|country_code|UA|
|country_code|AE|
|country_code|GB|
|country_code|US|
|country_code|UY|
|country_code|UZ|
|country_code|VU|
|country_code|VA|
|country_code|VE|
|country_code|VN|
|country_code|VG|
|country_code|VI|
|country_code|WF|
|country_code|EH|
|country_code|YE|
|country_code|ZM|
|country_code|ZW|
|company_position|ceo|
|company_position|cfo|
|company_position|coo|
|company_position|managing_member|
|company_position|general_partner|
|company_position|president|
|company_position|vice_president|
|company_position|treasurer|
|company_position|other_senior_management|
|company_position|other_executive_officer|
|company_position|other_non_executive_non_senior|
|Representative Role|ubo|
|Representative Role|authorised_signatory|
|Representative Role|control_person|
|type|passport|
|type|national_identity_card|
|type|driving_license|
|type|citizen_card|
|type|residence_permit|
|type|electoral_id|
|type|power_of_attorney|
|business_type|individual_or_sole_proprietorship|
|business_type|private_corporation|
|business_type|limited_liability_corporation|
|business_type|publicly_traded_corporation|
|business_type|limited_partnership|
|business_type|non_profit_entity|
|business_type|government_agency|
|business_type|regulated_financial_institution|
|business_type|sec_registered_entity|
|business_type|cftc_registered_entity|
|currency|USD|
|type|ein_letter|
|type|incorporation_document|
|type|memorandum_of_association|
|type|articles_of_association|
|type|bank_statement|
|type|certified_shareholder_structure|
|type|proof_of_legality|
|type|proof_of_address|
USCompanyLite2-0
```json
{
"reference": "string",
"status": "string",
"is_draft": true,
"profile": {
"urls": [
"http://example.com"
],
"mccs": [
"string"
]
},
"contact_details": {
"phone": {
"number": 2000000000
},
"email_addresses": {
"primary": null
},
"invitee": {
"email": null
}
},
"capabilities": {},
"requirements_due": [
{
"field": "string",
"reason": "string"
}
],
"instruments": [
{}
],
"company": {
"legal_name": "string",
"trading_name": "string",
"business_registration_number": "stringstr",
"principal_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "AL",
"zip": "string",
"country": "st"
},
"registered_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "AL",
"zip": "string",
"country": "st"
},
"representatives": [
{
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"identification": {
"national_id_number": "stringstr"
},
"date_of_birth": {
"day": 1,
"month": 1,
"year": 1900
},
"phone": {
"number": 10000000
},
"address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
},
"documents": {
"identity_verification": {
"type": "passport",
"front": "stringstringstringstringstrings",
"back": "stringstringstringstringstrings"
}
},
"roles": [
"ubo"
]
}
],
"business_type": "private_corporation",
"financial_details": {
"annual_processing_volume": 0,
"average_transaction_value": 0,
"highest_transaction_value": 0,
"currency": "USD"
}
},
"documents": {
"company_verification": {
"type": "incorporation_document",
"front": "stringstringstringstringstrings"
},
"tax_verification": {
"type": "ein_letter",
"front": "stringstringstringstringstrings"
}
}
}
```
US Company - Lite (2.0)
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|true|none|A unique reference you can later use to identify the sub-entity.|
|status|string|false|read-only|none|
|is_draft|boolean|false|write-only|Specifies whether the sub-entity details are in draft.
Marking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.|
|profile|object|true|none|Information about the profile of the sub-entity, primarily regarding the products/services offered.|
|» urls|[string]|true|none|A collection of website URLs the sub-entity accepts payments on.|
|»» Company website URL|string(uri)|false|none|The URL of the company's website.|
|» mccs|[any]|true|none|Select the categories that most closely describe the business|
|»» Merchant category code|number|false|none|The merchant category code (4-digit ISO 18245).|
|contact_details|object|true|none|none|
|» phone|object|true|none|none|
|»» number|any|true|none|Include the area code|
|» email_addresses|object|true|none|none|
|»» primary|any|true|none|The main email address for this sub-entity.|
|» invitee|object|false|none|none|
|»» email|any|false|none|The main email address for this sub-entity.|
|capabilities|object|false|read-only|The capabilities of the entity.|
|requirements_due|[object]|false|read-only|List of requirements due in order to be onboarded.|
|» Requirements due entry|object|false|read-only|A list of fields which require attention|
|»» field|string|false|none|The field that is needs to be addressed.|
|»» reason|string|false|none|The reason behind the field needing attention.|
|instruments|[object]|false|read-only|none|
|company|object|true|none|Information about the company represented by the sub-entity.|
|» legal_name|string|true|none|The legal name of the sub-entity.|
|» trading_name|string|true|none|The trading name of the sub-entity, also referred to as 'doing business as'.|
|» business_registration_number|string|false|none|Employer Identification Number (EIN).|
|» principal_address|object|true|none|The primary location of the company where business is performed.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|true|none|The address state. This field is required for addresses based in the US. For US addresses, provide the state as an ISO 3166-1 code.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» registered_address|object|true|none|The registered address of the company.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|true|none|The address state. This field is required for addresses based in the US. For US addresses, provide the state as an ISO 3166-1 code.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» representatives|[object]|true|none|Information about representatives of this company.|
|»» Representative|object|false|none|Information about representatives of this company.|
|»»» first_name|string|true|none|The representative's first name.|
|»»» middle_name|string|false|none|The representative's middle name. Required if appears in official docs|
|»»» last_name|string|true|none|The representative's last name.|
|»»» identification|object|false|none|Information about representatives of this company.|
|»»»» national_id_number|number|true|none|Social security number (SSN) or Individual Taxpayer Identification Number (ITIN) for non-US citizens|
|»»» date_of_birth|object|false|none|The date of birth of the person according to the Gregorian calendar.|
|»»»» day|integer|true|none|The calendar day of the month they were born.|
|»»»» month|integer|true|none|The month of the year they were born.|
|»»»» year|integer|true|none|The year they were born.|
|»»» phone|object|false|none|The phone number of the sub-entity.|
|»»»» number|any|true|none|The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)|
|»»» address|object|true|none|The representative's address.|
|»»»» address_line1|string|false|none|The first line of the address.|
|»»»» address_line2|number|false|none|The second line of the address.|
|»»»» city|string|false|none|The address city.|
|»»»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»»»» zip|string|false|none|The address zip/postal code.|
|»»»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|»»» documents|object|false|none|A legal document used to verify identity|
|»»»» identity_verification|object|true|none|The document to use to confirm the individual's identity.|
|»»»»» type|string|true|none|The type of document used for identity verification|
|»»»»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|»»»»» back|string|false|none|The ID of the back side of the document as represented within Checkout.com systems.|
|»»» roles|[string]|false|none|The individual's roles within the company|
|»»»» Representative Role|string|false|none|The representative's roles within the company|
|» business_type|string|false|none|The legal type of the company|
|» financial_details|object|false|none|Seller financial questions and supporting documents.|
|»» annual_processing_volume|integer|false|none|The estimated annual processing volume. In minor units without decimals.|
|»» average_transaction_value|integer|false|none|The expected average transaction value. In minor units without decimals.|
|»» highest_transaction_value|integer|false|none|The expected highest transaction value. In minor units without decimals.|
|»» currency|string|false|none|The currency used for the processing details provided.|
|documents|object|false|none|The documents used to support the verification of company details.|
|» company_verification|object|false|none|The document to use to confirm the company's identity.|
|»» type|string|true|none|The type of document being used for company verification.|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» tax_verification|object|false|none|Employer Identification Number document.|
|»» type|string|true|none|The type of document used for tax verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
#### Enumerated Values
|Property|Value|
|---|---|
|state|AL|
|state|AK|
|state|AZ|
|state|AR|
|state|CA|
|state|CO|
|state|CT|
|state|DE|
|state|DC|
|state|FL|
|state|GA|
|state|HI|
|state|ID|
|state|IL|
|state|IN|
|state|IA|
|state|KS|
|state|KY|
|state|LA|
|state|ME|
|state|MD|
|state|MA|
|state|MI|
|state|MN|
|state|MS|
|state|MO|
|state|MT|
|state|NE|
|state|NV|
|state|NH|
|state|NJ|
|state|NM|
|state|NY|
|state|NC|
|state|ND|
|state|OH|
|state|OK|
|state|OR|
|state|PA|
|state|RI|
|state|SC|
|state|SD|
|state|TN|
|state|TX|
|state|UT|
|state|VT|
|state|VA|
|state|WA|
|state|WV|
|state|WI|
|state|WY|
|state|AS|
|state|GU|
|state|MP|
|state|PR|
|state|VI|
|state|UM|
|state|AL|
|state|AK|
|state|AZ|
|state|AR|
|state|CA|
|state|CO|
|state|CT|
|state|DE|
|state|DC|
|state|FL|
|state|GA|
|state|HI|
|state|ID|
|state|IL|
|state|IN|
|state|IA|
|state|KS|
|state|KY|
|state|LA|
|state|ME|
|state|MD|
|state|MA|
|state|MI|
|state|MN|
|state|MS|
|state|MO|
|state|MT|
|state|NE|
|state|NV|
|state|NH|
|state|NJ|
|state|NM|
|state|NY|
|state|NC|
|state|ND|
|state|OH|
|state|OK|
|state|OR|
|state|PA|
|state|RI|
|state|SC|
|state|SD|
|state|TN|
|state|TX|
|state|UT|
|state|VT|
|state|VA|
|state|WA|
|state|WV|
|state|WI|
|state|WY|
|state|AS|
|state|GU|
|state|MP|
|state|PR|
|state|VI|
|state|UM|
|type|passport|
|type|national_identity_card|
|type|driving_license|
|type|citizen_card|
|type|residence_permit|
|type|electoral_id|
|Representative Role|ubo|
|Representative Role|authorised_signatory|
|Representative Role|control_person|
|business_type|private_corporation|
|business_type|publicly_traded_corporation|
|business_type|government_agency|
|business_type|individual_or_sole_proprietorship|
|business_type|limited_liability_corporation|
|business_type|limited_partnership|
|business_type|non_profit_entity|
|business_type|sec_registered_entity|
|business_type|cftc_registered_entity|
|business_type|regulated_financial_institution|
|currency|USD|
|type|incorporation_document|
|type|articles_of_association|
|type|ein_letter|
USISVSellerCompany3-0
```json
{
"reference": "isv-seller-example001",
"agreed_terms": {
"date": "2026-07-02T10:30:00Z",
"ip_address": "8.8.8.8",
"name": "Toby Arden",
"email": "toby.arden@example.com",
"version": "cko-platform-terms-1.0.0"
},
"seller_category": "cat_retail_001",
"processing_details": {
"annual_processing_volume": 1000,
"average_transaction_value": 2000,
"average_order_fulfillment_time": 3,
"target_countries": [
"US"
],
"currency": "USD",
"payments": {
"ach": {
"annual_ach_volume": 100000,
"average_ach_transaction_size": 5000,
"estimated_monthly_credit_volume": 50000,
"average_credit_amount": 2500
}
}
},
"contact_details": {
"phone": {
"number": "4155678900",
"country_code": "US"
},
"email_addresses": {
"primary": "toby.arden@example.com",
"pci_compliance_contact": "pci.contact@example.com"
}
},
"profile": {
"urls": [
"https://www.isv-seller-example.com"
],
"mccs": [
"5551"
],
"holding_currencies": [
"USD"
],
"default_holding_currency": "USD"
},
"company": {
"business_registration_number": "12-3456789",
"business_type": "private_corporation",
"legal_name": "ISV Seller Example Inc",
"trading_name": "ISV Seller Example",
"registered_address": {
"address_line1": "123 Main Street",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country": "US"
},
"principal_address": {
"address_line1": "123 Main Street",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country": "US"
},
"date_of_incorporation": {
"year": 2025,
"month": 10,
"day": 1
},
"representatives": [
{
"roles": [
"ubo",
"control_person"
],
"ownership_percentage": 25,
"company_position": "ceo",
"individual": {
"first_name": "Toby",
"last_name": "Arden",
"email_address": "toby.arden@example.com",
"national_id_type": "ssn",
"national_id_number": "123456789",
"date_of_birth": {
"day": 15,
"month": 1,
"year": 1990
},
"place_of_birth": {
"country": "US"
},
"citizenships": [
{
"country": "US"
}
],
"phone": {
"country_code": "US",
"number": "4155678901"
},
"address": {
"address_line1": "123 Main Street",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country": "US"
}
}
},
{
"roles": [
"authorised_signatory"
],
"individual": {
"first_name": "Alex",
"last_name": "Morgan",
"email_address": "alex.morgan@example.com",
"national_id_type": "ssn",
"national_id_number": "987654321",
"date_of_birth": {
"day": 22,
"month": 6,
"year": 1985
},
"place_of_birth": {
"country": "US"
},
"citizenships": [
{
"country": "US"
}
],
"phone": {
"country_code": "US",
"number": "4155678902"
},
"address": {
"address_line1": "123 Main Street",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country": "US"
}
}
}
]
}
}
```
US Company (SaaS)
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|true|none|A unique reference you can later use to identify the sub-entity. Immutable after creation.|
|status|string|false|read-only|The current lifecycle state of the sub-entity. Read-only on input. POST always returns Draft.|
|is_draft|boolean|false|write-only|Indicates whether the sub-entity should remain in Draft on PUT, skipping due-diligence checks. POST always creates the entity in Draft regardless of this field.|
|agreed_terms|object|true|none|Details of the person who agreed to the terms and conditions on behalf of the sub-entity, captured as evidence of consent to Checkout.com onboarding.|
|» date|string(date-time)|true|none|Date and time the terms were agreed in RFC 3339 or ISO 8601 format.|
|» ip_address|string|true|none|IP address (IPv4 or IPv6) of the person at the time they agreed the terms.|
|» name|string|true|none|First and last name of the person who agreed to the terms.|
|» email|string(email)|true|none|Email address of the person who agreed to the terms.|
|» version|string|true|none|Identifier of the terms version that was agreed.|
|seller_category|string|true|none|The identifier of a seller category set up for your platform. Seller categories define the pricing, capabilities, and risk profile applied to sub-entities, and are configured during your platform's onboarding with Checkout.com. Contact your account manager for your platform's list of available identifiers.|
|profile|object|true|none|Information about the profile of the sub-entity, primarily regarding the products/services offered.|
|» urls|[string]|true|none|The collection of website URLs the sub-entity accepts payments on.|
|»» Company website URL|string(uri)|false|none|The URL of the company's website.|
|» mccs|[string]|true|none|The collection of merchant category codes that most closely describe the business.|
|»» Merchant category code|string|false|none|The merchant category code as a four-digit ISO 18245.
Reference: [Merchant Category Codes](https://www.checkout.com/docs/developer-resources/codes/merchant-category-codes).|
|» default_holding_currency|string|true|none|The default holding currency's three-letter ISO 4217 code.|
|» holding_currencies|[string]|true|none|The collection of currencies in which incoming funds are held.|
|»» Currency|string|false|none|The three-letter ISO 4217 code of the currency.|
|contact_details|object|true|none|Contact details of this sub-entity.|
|» phone|object|true|none|Phone number with country code.|
|»» country_code|string|true|none|The two-letter ISO 3166-1 alpha-2 country code where the phone number is registered.|
|»» number|string|true|none|The phone number without the country calling code.|
|» email_addresses|object|true|none|Email addresses for this sub-entity.|
|»» primary|string(email)|true|none|The primary email address for this sub-entity.|
|»» pci_compliance_contact|string(email)|true|none|The email address of the person responsible for PCI compliance at this sub-entity.|
|processing_details|object|true|none|Information about the sub-entity's expected processing.|
|» annual_processing_volume|integer|true|none|The estimated annual processing volume in minor units without decimals.|
|» average_transaction_value|integer|true|none|The expected average transaction value in minor units without decimals.|
|» average_order_fulfillment_time|integer|true|none|The average time in days between accepting payment and fulfilling the order.|
|» currency|string|true|none|The currency used for the processing details provided.|
|» target_countries|[string]|true|none|The list of two-letter ISO 3166-1 alpha-2 target country codes with more than 10% expected volume processing with Checkout.com.|
|»» Country|string(iso-3166-1-alpha-2)|false|none|The two-letter ISO 3166-1 alpha-2 country code.|
|» payments|object|true|none|Payment method-specific processing details.|
|»» ach|object|true|none|ACH payment processing details.|
|»»» annual_ach_volume|integer|true|none|The estimated annual ACH processing volume in minor units without decimals.|
|»»» average_ach_transaction_size|integer|true|none|The expected average ACH transaction size in minor units without decimals.|
|»»» estimated_monthly_credit_volume|integer|true|none|The estimated monthly volume of ACH credit transactions (for example, refunds issued to customers) in minor units without decimals.|
|»»» average_credit_amount|integer|true|none|The average value of an ACH credit transaction (for example, a refund) in minor units without decimals.|
|company|object|true|none|Information about the company represented by the sub-entity.|
|» legal_name|string|true|none|The legal name of the sub-entity.|
|» trading_name|string|true|none|The trading name of the sub-entity, also referred to as 'Doing Business As'.|
|» additional_trading_names|[string]|false|none|The collection of additional trading names for the sub-entity.|
|»» Trading name|string|false|none|An additional trading name of the entity.|
|» business_type|string|true|none|The legal type of the company.|
|» business_registration_number|string|true|none|US Employer Identification Number (EIN). Nine digits, with optional hyphen.|
|» date_of_incorporation|object|true|none|The date the company was incorporated.|
|»» day|integer|true|none|The day of the month the company was incorporated.|
|»» month|integer|true|none|The month the company was incorporated.|
|»» year|integer|true|none|The year the company was incorporated.|
|» registered_address|object|true|none|The registered address of the company.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|string|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|true|none|The address state. Provide the US state as a two-letter ISO 3166-2 code.|
|»» zip|string|true|none|The address ZIP code or post code.|
|»» country|string|true|none|The two-letter ISO 3166-1 alpha-2 country code.
Reference: [Country codes](https://www.checkout.com/docs/developer-resources/codes/country-codes).|
|» principal_address|object|true|none|The primary location of the company where business is performed.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|string|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|false|none|The address state. For US addresses, provide the two-letter ISO 3166-2 code.|
|»» zip|string|false|none|The address ZIP code or post code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The two-letter ISO 3166-1 alpha-2 country code.
Reference: [Country codes](https://www.checkout.com/docs/developer-resources/codes/country-codes).|
|» representatives|[object]|true|none|The list of the company's representatives.|
|»» roles|[string]|true|none|The individual's roles within the company.|
|»»» Representative role|string|false|none|The representative's role.|
|»» ownership_percentage|integer|false|none|The percentage ownership of the UBO (required when the representative holds the ubo role).|
|»» company_position|string|false|none|The position of the representative within the company (required for control_person role).|
|»» individual|object|true|none|Personal information about the individual representing the sub-entity.|
|»»» first_name|string|true|none|The representative's first name.|
|»»» middle_name|string|false|none|The representative's middle name. Required if it appears in official documents.|
|»»» last_name|string|true|none|The representative's last name.|
|»»» email_address|string(email)|true|none|The representative's email address.|
|»»» date_of_birth|object|true|none|The person's date of birth according to the Gregorian calendar.|
|»»»» day|integer|true|none|The calendar day of the month they were born.|
|»»»» month|integer|true|none|The month of the year they were born.|
|»»»» year|integer|true|none|The year they were born.|
|»»» address|object|true|none|The representative's residential address.|
|»»»» address_line1|string|true|none|The first line of the address.|
|»»»» address_line2|string|false|none|The second line of the address.|
|»»»» city|string|true|none|The address city.|
|»»»» state|string|false|none|The address state. For US addresses, provide the two-letter ISO 3166-2 code.|
|»»»» zip|string|true|none|The address ZIP code or post code.|
|»»»» country|string(iso-3166-1-alpha-2)|true|none|The two-letter ISO 3166-1 alpha-2 country code.|
|»»» place_of_birth|object|true|none|The person's place of birth.|
|»»»» country|string(iso-3166-1-alpha-2)|true|none|The two-letter ISO 3166-1 alpha-2 country code.|
|»»» citizenships|[object]|true|none|The list of citizenships or legal statuses for the representative.|
|»»»» type|string|false|none|The type of citizenship or legal status (e.g. `citizenship`, `residency`).|
|»»»» country|string(iso-3166-1-alpha-2)|true|none|The two-letter ISO 3166-1 alpha-2 country code.|
|»»» national_id_type|string|true|none|The classification of the national identification number provided.|
|»»» national_id_number|string|true|none|When `national_id_type` is `ssn`, provide the SSN (or ITIN). Otherwise, provide the identifier from the chosen document type.|
|»»» phone|object|true|none|The representative's phone number.|
|»»»» country_code|string(iso-3166-1-alpha-2)|true|none|The two-letter ISO 3166-1 alpha-2 country code where the phone number is registered.|
|»»»» number|string|true|none|The phone number without the country calling code.|
|»» documents|object|false|none|Verification documents for the individual representative.|
|»»» identity_verification|object|false|none|The document to use to confirm the individual's identity.|
|»»»» type|string|true|none|The type of document used for identity verification.|
|»»»» front|string|true|none|The ID of the front side of the document.|
|»»»» back|string|false|none|The ID of the back side of the document.|
|»»» certified_authorised_signatory|object|false|none|Required for representatives with the `authorised_signatory` role, when the legal representative or other role owner is not registered on the certificate of incorporation.|
|»»»» type|string|true|none|The type of document.|
|»»»» front|string|true|none|The ID of the front side of the document.|
|documents|object|false|none|Verification documents for the sub-entity.|
|» tax_verification|object|false|none|IRS-issued document used to verify the entity's tax identification.|
|»» type|string|true|none|The type of IRS-issued document used for tax verification.|
|»» front|string|true|none|The ID of the front side of the document.|
|» company_verification|object|false|none|Certified by a power of attorney within the last 3 months.|
|»» type|string|true|none|The type of document used for company verification.|
|»» front|string|true|none|The ID of the front side of the document.|
|» articles_of_association|object|false|none|Memorandum or Articles of Association document.|
|»» type|string|true|none|The type of document used.|
|»» front|string|true|none|The ID of the front side of the document.|
|» shareholder_structure|object|false|none|Shareholder structure chart including the percentage of shares certified by a competent authority individual and dated within the last 3 months.|
|»» type|string|true|none|The type of document.|
|»» front|string|true|none|The ID of the front side of the document.|
|» proof_of_legality|object|false|none|A regulatory license document required for the company to operate if applicable.|
|»» type|string|true|none|The type of document used for proof of legality.|
|»» front|string|true|none|The ID of the front side of the document.|
|» proof_of_principal_address|object|false|none|Proof of principal place of business.|
|»» type|string|true|none|The type of document used for address verification.|
|»» front|string|true|none|The ID of the front side of the document.|
|» financial_statements|object|false|none|Audited or management-prepared financial statements (when applicable).|
|»» type|string|true|none|The type of document.|
|»» front|string|true|none|The ID of the front side of the document.|
#### Enumerated Values
|Property|Value|
|---|---|
|default_holding_currency|USD|
|Currency|USD|
|country_code|US|
|currency|USD|
|business_type|private_corporation|
|business_type|limited_liability_corporation|
|business_type|publicly_traded_corporation|
|business_type|limited_partnership|
|business_type|non_profit_entity|
|business_type|government_agency|
|business_type|regulated_financial_institution|
|business_type|sec_registered_entity|
|business_type|cftc_registered_entity|
|state|AL|
|state|AK|
|state|AZ|
|state|AR|
|state|CA|
|state|CO|
|state|CT|
|state|DE|
|state|DC|
|state|FL|
|state|GA|
|state|HI|
|state|ID|
|state|IL|
|state|IN|
|state|IA|
|state|KS|
|state|KY|
|state|LA|
|state|ME|
|state|MD|
|state|MA|
|state|MI|
|state|MN|
|state|MS|
|state|MO|
|state|MT|
|state|NE|
|state|NV|
|state|NH|
|state|NJ|
|state|NM|
|state|NY|
|state|NC|
|state|ND|
|state|OH|
|state|OK|
|state|OR|
|state|PA|
|state|RI|
|state|SC|
|state|SD|
|state|TN|
|state|TX|
|state|UT|
|state|VT|
|state|VA|
|state|WA|
|state|WV|
|state|WI|
|state|WY|
|state|AS|
|state|GU|
|state|MP|
|state|PR|
|state|VI|
|state|UM|
|country|US|
|Representative role|ubo|
|Representative role|authorised_signatory|
|Representative role|control_person|
|company_position|ceo|
|company_position|cfo|
|company_position|coo|
|company_position|managing_member|
|company_position|general_partner|
|company_position|president|
|company_position|vice_president|
|company_position|treasurer|
|company_position|other_senior_management|
|company_position|other_executive_officer|
|company_position|other_non_executive_non_senior|
|national_id_type|ssn|
|national_id_type|itin|
|national_id_type|passport|
|national_id_type|driving_license|
|national_id_type|national_id_card|
|national_id_type|residence_permit|
|national_id_type|other|
|type|passport|
|type|national_identity_card|
|type|driving_license|
|type|citizen_card|
|type|residence_permit|
|type|electoral_id|
|type|power_of_attorney|
|type|ein_letter|
|type|incorporation_document|
|type|memorandum_of_association|
|type|articles_of_association|
|type|certified_shareholder_structure|
|type|proof_of_legality|
|type|proof_of_address|
|type|financial_statements|
USISVSellerSoleTrader3-0
```json
{
"reference": "isv-sole-trader-example001",
"agreed_terms": {
"date": "2026-07-02T10:30:00Z",
"ip_address": "8.8.8.8",
"name": "Hannah Bret",
"email": "hannah.bret@example.com",
"version": "cko-platform-terms-1.0.0"
},
"seller_category": "cat_retail_001",
"processing_details": {
"annual_processing_volume": 1000,
"average_transaction_value": 2000,
"average_order_fulfillment_time": 3,
"target_countries": [
"US"
],
"currency": "USD",
"payments": {
"ach": {
"annual_ach_volume": 100000,
"average_ach_transaction_size": 5000,
"estimated_monthly_credit_volume": 50000,
"average_credit_amount": 2500
}
}
},
"contact_details": {
"phone": {
"number": "4155678900",
"country_code": "US"
},
"email_addresses": {
"primary": "hannah.bret@example.com",
"pci_compliance_contact": "pci.contact@example.com"
}
},
"profile": {
"urls": [
"https://www.isv-sole-trader-example.com"
],
"mccs": [
"5551"
],
"holding_currencies": [
"USD"
],
"default_holding_currency": "USD"
},
"company": {
"business_type": "individual_or_sole_proprietorship",
"is_registered_company": false,
"trading_name": "Hannah's Goods",
"date_of_incorporation": {
"year": 2025,
"month": 10,
"day": 1
},
"principal_address": {
"address_line1": "123 Main Street",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country": "US"
},
"representatives": [
{
"roles": [
"ubo"
],
"ownership_percentage": 100,
"individual": {
"first_name": "Hannah",
"last_name": "Bret",
"email_address": "hannah.bret@example.com",
"national_id_type": "ssn",
"national_id_number": "123456789",
"date_of_birth": {
"day": 15,
"month": 1,
"year": 1990
},
"place_of_birth": {
"country": "US"
},
"citizenships": [
{
"country": "US"
}
],
"phone": {
"country_code": "US",
"number": "4155678901"
},
"address": {
"address_line1": "123 Main Street",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country": "US"
}
}
}
]
}
}
```
US Sole Trader (SaaS)
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|true|none|A unique reference you can later use to identify the sub-entity. Immutable after creation.|
|status|string|false|read-only|The current lifecycle state of the sub-entity. Read-only on input. POST always returns Draft.|
|is_draft|boolean|false|write-only|Indicates whether the sub-entity should remain in Draft on PUT, skipping due-diligence checks. POST always creates the entity in Draft regardless of this field.|
|agreed_terms|object|true|none|Details of the sole trader who agreed to the terms and conditions, captured as evidence of consent to Checkout.com onboarding.|
|» date|string(date-time)|true|none|Date and time the terms were agreed in RFC 3339 or ISO 8601 format.|
|» ip_address|string|true|none|IP address (IPv4 or IPv6) of the sole trader at the time they agreed the terms.|
|» name|string|true|none|First and last name of the sole trader who agreed to the terms.|
|» email|string(email)|true|none|Email address of the sole trader who agreed to the terms.|
|» version|string|true|none|Identifier of the terms version that was agreed.|
|seller_category|string|true|none|The identifier of a seller category set up for your platform. Seller categories define the pricing, capabilities, and risk profile applied to sub-entities, and are configured during your platform's onboarding with Checkout.com. Contact your account manager for your platform's list of available identifiers.|
|profile|object|true|none|Information about the profile of the sub-entity, primarily regarding the products/services offered.|
|» urls|[string]|true|none|The collection of website URLs the sub-entity accepts payments on.|
|»» Company website URL|string(uri)|false|none|The URL of the website the sole trader accepts payments on.|
|» mccs|[string]|true|none|The collection of merchant category codes that most closely describe the business.|
|»» Merchant category code|string|false|none|The merchant category code as a four-digit ISO 18245.
Reference: [Merchant Category Codes](https://www.checkout.com/docs/developer-resources/codes/merchant-category-codes).|
|» default_holding_currency|string|true|none|The default holding currency's three-letter ISO 4217 code.|
|» holding_currencies|[string]|true|none|The collection of currencies in which incoming funds are held.|
|»» Currency|string|false|none|The three-letter ISO 4217 code of the currency.|
|contact_details|object|true|none|Contact details of this sub-entity.|
|» phone|object|true|none|Phone number with country code.|
|»» country_code|string|true|none|The two-letter ISO 3166-1 alpha-2 country code where the phone number is registered.|
|»» number|string|true|none|The phone number without the country calling code.|
|» email_addresses|object|true|none|Email addresses for this sub-entity.|
|»» primary|string(email)|true|none|The main email address for this sub-entity.|
|»» pci_compliance_contact|string(email)|true|none|The email address of the person responsible for PCI compliance at this sub-entity.|
|processing_details|object|true|none|Information about the sub-entity's processing.|
|» annual_processing_volume|integer|true|none|The estimated annual processing volume in minor units without decimals.|
|» average_transaction_value|integer|true|none|The expected average transaction value in minor units without decimals.|
|» average_order_fulfillment_time|integer|true|none|The average time in days between accepting payment and fulfilling the order.|
|» currency|string|true|none|The currency used for the processing details provided.|
|» target_countries|[string]|true|none|The list of two-letter ISO 3166-1 alpha-2 target country codes with more than 10% expected volume processing with Checkout.com.|
|»» Country|string(iso-3166-1-alpha-2)|false|none|The two-letter ISO 3166-1 alpha-2 country code.|
|» payments|object|true|none|Payment method-specific processing details.|
|»» ach|object|true|none|ACH payment processing details.|
|»»» annual_ach_volume|integer|true|none|The estimated annual ACH processing volume in minor units without decimals.|
|»»» average_ach_transaction_size|integer|true|none|The expected average ACH transaction size in minor units without decimals.|
|»»» estimated_monthly_credit_volume|integer|true|none|The estimated monthly volume of ACH credit transactions (for example, refunds issued to customers) in minor units without decimals.|
|»»» average_credit_amount|integer|true|none|The average value of an ACH credit transaction (for example, a refund) in minor units without decimals.|
|company|object|true|none|Information about the sole trader sub-entity.|
|» is_registered_company|boolean|true|none|Indicates whether the sub-entity is a registered legal entity. Must be `false` for this variant.|
|» trading_name|string|true|none|The trading name the sole trader uses, also referred to as 'Doing Business As'.|
|» additional_trading_names|[string]|false|none|The collection of additional trading names for the sub-entity.|
|»» Trading name|string|false|none|An additional trading name of the sole trader.|
|» business_type|string|true|none|The legal type of the entity. Must be `individual_or_sole_proprietorship` for this variant.|
|» date_of_incorporation|object|true|none|The date the sole trader started trading.|
|»» day|integer|true|none|The day of the month the sole trader started trading.|
|»» month|integer|true|none|The month the sole trader started trading.|
|»» year|integer|true|none|The year the sole trader started trading.|
|» principal_address|object|true|none|The primary location where the sole trader performs business.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|string|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|false|none|The address state. Provide the US state as a two-letter ISO 3166-2 code.|
|»» zip|string|true|none|The address ZIP code or post code.|
|»» country|string|true|none|The two-letter ISO 3166-1 alpha-2 country code.
Reference: [Country codes](https://www.checkout.com/docs/developer-resources/codes/country-codes).|
|» representatives|[object]|true|none|The list of representatives for the sub-entity. Sole traders must have exactly one representative — the individual themselves — with roles set to `[ubo]`.|
|»» roles|[string]|true|none|The representative's roles. For sole traders, must be `[ubo]` only.|
|»» ownership_percentage|integer|false|none|The percentage ownership of the sole trader with the UBO role.|
|»» individual|object|true|none|Personal information about the sole trader.|
|»»» first_name|string|true|none|The sole trader's first name.|
|»»» middle_name|string|false|none|The sole trader's middle name. Required if it appears in official documents.|
|»»» last_name|string|true|none|The sole trader's last name.|
|»»» email_address|string(email)|true|none|The sole trader's email address.|
|»»» date_of_birth|object|true|none|The person's date of birth according to the Gregorian calendar.|
|»»»» day|integer|true|none|The calendar day of the month they were born.|
|»»»» month|integer|true|none|The month of the year they were born.|
|»»»» year|integer|true|none|The year they were born.|
|»»» address|object|true|none|The sole trader's residential address.|
|»»»» address_line1|string|true|none|The first line of the address.|
|»»»» address_line2|string|false|none|The second line of the address.|
|»»»» city|string|true|none|The address city.|
|»»»» state|string|false|none|The address state. For US addresses, provide the two-letter ISO 3166-2 code.|
|»»»» zip|string|true|none|The address ZIP code or post code.|
|»»»» country|string(iso-3166-1-alpha-2)|true|none|The two-letter ISO 3166-1 alpha-2 country code.|
|»»» place_of_birth|object|true|none|The person's place of birth.|
|»»»» country|string(iso-3166-1-alpha-2)|true|none|The two-letter ISO 3166-1 alpha-2 country code.|
|»»» citizenships|[object]|true|none|The list of citizenships or legal statuses of the sole trader.|
|»»»» type|string|false|none|The type of citizenship or legal status (e.g. `citizenship`, `residency`).|
|»»»» country|string(iso-3166-1-alpha-2)|true|none|The two-letter ISO 3166-1 alpha-2 country code.|
|»»» national_id_type|string|true|none|The classification of the national identification number provided.|
|»»» national_id_number|string|true|none|When `national_id_type` is `ssn`, provide the SSN (or ITIN). Otherwise, provide the identifier from the chosen document type.|
|»»» phone|object|true|none|The sole trader's phone number.|
|»»»» country_code|string(iso-3166-1-alpha-2)|true|none|The two-letter ISO 3166-1 alpha-2 country code where the phone number is registered.|
|»»»» number|string|true|none|The phone number without the country calling code.|
|»» documents|object|false|none|Verification documents for the sole trader.|
|»»» identity_verification|object|false|none|The document to use to confirm the sole trader's identity.|
|»»»» type|string|true|none|The type of document used for identity verification.|
|»»»» front|string|true|none|The ID of the front side of the document.|
|»»»» back|string|false|none|The ID of the back side of the document.|
|documents|object|false|none|Verification documents for the sub-entity.|
|» tax_verification|object|false|none|IRS-issued document used to verify the entity's tax identification.|
|»» type|string|true|none|The type of IRS-issued document used for tax verification.|
|»» front|string|true|none|The ID of the front side of the document.|
|» company_verification|object|false|none|Certified by a power of attorney within the last 3 months.|
|»» type|string|true|none|The type of document used for company verification.|
|»» front|string|true|none|The ID of the front side of the document.|
|» articles_of_association|object|false|none|Memorandum or Articles of Association document.|
|»» type|string|true|none|The type of document used.|
|»» front|string|true|none|The ID of the front side of the document.|
|» proof_of_legality|object|false|none|A regulatory license document required for the company to operate if applicable.|
|»» type|string|true|none|The type of document used for proof of legality.|
|»» front|string|true|none|The ID of the front side of the document.|
|» proof_of_principal_address|object|false|none|Proof of principal place of business.|
|»» type|string|true|none|The type of document used for address verification.|
|»» front|string|true|none|The ID of the front side of the document.|
|» financial_statements|object|false|none|Financial statements (when applicable).|
|»» type|string|true|none|The type of document.|
|»» front|string|true|none|The ID of the front side of the document.|
#### Enumerated Values
|Property|Value|
|---|---|
|default_holding_currency|USD|
|Currency|USD|
|country_code|US|
|currency|USD|
|is_registered_company|false|
|business_type|individual_or_sole_proprietorship|
|state|AL|
|state|AK|
|state|AZ|
|state|AR|
|state|CA|
|state|CO|
|state|CT|
|state|DE|
|state|DC|
|state|FL|
|state|GA|
|state|HI|
|state|ID|
|state|IL|
|state|IN|
|state|IA|
|state|KS|
|state|KY|
|state|LA|
|state|ME|
|state|MD|
|state|MA|
|state|MI|
|state|MN|
|state|MS|
|state|MO|
|state|MT|
|state|NE|
|state|NV|
|state|NH|
|state|NJ|
|state|NM|
|state|NY|
|state|NC|
|state|ND|
|state|OH|
|state|OK|
|state|OR|
|state|PA|
|state|RI|
|state|SC|
|state|SD|
|state|TN|
|state|TX|
|state|UT|
|state|VT|
|state|VA|
|state|WA|
|state|WV|
|state|WI|
|state|WY|
|state|AS|
|state|GU|
|state|MP|
|state|PR|
|state|VI|
|state|UM|
|country|US|
|national_id_type|ssn|
|national_id_type|itin|
|national_id_type|passport|
|national_id_type|driving_license|
|national_id_type|national_id_card|
|national_id_type|residence_permit|
|national_id_type|other|
|type|passport|
|type|national_identity_card|
|type|driving_license|
|type|citizen_card|
|type|residence_permit|
|type|electoral_id|
|type|ein_letter|
|type|incorporation_document|
|type|memorandum_of_association|
|type|articles_of_association|
|type|proof_of_legality|
|type|proof_of_address|
|type|financial_statements|
USSoleTraderFull2-0
```json
{
"reference": "string",
"status": "string",
"is_draft": true,
"profile": {
"urls": [
"http://example.com"
],
"mccs": [
"string"
],
"default_holding_currency": null,
"holding_currencies": [
"USD"
]
},
"contact_details": {
"phone": {
"number": 2000000000
},
"email_addresses": {
"primary": null
},
"invitee": {
"email": null
}
},
"capabilities": {},
"requirements_due": [
{
"field": "string",
"reason": "string"
}
],
"instruments": [
{}
],
"documents": {
"identity_verification": {
"type": "passport",
"front": "stringstringstringstringstrings",
"back": "stringstringstringstringstrings"
}
},
"individual": {
"trading_name": "string",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"date_of_birth": {
"day": 1,
"month": 1,
"year": 1900
},
"registered_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "AL",
"zip": "string",
"country": "st"
},
"identification": {
"national_id_number": "stringstr"
},
"financial_details": {
"annual_processing_volume": 0,
"average_transaction_value": 0,
"highest_transaction_value": 0,
"currency": "USD"
}
}
}
```
US Sole Trader - Full (2.0)
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|true|none|A unique reference you can later use to identify the sub-entity.|
|status|string|false|read-only|none|
|is_draft|boolean|false|write-only|Specifies whether the sub-entity details are in draft.
Marking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.|
|profile|object|true|none|Information about the profile of the sub-entity, primarily regarding the products/services offered.|
|» urls|[string]|true|none|A collection of website URLs the sub-entity accepts payments on.|
|»» Company website URL|string(uri)|false|none|The URL of the company's website.|
|» mccs|[any]|true|none|Select the categories that most closely describe the business|
|»» Merchant category code|number|false|none|The merchant category code (4-digit ISO 18245).|
|» default_holding_currency|any|false|none|The default holding currency code (iso-4217)|
|» holding_currencies|array|false|none|Incoming funds are held in your selected currencies|
|»» Currency|string|false|none|The currency code (iso-4217)|
|contact_details|object|true|none|none|
|» phone|object|true|none|none|
|»» number|any|true|none|Include the area code|
|» email_addresses|object|true|none|none|
|»» primary|any|true|none|The main email address for this sub-entity.|
|» invitee|object|false|none|none|
|»» email|any|false|none|The main email address for this sub-entity.|
|capabilities|object|false|read-only|The capabilities of the entity.|
|requirements_due|[object]|false|read-only|List of requirements due in order to be onboarded.|
|» Requirements due entry|object|false|read-only|A list of fields which require attention|
|»» field|string|false|none|The field that is needs to be addressed.|
|»» reason|string|false|none|The reason behind the field needing attention.|
|instruments|[object]|false|read-only|none|
|documents|object|false|none|A legal document used to verify identity.|
|» identity_verification|object|true|none|The document to use to confirm the individual's identity.|
|»» type|string|true|none|The type of document used for identity verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|»» back|string|false|none|The ID of the back side of the document as represented within Checkout.com systems.|
|individual|object|true|none|Information about the individual represented by the sub-entity.|
|» trading_name|string|true|none|The trading name of the sub-entity, also referred to as 'doing business as'.|
|» first_name|string|true|none|The representative's first name.|
|» middle_name|string|false|none|The representative's middle name. Required if appears in official docs|
|» last_name|string|true|none|The representative's last name.|
|» date_of_birth|object|true|none|The date of birth of the person according to the Gregorian calendar.|
|»» day|integer|true|none|The calendar day of the month they were born.|
|»» month|integer|true|none|The month of the year they were born.|
|»» year|integer|true|none|The year they were born.|
|» registered_address|object|true|none|The registered address of the company.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|true|none|The address state. This field is required for addresses based in the US. For US addresses, provide the state as an ISO 3166-1 code.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» identification|object|true|none|Information about representatives of this company.|
|»» national_id_number|number|true|none|Social security number (SSN) or Individual Taxpayer Identification Number (ITIN) for non-US citizens|
|» financial_details|object|true|none|Seller financial questions and supporting documents.|
|»» annual_processing_volume|integer|true|none|The estimated annual processing volume. In minor units without decimals.|
|»» average_transaction_value|integer|true|none|The expected average transaction value. In minor units without decimals.|
|»» highest_transaction_value|integer|true|none|The expected highest transaction value. In minor units without decimals.|
|»» currency|string|true|none|The currency used for the processing details provided.|
#### Enumerated Values
|Property|Value|
|---|---|
|Currency|USD|
|type|passport|
|type|national_identity_card|
|type|driving_license|
|type|citizen_card|
|type|residence_permit|
|type|electoral_id|
|state|AL|
|state|AK|
|state|AZ|
|state|AR|
|state|CA|
|state|CO|
|state|CT|
|state|DE|
|state|DC|
|state|FL|
|state|GA|
|state|HI|
|state|ID|
|state|IL|
|state|IN|
|state|IA|
|state|KS|
|state|KY|
|state|LA|
|state|ME|
|state|MD|
|state|MA|
|state|MI|
|state|MN|
|state|MS|
|state|MO|
|state|MT|
|state|NE|
|state|NV|
|state|NH|
|state|NJ|
|state|NM|
|state|NY|
|state|NC|
|state|ND|
|state|OH|
|state|OK|
|state|OR|
|state|PA|
|state|RI|
|state|SC|
|state|SD|
|state|TN|
|state|TX|
|state|UT|
|state|VT|
|state|VA|
|state|WA|
|state|WV|
|state|WI|
|state|WY|
|state|AS|
|state|GU|
|state|MP|
|state|PR|
|state|VI|
|state|UM|
|currency|USD|
USSoleTraderFull3-0
```json
{
"reference": "string",
"status": "string",
"is_draft": true,
"profile": {
"urls": [
"http://example.com"
],
"mccs": [
"string"
],
"default_holding_currency": null,
"holding_currencies": [
"USD"
]
},
"contact_details": {
"phone": {
"country_code": "US",
"number": "stringstri"
},
"email_addresses": {
"primary": null
},
"invitee": {
"email": null
}
},
"capabilities": {},
"requirements_due": [
{
"field": "string",
"reason": "string",
"message": "string"
}
],
"company": {
"trading_name": "string",
"date_of_incorporation": {
"day": 1,
"month": 1,
"year": 1500
},
"principal_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "AL",
"zip": "string",
"country": "st"
},
"representatives": [
{
"id": "stringstringstringstringstring",
"individual": {
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"date_of_birth": {
"day": 1,
"month": 1,
"year": 1900
},
"place_of_birth": {
"country": "st"
},
"national_id_number": "stringstr",
"email_address": null,
"phone": {
"country_code": "AF",
"number": "string"
},
"address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"zip": "string",
"country": "st"
}
},
"roles": [
"ubo"
],
"documents": {
"identity_verification": {
"type": "passport",
"front": "stringstringstringstringstrings",
"back": "stringstringstringstringstrings"
}
}
}
],
"business_type": "individual_or_sole_proprietorship"
},
"processing_details": {
"settlement_country": "st",
"target_countries": [
"st"
],
"annual_processing_volume": 0,
"average_transaction_value": 0,
"highest_transaction_value": 0,
"currency": "USD"
},
"documents": {
"bank_verification": {
"type": "bank_statement",
"front": "stringstringstringstringstrings"
},
"additional_document1": {
"front": "stringstringstringstringstrings"
},
"additional_document2": {
"front": "stringstringstringstringstrings"
},
"additional_document3": {
"front": "stringstringstringstringstrings"
}
}
}
```
US Sole Trader - Full (3.0)
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|true|none|A unique reference you can later use to identify the sub-entity.|
|status|string|false|read-only|none|
|is_draft|boolean|false|write-only|Specifies whether the sub-entity details are in draft.
Marking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.|
|profile|object|true|none|Information about the profile of the sub-entity, primarily regarding the products/services offered.|
|» urls|[string]|true|none|A collection of website URLs the sub-entity accepts payments on.|
|»» Company website URL|string(uri)|false|none|The URL of the company's website.|
|» mccs|[any]|true|none|Select the categories that most closely describe the business|
|»» Merchant category code|number|false|none|The merchant category code (4-digit ISO 18245).|
|» default_holding_currency|any|true|none|The default holding currency code (iso-4217)|
|» holding_currencies|[string]|true|none|Incoming funds are held in your selected currencies|
|»» Currency|string|false|none|The currency code (iso-4217)|
|contact_details|object|true|none|Contact details of this sub-entity.|
|» phone|object|false|none|Phone number|
|»» country_code|string|true|none|The country code (iso-3166-1 alpha-2) where the phone number is registered|
|»» number|string|true|none|The phone number without the country calling code|
|» email_addresses|object|false|none|Email addresses for this sub-entity.|
|»» primary|any|true|none|The main email address for this sub-entity.|
|» invitee|object|false|none|The details of the user responsible for onboarding the sub-entity.|
|»» email|any|false|none|The main email address for this sub-entity.|
|capabilities|object|false|read-only|The capabilities of the entity.|
|requirements_due|[object]|false|read-only|List of requirements due in order to be onboarded.|
|» Requirements due entry|object|false|read-only|A list of fields which require attention|
|»» field|string|false|none|The field that is needs to be addressed.|
|»» reason|string|false|none|The reason behind the field needing attention.|
|»» message|string|false|none|A more descriptive message.|
|company|object|true|none|Information about the company represented by the sub-entity.|
|» trading_name|string|true|none|The trading name of the sub-entity, also referred to as 'doing business as'.|
|» date_of_incorporation|object|true|none|The date the company was incorporated.|
|»» day|integer|false|none|The day of the month the company was incorporated.|
|»» month|integer|true|none|The month the company was incorporated.|
|»» year|integer|true|none|The year the company was incorporated.|
|» principal_address|object|true|none|The primary location where business is performed.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|true|none|The address state. This field is required for addresses based in the US. For US addresses, provide the state as an ISO 3166-1 code.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» representatives|[object]|true|none|Information about representatives of this company.|
|»» Person of Interest|object|false|none|Personal information about the individual representing the sub-entity.|
|»»» id|number|false|none|The representative's id.|
|»»» individual|object|true|none|Information about the individual representing the sub-entity.|
|»»»» first_name|string|true|none|The representative's first name.|
|»»»» middle_name|string|false|none|The representative's middle name. Required if appears in official docs|
|»»»» last_name|string|true|none|The representative's last name.|
|»»»» date_of_birth|object|true|none|The date of birth of the person according to the Gregorian calendar.|
|»»»»» day|integer|true|none|The calendar day of the month they were born.|
|»»»»» month|integer|true|none|The month of the year they were born.|
|»»»»» year|integer|true|none|The year they were born.|
|»»»» place_of_birth|object|true|none|The place of birth of the person.|
|»»»»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|»»»» national_id_number|number|false|none|Social security number (SSN) or Individual Taxpayer Identification Number (ITIN) for non-US citizens|
|»»»» email_address|any|false|none|The representative's personal email address.|
|»»»» phone|object|false|none|Phone number|
|»»»»» country_code|string|true|none|The country code (iso-3166-1 alpha-2) where the phone number is registered|
|»»»»» number|string|true|none|The phone number without the country calling code|
|»»»» address|object|true|none|The representative's address.|
|»»»»» address_line1|string|true|none|The first line of the address.|
|»»»»» address_line2|number|false|none|The second line of the address.|
|»»»»» city|string|true|none|The address city.|
|»»»»» state|string|false|none|The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in.|
|»»»»» zip|string|true|none|The address zip/postal code.|
|»»»»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|»»» roles|[string]|true|none|The individual's roles within the company|
|»»»» Representative Role|string|false|none|The representative's role|
|»»» documents|object|true|none|Verification documents for the individual representative|
|»»»» identity_verification|object|true|none|The document to use to confirm the individual's identity.|
|»»»»» type|string|true|none|The type of document used for identity verification|
|»»»»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|»»»»» back|string|false|none|The ID of the back side of the document as represented within Checkout.com systems.|
|» business_type|string|true|none|The legal type of the company|
|processing_details|object|true|none|Seller processing details.|
|» settlement_country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2) where the settlement bank account is located|
|» target_countries|[string]|true|none|Target country codes (iso-3166-1 alpha-2) with more than 10% expected volume processing with Checkout|
|»» Country|string(iso-3166-1-alpha-2)|false|none|The country code (iso-3166-1 alpha-2)|
|» annual_processing_volume|integer|true|none|The estimated annual processing volume. In minor units without decimals.|
|» average_transaction_value|integer|true|none|The expected average transaction value. In minor units without decimals.|
|» highest_transaction_value|integer|true|none|The expected highest transaction value. In minor units without decimals.|
|» currency|string|true|none|The currency used for the processing details provided.|
|documents|object|true|none|The documents used to support the verification of business details.|
|» bank_verification|object|true|none|A document showing transactions from last 3 months|
|»» type|string|true|none|The type of document being used as bank verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» additional_document1|object|false|none|Additional space for documents to be provided when requested|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» additional_document2|object|false|none|Additional space for documents to be provided when requested|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|» additional_document3|object|false|none|Additional space for documents to be provided when requested|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
#### Enumerated Values
|Property|Value|
|---|---|
|Currency|USD|
|country_code|US|
|state|AL|
|state|AK|
|state|AZ|
|state|AR|
|state|CA|
|state|CO|
|state|CT|
|state|DE|
|state|DC|
|state|FL|
|state|GA|
|state|HI|
|state|ID|
|state|IL|
|state|IN|
|state|IA|
|state|KS|
|state|KY|
|state|LA|
|state|ME|
|state|MD|
|state|MA|
|state|MI|
|state|MN|
|state|MS|
|state|MO|
|state|MT|
|state|NE|
|state|NV|
|state|NH|
|state|NJ|
|state|NM|
|state|NY|
|state|NC|
|state|ND|
|state|OH|
|state|OK|
|state|OR|
|state|PA|
|state|RI|
|state|SC|
|state|SD|
|state|TN|
|state|TX|
|state|UT|
|state|VT|
|state|VA|
|state|WA|
|state|WV|
|state|WI|
|state|WY|
|state|AS|
|state|GU|
|state|MP|
|state|PR|
|state|VI|
|state|UM|
|country_code|AF|
|country_code|AL|
|country_code|DZ|
|country_code|AS|
|country_code|AD|
|country_code|AO|
|country_code|AI|
|country_code|AG|
|country_code|AR|
|country_code|AM|
|country_code|AW|
|country_code|AU|
|country_code|AT|
|country_code|AZ|
|country_code|BS|
|country_code|BH|
|country_code|BD|
|country_code|BB|
|country_code|BY|
|country_code|BE|
|country_code|BZ|
|country_code|BJ|
|country_code|BM|
|country_code|BT|
|country_code|BO|
|country_code|BA|
|country_code|BW|
|country_code|BR|
|country_code|BN|
|country_code|BG|
|country_code|BF|
|country_code|BI|
|country_code|CV|
|country_code|KH|
|country_code|CM|
|country_code|CA|
|country_code|KY|
|country_code|CF|
|country_code|TD|
|country_code|CL|
|country_code|CN|
|country_code|CO|
|country_code|KM|
|country_code|CD|
|country_code|CG|
|country_code|CK|
|country_code|CR|
|country_code|HR|
|country_code|CU|
|country_code|CW|
|country_code|CY|
|country_code|CZ|
|country_code|DK|
|country_code|DJ|
|country_code|DM|
|country_code|DO|
|country_code|EC|
|country_code|EG|
|country_code|SV|
|country_code|GQ|
|country_code|ER|
|country_code|EE|
|country_code|SZ|
|country_code|ET|
|country_code|FO|
|country_code|FJ|
|country_code|FI|
|country_code|FR|
|country_code|GF|
|country_code|PF|
|country_code|GA|
|country_code|GM|
|country_code|GE|
|country_code|DE|
|country_code|GH|
|country_code|GI|
|country_code|GR|
|country_code|GL|
|country_code|GD|
|country_code|GP|
|country_code|GU|
|country_code|GT|
|country_code|GG|
|country_code|GN|
|country_code|GW|
|country_code|GY|
|country_code|HT|
|country_code|HN|
|country_code|HK|
|country_code|HU|
|country_code|IS|
|country_code|IN|
|country_code|ID|
|country_code|IR|
|country_code|IQ|
|country_code|IE|
|country_code|IM|
|country_code|IL|
|country_code|IT|
|country_code|JM|
|country_code|JP|
|country_code|JE|
|country_code|JO|
|country_code|KZ|
|country_code|KE|
|country_code|KI|
|country_code|KP|
|country_code|KR|
|country_code|KW|
|country_code|KG|
|country_code|LA|
|country_code|LV|
|country_code|LB|
|country_code|LS|
|country_code|LR|
|country_code|LY|
|country_code|LI|
|country_code|LT|
|country_code|LU|
|country_code|MO|
|country_code|MG|
|country_code|MW|
|country_code|MY|
|country_code|MV|
|country_code|ML|
|country_code|MT|
|country_code|MH|
|country_code|MQ|
|country_code|MR|
|country_code|MU|
|country_code|MX|
|country_code|FM|
|country_code|MD|
|country_code|MC|
|country_code|MN|
|country_code|ME|
|country_code|MS|
|country_code|MA|
|country_code|MZ|
|country_code|MM|
|country_code|NA|
|country_code|NR|
|country_code|NP|
|country_code|NL|
|country_code|NC|
|country_code|NZ|
|country_code|NI|
|country_code|NE|
|country_code|NG|
|country_code|NU|
|country_code|NF|
|country_code|MK|
|country_code|MP|
|country_code|NO|
|country_code|OM|
|country_code|PK|
|country_code|PW|
|country_code|PA|
|country_code|PG|
|country_code|PY|
|country_code|PE|
|country_code|PH|
|country_code|PL|
|country_code|PT|
|country_code|PR|
|country_code|QA|
|country_code|RE|
|country_code|RO|
|country_code|RU|
|country_code|RW|
|country_code|BL|
|country_code|SH|
|country_code|KN|
|country_code|LC|
|country_code|PM|
|country_code|VC|
|country_code|WS|
|country_code|SM|
|country_code|ST|
|country_code|SA|
|country_code|SN|
|country_code|RS|
|country_code|SC|
|country_code|SL|
|country_code|SG|
|country_code|BQ|
|country_code|SX|
|country_code|SK|
|country_code|SI|
|country_code|SB|
|country_code|SO|
|country_code|ZA|
|country_code|GS|
|country_code|SS|
|country_code|ES|
|country_code|LK|
|country_code|SD|
|country_code|SR|
|country_code|SE|
|country_code|CH|
|country_code|SY|
|country_code|TW|
|country_code|TJ|
|country_code|TZ|
|country_code|TH|
|country_code|TL|
|country_code|TG|
|country_code|TK|
|country_code|TO|
|country_code|TT|
|country_code|TN|
|country_code|TR|
|country_code|TM|
|country_code|TC|
|country_code|TV|
|country_code|UG|
|country_code|UA|
|country_code|AE|
|country_code|GB|
|country_code|US|
|country_code|UY|
|country_code|UZ|
|country_code|VU|
|country_code|VA|
|country_code|VE|
|country_code|VN|
|country_code|VG|
|country_code|VI|
|country_code|WF|
|country_code|EH|
|country_code|YE|
|country_code|ZM|
|country_code|ZW|
|Representative Role|ubo|
|type|passport|
|type|national_identity_card|
|type|driving_license|
|type|citizen_card|
|type|residence_permit|
|type|electoral_id|
|business_type|individual_or_sole_proprietorship|
|business_type|private_corporation|
|business_type|limited_liability_corporation|
|business_type|publicly_traded_corporation|
|business_type|limited_partnership|
|business_type|non_profit_entity|
|business_type|government_agency|
|business_type|regulated_financial_institution|
|business_type|sec_registered_entity|
|business_type|cftc_registered_entity|
|currency|USD|
|type|bank_statement|
USSoleTraderLite2-0
```json
{
"reference": "string",
"status": "string",
"is_draft": true,
"profile": {
"urls": [
"http://example.com"
],
"mccs": [
"string"
]
},
"contact_details": {
"phone": {
"number": 2000000000
},
"email_addresses": {
"primary": null
},
"invitee": {
"email": null
}
},
"capabilities": {},
"requirements_due": [
{
"field": "string",
"reason": "string"
}
],
"instruments": [
{}
],
"documents": {
"identity_verification": {
"type": "passport",
"front": "stringstringstringstringstrings",
"back": "stringstringstringstringstrings"
}
},
"individual": {
"trading_name": "string",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"date_of_birth": {
"day": 1,
"month": 1,
"year": 1900
},
"registered_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "AL",
"zip": "string",
"country": "st"
},
"identification": {
"national_id_number": "stringstr"
},
"financial_details": {
"annual_processing_volume": 0,
"average_transaction_value": 0,
"highest_transaction_value": 0,
"currency": "USD"
}
}
}
```
US Sole Trader - Lite (2.0)
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|true|none|A unique reference you can later use to identify the sub-entity.|
|status|string|false|read-only|none|
|is_draft|boolean|false|write-only|Specifies whether the sub-entity details are in draft.
Marking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.|
|profile|object|true|none|Information about the profile of the sub-entity, primarily regarding the products/services offered.|
|» urls|[string]|true|none|A collection of website URLs the sub-entity accepts payments on.|
|»» Company website URL|string(uri)|false|none|The URL of the company's website.|
|» mccs|[any]|true|none|Select the categories that most closely describe the business|
|»» Merchant category code|number|false|none|The merchant category code (4-digit ISO 18245).|
|contact_details|object|true|none|none|
|» phone|object|true|none|none|
|»» number|any|true|none|Include the area code|
|» email_addresses|object|true|none|none|
|»» primary|any|true|none|The main email address for this sub-entity.|
|» invitee|object|false|none|none|
|»» email|any|false|none|The main email address for this sub-entity.|
|capabilities|object|false|read-only|The capabilities of the entity.|
|requirements_due|[object]|false|read-only|List of requirements due in order to be onboarded.|
|» Requirements due entry|object|false|read-only|A list of fields which require attention|
|»» field|string|false|none|The field that is needs to be addressed.|
|»» reason|string|false|none|The reason behind the field needing attention.|
|instruments|[object]|false|read-only|none|
|documents|object|false|none|A legal document used to verify identity.|
|» identity_verification|object|true|none|The document to use to confirm the individual's identity.|
|»» type|string|true|none|The type of document used for identity verification|
|»» front|string|true|none|The ID of the front side of the document as represented within Checkout.com systems.|
|»» back|string|false|none|The ID of the back side of the document as represented within Checkout.com systems.|
|individual|object|true|none|Information about the individual represented by the sub-entity.|
|» trading_name|string|true|none|The trading name of the sub-entity, also referred to as 'doing business as'.|
|» first_name|string|true|none|The representative's first name.|
|» middle_name|string|false|none|The representative's middle name. Required if appears in official docs|
|» last_name|string|true|none|The representative's last name.|
|» date_of_birth|object|true|none|The date of birth of the person according to the Gregorian calendar.|
|»» day|integer|true|none|The calendar day of the month they were born.|
|»» month|integer|true|none|The month of the year they were born.|
|»» year|integer|true|none|The year they were born.|
|» registered_address|object|true|none|The registered address of the company.|
|»» address_line1|string|true|none|The first line of the address.|
|»» address_line2|number|false|none|The second line of the address.|
|»» city|string|true|none|The address city.|
|»» state|string|true|none|The address state. This field is required for addresses based in the US. For US addresses, provide the state as an ISO 3166-1 code.|
|»» zip|string|true|none|The address zip/postal code.|
|»» country|string(iso-3166-1-alpha-2)|true|none|The country code (iso-3166-1 alpha-2)|
|» identification|object|false|none|Information about representatives of this company.|
|»» national_id_number|number|true|none|Social security number (SSN) or Individual Taxpayer Identification Number (ITIN) for non-US citizens|
|» financial_details|object|false|none|Seller financial questions and supporting documents.|
|»» annual_processing_volume|integer|false|none|The estimated annual processing volume. In minor units without decimals.|
|»» average_transaction_value|integer|false|none|The expected average transaction value. In minor units without decimals.|
|»» highest_transaction_value|integer|false|none|The expected highest transaction value. In minor units without decimals.|
|»» currency|string|false|none|The currency used for the processing details provided.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|passport|
|type|national_identity_card|
|type|driving_license|
|type|citizen_card|
|type|residence_permit|
|type|electoral_id|
|state|AL|
|state|AK|
|state|AZ|
|state|AR|
|state|CA|
|state|CO|
|state|CT|
|state|DE|
|state|DC|
|state|FL|
|state|GA|
|state|HI|
|state|ID|
|state|IL|
|state|IN|
|state|IA|
|state|KS|
|state|KY|
|state|LA|
|state|ME|
|state|MD|
|state|MA|
|state|MI|
|state|MN|
|state|MS|
|state|MO|
|state|MT|
|state|NE|
|state|NV|
|state|NH|
|state|NJ|
|state|NM|
|state|NY|
|state|NC|
|state|ND|
|state|OH|
|state|OK|
|state|OR|
|state|PA|
|state|RI|
|state|SC|
|state|SD|
|state|TN|
|state|TX|
|state|UT|
|state|VT|
|state|VA|
|state|WA|
|state|WV|
|state|WI|
|state|WY|
|state|AS|
|state|GU|
|state|MP|
|state|PR|
|state|VI|
|state|UM|
|currency|USD|
PreconditionRequiredError
```json
{
"status": "428"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|status|string|false|none|none|
Purpose
```json
"donations"
```
The purpose of the payment.
This field might be required for AFT transactions depending on the card's `issuer_country`. To view a card's `issuer_country`, [retrieve the card's metadata](https://api-reference.checkout.com/#operation/requestCardMetadata!c=200&path=issuer_country&t=response).
See the [AFT documentation page](https://www.checkout.com/docs/payments/manage-payments/perform-an-account-funding-transaction) for more details.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The purpose of the payment.
This field might be required for AFT transactions depending on the card's `issuer_country`. To view a card's `issuer_country`, [retrieve the card's metadata](https://api-reference.checkout.com/#operation/requestCardMetadata!c=200&path=issuer_country&t=response).
See the [AFT documentation page](https://www.checkout.com/docs/payments/manage-payments/perform-an-account-funding-transaction) for more details.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|donations|
|*anonymous*|education|
|*anonymous*|emergency_need|
|*anonymous*|expatriation|
|*anonymous*|family_support|
|*anonymous*|financial_services|
|*anonymous*|gifts|
|*anonymous*|income|
|*anonymous*|insurance|
|*anonymous*|investment|
|*anonymous*|it_services|
|*anonymous*|leisure|
|*anonymous*|loan_payment|
|*anonymous*|medical_treatment|
|*anonymous*|other|
|*anonymous*|pension|
|*anonymous*|royalties|
|*anonymous*|savings|
|*anonymous*|travel_and_tourism|
AccountResponse
```json
{
"client_id": "cli_bvaelhppmfiufdnatam37wrfc4",
"entity_id": "ent_znj4ih5kn4fuxiaquoudv5mvwy"
}
```
The client and entity details.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|client_id|string|false|none|The client ID.|
|entity_id|string|false|none|The entity ID.|
FileResponse
```json
{
"id": "file_7ysmgfkj4ipunduud22uf73iey",
"filename": "financial-actions_ent_znj4ih5kn4fuxiaquoudv5mvwy_20220218_000000001drl_1.csv",
"format": "CSV",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/reports/rpt_lmmldzousk7etoqijqundqexa4/files/file_lmmldzousk7etoqijqundqexa4"
}
}
}
```
Details of a file from the response.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The file ID.|
|filename|string|false|none|The file name.|
|format|string|false|none|The file format.|
|_links|object|false|none|The link to retrieve the file from.|
|» self|[Link](#schemalink)|false|none|The self object.|
ReportErrorResponse
```json
{
"request_id": "0HMJGFVAQ35TL:00000117",
"error_type": "string",
"error_codes": [
"string"
]
}
```
Error Response
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|request_id|string|false|none|Request Id|
|error_type|string|false|none|The type of error.
• invalid_request = Usually with an http status code 422. The request payload failed validation.
• not_found = Usually with an http status code 404. The requested resource was not found.
|
|error_codes|[string]|false|none|Error response code. Full list of error codes below:
• invalid_some_field = Usually with an error type `invalid_request` and http status code 422 Unprocessable entity. The field `some_field` failed validation. Please consult the API spec.
• some_resource_not_found = Usually with an error type `not_found`. The resource you are trying to get does not exist.
|
ReportListResponse
```json
{
"count": 1,
"limit": 5,
"data": [
{
"id": "rpt_lmmldzousk7etoqijqundqexa4",
"created_on": "2022-02-18T13:00:12.357Z",
"last_modified_on": "2022-02-18T13:16:12.357Z",
"type": "Authentication",
"description": "Reconciliation Report for X.",
"account": {
"client_id": "cli_bvaelhppmfiufdnatam37wrfc4",
"entity_id": "ent_znj4ih5kn4fuxiaquoudv5mvwy"
},
"tags": [
"payout_id:pay_123456789"
],
"from": "2022-02-17T12:00:00Z",
"to": "2022-02-18T12:00:00Z",
"files": [
{
"id": "file_7ysmgfkj4ipunduud22uf73iey",
"filename": "financial-actions_ent_znj4ih5kn4fuxiaquoudv5mvwy_20220218_000000001drl_1.csv",
"format": "CSV",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/reports/rpt_lmmldzousk7etoqijqundqexa4/files/file_lmmldzousk7etoqijqundqexa4"
}
}
}
],
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/reports/rpt_lmmldzousk7etoqijqundqexa4"
}
}
}
],
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/reports?entity_id=ent_znj4ih5kn4fuxiaquoudv5mvwy&created_after=2022-02-17T00:00:00.000Z&limit=5"
},
"next": {
"href": "https://{prefix}.api.checkout.com/reports?pagination_token=NaZMwq3KbreYcXg0dg752Dg8ps4orkwVK9pj9WFzkXk8rPoR32Wf74QWX0EkZ&entity_id=ent_znj4ih5kn4fuxiaquoudv5mvwy&created_after=2022-02-17T00:00:00.000Z&limit=5"
}
}
}
```
The list of reports in the response.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|count|integer(int32)|false|none|The total number of reports on the current page.|
|limit|integer(int32)|false|none|The maximum number of results included per page.|
|data|[[ReportResponse](#schemareportresponse)]|false|none|The list of reports from the current page.|
|_links|object|false|none|The links object.|
|» self|[Link](#schemalink)|false|none|The self object.|
|» next|[Link](#schemalink)|false|none|The next object.|
ReportResponse
```json
{
"id": "rpt_lmmldzousk7etoqijqundqexa4",
"created_on": "2022-02-18T13:00:12.357Z",
"last_modified_on": "2022-02-18T13:16:12.357Z",
"type": "Authentication",
"description": "Reconciliation Report for X.",
"account": {
"client_id": "cli_bvaelhppmfiufdnatam37wrfc4",
"entity_id": "ent_znj4ih5kn4fuxiaquoudv5mvwy"
},
"tags": [
"payout_id:pay_123456789"
],
"from": "2022-02-17T12:00:00Z",
"to": "2022-02-18T12:00:00Z",
"files": [
{
"id": "file_7ysmgfkj4ipunduud22uf73iey",
"filename": "financial-actions_ent_znj4ih5kn4fuxiaquoudv5mvwy_20220218_000000001drl_1.csv",
"format": "CSV",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/reports/rpt_lmmldzousk7etoqijqundqexa4/files/file_lmmldzousk7etoqijqundqexa4"
}
}
}
],
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/reports/rpt_lmmldzousk7etoqijqundqexa4"
}
}
}
```
Report response details.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The report ID.|
|created_on|string(date-time)|false|none|The date and time the report was created.|
|last_modified_on|string(date-time)|false|none|The date the report was last modified.|
|type|string|false|none|The report type.|
|description|string|false|none|The report description.|
|account|[AccountResponse](#schemaaccountresponse)|false|none|The client and entity details.|
|tags|[string]|false|none|The list of tags for filtering.|
|from|string(date-time)|false|none|The reporting period's start date and time.|
|to|string(date-time)|false|none|The reporting period's end date and time.|
|files|[[FileResponse](#schemafileresponse)]|false|none|The list of files included in the report.|
|_links|object|false|none|The links object.|
|» self|[Link](#schemalink)|false|none|The self object.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|Authentication|
|type|Balance|
|type|BalanceBreakdown|
|type|BankPayouts|
|type|CardPayouts|
|type|Disputes|
|type|FinancialActions|
|type|FinancialActionsByPayout|
|type|FraudDetection|
|type|IssuingAuthorizations|
|type|IssuingCards|
|type|IssuingChargebacks|
|type|IssuingPresentments|
|type|IssuingSettlementActivity|
|type|IssuingSettlementSummary|
|type|Manifest|
|type|Payments|
|type|PayoutSummary|
|type|RealTimeAccountUpdater|
|type|ReportedFraudulentTransactions|
|type|Retrievals|
|type|SettlementBreakdown|
|type|SettlementStatement|
CardSourcePrism
```json
{
"type": "card",
"number": "4543474002249996",
"expiry_month": 6,
"expiry_year": 2025,
"name": "Bruce Wayne",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
}
```
card
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type|
|number|string|true|none|The card number (without separators)|
|expiry_month|integer|true|none|The expiry month of the card|
|expiry_year|integer|true|none|The expiry year of the card|
|name|string|false|none|The name of the cardholder|
|billing_address|[Address](#schemaaddress)|false|none|The billing address of the cardholder|
|phone|[PhoneNumber](#schemaphonenumber)|false|none|The phone number of the cardholder|
CustomerSourcePrism
```json
{
"type": "customer",
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44"
}
```
customer
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type|
|id|string|true|none|The customer's identifier.|
IdSourcePrism
```json
{
"type": "id",
"id": "src_wmlfc3zyhqzehihu7giusaaawu",
"cvv": "956"
}
```
id
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type|
|id|string|true|none|The payment source identifier (e.g., a card source identifier)|
|cvv|string|false|none|The card verification value/code (for card sources). 3 digits, except for American Express (4 digits)|
RiskPaymentRequestSource
```json
{
"type": "token",
"token": "tok_ubfj2q76miwundwlk72vxt2i7q",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"store_for_future_use": false,
"account_holder": {}
}
```
The source of the payment.
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[PaymentRequestTokenSource](#schemapaymentrequesttokensource)|false|none|A token payment source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[IdSourcePrism](#schemaidsourceprism)|false|none|An existing payment source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[CardSourcePrism](#schemacardsourceprism)|false|none|A card payment source|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[CustomerSourcePrism](#schemacustomersourceprism)|false|none|A customer source|
Segment
```json
{
"brand": "Acme Corporation",
"business_category": "Inward Payments",
"market": "UK"
}
```
The dimension details about business segment for payment request. At least one dimension required.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|brand|string|false|none|The brand of business segment.|
|business_category|string|false|none|The category of business segment.|
|market|string|false|none|The market of business segment.|
ServerTimestamp
```json
"2019-08-24T14:15:22Z"
```
Read-only UTC timestamp, automatically assigned by us
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string(date-time)|false|read-only|Read-only UTC timestamp, automatically assigned by us|
SessionsBillingDescriptor
```json
{
"name": "SUPERHEROES.COM"
}
```
An optional dynamic billing descriptor.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|true|none|A dynamic description of the payment that replaces the Merchant Name that is displayed in 3DS Challenge window. Applies to card payments only. Special characters allowed: `.` `!` `*` `-` `=` `_` `@`|
SimulatorAvailableRequirement
```json
{
"field": "individual.identification.document",
"type": "string"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|field|string|false|none|The public path of the requirement field.|
|type|string|false|none|The data type of the field.|
SimulatorErrorResponse
```json
{
"error_codes": [
"invalid_status"
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|error_codes|[string]|false|none|Error codes describing what went wrong.|
SimulatorRunScenarioResponse
```json
{
"entity_id": "ent_w4jelhppmfiufdnatam37wrfc4",
"scenario_id": "go_active",
"scenario_name": "Go Active",
"previous_status": "RequirementsDue",
"current_status": "Active",
"requirements_due": [
"individual.identification.document"
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|entity_id|string|false|none|The ID of the entity.|
|scenario_id|string|false|none|The ID of the scenario that was run.|
|scenario_name|string|false|none|The name of the scenario that was run.|
|previous_status|string|false|none|The entity status before the scenario ran.|
|current_status|string|false|none|The entity status after the scenario ran.|
|requirements_due|[string]|false|none|Requirement fields applied by the scenario, if any.|
SimulatorScenario
```json
{
"id": "go_active",
"name": "Go Active",
"description": "Transitions the entity to active status.",
"action": "set_status",
"status": "active",
"requirements_due": [
"individual.identification.document"
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The unique identifier of the scenario.|
|name|string|false|none|Human-readable name of the scenario.|
|description|string|false|none|Description of what the scenario does.|
|action|string|false|none|The action type performed by this scenario.|
|status|string|false|none|The resulting entity status after the scenario runs. Empty string for non-status actions.|
|requirements_due|[string]|false|none|Requirement fields applied when the scenario runs, if any.|
SimulatorSetRequirementsDueRequest
```json
{
"fields": [
"individual.identification.document"
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|fields|[string]|true|none|The requirement fields to mark as due.
Call the [List available requirements](/#tag/Onboarding-Simulator/paths/~1simulate~1requirements-due/get) endpoint for a list of valid values.|
SimulatorSetRequirementsDueResponse
```json
{
"entity_id": "ent_w4jelhppmfiufdnatam37wrfc4",
"previous_status": "Active",
"current_status": "requirements_due",
"requirements_due": [
"individual.identification.document"
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|entity_id|string|false|none|The ID of the entity.|
|previous_status|string|false|none|The status before the update.|
|current_status|string|false|none|The status after the update.|
|requirements_due|[string]|false|none|The requirement fields that are now marked as due.|
SimulatorSetStatusRequest
```json
{
"status": "active"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|status|string|true|none|The status to set on the entity.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|draft|
|status|requirements_due|
|status|pending|
|status|active|
|status|restricted|
|status|rejected|
|status|inactive|
SimulatorSetStatusResponse
```json
{
"entity_id": "ent_w4jelhppmfiufdnatam37wrfc4",
"previous_status": "Pending",
"current_status": "Active"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|entity_id|string|false|none|The ID of the entity.|
|previous_status|string|false|none|The status before the update.|
|current_status|string|false|none|The status after the update.|
Acs
```json
{
"reference_number": "ACSRefNum1234",
"transaction_id": "be481bd1-1f1d-4ef8-9fa8-0fb2a38e3c87",
"operator_id": "ACSRefNum1234",
"url": "https://server.acsdomainname.com",
"signed_content": "eyJ4NWMiOlsiTUlJQjdEQ0NBWktnQXdJQkFnSVZBSzIxWEc5SVBCL083QzZjUTBvRlJJUkIwWDI0TUFvR0NDcUdTTTQ5QkFNQ01INHhDekFKQm",
"challenge_mandated": true,
"authentication_type": "string",
"challenge_cancel_reason": "cardholder_cancel",
"interface": "native_ui",
"ui_template": "text",
"challenge_cancel_reason_code": "string"
}
```
The access control server (ACS) information. Can be empty if the session is still pending or if communication with the ACS failed. This will be available when the channel data and issuer fingerprint result have been provided.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference_number|string|true|none|EMVCo-assigned unique identifier to track approved ACS|
|transaction_id|string|true|none|Universally unique transaction identifier assigned by the ACS|
|operator_id|string|true|none|DS assigned ACS identifier|
|url|string|false|none|Fully qualified URL of the ACS to be used for the challenge|
|signed_content|string|false|none|Contains the JSON web signature (JWS) compact serialization created by the ACS for a challenged app authentication. (Example has been truncated for readability.)|
|challenge_mandated|boolean|true|none|Indicates whether a challenge is required for the transaction to be authorized|
|authentication_type|string|false|none|The type of authentication as returned from the ACS provider.
• 01 = Static
• 02 = Dynamic
• 03 = OOB
• 04-79 = Reserved for EMVCo future use
• 80-99 = Reserved for DS use|
|challenge_cancel_reason|string|false|none|Indicator informing the ACS and the DS that the authentication has been cancelled|
|interface|string|false|none|none|
|ui_template|string|false|none|none|
|challenge_cancel_reason_code|string|false|none|Indicator in the 3D Secure 2 RReq when the challenge is cancelled|
#### Enumerated Values
|Property|Value|
|---|---|
|challenge_cancel_reason|cardholder_cancel|
|challenge_cancel_reason|transaction_timed_out|
|challenge_cancel_reason|challenge_timed_out|
|challenge_cancel_reason|transaction_error|
|challenge_cancel_reason|unknown|
|challenge_cancel_reason|sdk_timed_out|
|interface|native_ui|
|interface|html|
|ui_template|text|
|ui_template|single_select|
|ui_template|multi_select|
|ui_template|oob|
|ui_template|html_other|
Amount
```json
120
```
The amount in the minor currency.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|integer(int64)|false|none|The amount in the minor currency.|
App
```json
{
"channel": "app",
"sdk_app_id": "dbd64fcb-c19a-4728-8849-e3d50bfdde39",
"sdk_max_timeout": 5,
"sdk_ephem_pub_key": {
"kty": "EC",
"crv": "P-256",
"x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
"y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0"
},
"sdk_reference_number": "3DS_LOA_SDK_PPFU_020100_00007",
"sdk_encrypted_data": "",
"sdk_transaction_id": "b2385523-a66c-4907-ac3c-91848e8c0067",
"sdk_interface_type": "native",
"sdk_ui_elements": [
"text"
]
}
```
app
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|channel|string|true|none|none|
|sdk_app_id|string|true|none|Universally unique ID created upon all installations and updates of the 3DS Requestor App on a consumer device. This will be newly generated and stored by the 3DS SDK for each installation or update.|
|sdk_max_timeout|integer|true|none|Indicates maximum amount of time (in minutes) for all exchanges|
|sdk_ephem_pub_key|[SdkEphemeralPublicKey](#schemasdkephemeralpublickey)|true|none|Public key component of the ephemeral key pair generated by the 3DS SDK and used to establish session keys between the 3DS SDK and ACS. Refer to https://tools.ietf.org/html/rfc7517#appendix-A.1|
|sdk_reference_number|string|true|none|Identifies the vendor and version for the 3DS SDK that is integrated in a 3DS Requestor App, assigned by EMVCo when the 3DS SDK is approved.|
|sdk_encrypted_data|string|true|none|A JSON web encryption (JWE) object in compact serialization, containing data encrypted by the SDK for the Directory Server to decrypt.|
|sdk_transaction_id|string|true|none|Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction|
|sdk_interface_type|string|true|none|Lists all of the SDK interface types that the device supports for displaying specific challenge user interfaces within the SDK|
|sdk_ui_elements|[string]|true|none|Lists all the user interface elements that the cardholder's device supports for displaying specific challenge user interfaces within the SDK|
#### Enumerated Values
|Property|Value|
|---|---|
|channel|app|
|sdk_interface_type|native|
|sdk_interface_type|html|
|sdk_interface_type|both|
Approved
```json
false
```
Whether the authentication was successful. This will only be set if the Session is in a final state
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|boolean|false|none|Whether the authentication was successful. This will only be set if the Session is in a final state|
AuthenticationType
```json
"regular"
```
Indicates the type of payment this session is for. Please note the spelling of `installment` consists of two `l`s.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|Indicates the type of payment this session is for. Please note the spelling of `installment` consists of two `l`s.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|regular|
|*anonymous*|recurring|
|*anonymous*|installment|
|*anonymous*|maintain_card|
|*anonymous*|add_card|
Browser
```json
{
"channel": "browser",
"three_ds_method_completion": "U",
"accept_header": "Accept: *.*, q=0.1",
"java_enabled": true,
"javascript_enabled": true,
"language": "FR-fr",
"color_depth": "16",
"screen_height": "1080",
"screen_width": "1920",
"timezone": "60",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
"ip_address": "1.12.123.255",
"iframe_payment_allowed": true,
"user_agent_client_hint": "'Sec-CH-UA: \" Not A;Brand\";v=\"99\", \"Chromium\";v=\"96\", \"Google Chrome\";v=\"96\"'\n"
}
```
browser
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|channel|string|true|none|none|
|three_ds_method_completion|string|false|none|Indicates whether the 3DS Method successfully completed
• Y = Successfully completed
• N = Did not successfully complete
• U = Unavailable (3DS Method URL was not present in the preparation response (PRes) message data for the card range associated with the cardholder's account number)|
|accept_header|string|true|none|Exact content of the HTTP accept headers as sent to the 3DS Requestor from the cardholder’s browser|
|java_enabled|boolean|true|none|Boolean that represents the ability of the cardholder's browser to execute Java. Value is returned from the `navigator.javaEnabled` property.|
|javascript_enabled|boolean|true|none|Boolean that represents the ability of the cardholder's browser to execute Javascript. Value is returned from the `navigator.javascriptEnabled` property. *only applicable/required for authentication performed using 3DS 2.2. If authentications results in processing on 2.1 or lower, this field will be disregarded.|
|language|string|true|none|Value representing the browser language as defined in IETF BCP47. Returned from the `navigator.language` property.|
|color_depth|string|true|none|Value representing the bit depth of the color palette for displaying images, in bits per pixel. Obtained from the cardholder's browser from the `screen.colorDepth` property.|
|screen_height|string|true|none|Total height of the cardholder’s screen in pixels. Value is returned from the `screen.height` property.|
|screen_width|string|true|none|Total width of the cardholder’s screen in pixels. Value is returned from the `screen.width` property.|
|timezone|string|true|none|Time difference between UTC time and the local time of the cardholder's browser, in minutes.|
|user_agent|string|true|none|Exact content of the HTTP user-agent header|
|ip_address|string|true|none|IP address of the browser as returned by the HTTP headers to the 3DS Requestor|
|iframe_payment_allowed|boolean|false|none|Whether the Payment API is enabled for all parent frames. This is required for Google SPA support in hosted sessions.|
|user_agent_client_hint|string|false|none|The raw Sec-CH-UA header value. This can improve Google SPA support.|
#### Enumerated Values
|Property|Value|
|---|---|
|channel|browser|
|three_ds_method_completion|Y|
|three_ds_method_completion|N|
|three_ds_method_completion|U|
CardholderAccountInfo
```json
{
"purchase_count": 10,
"account_age": "no_account",
"add_card_attempts": 10,
"shipping_address_age": "this_transaction",
"account_name_matches_shipping_name": true,
"suspicious_account_activity": true,
"transactions_today": 10,
"authentication_method": "no_authentication",
"cardholder_account_age_indicator": "no_account,",
"account_change": "2019-08-24T14:15:22Z",
"account_change_indicator": "this_transaction",
"account_date": "2019-08-24T14:15:22Z",
"account_password_change": "2019-08-24T14:15:22Z",
"account_password_change_indicator": "no_change",
"transactions_per_year": 2,
"payment_account_age": "2019-08-24T14:15:22Z",
"shipping_address_usage": "2019-08-24T14:15:22Z",
"account_type": "not_applicable",
"account_id": "string",
"three_ds_requestor_authentication_info": {
"three_ds_req_auth_method": "no_threeds_requestor_authentication_occurred",
"three_ds_req_auth_timestamp": "2019-08-24T14:15:22Z",
"three_ds_req_auth_data": "string"
}
}
```
Additional information about the Cardholder's account.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|purchase_count|number|false|none|The number of purchases with this cardholder's account during the last six months.|
|account_age|string|false|none|The length of time that the payment account was enrolled in the cardholder's account.|
|add_card_attempts|number|false|none|The number of Add Card attempts in the last 24 hours.|
|shipping_address_age|string|false|none|Indicates when the shipping address used for this transaction was first used.|
|account_name_matches_shipping_name|boolean|false|none|Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.|
|suspicious_account_activity|boolean|false|none|Indicates whether suspicious activity on the cardholder account has been observed.|
|transactions_today|number|false|none|The number of transactions (successful and abandoned) for the cardholder account across all payment accounts in the previous 24 hours|
|authentication_method|string|false|none|Information about how the cardholder was authenticated before or during the transaction.|
|cardholder_account_age_indicator|string|false|none|The length of time the cardholder has held the account with the 3DS Requestor.|
|account_change|string(date-time)|false|none|The UTC date and time the cardholder’s account with the 3DS Requestor was last changed, in ISO 8601 format.
Changes that affect this value include:
- updating the billing or shipping address
- adding a new payment account
- adding a new user|
|account_change_indicator|string|false|none|The amount of time since the cardholder’s account information with the 3DS Requestor was last changed.
Changes that affect this value include:
- updating the billing or shipping address
- adding a new payment account
- adding a new user|
|account_date|string(date-time)|false|none|The UTC date and time the cardholder opened the account with the 3DS Requestor, in ISO 8601 format.|
|account_password_change|string(date-time)|false|none|The UTC date and time the cardholder’s account with the 3DS Requestor was last reset or had a password change, in ISO 8601 format.|
|account_password_change_indicator|string|false|none|The amount of time since the cardholder’s account with the 3DS Requestor was last reset or had a password change.|
|transactions_per_year|integer|false|none|The number of transactions associated with the cardholder's account with the 3DS Requestor in the previous year. This value includes both successful and abandoned transactions, across all payment accounts.
Set this value to `999` if the number of transactions is `1000` or greater.|
|payment_account_age|string(date-time)|false|none|The UTC date and time the payment account was enrolled in the cardholder’s account with the 3DS Requestor, in ISO 8601 format.|
|shipping_address_usage|string(date-time)|false|none|The UTC date and time the shipping address used for the transaction was first used with the 3DS Requestor, in ISO 8601 format.|
|account_type|string|false|none|The type of account, in the case of a card product with multiple accounts.|
|account_id|string|false|none|Additional information about the account optionally provided by the 3DS Requestor.|
|three_ds_requestor_authentication_info|[ThreeDsRequestorAuthenticationInfo](#schemathreedsrequestorauthenticationinfo)|false|none|Information about how the 3DS Requestor authenticated the cardholder before or during the transaction.|
#### Enumerated Values
|Property|Value|
|---|---|
|account_age|no_account|
|account_age|created_during_transaction|
|account_age|less_than_thirty_days|
|account_age|thirty_to_sixty_days|
|account_age|more_than_sixty_days|
|shipping_address_age|this_transaction|
|shipping_address_age|less_than_thirty_days|
|shipping_address_age|thirty_to_sixty_days|
|shipping_address_age|more_than_sixty_days|
|authentication_method|no_authentication|
|authentication_method|own_credentials|
|authentication_method|federated_id|
|authentication_method|issuer_credentials|
|authentication_method|third_party_authentication|
|authentication_method|fido|
|cardholder_account_age_indicator|no_account,|
|cardholder_account_age_indicator|this_transaction|
|cardholder_account_age_indicator|less_than_thirty_days|
|cardholder_account_age_indicator|thirty_to_sixty_days|
|cardholder_account_age_indicator|more_than_sixty_days|
|account_change_indicator|this_transaction|
|account_change_indicator|less_than_thirty_days|
|account_change_indicator|thirty_to_sixty_days|
|account_change_indicator|more_than_sixty_days|
|account_password_change_indicator|no_change|
|account_password_change_indicator|this_transaction|
|account_password_change_indicator|less_than_thirty_days|
|account_password_change_indicator|thirty_to_sixty_days|
|account_password_change_indicator|more_than_sixty_days|
|account_type|not_applicable|
|account_type|credit|
|account_type|debit|
CardInfo
```json
{
"instrument_id": "src_ubfj2q76miwundwlk72vxt2i7q",
"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
"metadata": {
"card_type": "CREDIT",
"card_category": "CONSUMER",
"issuer_name": "Checkout",
"issuer_country": "GB",
"product_id": "MDS",
"product_type": "Debit MasterCard® Card"
}
}
```
Details related to the Session source. This property should always be in the response, unless a `card` source was used and communication with Checkout.com's Vault was not possible.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|instrument_id|string|true|none|The identifier of the card instrument.|
|fingerprint|string|true|none|A token that can uniquely identify this card across all customers.|
|metadata|object|false|none|Additional details for this card|
|» card_type|string|false|none|The card type|
|» card_category|string|false|none|The card category.|
|» issuer_name|string|false|none|The card issuer's name.|
|» issuer_country|string|false|none|The two letter alpha country code of the card issuer.|
|» product_id|string|false|none|The issuer/card scheme product identifier.|
|» product_type|string|false|none|The issuer/card scheme product type.|
#### Enumerated Values
|Property|Value|
|---|---|
|card_type|CREDIT|
|card_type|DEBIT|
|card_type|PREPAID|
|card_type|CHARGE|
|card_type|DEFERRED DEBIT|
|card_category|CONSUMER|
|card_category|COMMERCIAL|
CardSource
```json
{
"type": "card",
"scheme": "amex",
"number": "4242424242424242",
"expiry_month": 12,
"expiry_year": 2077,
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "ABC building",
"address_line3": "14 Wells Mews",
"city": "London",
"state": "ENG",
"zip": "SW1A 1AA",
"country": "GB"
},
"home_phone": {
"country_code": "234",
"number": "0204567895"
},
"mobile_phone": {
"country_code": "234",
"number": "0204567895"
},
"work_phone": {
"country_code": "234",
"number": "0204567895"
},
"email": "bruce.wayne@email.com",
"name": "Bruce Wayne",
"stored": true
}
```
card
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type|
|scheme|string|false|none|Indicates the cardholder scheme choice|
|number|string|true|none|The card number.|
|expiry_month|integer|true|none|The expiry month of the card.|
|expiry_year|integer|true|none|The expiry year of the card.|
|billing_address|[SessionAddress](#schemasessionaddress)|false|none|The customer's billing address. Any special characters will be replaced.|
|home_phone|[SessionPhone](#schemasessionphone)|false|none|The cardholder's home phone number|
|mobile_phone|[SessionPhone](#schemasessionphone)|false|none|The cardholder's mobile phone number|
|work_phone|[SessionPhone](#schemasessionphone)|false|none|The cardholder's work phone number|
|email|string|false|none|The email of the cardholder|
|name|string|false|none|The name of the cardholder. Any special characters will be replaced.|
|stored|boolean|false|none|Indicates whether this card is being submitted from your own stored card-on-file system, rather than being entered by the customer at the time of payment. Set to `true` when you provide card details that you already have on file for the customer.|
#### Enumerated Values
|Property|Value|
|---|---|
|scheme|amex|
|scheme|cartes_bancaires|
|scheme|diners|
|scheme|mastercard|
|scheme|visa|
|scheme|discover|
|scheme|upi|
|scheme|jcb|
Category
```json
"payment"
```
Indicates the category of the authentication request
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|Indicates the category of the authentication request|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|payment|
|*anonymous*|non_payment|
ChallengeIndicator
```json
"no_preference"
```
Indicates whether a challenge is requested for this session.
The following are requests for exemption:
• `low_value`
• `trusted_listing`
• `trusted_listing_prompt`
• `transaction_risk_assessment`
If an exemption cannot be applied, then the value `no_challenge_requested` will be used instead.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|Indicates whether a challenge is requested for this session.
The following are requests for exemption:
• `low_value`
• `trusted_listing`
• `trusted_listing_prompt`
• `transaction_risk_assessment`
If an exemption cannot be applied, then the value `no_challenge_requested` will be used instead.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|no_preference|
|*anonymous*|no_challenge_requested|
|*anonymous*|challenge_requested|
|*anonymous*|challenge_requested_mandate|
|*anonymous*|low_value|
|*anonymous*|trusted_listing|
|*anonymous*|trusted_listing_prompt|
|*anonymous*|transaction_risk_assessment|
|*anonymous*|data_share|
ChannelData
```json
{
"channel": "browser",
"accept_header": "Accept: *.*, q=0.1",
"java_enabled": true,
"javascript_enabled": true,
"language": "FR-fr",
"color_depth": "16",
"screen_height": "1080",
"screen_width": "1920",
"timezone": "60",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
"three_ds_method_completion": "Y",
"ip_address": "1.12.123.255",
"iframe_payment_allowed": true,
"user_agent_client_hint": "Sec-CH-UA: \" Not A;Brand\";v=\"99\", \"Chromium\";v=\"96\", \"Google Chrome\";v=\"96\""
}
```
The information gathered from the environment used to initiate the session
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[Browser](#schemabrowser)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[App](#schemaapp)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[MerchantInitiated](#schemamerchantinitiated)|false|none|none|
CompletionInfo
```json
{
"type": "non_hosted",
"callback_url": "https://merchant.com/callback"
}
```
The redirect information needed for callbacks or redirects after the payment is completed
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[HostedCompletionInfo](#schemahostedcompletioninfo)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[NonHostedCompletionInfo](#schemanonhostedcompletioninfo)|false|none|none|
CreateSessionAcceptedResponse
```json
{
"session_secret": "sek_Dal7UyiH8rIFXA4PfgiIk2jUyQkVDeEWgVBEL4TsRTE=",
"id": "sid_y3oqhf46pyzuxjbcn2giaqnb44",
"transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c",
"scheme": "visa",
"amount": 120,
"currency": "USD",
"completed": false,
"authentication_type": "regular",
"authentication_category": "payment",
"status": "pending",
"next_actions": [
"collect_channel_data"
],
"protocol_version": "2.2.0",
"account_info": {
"purchase_count": 10,
"account_age": "no_account",
"add_card_attempts": 10,
"shipping_address_age": "this_transaction",
"account_name_matches_shipping_name": true,
"suspicious_account_activity": true,
"transactions_today": 10,
"authentication_method": "no_authentication",
"cardholder_account_age_indicator": "no_account,",
"account_change": "2019-08-24T14:15:22Z",
"account_change_indicator": "this_transaction",
"account_date": "2019-08-24T14:15:22Z",
"account_password_change": "2019-08-24T14:15:22Z",
"account_password_change_indicator": "no_change",
"transactions_per_year": 2,
"payment_account_age": "2019-08-24T14:15:22Z",
"shipping_address_usage": "2019-08-24T14:15:22Z",
"account_type": "not_applicable",
"account_id": "string",
"three_ds_requestor_authentication_info": {
"three_ds_req_auth_method": "no_threeds_requestor_authentication_occurred",
"three_ds_req_auth_timestamp": "2019-08-24T14:15:22Z",
"three_ds_req_auth_data": "string"
}
},
"merchant_risk_info": {
"delivery_email": "brucewayne@email.com",
"delivery_timeframe": "electronic_delivery",
"is_preorder": true,
"is_reorder": false,
"shipping_indicator": "billing_address",
"reorder_items_indicator": "first_time_ordered",
"pre_order_purchase_indicator": "merchandise_available",
"pre_order_date": "2019-08-24T14:15:22Z",
"gift_card_amount": "123",
"gift_card_currency": "USD",
"gift_card_count": "02"
},
"reference": "ORD-5023-4E89",
"transaction_type": "goods_service",
"card": {
"instrument_id": "src_ubfj2q76miwundwlk72vxt2i7q",
"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
"metadata": {
"card_type": "CREDIT",
"card_category": "CONSUMER",
"issuer_name": "Checkout",
"issuer_country": "GB",
"product_id": "MDS",
"product_type": "Debit MasterCard® Card"
}
},
"recurring": {
"days_between_payments": 28,
"expiry": "20220901"
},
"installment": {
"number_of_payments": 2,
"days_between_payments": 28,
"expiry": "20220901"
},
"initial_transaction": {
"acs_transaction_id": "stringstringstringstringstringstring",
"authentication_method": "frictionless_authentication",
"authentication_timestamp": "2023-02-06T15:00:00.000Z",
"authentication_data": "string",
"initial_session_id": "sid_p6prbhogijnuxgv4grm3ber55u"
},
"_links": {
"redirect_url": {
"href": "http://3ds2.checkout.com/interceptor/sid_y3oqhf46pyzuxjbcn2giaqnb44"
},
"issuer_fingerprint": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/issuer-fingerprint"
},
"collect_channel_data": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/collect-data"
},
"three_ds_method_url": {
"href": "https://api.hsbc.com/3dsmethod?tx=123456"
},
"acs_url": {
"href": "https://api.hsbc.com/challenge"
},
"complete": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/complete"
},
"success_url": {
"href": "string"
},
"failure_url": {
"href": "string"
},
"callback_url": {
"href": "string"
},
"self": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2giaqnb441"
}
},
"authentication_date": "2019-08-24T14:15:22Z",
"challenge_indicator": "no_preference",
"optimization": {
"optimized": true,
"framework": "acceptance_rates",
"optimized_properties": [
{
"field": "challenge_indicator",
"original_value": "trusted_listing",
"optimized_value": "transaction_risk_assessment"
}
]
},
"preferred_experiences": {
"google_spa": {
"status": "available",
"reason": [
"Invalid response"
]
},
"3ds": {
"status": "available",
"reason": [
"Invalid response"
]
}
},
"experience": "3ds",
"google_spa": {
"token": {
"number": "string",
"expiry_month": 0,
"expiry_year": 0
}
},
"ds": {
"ds_id": "A000000003",
"reference_number": "VISA.V 17 0003",
"transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c"
},
"certificates": {
"ds_public": "eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2IiwieCI6Ik1LQkNUTkljS1VTRGlpMTF5U3MzNTI2aURaOEFpVG83VHU2S1BBcXY3RDQiLCJ5IjoiNEV0bDZTUlcyWWlMVXJONXZmdlZIdWhwN3g4UHhsdG1XV2xiYk00SUZ5TSIsInVzZSI6ImVuYyIsImtpZCI6IjEifQ",
"ca_public": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxWEvDZRhKEefZ5sQS7RJZXWbSOPxus-ZyLQjtmrrAQawnKI-AG8BKpVdZVGlpcdxCnGbCIy8CKk2Oi7Mgdqfv5R_4_jI7yl4j7Svmh1Sw934eeF9RyB59Ihl36Y0pNfVW9hBqJuq2o8ulrA1TOtpTpje23CY8sjFE5QnJm1evZRB_ZZQ1txl4nrAiHkno4cVJPouBesryVGVQ0zi1bM0P-05Ydgksvph-1nyjnDldD68mejVF69Tijxa22b6BUCXEuPfbXZcW2NpM_W3msnvKiTWFaMlnIzGYIoFnAnCIVU7Min6CPn565tv0iyIt8BrcezsGzefUw17NEq0J4tCvWwIDAQAB",
"ca_public_all": [
"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxWEvDZRhKEefZ5sQS7RJZXWbSOPxus-ZyLQjtmrrAQawnKI-AG8BKpVdZVGlpcdxCnGbCIy8CKk2Oi7Mgdqfv5R_4_jI7yl4j7Svmh1Sw934eeF9RyB59Ihl36Y0pNfVW9hBqJuq2o8ulrA1TOtpTpje23CY8sjFE5QnJm1evZRB_ZZQ1txl4nrAiHkno4cVJPouBesryVGVQ0zi1bM0P-05Ydgksvph-1nyjnDldD68mejVF69Tijxa22b6BUCXEuPfbXZcW2NpM_W3msnvKiTWFaMlnIzGYIoFnAnCIVU7Min6CPn565tv0iyIt8BrcezsGzefUw17NEq0J4tCvWwIDAQAB"
]
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|session_secret|[SessionSecret](#schemasessionsecret)|true|none|A base64 encoded value prefixed with `sek_` that gives access to client-side operations for a single authentication within the Sessions API. This value is returned as the `session_secret` when requesting a session.|
|id|[SessionId](#schemasessionid)|true|none|Session unique identifier|
|transaction_id|string|true|none|The transaction identifier that needs to be provided when communicating directly with the Access Control Server (ACS)|
|scheme|string|true|none|Indicates the scheme this authentication is carried out against|
|amount|[Amount](#schemaamount)|true|none|The amount in the minor currency.|
|currency|[Currency](#schemacurrency)|true|none|The three-letter ISO currency code|
|completed|boolean|false|none|Specifies if the session was completed.|
|authentication_type|[AuthenticationType](#schemaauthenticationtype)|true|none|Indicates the type of payment this session is for. Please note the spelling of `installment` consists of two `l`s.|
|authentication_category|[Category](#schemacategory)|true|none|Indicates the category of the authentication request|
|status|string|true|none|The status of the session.|
|next_actions|[string]|true|none|Specifies which action to take in order to complete the session.
The `redirect_cardholder` action is only applicable for hosted sessions.|
|protocol_version|[ProtocolVersion](#schemaprotocolversion)|true|none|The protocol version number of the specification used by the API for authentication|
|account_info|[CardholderAccountInfo](#schemacardholderaccountinfo)|false|none|Additional information about the Cardholder's account.|
|merchant_risk_info|[MerchantRiskInfo](#schemamerchantriskinfo)|false|none|Additional information about the cardholder's purchase.|
|reference|[Reference](#schemareference)|false|none|A reference you can later use to identify this payment, such as an order number. **Do not pass sensitive information in this field e.g. card details**|
|transaction_type|[TransactionType](#schematransactiontype)|false|none|Identifies the type of transaction being authenticated|
|card|[CardInfo](#schemacardinfo)|false|none|Details related to the Session source. This property should always be in the response, unless a `card` source was used and communication with Checkout.com's Vault was not possible.|
|recurring|[Recurring](#schemarecurring)|false|none|Details of a recurring authentication. This property is needed only for a recurring authentication type. Value will be ignored in any other cases.|
|installment|[Installment](#schemainstallment)|false|none|Details of an installment authentication. This property is needed only for an installment authentication type. Value will be ignored in any other cases.|
|initial_transaction|[InitialTransaction](#schemainitialtransaction)|false|none|Details of a previous transaction|
|_links|[CreateSessionLinks](#schemacreatesessionlinks)|true|none|none|
|authentication_date|string(date-time)|true|none|Authentication date and time|
|challenge_indicator|string|true|none|Indicates the preference for whether or not a 3DS challenge should be performed. The customer’s bank has the final say on whether or not the customer receives the challenge|
|optimization|object|false|none|The information about the optimization options selected|
|» optimized|boolean|false|none|Indicates if any optimization has been applied|
|» framework|string|false|none|The optimization framework applied|
|» optimized_properties|[[OptimizedProperty](#schemaoptimizedproperty)]|false|none|The collection of optimized fields|
|preferred_experiences|[PreferredExperiences](#schemapreferredexperiences)|false|none|Preferred Experiences|
|experience|[Experience](#schemaexperience)|false|none|The authentication experience that was used for processing|
|google_spa|[GoogleSpaInfo](#schemagooglespainfo)|false|none|Details of Google SPA (Secure Payment Authentication)|
|ds|[Ds](#schemads)|false|none|The directory server (DS) information. Can be empty if the session is pending or communication with the DS failed|
|certificates|[DsPublicKeys](#schemadspublickeys)|false|none|Public certificates specific to a Directory Server (DS) for encrypting device data and verifying ACS signed content. Required when channel is `app`.|
#### Enumerated Values
|Property|Value|
|---|---|
|scheme|visa|
|scheme|mastercard|
|scheme|jcb|
|scheme|amex|
|scheme|diners|
|scheme|cartes_bancaires|
|scheme|discover|
|scheme|upi|
|status|pending|
|status|processing|
|status|challenged|
|status|challenge_abandoned|
|status|expired|
|status|approved|
|status|attempted|
|status|unavailable|
|status|declined|
|status|rejected|
|challenge_indicator|no_preference|
|challenge_indicator|no_challenge_requested|
|challenge_indicator|challenge_requested|
|challenge_indicator|challenge_requested_mandate|
|framework|acceptance_rates|
CreateSessionLinks
```json
{
"redirect_url": {
"href": "http://3ds2.checkout.com/interceptor/sid_y3oqhf46pyzuxjbcn2giaqnb44"
},
"issuer_fingerprint": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/issuer-fingerprint"
},
"collect_channel_data": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/collect-data"
},
"three_ds_method_url": {
"href": "https://api.hsbc.com/3dsmethod?tx=123456"
},
"acs_url": {
"href": "https://api.hsbc.com/challenge"
},
"complete": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/complete"
},
"success_url": {
"href": "string"
},
"failure_url": {
"href": "string"
},
"callback_url": {
"href": "string"
},
"self": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2giaqnb441"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|redirect_url|object|false|none|The link to which the cardholder should be redirected. Only available when the `hosted` value is `true`.|
|» href|string|true|none|none|
CreateSessionOkResponse
```json
{
"id": "sid_y3oqhf46pyzuxjbcn2giaqnb44",
"session_secret": "sek_Dal7UyiH8rIFXA4PfgiIk2jUyQkVDeEWgVBEL4TsRTE=",
"transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c",
"scheme": "visa",
"amount": 120,
"currency": "USD",
"completed": false,
"challenged": true,
"authentication_type": "regular",
"authentication_category": "payment",
"certificates": {
"ds_public": "eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2IiwieCI6Ik1LQkNUTkljS1VTRGlpMTF5U3MzNTI2aURaOEFpVG83VHU2S1BBcXY3RDQiLCJ5IjoiNEV0bDZTUlcyWWlMVXJONXZmdlZIdWhwN3g4UHhsdG1XV2xiYk00SUZ5TSIsInVzZSI6ImVuYyIsImtpZCI6IjEifQ",
"ca_public": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxWEvDZRhKEefZ5sQS7RJZXWbSOPxus-ZyLQjtmrrAQawnKI-AG8BKpVdZVGlpcdxCnGbCIy8CKk2Oi7Mgdqfv5R_4_jI7yl4j7Svmh1Sw934eeF9RyB59Ihl36Y0pNfVW9hBqJuq2o8ulrA1TOtpTpje23CY8sjFE5QnJm1evZRB_ZZQ1txl4nrAiHkno4cVJPouBesryVGVQ0zi1bM0P-05Ydgksvph-1nyjnDldD68mejVF69Tijxa22b6BUCXEuPfbXZcW2NpM_W3msnvKiTWFaMlnIzGYIoFnAnCIVU7Min6CPn565tv0iyIt8BrcezsGzefUw17NEq0J4tCvWwIDAQAB",
"ca_public_all": [
"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxWEvDZRhKEefZ5sQS7RJZXWbSOPxus-ZyLQjtmrrAQawnKI-AG8BKpVdZVGlpcdxCnGbCIy8CKk2Oi7Mgdqfv5R_4_jI7yl4j7Svmh1Sw934eeF9RyB59Ihl36Y0pNfVW9hBqJuq2o8ulrA1TOtpTpje23CY8sjFE5QnJm1evZRB_ZZQ1txl4nrAiHkno4cVJPouBesryVGVQ0zi1bM0P-05Ydgksvph-1nyjnDldD68mejVF69Tijxa22b6BUCXEuPfbXZcW2NpM_W3msnvKiTWFaMlnIzGYIoFnAnCIVU7Min6CPn565tv0iyIt8BrcezsGzefUw17NEq0J4tCvWwIDAQAB"
]
},
"status": "challenged",
"status_reason": "ares_status",
"approved": false,
"protocol_version": "2.2.0",
"account_info": {
"purchase_count": 10,
"account_age": "no_account",
"add_card_attempts": 10,
"shipping_address_age": "this_transaction",
"account_name_matches_shipping_name": true,
"suspicious_account_activity": true,
"transactions_today": 10,
"authentication_method": "no_authentication",
"cardholder_account_age_indicator": "no_account,",
"account_change": "2019-08-24T14:15:22Z",
"account_change_indicator": "this_transaction",
"account_date": "2019-08-24T14:15:22Z",
"account_password_change": "2019-08-24T14:15:22Z",
"account_password_change_indicator": "no_change",
"transactions_per_year": 2,
"payment_account_age": "2019-08-24T14:15:22Z",
"shipping_address_usage": "2019-08-24T14:15:22Z",
"account_type": "not_applicable",
"account_id": "string",
"three_ds_requestor_authentication_info": {
"three_ds_req_auth_method": "no_threeds_requestor_authentication_occurred",
"three_ds_req_auth_timestamp": "2019-08-24T14:15:22Z",
"three_ds_req_auth_data": "string"
}
},
"merchant_risk_info": {
"delivery_email": "brucewayne@email.com",
"delivery_timeframe": "electronic_delivery",
"is_preorder": true,
"is_reorder": false,
"shipping_indicator": "billing_address",
"reorder_items_indicator": "first_time_ordered",
"pre_order_purchase_indicator": "merchandise_available",
"pre_order_date": "2019-08-24T14:15:22Z",
"gift_card_amount": "123",
"gift_card_currency": "USD",
"gift_card_count": "02"
},
"reference": "ORD-5023-4E89",
"transaction_type": "goods_service",
"next_actions": [
"redirect_cardholder"
],
"ds": {
"ds_id": "A000000003",
"reference_number": "VISA.V 17 0003",
"transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c"
},
"acs": {
"reference_number": "ACSRefNum1234",
"transaction_id": "be481bd1-1f1d-4ef8-9fa8-0fb2a38e3c87",
"operator_id": "ACSRefNum1234",
"url": "https://server.acsdomainname.com",
"signed_content": "eyJ4NWMiOlsiTUlJQjdEQ0NBWktnQXdJQkFnSVZBSzIxWEc5SVBCL083QzZjUTBvRlJJUkIwWDI0TUFvR0NDcUdTTTQ5QkFNQ01INHhDekFKQm",
"challenge_mandated": true,
"authentication_type": "string",
"challenge_cancel_reason": "cardholder_cancel",
"interface": "native_ui",
"ui_template": "text",
"challenge_cancel_reason_code": "string"
},
"response_code": "Y",
"response_status_reason": "01",
"cryptogram": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
"eci": "05",
"xid": "XSUErNftqkiTdlkpSk8p32GWOFA",
"cardholder_info": "Card declined. Please contact your issuing bank.",
"card": {
"instrument_id": "src_ubfj2q76miwundwlk72vxt2i7q",
"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
"metadata": {
"card_type": "CREDIT",
"card_category": "CONSUMER",
"issuer_name": "Checkout",
"issuer_country": "GB",
"product_id": "MDS",
"product_type": "Debit MasterCard® Card"
}
},
"recurring": {
"days_between_payments": 28,
"expiry": "20220901"
},
"installment": {
"number_of_payments": 2,
"days_between_payments": 28,
"expiry": "20220901"
},
"initial_transaction": {
"acs_transaction_id": "stringstringstringstringstringstring",
"authentication_method": "frictionless_authentication",
"authentication_timestamp": "2023-02-06T15:00:00.000Z",
"authentication_data": "string",
"initial_session_id": "sid_p6prbhogijnuxgv4grm3ber55u"
},
"customer_ip": "192.168.1.1",
"_links": {
"issuer_fingerprint": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/issuer-fingerprint"
},
"collect_channel_data": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/collect-data"
},
"three_ds_method_url": {
"href": "https://api.hsbc.com/3dsmethod?tx=123456"
},
"acs_url": {
"href": "https://api.hsbc.com/challenge"
},
"complete": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/complete"
},
"success_url": {
"href": "string"
},
"failure_url": {
"href": "string"
},
"callback_url": {
"href": "string"
},
"self": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2giaqnb441"
}
},
"authentication_date": "2019-08-24T14:15:22Z",
"exemption": {
"requested": "none",
"applied": "none",
"code": "string",
"trusted_beneficiary": {
"status": "Y",
"source": "01"
}
},
"flow_type": "challenged",
"challenge_indicator": "no_preference",
"optimization": {
"optimized": true,
"framework": "acceptance_rates",
"optimized_properties": [
{
"field": "challenge_indicator",
"original_value": "trusted_listing",
"optimized_value": "transaction_risk_assessment"
}
]
},
"scheme_info": {
"name": "cartes_bancaires",
"score": "string",
"avalgo": "string"
},
"3ds": {
"challenge_request": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjYwYTY2ZDRjLTdjY2EtNDc1Zi04YzMxLWFiMjkwNTI1M2M4NiIsImFjc1RyYW5zSUQiOiI1ODVhM2NlZi04OWQ4LTQ3ZDMtYjk4Yi0xMDhiMGRjYjEyYzEiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0",
"interaction_counter": "03",
"error_details": {
"error_code": "101",
"error_component": "D",
"error_detail": "acctNumber",
"error_description": "Cardholder Account Number is not in a range belonging to Issuer."
}
},
"preferred_experiences": {
"google_spa": {
"status": "available",
"reason": [
"Invalid response"
]
},
"3ds": {
"status": "available",
"reason": [
"Invalid response"
]
}
},
"experience": "3ds",
"google_spa": {
"token": {
"number": "string",
"expiry_month": 0,
"expiry_year": 0
}
}
}
```
### Properties
*None*
Cryptogram
```json
"MTIzNDU2Nzg5MDA5ODc2NTQzMjE="
```
Payment system-specific value provided as part of the ACS registration for each supported DS. Please be advised that this field will only be included in responses when authenticating with a valid OAuth token and not when authenticating
with `session_secret`. Cryptogram can only be retrieved for up to 24 hours after the session is created.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|Payment system-specific value provided as part of the ACS registration for each supported DS. Please be advised that this field will only be included in responses when authenticating with a valid OAuth token and not when authenticating
with `session_secret`. Cryptogram can only be retrieved for up to 24 hours after the session is created.|
Currency
```json
"USD"
```
The three-letter ISO currency code
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The three-letter ISO currency code|
```json
{
"device_id": "string",
"device_session_id": "dsid_ipsmclhxwq72phhr32iwfvrflm"
}
```
Details of the device from which the authentication originated.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|device_id|string|false|none|The unique identifier for the device.|
|device_session_id|string|false|none|Device session ID collected from our standalone Risk.js package.|
Ds
```json
{
"ds_id": "A000000003",
"reference_number": "VISA.V 17 0003",
"transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c"
}
```
The directory server (DS) information. Can be empty if the session is pending or communication with the DS failed
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|ds_id|string|false|none|Required if the session is deemed app-based. Registered application provider identifier (RID) that is unique to the payment system. RIDs are defined by the ISO 7816-5 standard. Used as part of the device data encryption process.|
|reference_number|string|false|none|EMVCo-assigned unique identifier to track approved DS|
|transaction_id|string|false|none|Universally unique transaction identifier assigned by the DS|
DsPublicKeys
```json
{
"ds_public": "eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2IiwieCI6Ik1LQkNUTkljS1VTRGlpMTF5U3MzNTI2aURaOEFpVG83VHU2S1BBcXY3RDQiLCJ5IjoiNEV0bDZTUlcyWWlMVXJONXZmdlZIdWhwN3g4UHhsdG1XV2xiYk00SUZ5TSIsInVzZSI6ImVuYyIsImtpZCI6IjEifQ",
"ca_public": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxWEvDZRhKEefZ5sQS7RJZXWbSOPxus-ZyLQjtmrrAQawnKI-AG8BKpVdZVGlpcdxCnGbCIy8CKk2Oi7Mgdqfv5R_4_jI7yl4j7Svmh1Sw934eeF9RyB59Ihl36Y0pNfVW9hBqJuq2o8ulrA1TOtpTpje23CY8sjFE5QnJm1evZRB_ZZQ1txl4nrAiHkno4cVJPouBesryVGVQ0zi1bM0P-05Ydgksvph-1nyjnDldD68mejVF69Tijxa22b6BUCXEuPfbXZcW2NpM_W3msnvKiTWFaMlnIzGYIoFnAnCIVU7Min6CPn565tv0iyIt8BrcezsGzefUw17NEq0J4tCvWwIDAQAB",
"ca_public_all": [
"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxWEvDZRhKEefZ5sQS7RJZXWbSOPxus-ZyLQjtmrrAQawnKI-AG8BKpVdZVGlpcdxCnGbCIy8CKk2Oi7Mgdqfv5R_4_jI7yl4j7Svmh1Sw934eeF9RyB59Ihl36Y0pNfVW9hBqJuq2o8ulrA1TOtpTpje23CY8sjFE5QnJm1evZRB_ZZQ1txl4nrAiHkno4cVJPouBesryVGVQ0zi1bM0P-05Ydgksvph-1nyjnDldD68mejVF69Tijxa22b6BUCXEuPfbXZcW2NpM_W3msnvKiTWFaMlnIzGYIoFnAnCIVU7Min6CPn565tv0iyIt8BrcezsGzefUw17NEq0J4tCvWwIDAQAB"
]
}
```
Public certificates specific to a Directory Server (DS) for encrypting device data and verifying ACS signed content. Required when channel is `app`.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|ds_public|string|true|none|A public certificate provided by the DS for encryption of device data. It is a base64 URL encoded JSON web key.|
|ca_public|string|false|none|Certificate authority (CA) public certificate (root) of the DS-CA. This certificate is used to validate the ACS signed content JSON web signature (JWS) object. It is a base64 URL encoded DER encoded X.509.|
|ca_public_all|[string]|false|none|An array of available certificate authority (CA) public certificates (root) of the DS-CA.
The certificates are used to validate the JSON web signature (JWS) object signed by the access control server (ACS). Each array element is a Base64 URL-encoded DER-encoded X.509 certificate.|
Eci
```json
"05"
```
Electronic Commerce Indicator. Please be advised that this field will only be included in responses when authenticating with a valid OAuth token and not when authenticating with `session_secret`.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|Electronic Commerce Indicator. Please be advised that this field will only be included in responses when authenticating with a valid OAuth token and not when authenticating with `session_secret`.|
ErrorDetails
```json
{
"error_code": "101",
"error_component": "D",
"error_detail": "acctNumber",
"error_description": "Cardholder Account Number is not in a range belonging to Issuer."
}
```
Provides additional information about the error returned.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|error_code|string|false|none|An error code identifying the type of issue.|
|error_component|string|false|none|A code that specifies which 3D Secure component identified the error.|
|error_detail|string|false|none|Provides additional details about the issue.|
|error_description|string|false|none|A description of the issue identified.|
ErrorResponse
```json
{
"request_id": "5342217f-7fa2-4626-a6c9-c979a04671a6",
"error_type": "operation_not_allowed",
"error_codes": [
"string"
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|request_id|string|true|none|none|
|error_type|string|true|none|The type of error.
• operation_not_allowed = Usually with an http status code 403. The request is not allowed by business rules.
• not_implemented = Usually with an http status code 501. This particular feature is not implemented yet.
• not_found = Usually with an http status code 404. The resource requested was not found.
• forbidden = Usually with an http status code 401. You do not have permissions for the requested operation.
• callback_failed = (Non Hosted Only) Only during the complete request. The callback_url responded with a non-success status code.
• internal_server_error = Usually with an http status code 500. Unexpected error during the request or an upstream service failure.
• unprocessable_entity = Usually with an http status code 422. The request payload failed validation.
• conflict = Usually with an http status code 409 during the creation of a resource. The resource already exists.
• duplicate_requests_detected = Usually with an http status code 409. This is returned when a Session is currently being processed.
• service_not_available = Usually with an http status code 503. Triggered given an upstream service failure.
|
|error_codes|[string]|true|none|Error response code. Full list of error codes below:
• unknown_error = Usually with an error type `internal_server_error`. An unexpected/unhandled error occurred.
• operation_not_allowed = Usually with an error type `operation_not_allowed`. The request is not allowed by business rules.
• scheme_not_supported = The processor was setup with a scheme not supported by the server.
• card_not_enrolled = The card number was not enrolled for 3DS2 and 3DS1 was either not enabled or not supported for Session (eg amount is 0).
• card_not_eligible = The card number was not eligible for 3DS1.
• card_eligibility_unavailable = A technical issue prevented the 3DS1 transaction from completing.
• card_protocol_version_not_supported = The protocol version provided is not enabled for the processor being used.
• update_not_allowed_due_to_state = The Session was in a state that did not allow for the operation attempted.
• source_not_supported = Support for the Session Source used is not implemented yet.
• session_callback_failed = (Non Hosted Only) Only during the complete request. The callback_url responded with a non-success status code.
• session_persistence_failed = Usually with an error type `internal_server_error`. The API failed to persist the Session. Can be retried.
• hosted_not_supported_for_app = You tried to create a Hosted Session with app channel data which is not allowed.
• three_ds_method_not_supported_for_app = You tried to perform issuer fingerprint on a Session with app channel data which is not allowed.
• three_ds_method_not_supported_without_url = You tried to perform issuer fingerprint on a Session without a 3DS method URL which is not allowed.
• operation_not_allowed_for_scope = You are using an OAuth2.0 token that does not contain the right scope.
• protocol_version_not_supported_by_sdk = You created an App channel Session with a protocol version not supported by the relevant mobile SDK.
• ds_error = The Directory Server (schemes) responded with an unexpected error or timed out.
• processing_channel_disabled = The Processing Channel or processor used for this Session is not active.
• vault_not_configured_for_processing_channel = Using a Processing Channel not configured for use with Checkout.com Vault offering but trying to use a relevant source (`id` or `token`).
• error_getting_instrument = Getting an instrument responded with an unexpected error or timed out. Only relevant for sources `id` or `token`.
• invalid_token = The token used in the source object was invalid.
• instrument_used_is_not_card = Using an `id` type source that is not a card (only card type instruments are supported in 3DS) .
• no_processor_configured_for_card_scheme = Using a card that belongs to a scheme that is not configured in the Processing Channel being used.
• currency_not_supported = An American Express SE number is not associated with the currency in the request.
• scheme_outage = With error type `operation_not_allowed`. This is returned when there is a technical issue on the scheme's platform.
• session_already_in_use = With error type `duplicate_requests_detected`. More than one action requests have been sent in parallel for the same session.
• merchant_initiated_request_not_supported_by_3ds_protocol = With error type `unprocessable_entity`. The merchant-initiated request is not supported by the selected 3DS protocol version.
• initial_session_not_found = With error type `unprocessable_entity`. A previous session could not be found with the provided initial session ID.
• initial_session_invalid = With error type `unprocessable_entity`. The previous session was not valid to be used as an initial transaction.
• invalid_target_scheme = With error type `unprocessable_entity`. The card number cannot be processed with the specified scheme.
• unrecognized_scheme = With error type `unprocessable_entity`. The card number is associated with a scheme that is not supported.
Also, there is a number of generic error codes as described below:
• some_field_required = Usually with an error type `unprocessable_entity`. The field `some_field` is required but not provided in the payload.
• some_field_invalid = Usually with an error type `unprocessable_entity`. The field `some_field` failed validation. Please consult the API spec.
• unable_to_verify_some_field = Usually with an error type `service_not_available`. The field `some_field` could not be validated due to an upstream service failure.
• some_resource_already_exists = Usually with an error type `conflict`. The resource you are trying to create already exists (not relevant for Sessions with an auto-generated id).
• some_resource_not_found = Usually with an error type `not_found`. The resource you are trying to get does not exist.
|
#### Enumerated Values
|Property|Value|
|---|---|
|error_type|operation_not_allowed|
|error_type|not_implemented|
|error_type|not_found|
|error_type|forbidden|
|error_type|callback_failed|
|error_type|internal_server_error|
|error_type|unprocessable_entity|
|error_type|conflict|
|error_type|duplicate_requests_detected|
|error_type|service_not_available|
Experience
```json
"3ds"
```
The authentication experience that was used for processing
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The authentication experience that was used for processing|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|3ds|
|*anonymous*|google_spa|
GetBaseSessionLinks
```json
{
"self": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2giaqnb441"
}
}
```
The links related to the session
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|self|object|true|none|The URI of the session|
|» href|string|true|none|none|
GetFingerprintSessionLinks
```json
{
"complete": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/complete"
},
"issuer_fingerprint": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/issuer-fingerprint"
},
"collect_channel_data": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/collect-data"
},
"three_ds_method_url": {
"href": "https://api.hsbc.com/3dsmethod?tx=123456"
},
"self": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2giaqnb441"
}
}
```
The links related to the session
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|complete|object|false|none|The URI to signal the session as complete. Only available if `next_actions` contains `complete`|
|» href|string|true|none|none|
|issuer_fingerprint|object|false|none|The URI to send the 3ds method completion indicator to. Use this if device information was sent when requesting a session. Only available if `next_actions` contains `issuer_fingerprint`|
|» href|string|true|none|none|
|collect_channel_data|object|false|none|The URI to send device information to. Only available if `next_actions` contains `collect_data`|
|» href|string|true|none|none|
|three_ds_method_url|object|false|none|The URI of the issuer fingerprint (3DS method). Only available if `next_actions` contains `issuer_fingerprint`|
|» href|string|true|none|none|
GetSessionLinks
```json
{
"issuer_fingerprint": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/issuer-fingerprint"
},
"collect_channel_data": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/collect-data"
},
"three_ds_method_url": {
"href": "https://api.hsbc.com/3dsmethod?tx=123456"
},
"acs_url": {
"href": "https://api.hsbc.com/challenge"
},
"complete": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/complete"
},
"success_url": {
"href": "string"
},
"failure_url": {
"href": "string"
},
"callback_url": {
"href": "string"
},
"self": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2giaqnb441"
}
}
```
The links related to the session
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|issuer_fingerprint|object|false|none|The URI to send the 3ds method completion indicator to. Use this if device information was sent when requesting a session. Only available if `next_actions` contains `issuer_fingerprint`|
|» href|string|true|none|none|
|collect_channel_data|object|false|none|The URI to send device information to. Only available if `next_actions` contains `collect_data`|
|» href|string|true|none|none|
|three_ds_method_url|object|false|none|The URI of the issuer fingerprint (3DS method). Only available if `next_actions` contains `issuer_fingerprint`|
|» href|string|true|none|none|
|acs_url|object|false|none|Fully qualified URL of the ACS to be used for the challenge. Only available if `next_actions` contains `authenticate`|
|» href|string|true|none|none|
|complete|object|false|none|The URI to signal the session as complete. Only available if `next_actions` contains `complete`|
|» href|string|true|none|none|
|success_url|object|false|none|The cardholder will be redirected to this URI given an authentication was approved or attempted. Only available if the completion type is `hosted`.|
|» href|string|true|none|none|
|failure_url|object|false|none|The cardholder will be redirected to this URI given an authentication was not approved or attempted. Only available if the completion type is `hosted`.|
|» href|string|true|none|none|
|callback_url|object|false|none|An endpoint which will receive a POST request highlighting the result of an authentication. See the "Complete a Session" request for more details. Only available if the completion type is `non_hosted`.|
|» href|string|true|none|none|
GetSessionResponse
```json
{
"id": "sid_y3oqhf46pyzuxjbcn2giaqnb44",
"session_secret": "sek_Dal7UyiH8rIFXA4PfgiIk2jUyQkVDeEWgVBEL4TsRTE=",
"transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c",
"scheme": "visa",
"amount": 120,
"currency": "USD",
"completed": false,
"challenged": true,
"authentication_type": "regular",
"authentication_category": "payment",
"certificates": {
"ds_public": "eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2IiwieCI6Ik1LQkNUTkljS1VTRGlpMTF5U3MzNTI2aURaOEFpVG83VHU2S1BBcXY3RDQiLCJ5IjoiNEV0bDZTUlcyWWlMVXJONXZmdlZIdWhwN3g4UHhsdG1XV2xiYk00SUZ5TSIsInVzZSI6ImVuYyIsImtpZCI6IjEifQ",
"ca_public": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxWEvDZRhKEefZ5sQS7RJZXWbSOPxus-ZyLQjtmrrAQawnKI-AG8BKpVdZVGlpcdxCnGbCIy8CKk2Oi7Mgdqfv5R_4_jI7yl4j7Svmh1Sw934eeF9RyB59Ihl36Y0pNfVW9hBqJuq2o8ulrA1TOtpTpje23CY8sjFE5QnJm1evZRB_ZZQ1txl4nrAiHkno4cVJPouBesryVGVQ0zi1bM0P-05Ydgksvph-1nyjnDldD68mejVF69Tijxa22b6BUCXEuPfbXZcW2NpM_W3msnvKiTWFaMlnIzGYIoFnAnCIVU7Min6CPn565tv0iyIt8BrcezsGzefUw17NEq0J4tCvWwIDAQAB",
"ca_public_all": [
"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxWEvDZRhKEefZ5sQS7RJZXWbSOPxus-ZyLQjtmrrAQawnKI-AG8BKpVdZVGlpcdxCnGbCIy8CKk2Oi7Mgdqfv5R_4_jI7yl4j7Svmh1Sw934eeF9RyB59Ihl36Y0pNfVW9hBqJuq2o8ulrA1TOtpTpje23CY8sjFE5QnJm1evZRB_ZZQ1txl4nrAiHkno4cVJPouBesryVGVQ0zi1bM0P-05Ydgksvph-1nyjnDldD68mejVF69Tijxa22b6BUCXEuPfbXZcW2NpM_W3msnvKiTWFaMlnIzGYIoFnAnCIVU7Min6CPn565tv0iyIt8BrcezsGzefUw17NEq0J4tCvWwIDAQAB"
]
},
"status": "challenged",
"status_reason": "ares_status",
"approved": false,
"protocol_version": "2.2.0",
"account_info": {
"purchase_count": 10,
"account_age": "no_account",
"add_card_attempts": 10,
"shipping_address_age": "this_transaction",
"account_name_matches_shipping_name": true,
"suspicious_account_activity": true,
"transactions_today": 10,
"authentication_method": "no_authentication",
"cardholder_account_age_indicator": "no_account,",
"account_change": "2019-08-24T14:15:22Z",
"account_change_indicator": "this_transaction",
"account_date": "2019-08-24T14:15:22Z",
"account_password_change": "2019-08-24T14:15:22Z",
"account_password_change_indicator": "no_change",
"transactions_per_year": 2,
"payment_account_age": "2019-08-24T14:15:22Z",
"shipping_address_usage": "2019-08-24T14:15:22Z",
"account_type": "not_applicable",
"account_id": "string",
"three_ds_requestor_authentication_info": {
"three_ds_req_auth_method": "no_threeds_requestor_authentication_occurred",
"three_ds_req_auth_timestamp": "2019-08-24T14:15:22Z",
"three_ds_req_auth_data": "string"
}
},
"merchant_risk_info": {
"delivery_email": "brucewayne@email.com",
"delivery_timeframe": "electronic_delivery",
"is_preorder": true,
"is_reorder": false,
"shipping_indicator": "billing_address",
"reorder_items_indicator": "first_time_ordered",
"pre_order_purchase_indicator": "merchandise_available",
"pre_order_date": "2019-08-24T14:15:22Z",
"gift_card_amount": "123",
"gift_card_currency": "USD",
"gift_card_count": "02"
},
"reference": "ORD-5023-4E89",
"transaction_type": "goods_service",
"next_actions": [
"redirect_cardholder"
],
"ds": {
"ds_id": "A000000003",
"reference_number": "VISA.V 17 0003",
"transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c"
},
"acs": {
"reference_number": "ACSRefNum1234",
"transaction_id": "be481bd1-1f1d-4ef8-9fa8-0fb2a38e3c87",
"operator_id": "ACSRefNum1234",
"url": "https://server.acsdomainname.com",
"signed_content": "eyJ4NWMiOlsiTUlJQjdEQ0NBWktnQXdJQkFnSVZBSzIxWEc5SVBCL083QzZjUTBvRlJJUkIwWDI0TUFvR0NDcUdTTTQ5QkFNQ01INHhDekFKQm",
"challenge_mandated": true,
"authentication_type": "string",
"challenge_cancel_reason": "cardholder_cancel",
"interface": "native_ui",
"ui_template": "text",
"challenge_cancel_reason_code": "string"
},
"response_code": "Y",
"response_status_reason": "01",
"cryptogram": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
"eci": "05",
"xid": "XSUErNftqkiTdlkpSk8p32GWOFA",
"cardholder_info": "Card declined. Please contact your issuing bank.",
"card": {
"instrument_id": "src_ubfj2q76miwundwlk72vxt2i7q",
"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
"metadata": {
"card_type": "CREDIT",
"card_category": "CONSUMER",
"issuer_name": "Checkout",
"issuer_country": "GB",
"product_id": "MDS",
"product_type": "Debit MasterCard® Card"
}
},
"recurring": {
"days_between_payments": 28,
"expiry": "20220901"
},
"installment": {
"number_of_payments": 2,
"days_between_payments": 28,
"expiry": "20220901"
},
"initial_transaction": {
"acs_transaction_id": "stringstringstringstringstringstring",
"authentication_method": "frictionless_authentication",
"authentication_timestamp": "2023-02-06T15:00:00.000Z",
"authentication_data": "string",
"initial_session_id": "sid_p6prbhogijnuxgv4grm3ber55u"
},
"customer_ip": "192.168.1.1",
"_links": {
"issuer_fingerprint": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/issuer-fingerprint"
},
"collect_channel_data": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/collect-data"
},
"three_ds_method_url": {
"href": "https://api.hsbc.com/3dsmethod?tx=123456"
},
"acs_url": {
"href": "https://api.hsbc.com/challenge"
},
"complete": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/complete"
},
"success_url": {
"href": "string"
},
"failure_url": {
"href": "string"
},
"callback_url": {
"href": "string"
},
"self": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2giaqnb441"
}
},
"authentication_date": "2019-08-24T14:15:22Z",
"exemption": {
"requested": "none",
"applied": "none",
"code": "string",
"trusted_beneficiary": {
"status": "Y",
"source": "01"
}
},
"flow_type": "challenged",
"challenge_indicator": "no_preference",
"optimization": {
"optimized": true,
"framework": "acceptance_rates",
"optimized_properties": [
{
"field": "challenge_indicator",
"original_value": "trusted_listing",
"optimized_value": "transaction_risk_assessment"
}
]
},
"scheme_info": {
"name": "cartes_bancaires",
"score": "string",
"avalgo": "string"
},
"3ds": {
"challenge_request": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjYwYTY2ZDRjLTdjY2EtNDc1Zi04YzMxLWFiMjkwNTI1M2M4NiIsImFjc1RyYW5zSUQiOiI1ODVhM2NlZi04OWQ4LTQ3ZDMtYjk4Yi0xMDhiMGRjYjEyYzEiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0",
"interaction_counter": "03",
"error_details": {
"error_code": "101",
"error_component": "D",
"error_detail": "acctNumber",
"error_description": "Cardholder Account Number is not in a range belonging to Issuer."
}
},
"preferred_experiences": {
"google_spa": {
"status": "available",
"reason": [
"Invalid response"
]
},
"3ds": {
"status": "available",
"reason": [
"Invalid response"
]
}
},
"experience": "3ds",
"google_spa": {
"token": {
"number": "string",
"expiry_month": 0,
"expiry_year": 0
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[SessionId](#schemasessionid)|true|none|Session unique identifier|
|session_secret|[SessionSecret](#schemasessionsecret)|false|none|A base64 encoded value prefixed with `sek_` that gives access to client-side operations for a single authentication within the Sessions API. This value is returned as the `session_secret` when requesting a session.|
|transaction_id|string|true|none|The transaction identifier that needs to be provided when communicating directly with the Access Control Server (ACS)|
|scheme|string|true|none|Indicates the scheme this authentication is carried out against|
|amount|[Amount](#schemaamount)|true|none|The amount in the minor currency.|
|currency|[Currency](#schemacurrency)|true|none|The three-letter ISO currency code|
|completed|boolean|false|none|Indicates whether this session has been completed|
|challenged|boolean|false|none|Indicates whether this session involved a challenge. This will only be set after communication with the scheme is finished.|
|authentication_type|[AuthenticationType](#schemaauthenticationtype)|true|none|Indicates the type of payment this session is for. Please note the spelling of `installment` consists of two `l`s.|
|authentication_category|[Category](#schemacategory)|true|none|Indicates the category of the authentication request|
|certificates|[DsPublicKeys](#schemadspublickeys)|false|none|Public certificates specific to a Directory Server (DS) for encrypting device data and verifying ACS signed content. Required when channel is `app`.|
|status|[Status](#schemastatus)|true|none|Indicates the status of the session|
|status_reason|[StatusReason](#schemastatusreason)|false|none|When the Session is unavailable this will point to the reason it is so.
• ares_error = There was an issue in the Authentication response we got back from the Directory Server (scheme server - 3DS2)
• ares_status = The status was set to the status in the Authentication response we got back from the Directory Server (scheme server - 3DS2)
• rreq_error = There was an issue in the Response we got back from the Access Control Server (issuer server - 3DS2)
• rreq_status = The status was set to the status in the Response we got back from the Access Control Server (issuer server - 3DS2)
• risk_declined = The status was set to declined because the Risk engine recommended we decline the authentication
|
|approved|[Approved](#schemaapproved)|false|none|Whether the authentication was successful. This will only be set if the Session is in a final state|
|protocol_version|[ProtocolVersion](#schemaprotocolversion)|true|none|The protocol version number of the specification used by the API for authentication|
|account_info|[CardholderAccountInfo](#schemacardholderaccountinfo)|false|none|Additional information about the Cardholder's account.|
|merchant_risk_info|[MerchantRiskInfo](#schemamerchantriskinfo)|false|none|Additional information about the cardholder's purchase.|
|reference|[Reference](#schemareference)|false|none|A reference you can later use to identify this payment, such as an order number. **Do not pass sensitive information in this field e.g. card details**|
|transaction_type|[TransactionType](#schematransactiontype)|false|none|Identifies the type of transaction being authenticated|
|next_actions|[NextActions](#schemanextactions)|false|none|Specifies which action to take in order to complete the session.
The `redirect_cardholder` action is only applicable for hosted sessions.|
|ds|[Ds](#schemads)|false|none|The directory server (DS) information. Can be empty if the session is pending or communication with the DS failed|
|acs|[Acs](#schemaacs)|false|none|The access control server (ACS) information. Can be empty if the session is still pending or if communication with the ACS failed. This will be available when the channel data and issuer fingerprint result have been provided.|
|response_code|[ResponseCode](#schemaresponsecode)|false|none|Only available as a result of a 3DS2 authentication.
The response from the DS or ACS which indicates whether a transaction qualifies as an authenticated transaction or account verification.
Only available if communication with the scheme was successful and the Session is in a final state.
• Y = Authentication Verification Successful.
• N = Not Authenticated /Account Not Verified; Transaction denied.
• U = Authentication/ Account Verification Could Not Be Performed; Technical or other problem, as indicated in ARes or RReq.
• A = Attempts Processing Performed; Not Authenticated/Verified, but a proof of attempted authentication/verification is provided.
• C = Challenge Required; Additional authentication is required using the CReq/CRes.
• D = Challenge Required; Decoupled Authentication confirmed.
• R = Authentication/ Account Verification Rejected; Issuer is rejecting authentication/verification and request that authorization not be attempted.
• I = Informational Only; 3DS Requestor challenge preference acknowledged.|
|response_status_reason|[ResponseStatusReason](#schemaresponsestatusreason)|false|none|Only available as a result of a 3DS2 authentication.
The response from the DS or ACS which provides information on why the `response_code` field has the specified value.
Only available when `response_code` is not `Y`.
Learn more about the reasons for authentication failures.
|
|cryptogram|[Cryptogram](#schemacryptogram)|false|none|Payment system-specific value provided as part of the ACS registration for each supported DS. Please be advised that this field will only be included in responses when authenticating with a valid OAuth token and not when authenticating
with `session_secret`. Cryptogram can only be retrieved for up to 24 hours after the session is created.|
|eci|[Eci](#schemaeci)|false|none|Electronic Commerce Indicator. Please be advised that this field will only be included in responses when authenticating with a valid OAuth token and not when authenticating with `session_secret`.|
|xid|string|false|none|The xid value to use for authorization|
|cardholder_info|string|false|none|May provide cardholder information from the DS to be presented to the cardholder|
|card|[CardInfo](#schemacardinfo)|false|none|Details related to the Session source. This property should always be in the response, unless a `card` source was used and communication with Checkout.com's Vault was not possible.|
|recurring|[Recurring](#schemarecurring)|false|none|Details of a recurring authentication. This property is needed only for a recurring authentication type. Value will be ignored in any other cases.|
|installment|[Installment](#schemainstallment)|false|none|Details of an installment authentication. This property is needed only for an installment authentication type. Value will be ignored in any other cases.|
|initial_transaction|[InitialTransaction](#schemainitialtransaction)|false|none|Details of a previous transaction|
|customer_ip|string|false|none|Indicates the card holder's IP address. Only available when the scheme selected is Cartes Bancaires.|
|_links|[GetSessionLinks](#schemagetsessionlinks)|true|none|The links related to the session|
|authentication_date|string(date-time)|false|none|Authentication date and time|
|exemption|object|false|none|Details related to exemption present in 3DS flow|
|» requested|string|false|none|Indicates merchant requested exemption|
|» applied|string|false|none|Indicates Issuer accepted or applied exemption|
|» code|string|false|none|Indicates Cartes Bancaire specific exemption value|
|» trusted_beneficiary|[TrustedBeneficiary](#schematrustedbeneficiary)|false|none|Details of the trusted listing status of the merchant.|
|flow_type|string|false|none|Indicates whether the 3D Secure 2 authentication was challenged or frictionless|
|challenge_indicator|string|true|none|Indicates the preference for whether or not a 3DS challenge should be performed. The customer’s bank has the final say on whether or not the customer receives the challenge|
|optimization|object|false|none|The information about the optimization options selected|
|» optimized|boolean|false|none|Indicates if any optimization has been applied|
|» framework|string|false|none|The optimization framework applied|
|» optimized_properties|[[OptimizedProperty](#schemaoptimizedproperty)]|false|none|The collection of fields optimized|
|scheme_info|object|false|none|Indicates scheme-specific information|
|» name|string|false|none|Indicates which scheme was used to perform authentication|
|» score|string|false|none|Risk score calculated by Directory Server (DS). Cartes Bancaires 3D Secure 2 only|
|» avalgo|string|false|none|Identification of the algorithm used by the ACS to calculate the Authentication Value indicated|
|3ds|object|false|none|This object provides more information about the 3DS experience|
|» challenge_request|string|false|none|The CReq message, encoded in Base 64.|
|» interaction_counter|string|false|none|The number of authentication attempts performed by the cardholder.|
|» error_details|[ErrorDetails](#schemaerrordetails)|false|none|Provides additional information about the error returned.|
|preferred_experiences|[PreferredExperiences](#schemapreferredexperiences)|false|none|Preferred Experiences|
|experience|[Experience](#schemaexperience)|false|none|The authentication experience that was used for processing|
|google_spa|[GoogleSpaInfo](#schemagooglespainfo)|false|none|Details of Google SPA (Secure Payment Authentication)|
#### Enumerated Values
|Property|Value|
|---|---|
|scheme|visa|
|scheme|mastercard|
|scheme|jcb|
|scheme|amex|
|scheme|diners|
|scheme|cartes_bancaires|
|scheme|discover|
|scheme|upi|
|requested|none|
|applied|none|
|applied|low_value|
|applied|transaction_risk_assessment|
|applied|secure_corporate_payment|
|applied|trusted_listing|
|applied|3ds_outage|
|applied|sca_delegation|
|applied|out_of_sca_scope|
|applied|other|
|applied|low_risk_program|
|flow_type|challenged|
|flow_type|frictionless|
|flow_type|frictionless_delegated|
|challenge_indicator|no_preference|
|challenge_indicator|no_challenge_requested|
|challenge_indicator|challenge_requested|
|challenge_indicator|challenge_requested_mandate|
|framework|acceptance_rates|
|name|cartes_bancaires|
|name|visa|
|name|mastercard|
GetSessionResponseAfterChannelDataSupplied
```json
{
"id": "sid_y3oqhf46pyzuxjbcn2giaqnb44",
"session_secret": "sek_Dal7UyiH8rIFXA4PfgiIk2jUyQkVDeEWgVBEL4TsRTE=",
"transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c",
"scheme": "visa",
"amount": 120,
"currency": "USD",
"completed": false,
"challenged": true,
"authentication_type": "regular",
"authentication_category": "payment",
"status": "challenged",
"status_reason": "ares_status",
"approved": false,
"protocol_version": "2.2.0",
"account_info": {
"purchase_count": 10,
"account_age": "no_account",
"add_card_attempts": 10,
"shipping_address_age": "this_transaction",
"account_name_matches_shipping_name": true,
"suspicious_account_activity": true,
"transactions_today": 10,
"authentication_method": "no_authentication",
"cardholder_account_age_indicator": "no_account,",
"account_change": "2019-08-24T14:15:22Z",
"account_change_indicator": "this_transaction",
"account_date": "2019-08-24T14:15:22Z",
"account_password_change": "2019-08-24T14:15:22Z",
"account_password_change_indicator": "no_change",
"transactions_per_year": 2,
"payment_account_age": "2019-08-24T14:15:22Z",
"shipping_address_usage": "2019-08-24T14:15:22Z",
"account_type": "not_applicable",
"account_id": "string",
"three_ds_requestor_authentication_info": {
"three_ds_req_auth_method": "no_threeds_requestor_authentication_occurred",
"three_ds_req_auth_timestamp": "2019-08-24T14:15:22Z",
"three_ds_req_auth_data": "string"
}
},
"merchant_risk_info": {
"delivery_email": "brucewayne@email.com",
"delivery_timeframe": "electronic_delivery",
"is_preorder": true,
"is_reorder": false,
"shipping_indicator": "billing_address",
"reorder_items_indicator": "first_time_ordered",
"pre_order_purchase_indicator": "merchandise_available",
"pre_order_date": "2019-08-24T14:15:22Z",
"gift_card_amount": "123",
"gift_card_currency": "USD",
"gift_card_count": "02"
},
"reference": "ORD-5023-4E89",
"transaction_type": "goods_service",
"initial_transaction": {
"acs_transaction_id": "stringstringstringstringstringstring",
"authentication_method": "frictionless_authentication",
"authentication_timestamp": "2023-02-06T15:00:00.000Z",
"authentication_data": "string",
"initial_session_id": "sid_p6prbhogijnuxgv4grm3ber55u"
},
"next_actions": [
"redirect_cardholder"
],
"ds": {
"ds_id": "A000000003",
"reference_number": "VISA.V 17 0003",
"transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c"
},
"acs": {
"reference_number": "ACSRefNum1234",
"transaction_id": "be481bd1-1f1d-4ef8-9fa8-0fb2a38e3c87",
"operator_id": "ACSRefNum1234",
"url": "https://server.acsdomainname.com",
"signed_content": "eyJ4NWMiOlsiTUlJQjdEQ0NBWktnQXdJQkFnSVZBSzIxWEc5SVBCL083QzZjUTBvRlJJUkIwWDI0TUFvR0NDcUdTTTQ5QkFNQ01INHhDekFKQm",
"challenge_mandated": true,
"authentication_type": "string",
"challenge_cancel_reason": "cardholder_cancel",
"interface": "native_ui",
"ui_template": "text",
"challenge_cancel_reason_code": "string"
},
"response_code": "Y",
"response_status_reason": "01",
"cryptogram": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
"eci": "05",
"xid": "XSUErNftqkiTdlkpSk8p32GWOFA",
"preferred_experiences": {
"google_spa": {
"status": "available",
"reason": [
"Invalid response"
]
},
"3ds": {
"status": "available",
"reason": [
"Invalid response"
]
}
},
"experience": "3ds",
"google_spa": {
"token": {
"number": "string",
"expiry_month": 0,
"expiry_year": 0
}
},
"card": {
"instrument_id": "src_ubfj2q76miwundwlk72vxt2i7q",
"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
"metadata": {
"card_type": "CREDIT",
"card_category": "CONSUMER",
"issuer_name": "Checkout",
"issuer_country": "GB",
"product_id": "MDS",
"product_type": "Debit MasterCard® Card"
}
},
"_links": {
"complete": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/complete"
},
"issuer_fingerprint": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/issuer-fingerprint"
},
"collect_channel_data": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/collect-data"
},
"three_ds_method_url": {
"href": "https://api.hsbc.com/3dsmethod?tx=123456"
},
"self": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2giaqnb441"
}
},
"3ds": {
"challenge_request": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjYwYTY2ZDRjLTdjY2EtNDc1Zi04YzMxLWFiMjkwNTI1M2M4NiIsImFjc1RyYW5zSUQiOiI1ODVhM2NlZi04OWQ4LTQ3ZDMtYjk4Yi0xMDhiMGRjYjEyYzEiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0",
"interaction_counter": "03",
"error_details": {
"error_code": "101",
"error_component": "D",
"error_detail": "acctNumber",
"error_description": "Cardholder Account Number is not in a range belonging to Issuer."
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|[SessionId](#schemasessionid)|true|none|Session unique identifier|
|session_secret|[SessionSecret](#schemasessionsecret)|false|none|A base64 encoded value prefixed with `sek_` that gives access to client-side operations for a single authentication within the Sessions API. This value is returned as the `session_secret` when requesting a session.|
|transaction_id|string|true|none|The transaction identifier that needs to be provided when communicating directly with the Access Control Server (ACS)|
|scheme|string|true|none|Indicates the scheme this authentication is carried out against|
|amount|[Amount](#schemaamount)|true|none|The amount in the minor currency.|
|currency|[Currency](#schemacurrency)|true|none|The three-letter ISO currency code|
|completed|boolean|false|none|Indicates whether this session has been completed|
|challenged|boolean|false|none|Indicates whether this session involved a challenge. This will only be set after communication with the scheme is finished.|
|authentication_type|[AuthenticationType](#schemaauthenticationtype)|true|none|Indicates the type of payment this session is for. Please note the spelling of `installment` consists of two `l`s.|
|authentication_category|[Category](#schemacategory)|true|none|Indicates the category of the authentication request|
|status|[Status](#schemastatus)|true|none|Indicates the status of the session|
|status_reason|[StatusReason](#schemastatusreason)|false|none|When the Session is unavailable this will point to the reason it is so.
• ares_error = There was an issue in the Authentication response we got back from the Directory Server (scheme server - 3DS2)
• ares_status = The status was set to the status in the Authentication response we got back from the Directory Server (scheme server - 3DS2)
• rreq_error = There was an issue in the Response we got back from the Access Control Server (issuer server - 3DS2)
• rreq_status = The status was set to the status in the Response we got back from the Access Control Server (issuer server - 3DS2)
• risk_declined = The status was set to declined because the Risk engine recommended we decline the authentication
|
|approved|[Approved](#schemaapproved)|false|none|Whether the authentication was successful. This will only be set if the Session is in a final state|
|protocol_version|[ProtocolVersion](#schemaprotocolversion)|true|none|The protocol version number of the specification used by the API for authentication|
|account_info|[CardholderAccountInfo](#schemacardholderaccountinfo)|false|none|Additional information about the Cardholder's account.|
|merchant_risk_info|[MerchantRiskInfo](#schemamerchantriskinfo)|false|none|Additional information about the cardholder's purchase.|
|reference|[Reference](#schemareference)|false|none|A reference you can later use to identify this payment, such as an order number. **Do not pass sensitive information in this field e.g. card details**|
|transaction_type|[TransactionType](#schematransactiontype)|false|none|Identifies the type of transaction being authenticated|
|initial_transaction|[InitialTransaction](#schemainitialtransaction)|false|none|Details of a previous transaction|
|next_actions|[NextActions](#schemanextactions)|false|none|Specifies which action to take in order to complete the session.
The `redirect_cardholder` action is only applicable for hosted sessions.|
|ds|[Ds](#schemads)|false|none|The directory server (DS) information. Can be empty if the session is pending or communication with the DS failed|
|acs|[Acs](#schemaacs)|false|none|The access control server (ACS) information. Can be empty if the session is still pending or if communication with the ACS failed. This will be available when the channel data and issuer fingerprint result have been provided.|
|response_code|[ResponseCode](#schemaresponsecode)|false|none|Only available as a result of a 3DS2 authentication.
The response from the DS or ACS which indicates whether a transaction qualifies as an authenticated transaction or account verification.
Only available if communication with the scheme was successful and the Session is in a final state.
• Y = Authentication Verification Successful.
• N = Not Authenticated /Account Not Verified; Transaction denied.
• U = Authentication/ Account Verification Could Not Be Performed; Technical or other problem, as indicated in ARes or RReq.
• A = Attempts Processing Performed; Not Authenticated/Verified, but a proof of attempted authentication/verification is provided.
• C = Challenge Required; Additional authentication is required using the CReq/CRes.
• D = Challenge Required; Decoupled Authentication confirmed.
• R = Authentication/ Account Verification Rejected; Issuer is rejecting authentication/verification and request that authorization not be attempted.
• I = Informational Only; 3DS Requestor challenge preference acknowledged.|
|response_status_reason|[ResponseStatusReason](#schemaresponsestatusreason)|false|none|Only available as a result of a 3DS2 authentication.
The response from the DS or ACS which provides information on why the `response_code` field has the specified value.
Only available when `response_code` is not `Y`.
Learn more about the reasons for authentication failures.
|
|cryptogram|[Cryptogram](#schemacryptogram)|false|none|Payment system-specific value provided as part of the ACS registration for each supported DS. Please be advised that this field will only be included in responses when authenticating with a valid OAuth token and not when authenticating
with `session_secret`. Cryptogram can only be retrieved for up to 24 hours after the session is created.|
|eci|[Eci](#schemaeci)|false|none|Electronic Commerce Indicator. Please be advised that this field will only be included in responses when authenticating with a valid OAuth token and not when authenticating with `session_secret`.|
|xid|string|false|none|The xid value to use for authorization|
|preferred_experiences|[PreferredExperiences](#schemapreferredexperiences)|false|none|Preferred Experiences|
|experience|[Experience](#schemaexperience)|false|none|The authentication experience that was used for processing|
|google_spa|[GoogleSpaInfo](#schemagooglespainfo)|false|none|Details of Google SPA (Secure Payment Authentication)|
|card|[CardInfo](#schemacardinfo)|false|none|Details related to the Session source. This property should always be in the response, unless a `card` source was used and communication with Checkout.com's Vault was not possible.|
|_links|[GetFingerprintSessionLinks](#schemagetfingerprintsessionlinks)|true|none|The links related to the session|
|3ds|object|false|none|Provides additional information about the 3DS authentication experience.|
|» challenge_request|string|false|none|The CReq message, encoded in Base 64.|
|» interaction_counter|string|false|none|The number of authentication attempts performed by the cardholder.|
|» error_details|[ErrorDetails](#schemaerrordetails)|false|none|Provides additional information about the error returned.|
#### Enumerated Values
|Property|Value|
|---|---|
|scheme|visa|
|scheme|mastercard|
|scheme|jcb|
|scheme|amex|
|scheme|diners|
|scheme|cartes_bancaires|
|scheme|discover|
|scheme|upi|
GoogleSpaInfo
```json
{
"token": {
"number": "string",
"expiry_month": 0,
"expiry_year": 0
}
}
```
Details of Google SPA (Secure Payment Authentication)
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[HostedGoogleSpaInfo](#schemahostedgooglespainfo)|false|none|Details of Google SPA (Secure Payment Authentication) for a hosted authentication|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[NonHostedGoogleSpaInfo](#schemanonhostedgooglespainfo)|false|none|Details of Google SPA (Secure Payment Authentication) for a non-hosted authentication|
GoogleSpaToken
```json
{
"number": "string",
"expiry_month": 0,
"expiry_year": 0
}
```
Token for the given PAN provisioned and authenticated
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|number|string|false|none|Value of token. Represented as a numerical string|
|expiry_month|number|false|none|Expiry month of the token|
|expiry_year|number|false|none|Expiry year of the token|
HostedCompletionInfo
```json
{
"type": "hosted",
"success_url": "http://example.com/payments/success",
"failure_url": "http://example.com/payments/fail"
}
```
hosted
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|Whether the session should be hosted by Checkout.com.|
|success_url|string(uri)|true|none|For `hosted` sessions, this overrides the default success redirect URL configured on your account|
|failure_url|string(uri)|true|none|For `hosted` sessions, this overrides the default failure redirect URL configured on your account|
#### Enumerated Values
|Property|Value|
|---|---|
|type|hosted|
HostedGoogleSpaInfo
```json
{
"token": {
"number": "string",
"expiry_month": 0,
"expiry_year": 0
}
}
```
Hosted
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|token|[GoogleSpaToken](#schemagooglespatoken)|false|none|Token for the given PAN provisioned and authenticated|
IdSource
```json
{
"type": "id",
"scheme": "amex",
"number": "4242424242424242",
"expiry_month": 12,
"expiry_year": 2077,
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "ABC building",
"address_line3": "14 Wells Mews",
"city": "London",
"state": "ENG",
"zip": "SW1A 1AA",
"country": "GB"
},
"home_phone": {
"country_code": "234",
"number": "0204567895"
},
"mobile_phone": {
"country_code": "234",
"number": "0204567895"
},
"work_phone": {
"country_code": "234",
"number": "0204567895"
},
"email": "bruce.wayne@email.com",
"id": "src_4gzeau5o2uqubbk6fufs3m7p54"
}
```
id
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type|
|scheme|string|false|none|Indicates the cardholder scheme choice|
|number|string|false|none|The card number.|
|expiry_month|integer|false|none|The expiry month of the card.|
|expiry_year|integer|false|none|The expiry year of the card.|
|billing_address|[SessionAddress](#schemasessionaddress)|false|none|The customer's billing address. Any special characters will be replaced.|
|home_phone|[SessionPhone](#schemasessionphone)|false|none|The cardholder's home phone number|
|mobile_phone|[SessionPhone](#schemasessionphone)|false|none|The cardholder's mobile phone number|
|work_phone|[SessionPhone](#schemasessionphone)|false|none|The cardholder's work phone number|
|email|string|false|none|The email of the cardholder|
|id|string|true|none|The card instrument id|
#### Enumerated Values
|Property|Value|
|---|---|
|scheme|amex|
|scheme|cartes_bancaires|
|scheme|diners|
|scheme|mastercard|
|scheme|visa|
|scheme|discover|
|scheme|upi|
|scheme|jcb|
InitialTransaction
```json
{
"acs_transaction_id": "stringstringstringstringstringstring",
"authentication_method": "frictionless_authentication",
"authentication_timestamp": "2023-02-06T15:00:00.000Z",
"authentication_data": "string",
"initial_session_id": "sid_p6prbhogijnuxgv4grm3ber55u"
}
```
Details of a previous transaction
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|acs_transaction_id|string|false|none|The Access Control Server (ACS) transaction ID for a previously authenticated transaction|
|authentication_method|string|false|none|none|
|authentication_timestamp|string|false|none|The timestamp of the previous authentication, in ISO 8601 format.|
|authentication_data|string|false|none|Data that documents and supports a specific authentication process|
|initial_session_id|string|false|none|The ID for a previous session, which is used for retrieve the initial transaction's properties|
#### Enumerated Values
|Property|Value|
|---|---|
|authentication_method|frictionless_authentication|
|authentication_method|challenge_occurred|
|authentication_method|avs_verified|
|authentication_method|other_issuer_methods|
Installment
```json
{
"number_of_payments": 2,
"days_between_payments": 28,
"expiry": "20220901"
}
```
Details of an installment authentication. This property is needed only for an installment authentication type. Value will be ignored in any other cases.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|number_of_payments|integer|true|none|Indicates the agreed total number of payment installments to be made in the duration of the installment agreement. Required when the authentication type is `instalment`.|
|days_between_payments|integer|false|none|Indicates the minimum number of days between authorisations. If no value is specified for an installment authentication type the default value will be used.|
|expiry|string|false|none|Date after which no further authorisations are performed in the format yyyyMMdd. If no value is specified for an installment authentication type the default value will be used.|
MerchantInitiated
```json
{
"channel": "merchant_initiated",
"request_type": "recurring_transaction"
}
```
merchant_initiated
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|channel|string|true|none|none|
|request_type|string|true|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|channel|merchant_initiated|
|request_type|recurring_transaction|
|request_type|installment_transaction|
|request_type|add_card|
|request_type|maintain_card_information|
|request_type|account_verification|
|request_type|split_or_delayed_shipment|
|request_type|top_up|
|request_type|mail_order|
|request_type|telephone_order|
|request_type|whitelist_status_check|
|request_type|other_payment|
MerchantRiskInfo
```json
{
"delivery_email": "brucewayne@email.com",
"delivery_timeframe": "electronic_delivery",
"is_preorder": true,
"is_reorder": false,
"shipping_indicator": "billing_address",
"reorder_items_indicator": "first_time_ordered",
"pre_order_purchase_indicator": "merchandise_available",
"pre_order_date": "2019-08-24T14:15:22Z",
"gift_card_amount": "123",
"gift_card_currency": "USD",
"gift_card_count": "02"
}
```
Additional information about the cardholder's purchase.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|delivery_email|string|false|none|For Electronic delivery, the email address to which the merchandise was delivered.|
|delivery_timeframe|string|false|none|Indicates the merchandise delivery timeframe.|
|is_preorder|boolean|false|none|Indicates whether the cardholder is placing an order for merchandise with a future availability or release date.|
|is_reorder|boolean|false|none|Indicates whether the cardholder is reordering previously purchased merchandise.|
|shipping_indicator|string|false|none|Indicates the shipping method chosen for the transaction. Please choose an option that accurately describes the cardholder's specific transaction.|
|reorder_items_indicator|string|false|none|Specifies whether the cardholder is reordering merchandise they've previously purchased.|
|pre_order_purchase_indicator|string|false|none|Specifies whether the cardholder is placing an order for merchandise with an availability date or release date in the future.|
|pre_order_date|string(date-time)|false|none|The UTC date the pre-ordered merchandise is expected to be available, in ISO 8601 format.|
|gift_card_amount|string|false|none|The total purchase amount, in major units. For example, the major unit amount for a gift card purchase of 135.20 USD is `135`. Only applicable for prepaid or gift card purchases.|
|gift_card_currency|string|false|none|The currency code of the gift card, as a three-digit ISO 4217 code. Only applicable for prepaid or gift card purchases.|
|gift_card_count|string|false|none|The total number of individual prepaid cards, gift cards, or gift codes purchased. Only applicable for prepaid or gift card purchases.|
#### Enumerated Values
|Property|Value|
|---|---|
|delivery_timeframe|electronic_delivery|
|delivery_timeframe|same_day|
|delivery_timeframe|overnight|
|delivery_timeframe|two_day_or_more|
|shipping_indicator|billing_address|
|shipping_indicator|another_address_on_file|
|shipping_indicator|not_on_file|
|shipping_indicator|store_pick_up|
|shipping_indicator|digital_goods|
|shipping_indicator|travel_and_event_no_shipping|
|shipping_indicator|other|
|reorder_items_indicator|first_time_ordered|
|reorder_items_indicator|reordered|
|pre_order_purchase_indicator|merchandise_available|
|pre_order_purchase_indicator|future_availability|
NetworkTokenSource
```json
{
"type": "network_token",
"scheme": "amex",
"number": "4242424242424242",
"expiry_month": 12,
"expiry_year": 2077,
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "ABC building",
"address_line3": "14 Wells Mews",
"city": "London",
"state": "ENG",
"zip": "SW1A 1AA",
"country": "GB"
},
"home_phone": {
"country_code": "234",
"number": "0204567895"
},
"mobile_phone": {
"country_code": "234",
"number": "0204567895"
},
"work_phone": {
"country_code": "234",
"number": "0204567895"
},
"email": "bruce.wayne@email.com",
"token": "4543474002249996",
"name": "Bruce Wayne",
"stored": true
}
```
network_token
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type|
|scheme|string|false|none|Indicates the cardholder scheme choice|
|number|string|false|none|The card number.|
|expiry_month|integer|true|none|The expiry month of the card.|
|expiry_year|integer|true|none|The expiry year of the card.|
|billing_address|[SessionAddress](#schemasessionaddress)|false|none|The customer's billing address. Any special characters will be replaced.|
|home_phone|[SessionPhone](#schemasessionphone)|false|none|The cardholder's home phone number|
|mobile_phone|[SessionPhone](#schemasessionphone)|false|none|The cardholder's mobile phone number|
|work_phone|[SessionPhone](#schemasessionphone)|false|none|The cardholder's work phone number|
|email|string|false|none|The email of the cardholder|
|token|string|true|none|The network token PAN|
|name|string|false|none|The customer's name. Any special characters will be replaced.|
|stored|boolean|false|none|Indicates whether this card is being submitted from your own stored card-on-file system, rather than being entered by the customer at the time of payment. Set to `true` when you provide card details that you already have on file for the customer.|
#### Enumerated Values
|Property|Value|
|---|---|
|scheme|amex|
|scheme|cartes_bancaires|
|scheme|diners|
|scheme|mastercard|
|scheme|visa|
|scheme|discover|
|scheme|upi|
|scheme|jcb|
NextActions
```json
[
"redirect_cardholder"
]
```
Specifies which action to take in order to complete the session.
The `redirect_cardholder` action is only applicable for hosted sessions.
### Properties
*None*
NonHostedCompletionInfo
```json
{
"type": "non_hosted",
"callback_url": "http://example.com/payments/callback/pay_mbabizu24mvu3mela5njyhpit4",
"challenge_notification_url": "http://example.com/payments/challenge/sid_mbabizu24mvu3mela5njyhpit4"
}
```
non_hosted
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|Whether the session should be hosted by Checkout.com.|
|callback_url|string(uri)|false|none|For `non-hosted` sessions, you can define a URL to be called once the session is complete|
|challenge_notification_url|string(uri)|false|none|For `non-hosted` sessions, you can define a URL to be your own challenge notification endpoint. When not provided, a Checkout.com endpoint will be used.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|non_hosted|
NonHostedGoogleSpaInfo
```json
{
"challenge_url": "string",
"initial_timeout": "string",
"max_timeout": "string",
"iframe": {
"height": "string",
"width": "string"
},
"token": {
"number": "string",
"expiry_month": 0,
"expiry_year": 0
}
}
```
Non Hosted
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|challenge_url|string|false|none|Fully qualified URL of the Google SPA (Secure Payment Authentication) frontend for user challenge/unlock|
|initial_timeout|string|false|none|Indicates the amount of time (in minutes) allowed for establishing the initial connection to the user's specific authentication session, as determined by the challenge_url)|
|max_timeout|string|false|none|Indicates maximum amount of time (in minutes) allowed for completing all PSP-Google message exchanges for current authentication session|
|iframe|object|false|none|Details of the challenge iframe displayed in the Cardholder browser window|
|» height|string|false|none|Height of the challenge iframe displayed in the Cardholder browser window.|
|» width|string|false|none|Width of the challenge iframe displayed in the Cardholder browser window.|
|token|[GoogleSpaToken](#schemagooglespatoken)|false|none|Token for the given PAN provisioned and authenticated|
Optimization
```json
{
"framework": "acceptance_rates"
}
```
Optionally opt into request optimization
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|framework|string|false|none|The theme-based option for optimization|
#### Enumerated Values
|Property|Value|
|---|---|
|framework|acceptance_rates|
OptimizedProperty
```json
{
"field": "challenge_indicator",
"original_value": "trusted_listing",
"optimized_value": "transaction_risk_assessment"
}
```
Optionally opt into request optimization
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|field|string|false|none|Name of the field which has been optimized.|
|original_value|string|false|none|Value prior to optimization.|
|optimized_value|string|false|none|Value prior to optimization.|
PreferredExperiences
```json
{
"google_spa": {
"status": "available",
"reason": [
"Invalid response"
]
},
"3ds": {
"status": "available",
"reason": [
"Invalid response"
]
}
}
```
Preferred Experiences
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|google_spa|object|false|none|Google SPA experience.|
|» status|string|false|none|none|
|» reason|[string]|false|none|Reason(s) why processing the experience was unsuccessful.|
|3ds|object|false|none|3DS experience.|
|» status|string|false|none|none|
|» reason|[string]|false|none|Reason(s) why processing the experience was unsuccessful.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|available|
|status|unprocessed|
|status|processed|
|status|unavailable|
|status|available|
|status|unprocessed|
|status|processed|
|status|unavailable|
ProtocolVersion
```json
"2.2.0"
```
The protocol version number of the specification used by the API for authentication
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|The protocol version number of the specification used by the API for authentication|
Recurring
```json
{
"days_between_payments": 28,
"expiry": "20220901"
}
```
Details of a recurring authentication. This property is needed only for a recurring authentication type. Value will be ignored in any other cases.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|days_between_payments|integer|false|none|Indicates the minimum number of days between authorisations. If no value is specified for a recurring authentication type the default value will be used.|
|expiry|string|false|none|Date after which no further authorisations are performed in the format yyyyMMdd. If no value is specified for a recurring authentication type the default value will be used.|
Reference
```json
"ORD-5023-4E89"
```
A reference you can later use to identify this payment, such as an order number. **Do not pass sensitive information in this field e.g. card details**
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|A reference you can later use to identify this payment, such as an order number. **Do not pass sensitive information in this field e.g. card details**|
ResponseCode
```json
"Y"
```
Only available as a result of a 3DS2 authentication.
The response from the DS or ACS which indicates whether a transaction qualifies as an authenticated transaction or account verification.
Only available if communication with the scheme was successful and the Session is in a final state.
• Y = Authentication Verification Successful.
• N = Not Authenticated /Account Not Verified; Transaction denied.
• U = Authentication/ Account Verification Could Not Be Performed; Technical or other problem, as indicated in ARes or RReq.
• A = Attempts Processing Performed; Not Authenticated/Verified, but a proof of attempted authentication/verification is provided.
• C = Challenge Required; Additional authentication is required using the CReq/CRes.
• D = Challenge Required; Decoupled Authentication confirmed.
• R = Authentication/ Account Verification Rejected; Issuer is rejecting authentication/verification and request that authorization not be attempted.
• I = Informational Only; 3DS Requestor challenge preference acknowledged.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|Only available as a result of a 3DS2 authentication.
The response from the DS or ACS which indicates whether a transaction qualifies as an authenticated transaction or account verification.
Only available if communication with the scheme was successful and the Session is in a final state.
• Y = Authentication Verification Successful.
• N = Not Authenticated /Account Not Verified; Transaction denied.
• U = Authentication/ Account Verification Could Not Be Performed; Technical or other problem, as indicated in ARes or RReq.
• A = Attempts Processing Performed; Not Authenticated/Verified, but a proof of attempted authentication/verification is provided.
• C = Challenge Required; Additional authentication is required using the CReq/CRes.
• D = Challenge Required; Decoupled Authentication confirmed.
• R = Authentication/ Account Verification Rejected; Issuer is rejecting authentication/verification and request that authorization not be attempted.
• I = Informational Only; 3DS Requestor challenge preference acknowledged.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|Y|
|*anonymous*|N|
|*anonymous*|U|
|*anonymous*|A|
|*anonymous*|C|
|*anonymous*|D|
|*anonymous*|R|
|*anonymous*|I|
ResponseStatusReason
```json
"01"
```
Only available as a result of a 3DS2 authentication.
The response from the DS or ACS which provides information on why the `response_code` field has the specified value.
Only available when `response_code` is not `Y`.
Learn more about the reasons for authentication failures.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|Only available as a result of a 3DS2 authentication.
The response from the DS or ACS which provides information on why the `response_code` field has the specified value.
Only available when `response_code` is not `Y`.
Learn more about the reasons for authentication failures.
|
SdkEphemeralPublicKey
```json
{
"kty": "EC",
"crv": "P-256",
"x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
"y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0"
}
```
Public key component of the ephemeral key pair generated by the 3DS SDK and used to establish session keys between the 3DS SDK and ACS. Refer to https://tools.ietf.org/html/rfc7517#appendix-A.1
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|kty|string|false|none|The key type.|
|crv|string|false|none|The type of elliptic curve.|
|x|string|false|none|x coordinate of the elliptic curve that is base64url-encoded.|
|y|string|false|none|y coordinate of the elliptic curve that is base64url-encoded.|
#### Enumerated Values
|Property|Value|
|---|---|
|kty|EC|
SessionAddress
```json
{
"address_line1": "123 High St.",
"address_line2": "ABC building",
"address_line3": "14 Wells Mews",
"city": "London",
"state": "ENG",
"zip": "SW1A 1AA",
"country": "GB"
}
```
The shipping address. Any special characters will be replaced.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|address_line1|string|false|none|The first line of the address|
|address_line2|string|false|none|The second line of the address|
|address_line3|string|false|none|The third line of the address|
|city|string|false|none|The address city|
|state|string|false|none|The country subdivision code defined in ISO 3166-2|
|zip|string|false|none|The address zip/postal code|
|country|string|false|none|The two-letter ISO country code of the address|
SessionId
```json
"sid_y3oqhf46pyzuxjbcn2giaqnb44"
```
Session unique identifier
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|Session unique identifier|
SessionMarketplaceData
```json
{
"sub_entity_id": "ent_rgyzti4x74xubmu72m6r3pvksa"
}
```
Information related to authentication for payfac payments
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|sub_entity_id|string|false|none|The sub-entity that the authentication is being processed on behalf of|
SessionPhone
```json
{
"country_code": "234",
"number": "0204567895"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|country_code|string|true|none|Country code. According to ITU-E.164|
|number|string|true|none|The rest of the number. According to ITU-E.164|
SessionRequest
```json
{
"source": {
"type": "card",
"scheme": "amex",
"number": "4242424242424242",
"expiry_month": 12,
"expiry_year": 2077,
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "ABC building",
"address_line3": "14 Wells Mews",
"city": "London",
"state": "ENG",
"zip": "SW1A 1AA",
"country": "GB"
},
"home_phone": {
"country_code": "234",
"number": "0204567895"
},
"mobile_phone": {
"country_code": "234",
"number": "0204567895"
},
"work_phone": {
"country_code": "234",
"number": "0204567895"
},
"email": "bruce.wayne@email.com",
"name": "Bruce Wayne",
"stored": true
},
"amount": 6540,
"currency": "USD",
"processing_channel_id": "string",
"marketplace": {
"sub_entity_id": "ent_rgyzti4x74xubmu72m6r3pvksa"
},
"authentication_type": "regular",
"authentication_category": "payment",
"account_info": {
"purchase_count": 10,
"account_age": "no_account",
"add_card_attempts": 10,
"shipping_address_age": "this_transaction",
"account_name_matches_shipping_name": true,
"suspicious_account_activity": true,
"transactions_today": 10,
"authentication_method": "no_authentication",
"cardholder_account_age_indicator": "no_account,",
"account_change": "2019-08-24T14:15:22Z",
"account_change_indicator": "this_transaction",
"account_date": "2019-08-24T14:15:22Z",
"account_password_change": "2019-08-24T14:15:22Z",
"account_password_change_indicator": "no_change",
"transactions_per_year": 2,
"payment_account_age": "2019-08-24T14:15:22Z",
"shipping_address_usage": "2019-08-24T14:15:22Z",
"account_type": "not_applicable",
"account_id": "string",
"three_ds_requestor_authentication_info": {
"three_ds_req_auth_method": "no_threeds_requestor_authentication_occurred",
"three_ds_req_auth_timestamp": "2019-08-24T14:15:22Z",
"three_ds_req_auth_data": "string"
}
},
"challenge_indicator": "no_preference",
"billing_descriptor": {
"name": "SUPERHEROES.COM"
},
"reference": "ORD-5023-4E89",
"merchant_risk_info": {
"delivery_email": "brucewayne@email.com",
"delivery_timeframe": "electronic_delivery",
"is_preorder": true,
"is_reorder": false,
"shipping_indicator": "billing_address",
"reorder_items_indicator": "first_time_ordered",
"pre_order_purchase_indicator": "merchandise_available",
"pre_order_date": "2019-08-24T14:15:22Z",
"gift_card_amount": "123",
"gift_card_currency": "USD",
"gift_card_count": "02"
},
"transaction_type": "goods_service",
"shipping_address": {
"address_line1": "123 High St.",
"address_line2": "ABC building",
"address_line3": "14 Wells Mews",
"city": "London",
"state": "ENG",
"zip": "SW1A 1AA",
"country": "GB"
},
"shipping_address_matches_billing": false,
"completion": {
"type": "non_hosted",
"callback_url": "https://merchant.com/callback"
},
"channel_data": {
"channel": "browser",
"accept_header": "Accept: *.*, q=0.1",
"java_enabled": true,
"javascript_enabled": true,
"language": "FR-fr",
"color_depth": "16",
"screen_height": "1080",
"screen_width": "1920",
"timezone": "60",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
"three_ds_method_completion": "Y",
"ip_address": "1.12.123.255",
"iframe_payment_allowed": true,
"user_agent_client_hint": "Sec-CH-UA: \" Not A;Brand\";v=\"99\", \"Chromium\";v=\"96\", \"Google Chrome\";v=\"96\""
},
"recurring": {
"days_between_payments": 28,
"expiry": "20220901"
},
"installment": {
"number_of_payments": 2,
"days_between_payments": 28,
"expiry": "20220901"
},
"optimization": {
"framework": "acceptance_rates"
},
"initial_transaction": {
"acs_transaction_id": "stringstringstringstringstringstring",
"authentication_method": "frictionless_authentication",
"authentication_timestamp": "2023-02-06T15:00:00.000Z",
"authentication_data": "string",
"initial_session_id": "sid_p6prbhogijnuxgv4grm3ber55u"
},
"google_spa": {
"continue_url": "string"
},
"preferred_experiences": [
"3ds"
],
"device_information": {
"device_id": "string",
"device_session_id": "dsid_ipsmclhxwq72phhr32iwfvrflm"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|source|[SessionSource](#schemasessionsource)|true|none|The source of the authentication.|
|amount|integer|false|none|The payment amount in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-payment-amount).
For `recurring` and `installment` payment types, this value is required and must be greater than zero.
Omitting this value will set `authentication_category` to `non_payment`.|
|currency|string|true|none|The three-letter ISO currency code|
|processing_channel_id|string|false|none|The processing channel to be used for the session. Required if this was not set in the request for the OAuth token.|
|marketplace|[SessionMarketplaceData](#schemasessionmarketplacedata)|false|none|Information related to authentication for payfac payments|
|authentication_type|[AuthenticationType](#schemaauthenticationtype)|false|none|Indicates the type of payment this session is for. Please note the spelling of `installment` consists of two `l`s.|
|authentication_category|[Category](#schemacategory)|false|none|Indicates the category of the authentication request|
|account_info|[CardholderAccountInfo](#schemacardholderaccountinfo)|false|none|Additional information about the Cardholder's account.|
|challenge_indicator|[ChallengeIndicator](#schemachallengeindicator)|false|none|Indicates whether a challenge is requested for this session.
The following are requests for exemption:
• `low_value`
• `trusted_listing`
• `trusted_listing_prompt`
• `transaction_risk_assessment`
If an exemption cannot be applied, then the value `no_challenge_requested` will be used instead.|
|billing_descriptor|[SessionsBillingDescriptor](#schemasessionsbillingdescriptor)|false|none|An optional dynamic billing descriptor.|
|reference|[Reference](#schemareference)|false|none|A reference you can later use to identify this payment, such as an order number. **Do not pass sensitive information in this field e.g. card details**|
|merchant_risk_info|[MerchantRiskInfo](#schemamerchantriskinfo)|false|none|Additional information about the cardholder's purchase.|
|transaction_type|[TransactionType](#schematransactiontype)|false|none|Identifies the type of transaction being authenticated|
|shipping_address|[SessionAddress](#schemasessionaddress)|false|none|The shipping address. Any special characters will be replaced.|
|shipping_address_matches_billing|boolean|false|none|Indicates whether the cardholder shipping address and billing address are the same.|
|completion|[CompletionInfo](#schemacompletioninfo)|true|none|The redirect information needed for callbacks or redirects after the payment is completed|
|channel_data|[ChannelData](#schemachanneldata)|false|none|The information gathered from the environment used to initiate the session|
|recurring|[Recurring](#schemarecurring)|false|none|Details of a recurring authentication. This property is needed only for a recurring authentication type. Value will be ignored in any other cases.|
|installment|[Installment](#schemainstallment)|false|none|Details of an installment authentication. This property is needed only for an installment authentication type. Value will be ignored in any other cases.|
|optimization|[Optimization](#schemaoptimization)|false|none|Optionally opt into request optimization|
|initial_transaction|[InitialTransaction](#schemainitialtransaction)|false|none|Details of a previous transaction|
|google_spa|object|false|none|This object contains the Google SPA properties (non-hosted only)|
|» continue_url|string|false|none|Fully qualified URL for redirecting the user's browser session after authentication.
For example, this field may be the merchant's website for purchase confirmation once payment is complete.
Required if in full redirect (not iframe) mode.
|
|preferred_experiences|[[Experience](#schemaexperience)]|false|none|Indicates the chosen experience(s) for this session.
Available experiences include:
• `3ds`
• `google_spa`
|
|device_information|[DeviceInformation](#schemadeviceinformation)|false|none|Details of the device from which the authentication originated.|
SessionSecret
```json
"sek_Dal7UyiH8rIFXA4PfgiIk2jUyQkVDeEWgVBEL4TsRTE="
```
A base64 encoded value prefixed with `sek_` that gives access to client-side operations for a single authentication within the Sessions API. This value is returned as the `session_secret` when requesting a session.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|A base64 encoded value prefixed with `sek_` that gives access to client-side operations for a single authentication within the Sessions API. This value is returned as the `session_secret` when requesting a session.|
SessionSource
```json
{
"type": "card",
"scheme": "amex",
"number": "4242424242424242",
"expiry_month": 12,
"expiry_year": 2077,
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "ABC building",
"address_line3": "14 Wells Mews",
"city": "London",
"state": "ENG",
"zip": "SW1A 1AA",
"country": "GB"
},
"home_phone": {
"country_code": "234",
"number": "0204567895"
},
"mobile_phone": {
"country_code": "234",
"number": "0204567895"
},
"work_phone": {
"country_code": "234",
"number": "0204567895"
},
"email": "bruce.wayne@email.com",
"name": "Bruce Wayne",
"stored": true
}
```
The source of the authentication.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type|
|scheme|string|false|none|Indicates the cardholder scheme choice|
|number|string|false|none|The card number.|
|expiry_month|integer|false|none|The expiry month of the card.|
|expiry_year|integer|false|none|The expiry year of the card.|
|billing_address|[SessionAddress](#schemasessionaddress)|false|none|The customer's billing address. Any special characters will be replaced.|
|home_phone|[SessionPhone](#schemasessionphone)|false|none|The cardholder's home phone number|
|mobile_phone|[SessionPhone](#schemasessionphone)|false|none|The cardholder's mobile phone number|
|work_phone|[SessionPhone](#schemasessionphone)|false|none|The cardholder's work phone number|
|email|string|false|none|The email of the cardholder|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[CardSource](#schemacardsource)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[IdSource](#schemaidsource)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TokenSource](#schematokensource)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[NetworkTokenSource](#schemanetworktokensource)|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|scheme|amex|
|scheme|cartes_bancaires|
|scheme|diners|
|scheme|mastercard|
|scheme|visa|
|scheme|discover|
|scheme|upi|
|scheme|jcb|
Status
```json
"challenged"
```
Indicates the status of the session
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|Indicates the status of the session|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|challenged|
|*anonymous*|pending|
|*anonymous*|processing|
|*anonymous*|challenge_abandoned|
|*anonymous*|expired|
|*anonymous*|approved|
|*anonymous*|attempted|
|*anonymous*|unavailable|
|*anonymous*|declined|
|*anonymous*|rejected|
StatusReason
```json
"ares_status"
```
When the Session is unavailable this will point to the reason it is so.
• ares_error = There was an issue in the Authentication response we got back from the Directory Server (scheme server - 3DS2)
• ares_status = The status was set to the status in the Authentication response we got back from the Directory Server (scheme server - 3DS2)
• rreq_error = There was an issue in the Response we got back from the Access Control Server (issuer server - 3DS2)
• rreq_status = The status was set to the status in the Response we got back from the Access Control Server (issuer server - 3DS2)
• risk_declined = The status was set to declined because the Risk engine recommended we decline the authentication
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|When the Session is unavailable this will point to the reason it is so.
• ares_error = There was an issue in the Authentication response we got back from the Directory Server (scheme server - 3DS2)
• ares_status = The status was set to the status in the Authentication response we got back from the Directory Server (scheme server - 3DS2)
• rreq_error = There was an issue in the Response we got back from the Access Control Server (issuer server - 3DS2)
• rreq_status = The status was set to the status in the Response we got back from the Access Control Server (issuer server - 3DS2)
• risk_declined = The status was set to declined because the Risk engine recommended we decline the authentication
|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|ares_status|
|*anonymous*|ares_error|
|*anonymous*|rreq_error|
|*anonymous*|rreq_status|
|*anonymous*|risk_declined|
ThreeDsMethodCompletion
```json
{
"three_ds_method_completion": "Y"
}
```
The result of the 3DS method url
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|three_ds_method_completion|string|true|none|The result of the 3DS method URL.
Default to `U` if a response is not received from the 3DS Method URL within 10 seconds.|
#### Enumerated Values
|Property|Value|
|---|---|
|three_ds_method_completion|Y|
|three_ds_method_completion|N|
|three_ds_method_completion|U|
ThreeDsRequestorAuthenticationInfo
```json
{
"three_ds_req_auth_method": "no_threeds_requestor_authentication_occurred",
"three_ds_req_auth_timestamp": "2019-08-24T14:15:22Z",
"three_ds_req_auth_data": "string"
}
```
Information about how the 3DS Requestor authenticated the cardholder before or during the transaction.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|three_ds_req_auth_method|string|false|none|The mechanism used by the cardholder to authenticate with the 3DS Requestor.|
|three_ds_req_auth_timestamp|string(date-time)|false|none|The UTC date and time the cardholder authenticated with the 3DS Requestor, in ISO 8601 format.|
|three_ds_req_auth_data|string|false|none|Data that documents and supports a specific authentication process.|
#### Enumerated Values
|Property|Value|
|---|---|
|three_ds_req_auth_method|no_threeds_requestor_authentication_occurred|
|three_ds_req_auth_method|three3ds_requestor_own_credentials|
|three_ds_req_auth_method|federated_id|
|three_ds_req_auth_method|issuer_credentials|
|three_ds_req_auth_method|third_party_authentication|
|three_ds_req_auth_method|fido_authenticator|
|three_ds_req_auth_method|fido_authenticator_fido_assurance_data_signed|
|three_ds_req_auth_method|src_assurance_data|
TokenSource
```json
{
"type": "token",
"scheme": "amex",
"number": "4242424242424242",
"expiry_month": 12,
"expiry_year": 2077,
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "ABC building",
"address_line3": "14 Wells Mews",
"city": "London",
"state": "ENG",
"zip": "SW1A 1AA",
"country": "GB"
},
"home_phone": {
"country_code": "234",
"number": "0204567895"
},
"mobile_phone": {
"country_code": "234",
"number": "0204567895"
},
"work_phone": {
"country_code": "234",
"number": "0204567895"
},
"email": "bruce.wayne@email.com",
"token": "tok_4gzeau5o2uqubbk6fufs3m7p54"
}
```
token
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The payment source type|
|scheme|string|false|none|Indicates the cardholder scheme choice|
|number|string|false|none|The card number.|
|expiry_month|integer|false|none|The expiry month of the card.|
|expiry_year|integer|false|none|The expiry year of the card.|
|billing_address|[SessionAddress](#schemasessionaddress)|false|none|The customer's billing address. Any special characters will be replaced.|
|home_phone|[SessionPhone](#schemasessionphone)|false|none|The cardholder's home phone number|
|mobile_phone|[SessionPhone](#schemasessionphone)|false|none|The cardholder's mobile phone number|
|work_phone|[SessionPhone](#schemasessionphone)|false|none|The cardholder's work phone number|
|email|string|false|none|The email of the cardholder|
|token|string|true|none|The Checkout.com card token|
#### Enumerated Values
|Property|Value|
|---|---|
|scheme|amex|
|scheme|cartes_bancaires|
|scheme|diners|
|scheme|mastercard|
|scheme|visa|
|scheme|discover|
|scheme|upi|
|scheme|jcb|
TransactionType
```json
"goods_service"
```
Identifies the type of transaction being authenticated
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|Identifies the type of transaction being authenticated|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|goods_service|
|*anonymous*|check_acceptance|
|*anonymous*|account_funding|
|*anonymous*|quasi_card_transaction|
|*anonymous*|prepaid_activation_and_load|
TrustedBeneficiary
```json
{
"status": "Y",
"source": "01"
}
```
Details of the trusted listing status of the merchant.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|status|string|false|none|Enables the communication of trusted beneficiary status between the Access Control Server (ACS), the Directory Server (DS), and the 3D Secure (3DS) Requestor.
• Y = 3DS Requestor is allowlisted by cardholder
• N = 3DS Requestor is not allowlisted by cardholder
• E = Not eligible as determined by issuer
• P = Pending confirmation by cardholder
• R = Cardholder rejected
• U = Allowlist status unknown, unavailable, or does not apply|
|source|string|false|none|The system setting trusted beneficiary status.
• 01 = 3DS Server
• 02 = DS
• 03 = ACS
• 80-99 = DS-specific values
|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Y|
|status|N|
|status|E|
|status|P|
|status|R|
|status|U|
AccountUpdaterRequest
```json
{
"source_options": {
"card": {
"number": "5436424242424242",
"expiry_month": 5,
"expiry_year": 2025
},
"instrument": {
"id": "src_nmukohhu7vbe5f55ndwqzwv2c4"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|source_options|object|false|none|The source to update. You must provide either `card` or `instrument` object, but not both.|
|» card|[CardDetailsRequest](#schemacarddetailsrequest)|false|none|The card details|
|» instrument|[Instrument](#schemainstrument)|false|none|Instrument reference|
AccountUpdaterResponse
```json
{
"account_update_status": "CARD_UPDATED",
"account_update_failure_code": "CARDHOLDER_OPT_OUT",
"card": {
"encrypted_card_number": "3nCryp73dFPANv4lu3",
"bin": "543642",
"last4": "4242",
"expiry_month": 5,
"expiry_year": 2025,
"fingerprint": "abc123fingerprint"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|account_update_status|string|true|none|Result of the update operation.|
|account_update_failure_code|string|false|none|This field is returned when the update fails and the scheme returns an appropriate reason code.
For more information, see [Standalone Account Updater](https://checkout.com/docs/payments/store-and-manage-credentials/update-stored-credentials/standalone-account-updater)|
|card|[CardDetailsResponse](#schemacarddetailsresponse)|false|none|Updated card details. Fields vary depending on PCI compliance level.|
#### Enumerated Values
|Property|Value|
|---|---|
|account_update_status|CARD_UPDATED|
|account_update_status|CARD_EXPIRY_UPDATED|
|account_update_status|CARD_CLOSED|
|account_update_status|UPDATE_FAILED|
|account_update_failure_code|CARDHOLDER_OPT_OUT|
|account_update_failure_code|UP_TO_DATE|
|account_update_failure_code|NON_PARTICIPATING_BIN|
|account_update_failure_code|UNKNOWN|
CardDetailsRequest
```json
{
"number": "5436424242424242",
"expiry_month": 5,
"expiry_year": 2025
}
```
The card details
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|number|string|true|none|The card number.|
|expiry_month|integer(int32)|true|none|The expiry month of the card|
|expiry_year|integer(int32)|true|none|The four-digit expiry year of the card|
CardDetailsResponse
```json
{
"encrypted_card_number": "3nCryp73dFPANv4lu3",
"bin": "543642",
"last4": "4242",
"expiry_month": 5,
"expiry_year": 2025,
"fingerprint": "abc123fingerprint"
}
```
Updated card details. Fields vary depending on PCI compliance level.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|encrypted_card_number|string|false|none|The encrypted full Primary Account Number (PAN). Returned only for PCI SAQ D merchants.|
|bin|string|false|none|The first 6 digits of the PAN.|
|last4|string|false|none|Last 4 digits of the PAN.|
|expiry_month|integer(int32)|true|none|Expiry month. Expressed in number.|
|expiry_year|integer(int32)|true|none|Four-digit expiry year.|
|fingerprint|string|false|none|Unique identifier for the card|
Instrument
```json
{
"id": "src_nmukohhu7vbe5f55ndwqzwv2c4"
}
```
Instrument reference
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|true|none|Unique instrument identifier|
Timestamp
```json
"2019-08-24T14:15:22Z"
```
ISO 8601 timestamp
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string(date-time)|false|none|ISO 8601 timestamp|
01_CardTokenRequest
```json
{
"type": "card",
"number": "4543474002249996",
"expiry_month": 6,
"expiry_year": 2025,
"name": "Bruce Wayne",
"cvv": "956",
"pin": "12",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
}
```
card
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of card details to be tokenized|
|number|string|true|none|The card number|
|expiry_month|integer|true|none|The expiry month of the card|
|expiry_year|integer|true|none|The expiry year of the card|
|name|string|false|none|The cardholder's name|
|cvv|string|false|none|The card verification value/code. 3 digits, except for American Express (4 digits)|
|pin|string|false|none|The first 2 digits of the card PIN|
|billing_address|[Address](#schemaaddress)|false|none|The payment source owner's billing address|
|phone|[PhoneNumber](#schemaphonenumber)|false|none|The payment source owner's phone number|
#### Enumerated Values
|Property|Value|
|---|---|
|type|card|
01_CardTokenResponse
```json
{
"type": "card",
"token": "tok_ubfj2q76miwundwlk72vxt2i7q",
"expires_on": "2019-08-24T14:15:22Z",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"expiry_month": 6,
"expiry_year": 2025,
"name": "Bruce Wayne",
"scheme": "VISA",
"scheme_local": "cartes_bancaires",
"last4": "9996",
"bin": "454347",
"card_type": "CREDIT",
"card_category": "CONSUMER",
"issuer": "GOTHAM STATE BANK",
"issuer_country": "US",
"product_id": "F",
"product_type": "CLASSIC"
}
```
card
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The type of card details to be tokenized|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[TokenResponseType](#schematokenresponsetype)|false|none|Ordered list of token response types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|token|string|true|none|The reference token|
|expires_on|[ServerTimestamp](#schemaservertimestamp)|true|none|The date/time the token will expire|
|billing_address|[Address](#schemaaddress)|false|none|The payment source owner's billing address|
|phone|[PhoneNumber](#schemaphonenumber)|false|none|The payment source owner's phone number|
|expiry_month|integer|true|none|The expiry month|
|expiry_year|integer|true|none|The expiry year|
|name|string|false|none|The cardholder's name|
|scheme|string|true|none|The card scheme|
|scheme_local|string|false|none|The local co-branded card scheme|
|last4|string|true|none|The last four digits of the card number|
|bin|string|true|none|The card issuer's Bank Identification Number (BIN)|
|card_type|string|false|none|The card type|
|card_category|string|false|none|The card category|
|issuer|string|false|none|The name of the card issuer|
|issuer_country|string|false|none|The card issuer's country (two-letter ISO code)|
|product_id|string|false|none|The issuer/card scheme product identifier|
|product_type|string|false|none|The issuer/card scheme product type|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|card|
|scheme_local|cartes_bancaires|
|card_type|CREDIT|
|card_type|DEBIT|
|card_type|PREPAID|
|card_type|CHARGE|
|card_type|DEFERRED DEBIT|
|card_category|CONSUMER|
|card_category|COMMERCIAL|
02_GooglePayTokenRequest
```json
{
"type": "googlepay",
"token_data": {
"protocolVersion": "ECv1",
"signature": "TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ",
"signedMessage": "{\"encryptedMessage\": \"ZW5jcnlwdGVkTWVzc2FnZQ==\", \"ephemeralPublicKey\": \"ZXBoZW1lcmFsUHVibGljS2V5\", \"tag\": \"c2lnbmF0dXJl\"}"
}
}
```
googlepay
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of card details to be tokenized|
|token_data|object|false|none|The Google Pay payment token|
|» signature|string|false|none|Verifies the message came from Google. The signature is created using ECDSA|
|» protocolVersion|string|false|none|Identifies which encryption/signing scheme created this message. In this way, the protocol can evolve over time if needed. If it is not set, assume ECv0|
|» signedMessage|string|false|none|A serialized JSON string containing the encryptedMessage, ephemeralPublicKey, and tag. To simplify the signature verification process, this value is serialized|
#### Enumerated Values
|Property|Value|
|---|---|
|type|googlepay|
02_GooglePayTokenResponse
```json
{
"type": "googlepay",
"token": "tok_ubfj2q76miwundwlk72vxt2i7q",
"expires_on": "2019-08-24T14:15:22Z",
"expiry_month": 6,
"expiry_year": 2025,
"scheme": "VISA",
"scheme_local": "cartes_bancaires",
"last4": "9996",
"bin": "454347",
"card_type": "CREDIT",
"card_category": "CONSUMER",
"issuer": "GOTHAM STATE BANK",
"issuer_country": "US",
"product_id": "F",
"product_type": "CLASSIC",
"token_format": "pan_only"
}
```
googlepay
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The type of card details to be tokenized|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[TokenResponseType](#schematokenresponsetype)|false|none|Ordered list of token response types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|token|string|true|none|The reference token|
|expires_on|[ServerTimestamp](#schemaservertimestamp)|true|none|The date/time the token will expire|
|expiry_month|integer|true|none|The expiry month|
|expiry_year|integer|true|none|expiry year|
|scheme|string|true|none|The card scheme|
|scheme_local|string|false|none|The local co-branded card scheme|
|last4|string|true|none|The last four digits of the card number|
|bin|string|true|none|The card issuer BIN|
|card_type|string|false|none|The card type|
|card_category|string|false|none|The card category|
|issuer|string|false|none|The name of the card issuer|
|issuer_country|string|false|none|The card issuer country ISO-2 code|
|product_id|string|false|none|The issuer/card scheme product identifier|
|product_type|string|false|none|The issuer/card scheme product type|
|token_format|string|false|none|The format of the token.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|googlepay|
|scheme_local|cartes_bancaires|
|card_type|CREDIT|
|card_type|DEBIT|
|card_type|PREPAID|
|card_type|CHARGE|
|card_type|DEFERRED DEBIT|
|card_category|CONSUMER|
|card_category|COMMERCIAL|
|token_format|pan_only|
|token_format|cryptogram_3ds|
03_ApplePayTokenRequest
```json
{
"type": "applepay",
"token_data": {
"version": "EC_v1",
"data": "t7GeajLB9skXB6QSWfEpPA4WPhDqB7ekdd+F7588arLzvebKp3P0TekUslSQ8nkuacUgLdks2IKyCm7U3OL/PEYLXE7w60VkQ8WE6FXs/cqHkwtSW9vkzZNDxSLDg9slgLYxAH2/iztdipPpyIYKl0Kb6Rn9rboF+lwgRxM1B3n84miApwF5Pxl8ZOOXGY6F+3DsDo7sMCUTaJK74DUJJcjIXrigtINWKW6RFa/4qmPEC/Y+syg04x7B99mbLQQzWFm7z6HfRmynPM9/GA0kbsqd/Kn5Mkqssfhn/m6LuNKsqEmbKi85FF6kip+F17LRawG48bF/lT8wj/QEuDY0G7t/ryOnGLtKteXmAf0oJnwkelIyfyj2KI8GChBuTJonGlXKr5klPE89/ycmkgDl+T6Ms7PhiNZpuGEE2QE=",
"signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID5jCCA4ugAwIBAgIIaGD2mdnMpw8wCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE2MDYwMzE4MTY0MFoXDTIxMDYwMjE4MTY0MFowYjEoMCYGA1UEAwwfZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtU0FOREJPWDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgjD9q8Oc914gLFDZm0US5jfiqQHdbLPgsc1LUmeY+M9OvegaJajCHkwz3c6OKpbC9q+hkwNFxOh6RCbOlRsSlaOCAhEwggINMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDIwHQYDVR0OBBYEFAIkMAua7u1GMZekplopnkJxghxFMAwGA1UdEwEB/wQCMAAwHwYDVR0jBBgwFoAUI/JJxE+T5O8n5sT2KGw/orv9LkswggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMA4GA1UdDwEB/wQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0kAMEYCIQDaHGOui+X2T44R6GVpN7m2nEcr6T6sMjOhZ5NuSo1egwIhAL1a+/hp88DKJ0sv3eT3FxWcs71xmbLKD/QJ3mWagrJNMIIC7jCCAnWgAwIBAgIISW0vvzqY2pcwCgYIKoZIzj0EAwIwZzEbMBkGA1UEAwwSQXBwbGUgUm9vdCBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwHhcNMTQwNTA2MjM0NjMwWhcNMjkwNTA2MjM0NjMwWjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATwFxGEGddkhdUaXiWBB3bogKLv3nuuTeCN/EuT4TNW1WZbNa4i0Jd2DSJOe7oI/XYXzojLdrtmcL7I6CmE/1RFo4H3MIH0MEYGCCsGAQUFBwEBBDowODA2BggrBgEFBQcwAYYqaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZXJvb3RjYWczMB0GA1UdDgQWBBQj8knET5Pk7yfmxPYobD+iu/0uSzAPBgNVHRMBAf8EBTADAQH/MB8GA1UdIwQYMBaAFLuw3qFYM4iapIqZ3r6966/ayySrMDcGA1UdHwQwMC4wLKAqoCiGJmh0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlcm9vdGNhZzMuY3JsMA4GA1UdDwEB/wQEAwIBBjAQBgoqhkiG92NkBgIOBAIFADAKBggqhkjOPQQDAgNnADBkAjA6z3KDURaZsYb7NcNWymK/9Bft2Q91TaKOvvGcgV5Ct4n4mPebWZ+Y1UENj53pwv4CMDIt1UQhsKMFd2xd8zg7kGf9F3wsIW2WT8ZyaYISb1T4en0bmcubCYkhYQaZDwmSHQAAMYIBjTCCAYkCAQEwgYYwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTAghoYPaZ2cynDzANBglghkgBZQMEAgEFAKCBlTAYBgkqhkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0xNzA4MDIxNjA5NDZaMCoGCSqGSIb3DQEJNDEdMBswDQYJYIZIAWUDBAIBBQChCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEIGEfVr+4x9RQXyfF8IYA0kraoK0pcZEaBlINo6EGrOReMAoGCCqGSM49BAMCBEgwRgIhAKunK47QEr/ZjxPlVl+etzVzbKA41xPLWtO01oUOlulmAiEAiaFH9F9LK6uqTFAUW/WIDkHWiFuSm5a3NVox7DlyIf0AAAAAAAA=",
"header": {
"ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEX1ievoT8DRB8T5zGkhHZHeDr0oBmYEgsDSxyT0MD0IZ2Mpfjz2LdWq6LUwSH9EmxdPEzMunsZKWMyOr3K/zlsw==",
"publicKeyHash": "tqYV+tmG9aMh+l/K6cicUnPqkb1gUiLjSTM9gEz6Nl0=",
"transactionId": "3cee89679130a4b2617c76118a1c62fd400cd45b49dc0916d5b951b560cd17b4"
}
}
}
```
applepay
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of card details to be tokenized|
|token_data|[TokenData](#schematokendata)|true|none|The Apple Pay payment token|
#### Enumerated Values
|Property|Value|
|---|---|
|type|applepay|
03_ApplePayTokenResponse
```json
{
"type": "applepay",
"token": "tok_ubfj2q76miwundwlk72vxt2i7q",
"expires_on": "2019-08-24T14:15:22Z",
"expiry_month": 6,
"expiry_year": 2025,
"scheme": "VISA",
"scheme_local": "cartes_bancaires",
"last4": "9996",
"bin": "454347",
"card_type": "CREDIT",
"card_category": "CONSUMER",
"issuer": "GOTHAM STATE BANK",
"issuer_country": "US",
"product_id": "F",
"product_type": "CLASSIC",
"token_format": "cryptogram_3ds"
}
```
applepay
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The type of card details to be tokenized|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[TokenResponseType](#schematokenresponsetype)|false|none|Ordered list of token response types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|token|string|true|none|The reference token|
|expires_on|[ServerTimestamp](#schemaservertimestamp)|true|none|The date/time the token will expire|
|expiry_month|integer|true|none|The expiry month|
|expiry_year|integer|true|none|expiry year|
|scheme|string|true|none|The card scheme|
|scheme_local|string|false|none|The local co-branded card scheme|
|last4|string|true|none|The last four digits of the card number|
|bin|string|true|none|The card issuer BIN|
|card_type|string|false|none|The card type|
|card_category|string|false|none|The card category|
|issuer|string|false|none|The name of the card issuer|
|issuer_country|string|false|none|The card issuer country ISO-2 code|
|product_id|string|false|none|The issuer/card scheme product identifier|
|product_type|string|false|none|The issuer/card scheme product type|
|token_format|string|false|none|The format of the token.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|applepay|
|scheme_local|cartes_bancaires|
|card_type|CREDIT|
|card_type|DEBIT|
|card_type|PREPAID|
|card_type|CHARGE|
|card_type|DEFERRED DEBIT|
|card_category|CONSUMER|
|card_category|COMMERCIAL|
|token_format|cryptogram_3ds|
04_CvvTokenRequest
```json
{
"type": "cvv",
"token_data": {
"cvv": "123"
}
}
```
cvv
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of card details to be tokenized|
|token_data|object|true|none|Data containing the CVV token value|
|» cvv|string|false|none|The card verification value/code. 3 digits, except for American Express (4 digits)|
#### Enumerated Values
|Property|Value|
|---|---|
|type|cvv|
04_CvvTokenResponse
```json
{
"type": "cvv",
"token": "tok_ubfj2q76miwundwlk72vxt2i7q",
"expires_on": "2023-07-11T15:57:32.435+00:00"
}
```
cvv
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The type of card details to be tokenized|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[TokenResponseType](#schematokenresponsetype)|false|none|Ordered list of token response types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|token|string|true|none|The token id.|
|expires_on|string(date-time)|true|none|The expiry value for the token id.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|cvv|
05_PinTokenRequest
```json
{
"type": "pin",
"token_data": {
"pin": "12"
}
}
```
pin
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of card details to be tokenized|
|token_data|object|true|none|Data containing the PIN token value|
|» pin|string|false|none|The first 2 digits of the card PIN|
#### Enumerated Values
|Property|Value|
|---|---|
|type|pin|
05_PinTokenResponse
```json
{
"type": "pin",
"token": "tok_ubfj2q76miwundwlk72vxt2i7q",
"expires_on": "2023-07-11T15:57:32.435+00:00"
}
```
pin
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|any|true|none|The type of card details to be tokenized|
allOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[TokenResponseType](#schematokenresponsetype)|false|none|Ordered list of token response types used for discriminators|
and
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|string|false|none|none|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|token|string|true|none|The token id.|
|expires_on|string(date-time)|true|none|The expiry value for the token id.|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|pin|
TokenData
```json
{
"version": "EC_v1",
"data": "t7GeajLB9skXB6QSWfEpPA4WPhDqB7ekdd+F7588arLzvebKp3P0TekUslSQ8nkuacUgLdks2IKyCm7U3OL/PEYLXE7w60VkQ8WE6FXs/cqHkwtSW9vkzZNDxSLDg9slgLYxAH2/iztdipPpyIYKl0Kb6Rn9rboF+lwgRxM1B3n84miApwF5Pxl8ZOOXGY6F+3DsDo7sMCUTaJK74DUJJcjIXrigtINWKW6RFa/4qmPEC/Y+syg04x7B99mbLQQzWFm7z6HfRmynPM9/GA0kbsqd/Kn5Mkqssfhn/m6LuNKsqEmbKi85FF6kip+F17LRawG48bF/lT8wj/QEuDY0G7t/ryOnGLtKteXmAf0oJnwkelIyfyj2KI8GChBuTJonGlXKr5klPE89/ycmkgDl+T6Ms7PhiNZpuGEE2QE=",
"signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID5jCCA4ugAwIBAgIIaGD2mdnMpw8wCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE2MDYwMzE4MTY0MFoXDTIxMDYwMjE4MTY0MFowYjEoMCYGA1UEAwwfZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtU0FOREJPWDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgjD9q8Oc914gLFDZm0US5jfiqQHdbLPgsc1LUmeY+M9OvegaJajCHkwz3c6OKpbC9q+hkwNFxOh6RCbOlRsSlaOCAhEwggINMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDIwHQYDVR0OBBYEFAIkMAua7u1GMZekplopnkJxghxFMAwGA1UdEwEB/wQCMAAwHwYDVR0jBBgwFoAUI/JJxE+T5O8n5sT2KGw/orv9LkswggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMA4GA1UdDwEB/wQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0kAMEYCIQDaHGOui+X2T44R6GVpN7m2nEcr6T6sMjOhZ5NuSo1egwIhAL1a+/hp88DKJ0sv3eT3FxWcs71xmbLKD/QJ3mWagrJNMIIC7jCCAnWgAwIBAgIISW0vvzqY2pcwCgYIKoZIzj0EAwIwZzEbMBkGA1UEAwwSQXBwbGUgUm9vdCBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwHhcNMTQwNTA2MjM0NjMwWhcNMjkwNTA2MjM0NjMwWjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATwFxGEGddkhdUaXiWBB3bogKLv3nuuTeCN/EuT4TNW1WZbNa4i0Jd2DSJOe7oI/XYXzojLdrtmcL7I6CmE/1RFo4H3MIH0MEYGCCsGAQUFBwEBBDowODA2BggrBgEFBQcwAYYqaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZXJvb3RjYWczMB0GA1UdDgQWBBQj8knET5Pk7yfmxPYobD+iu/0uSzAPBgNVHRMBAf8EBTADAQH/MB8GA1UdIwQYMBaAFLuw3qFYM4iapIqZ3r6966/ayySrMDcGA1UdHwQwMC4wLKAqoCiGJmh0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlcm9vdGNhZzMuY3JsMA4GA1UdDwEB/wQEAwIBBjAQBgoqhkiG92NkBgIOBAIFADAKBggqhkjOPQQDAgNnADBkAjA6z3KDURaZsYb7NcNWymK/9Bft2Q91TaKOvvGcgV5Ct4n4mPebWZ+Y1UENj53pwv4CMDIt1UQhsKMFd2xd8zg7kGf9F3wsIW2WT8ZyaYISb1T4en0bmcubCYkhYQaZDwmSHQAAMYIBjTCCAYkCAQEwgYYwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTAghoYPaZ2cynDzANBglghkgBZQMEAgEFAKCBlTAYBgkqhkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0xNzA4MDIxNjA5NDZaMCoGCSqGSIb3DQEJNDEdMBswDQYJYIZIAWUDBAIBBQChCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEIGEfVr+4x9RQXyfF8IYA0kraoK0pcZEaBlINo6EGrOReMAoGCCqGSM49BAMCBEgwRgIhAKunK47QEr/ZjxPlVl+etzVzbKA41xPLWtO01oUOlulmAiEAiaFH9F9LK6uqTFAUW/WIDkHWiFuSm5a3NVox7DlyIf0AAAAAAAA=",
"header": {
"ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEX1ievoT8DRB8T5zGkhHZHeDr0oBmYEgsDSxyT0MD0IZ2Mpfjz2LdWq6LUwSH9EmxdPEzMunsZKWMyOr3K/zlsw==",
"publicKeyHash": "tqYV+tmG9aMh+l/K6cicUnPqkb1gUiLjSTM9gEz6Nl0=",
"transactionId": "3cee89679130a4b2617c76118a1c62fd400cd45b49dc0916d5b951b560cd17b4"
}
}
```
The Apple Pay payment token
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|version|string|false|none|Version information about the payment token. The token uses `EC_v1` for ECC-encrypted data, and `RSA_v1` for RSA-encrypted data|
|data|string|false|none|Encrypted payment data. Base64 encoded as a string|
|signature|string|false|none|Signature of the payment and header data. The signature includes the signing certificate, its intermediate CA certificate, and information about the signing algorithm|
|header|object|false|none|Additional version-dependent information used to decrypt and verify the payment|
```json
{
"token": "tok_4gzeau5o2uqubbk6fudbloo47a",
"type": "card",
"expires_on": "2019-08-24T14:15:22Z",
"expiry_month": 12,
"expiry_year": 2030,
"scheme": "Visa",
"last4": "4242",
"bin": "424242",
"card_type": "CREDIT",
"card_category": "CONSUMER",
"issuer": "JPMORGAN CHASE BANK NA",
"issuer_country": "US",
"product_id": "A",
"product_type": "Visa Traditional",
"billing_address": {
"city": "London",
"country": "GB"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|token|string|true|none|The token ID|
|type|string|true|none|The token type.|
|expires_on|[ServerTimestamp](#schemaservertimestamp)|true|none|The date/time the token will expire.|
|expiry_month|integer|true|none|The card expiry month.|
|expiry_year|integer|true|none|The card expiry year.|
|scheme|string|true|none|The card scheme.|
|last4|string|true|none|The last four digits of the card number.|
|bin|string|true|none|The card issuer BIN.|
|card_type|string|false|none|The card type.|
|card_category|string|false|none|The card category.|
|issuer|string|false|none|The name of the card issuer.|
|issuer_country|string|false|none|The card issuer's country (two-letter ISO code).|
|product_id|string|false|none|The issuer or card scheme's product identifier.|
|product_type|string|false|none|The issuer or card scheme's product type.|
|billing_address|object¦null|false|none|Partial billing address — city and country only.|
|» city|string|false|none|The address city|
|» country|string|false|none|The billing address country's (two-letter ISO code).|
#### Enumerated Values
|Property|Value|
|---|---|
|card_type|CREDIT|
|card_type|DEBIT|
|card_type|PREPAID|
|card_type|CHARGE|
|card_type|DEFERRED DEBIT|
|card_category|CONSUMER|
|card_category|COMMERCIAL|
TokenRequest
```json
{
"type": "card",
"number": "4543474002249996",
"expiry_month": 6,
"expiry_year": 2025,
"name": "Bruce Wayne",
"cvv": "956",
"pin": "12",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
}
```
The source of the payment
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[01_CardTokenRequest](#schema01_cardtokenrequest)|false|none|Card Token Request|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[02_GooglePayTokenRequest](#schema02_googlepaytokenrequest)|false|none|Google Pay Token Request|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[03_ApplePayTokenRequest](#schema03_applepaytokenrequest)|false|none|Apple Pay Token Request|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[04_CvvTokenRequest](#schema04_cvvtokenrequest)|false|none|CVV Token Request|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[05_PinTokenRequest](#schema05_pintokenrequest)|false|none|PIN Token Request|
TokenResponse
```json
{
"type": "card",
"token": "tok_ubfj2q76miwundwlk72vxt2i7q",
"expires_on": "2019-08-24T14:15:22Z",
"expiry_month": 6,
"expiry_year": 2025,
"scheme": "VISA",
"scheme_local": "cartes_bancaires",
"last4": "9996",
"bin": "454347",
"card_type": "CREDIT",
"card_category": "CONSUMER",
"issuer": "GOTHAM STATE BANK",
"issuer_country": "US",
"product_id": "F",
"product_type": "CLASSIC",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"name": "Bruce Wayne"
}
```
The source of the payment
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|[TokenResponseType](#schematokenresponsetype)|true|none|The type of card details to be tokenized|
|token|string|true|none|The reference token|
|expires_on|[ServerTimestamp](#schemaservertimestamp)|true|none|The date/time the token will expire|
|expiry_month|integer|false|none|The expiry month|
|expiry_year|integer|false|none|expiry year|
|scheme|string|false|none|The card scheme|
|scheme_local|string|false|none|The local co-branded card scheme|
|last4|string|false|none|The last four digits of the card number|
|bin|string|false|none|The card issuer BIN|
|card_type|string|false|none|The card type|
|card_category|string|false|none|The card category|
|issuer|string|false|none|The name of the card issuer|
|issuer_country|string|false|none|The card issuer country ISO-2 code|
|product_id|string|false|none|The issuer/card scheme product identifier|
|product_type|string|false|none|The issuer/card scheme product type|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[01_CardTokenResponse](#schema01_cardtokenresponse)|false|none|Card Token Response|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[02_GooglePayTokenResponse](#schema02_googlepaytokenresponse)|false|none|Google Pay Token Response|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[03_ApplePayTokenResponse](#schema03_applepaytokenresponse)|false|none|Apple Pay Token Response|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[04_CvvTokenResponse](#schema04_cvvtokenresponse)|false|none|CVV Token Response|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[05_PinTokenResponse](#schema05_pintokenresponse)|false|none|PIN Token Response|
#### Enumerated Values
|Property|Value|
|---|---|
|scheme_local|cartes_bancaires|
|card_type|CREDIT|
|card_type|DEBIT|
|card_type|PREPAID|
|card_type|CHARGE|
|card_type|DEFERRED DEBIT|
|card_category|CONSUMER|
|card_category|COMMERCIAL|
TokenResponseType
```json
"card"
```
Ordered list of token response types used for discriminators
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|string|false|none|Ordered list of token response types used for discriminators|
#### Enumerated Values
|Property|Value|
|---|---|
|*anonymous*|card|
|*anonymous*|googlepay|
|*anonymous*|applepay|
|*anonymous*|cvv|
|*anonymous*|pin|
CreateTransferRequest
```json
{
"reference": "superhero1234",
"transfer_type": "commission",
"source": {
"id": "ent_azsiyswl7bwe2ynjzujy7lcjca",
"amount": 100,
"currency": "GBP"
},
"destination": {
"id": "ent_w4jelhppmfiufdnatam37wrfc4"
}
}
```
Create transfer request
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reference|string|false|none|A reference you can use later to identify this transfer|
|transfer_type|[TransferType](#schematransfertype)|true|none|The type of transfer|
|source|[TransferSource](#schematransfersource)|true|none|The object representing the source of the funds involved in the transfer.|
|destination|[TransferDestination](#schematransferdestination)|true|none|The object representing the destination of the funds involved in the transfer.|
CreateTransferResponse
```json
{
"id": "tra_y3oqhf46pyzuxjbcn2giaqnb4",
"status": "pending",
"_links": {
"self": {
"href": "https://transfers.checkout.com/transfers/tra_y3oqhf46pyzuxjbcn2giaqnb4"
}
}
}
```
Create transfer response
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The `id` representing the initiated transfer.|
|status|[TransferStatus](#schematransferstatus)|false|none|The current state of the initiated transfer.|
|_links|object|false|none|none|
|» self|[TransferLink](#schematransferlink)|false|none|none|
Transfer
```json
{
"id": "tra_y3oqhf46pyzuxjbcn2giaqnb4",
"reference": "superhero1234",
"status": "rejected",
"transfer_type": "commission",
"requested_on": "2021-12-15T09:15:02.3845763Z",
"reason_codes": [
"destination_transfers_capability_disabled",
"source_and_destination_currency_accounts_must_be_different"
],
"source": {
"entity_id": "ent_azsiyswl7bwe2ynjzujy7lcjca",
"amount": 100,
"currency": "GBP"
},
"destination": {
"entity_id": "ent_bqik7gxoavwhmy3ot6kvmbx6py"
},
"_links": {
"self": {
"href": "https://transfers.checkout.com/transfers/tra_y3oqhf46pyzuxjbcn2giaqnb4"
}
}
}
```
The transfer information
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The transfer identifier|
|reference|string|false|none|A unique reference used to identify this transfer|
|status|[TransferStatus](#schematransferstatus)|false|none|The current state of the initiated transfer.|
|transfer_type|[TransferType](#schematransfertype)|false|none|The type of transfer|
|requested_on|string|false|none|The date the transfer was requested on|
|reason_codes|[string]|false|none|An optional set of reason codes describing why the transfer is in its current state|
|source|object|false|none|The source of the funds involved in the transfer|
|» entity_id|string|false|none|The ID of the entity that sent the transfer|
|» amount|integer|false|none|The amount transferred, in the minor unit of the currency represented by the `currency` property|
|» currency|string|false|none|The ISO currency code of the funds being transferred|
|destination|object|false|none|The destination of the funds involved in the transfer|
|» entity_id|string|false|none|The ID of the entity that received the transfer|
|_links|object|false|none|none|
|» self|[TransferLink](#schematransferlink)|false|none|none|
TransferDestination
```json
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4"
}
```
Transfer destination
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The identifier representing the destination of the funds. Currently this should be an entity ID.|
TransferLink
```json
{
"href": "string"
}
```
Transfer link
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|href|string|false|none|The link URL.|
TransferSource
```json
{
"id": "ent_azsiyswl7bwe2ynjzujy7lcjca",
"amount": 100,
"currency": "GBP"
}
```
Transfer source
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The identifier representing the source of the funds. Currently this should be an entity ID.|
|amount|integer|false|none|The amount to be transferred, in the minor unit of the currency (which is represented by the `id` and, optionally, the `currency` property)|
|currency|string(ISO 4217)|false|none|The currency that the transfer should be made in. This should be a currency supported by both the source and destination of the transfer.|
TransferStatus
```json
"pending"
```
Transfer status
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|Transfer status|string|false|none|The current state of the initiated transfer.|
#### Enumerated Values
|Property|Value|
|---|---|
|Transfer status|pending|
|Transfer status|completed|
|Transfer status|rejected|
TransferType
```json
"commission"
```
Transfer type
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|Transfer type|string|false|none|The type of transfer|
#### Enumerated Values
|Property|Value|
|---|---|
|Transfer type|commission|
|Transfer type|promotion|
|Transfer type|refund|
UnreferencedRefundRequestAccountHolder
```json
{
"type": "individual",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"billing_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "str",
"zip": "string",
"country": "st"
},
"phone": {
"country_code": "string",
"number": "string"
},
"identification": {
"type": "passport",
"number": "string",
"issuing_country": "st",
"date_of_expiry": "stringstri"
},
"email": "string",
"date_of_birth": "stringstri",
"country_of_birth": "st"
}
```
The unreferenced refund destination account holder.
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[UnreferencedRefundRequestIndividualAccountHolder](#schemaunreferencedrefundrequestindividualaccountholder)|false|none|The unreferenced refund destination account holder's details.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[UnreferencedRefundRequestCorporateAccountHolder](#schemaunreferencedrefundrequestcorporateaccountholder)|false|none|The unreferenced refund destination account holder's details.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[UnreferencedRefundRequestGovernmentAccountHolder](#schemaunreferencedrefundrequestgovernmentaccountholder)|false|none|The unreferenced refund destination account holder's details.|
UnreferencedRefundRequestCorporateAccountHolder
```json
{
"type": "corporate",
"company_name": "string",
"billing_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "str",
"zip": "string",
"country": "st"
},
"phone": {
"country_code": "string",
"number": "string"
},
"identification": {
"type": "passport",
"number": "string",
"issuing_country": "st",
"date_of_expiry": "stringstri"
},
"email": "string"
}
```
corporate
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of account receiving the unreferenced refund.|
|company_name|string|true|none|The corporate account holder's company name.
This must be a valid legal name. The following formats for the `company_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors):
- a single character
- all non-alphabetic characters|
|billing_address|object|false|none|The account holder's billing address.
If your company is incorporated in the United States, this field is required for all unreferenced refunds you perform.|
|» address_line1|string|false|none|The first line of the address.|
|» address_line2|string|false|none|The second line of the address.|
|» city|string|false|none|The address city.|
|» state|string|false|none|The address state.|
|» zip|string|false|none|The address ZIP or postal code.
You must provide US ZIPs in the format `00000`, or `00000-0000`.|
|» country|string|false|none|The address country, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes).|
|phone|object|false|none|The account holder's phone number.|
|» country_code|string|true|none|The international dialing code for the account holder's address `country`, as an [ITU-T E.164 code](https://www.checkout.com/docs/developer-resources/codes/country-codes).|
|» number|string|true|none|The digits of the phone number, not including the `country_code`.|
|identification|object|false|none|The account holder's identification.
Providing identification details for the unreferenced refund recipient increases the likelihood of a successful unreferenced refund.|
|» type|string|true|none|The type of identification for the account holder.|
|» number|string|true|none|The account holder's identification number.|
|» issuing_country|string|false|none|If applicable, the country that issued the account holder's identification, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes).
Providing `issuing_country` increases the likelihood of a successful identity verification.|
|» date_of_expiry|string|false|none|If applicable, the expiration date of the account holder's identification, in the format `YYYY-MM-DD`.
Providing `date_of_expiry` increases the likelihood of a successful identity verification.|
|email|string|false|none|The account holder's email address.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|passport|
|type|driving_license|
|type|national_id|
|type|company_registration|
|type|tax_id|
UnreferencedRefundRequestGovernmentAccountHolder
```json
{
"type": "government",
"company_name": "string",
"billing_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "str",
"zip": "string",
"country": "st"
},
"phone": {
"country_code": "string",
"number": "string"
},
"identification": {
"type": "passport",
"number": "string",
"issuing_country": "st",
"date_of_expiry": "stringstri"
},
"email": "string"
}
```
government
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of account receiving the unreferenced refund.|
|company_name|string|true|none|The account holder's company name.
This must be a valid legal name. The following formats for the `company_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors):
- a single character
- all non-alphabetic characters|
|billing_address|object|false|none|The account holder's billing address.
If your company is incorporated in the United States, this field is required for all unreferenced refunds you perform.|
|» address_line1|string|false|none|The first line of the address.|
|» address_line2|string|false|none|The second line of the address.|
|» city|string|false|none|The address city.|
|» state|string|false|none|The address state.|
|» zip|string|false|none|The address ZIP or postal code.
You must provide United States ZIPs in the format `00000`, or `00000-0000`.|
|» country|string|false|none|The address country, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes).|
|phone|object|false|none|The account holder's phone number.|
|» country_code|string|true|none|The international dialing code for the account holder's address `country`, as an [ITU-T E.164 code](https://www.checkout.com/docs/developer-resources/codes/country-codes).|
|» number|string|true|none|The digits for the phone number, not including the `country_code`.|
|identification|object|false|none|The account holder's identification.
Providing identification details for the unreferenced refund recipient increases the likelihood of a successful unreferenced refund.|
|» type|string|true|none|The type of identification for the account holder.|
|» number|string|true|none|The account holder's identification number.|
|» issuing_country|string|false|none|If applicable, the country that issued the account holder's identification, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes).
Providing `issuing_country` increases the likelihood of a successful identity verification.|
|» date_of_expiry|string|false|none|If applicable, the expiration date of the account holder's identification, in the format `YYYY-MM-DD`.
Providing `date_of_expiry` increases the likelihood of a successful identity verification.|
|email|string|false|none|The account holder's email address.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|passport|
|type|driving_license|
|type|national_id|
|type|company_registration|
|type|tax_id|
UnreferencedRefundRequestIndividualAccountHolder
```json
{
"type": "individual",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"billing_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "str",
"zip": "string",
"country": "st"
},
"phone": {
"country_code": "string",
"number": "string"
},
"identification": {
"type": "passport",
"number": "string",
"issuing_country": "st",
"date_of_expiry": "stringstri"
},
"email": "string",
"date_of_birth": "stringstri",
"country_of_birth": "st"
}
```
individual
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|false|none|The type of account receiving the unreferenced refund.|
|first_name|string|false|none|The account holder's first name.
This must be a valid legal name. The following formats for the `first_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors):
- a single character
- all numeric characters
- all punctuation characters|
|middle_name|string|false|none|The account holder's middle name.|
|last_name|string|false|none|The account holder's last name.
This must be a valid legal name. The following formats for the `last_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors):
- a single character
- all numeric characters
- all punctuation characters|
|billing_address|object|false|none|The account holder's billing address.
If your company is incorporated in the United States, this field is required for all unreferenced refunds you perform.|
|» address_line1|string|false|none|The first line of the address.|
|» address_line2|string|false|none|The second line of the address.|
|» city|string|false|none|The address city.|
|» state|string|false|none|The address state.|
|» zip|string|false|none|The address ZIP or postal code.
You must provide United States ZIPs in the format `00000`, or `00000-0000`.|
|» country|string|false|none|The address country, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes).|
|phone|object|false|none|The account holder's phone number.|
|» country_code|string|true|none|The international dialing code for the account holder's address `country`, as an [ITU-T E.164 code](https://www.checkout.com/docs/developer-resources/codes/country-codes).|
|» number|string|true|none|The digits for the phone number, not including the `country_code`.|
|identification|object|false|none|The account holder's identification.
Providing identification details for the unreferenced refund recipient increases the likelihood of a successful payout.|
|» type|string|true|none|The type of identification for the account holder.|
|» number|string|true|none|The account holder's identification number.|
|» issuing_country|string|false|none|If applicable, the country that issued the account holder's identification, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes).
Providing `issuing_country` increases the likelihood of a successful identity verification.|
|» date_of_expiry|string|false|none|If applicable, the expiration date of the account holder's identification, in the format `YYYY-MM-DD`.
Providing `date_of_expiry` increases the likelihood of a successful identity verification.|
|email|string|false|none|The account holder's email address.|
|date_of_birth|string|false|none|The account holder's date of birth, in the format `YYYY-MM-DD`.|
|country_of_birth|string|false|none|The account holder's country of birth, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes).|
#### Enumerated Values
|Property|Value|
|---|---|
|type|passport|
|type|driving_license|
|type|national_id|
|type|company_registration|
|type|tax_id|
UnreferencedRefundRequestIndividualCardTypeAccountHolder
```json
{
"type": "individual",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"billing_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "str",
"zip": "string",
"country": "st"
},
"phone": {
"country_code": "string",
"number": "string"
},
"identification": {
"type": "passport",
"number": "string",
"issuing_country": "st",
"date_of_expiry": "stringstri"
},
"email": "string",
"date_of_birth": "stringstri",
"country_of_birth": "st"
}
```
individual
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The type of account receiving the unreferenced refund.|
|first_name|string|true|none|The account holder's first name.
This must be a valid legal name. The following formats for the `first_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors):
- a single character
- all non-alphabetic characters|
|middle_name|string|false|none|The account holder's middle name.|
|last_name|string|true|none|The account holder's last name.
This must be a valid legal name. The following formats for the `last_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors):
- a single character
- all non-alphabetic characters|
|billing_address|object|false|none|The account holder's billing address.
If your company is incorporated in the United States, this field is required for all unreferenced refunds you perform.|
|» address_line1|string|false|none|The first line of the address.|
|» address_line2|string|false|none|The second line of the address.|
|» city|string|false|none|The address city.|
|» state|string|false|none|The address state.|
|» zip|string|false|none|The address ZIP or postal code.
You must provide United States ZIPs in the format `00000`, or `00000-0000`.|
|» country|string|false|none|The address country, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes).|
|phone|object|false|none|The account holder's phone number.|
|» country_code|string|true|none|The international dialing code for the account holder's address `country`, as an [ITU-T E.164 code](https://www.checkout.com/docs/developer-resources/codes/country-codes).|
|» number|string|true|none|The digits for the phone number, not including the `country_code`.|
|identification|object|false|none|The account holder's identification.
Providing identification details for the unreferenced refund recipient increases the likelihood of a successful unreferenced refund.|
|» type|string|true|none|The type of identification for the account holder.|
|» number|string|true|none|The account holder's identification number.|
|» issuing_country|string|false|none|If applicable, the country that issued the account holder's identification, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes).
Providing `issuing_country` increases the likelihood of a successful identity verification.|
|» date_of_expiry|string|false|none|If applicable, the expiration date of the account holder's identification, in the format `YYYY-MM-DD`.
Providing `date_of_expiry` increases the likelihood of a successful identity verification.|
|email|string|false|none|The account holder's email address.|
|date_of_birth|string|false|none|The account holder's date of birth, in the format `YYYY-MM-DD`.|
|country_of_birth|string|false|none|The account holder's country of birth, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes).|
#### Enumerated Values
|Property|Value|
|---|---|
|type|passport|
|type|driving_license|
|type|national_id|
|type|company_registration|
|type|tax_id|
UnreferencedRefundRequestNameRequiredAccountHolder
```json
{
"type": "individual",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"billing_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "str",
"zip": "string",
"country": "st"
},
"phone": {
"country_code": "string",
"number": "string"
},
"identification": {
"type": "passport",
"number": "string",
"issuing_country": "st",
"date_of_expiry": "stringstri"
},
"email": "string",
"date_of_birth": "stringstri",
"country_of_birth": "st"
}
```
The unreferenced refund destination account holder.
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[UnreferencedRefundRequestIndividualCardTypeAccountHolder](#schemaunreferencedrefundrequestindividualcardtypeaccountholder)|false|none|The unreferenced refund destination account holder's details.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[UnreferencedRefundRequestCorporateAccountHolder](#schemaunreferencedrefundrequestcorporateaccountholder)|false|none|The unreferenced refund destination account holder's details.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[UnreferencedRefundRequestGovernmentAccountHolder](#schemaunreferencedrefundrequestgovernmentaccountholder)|false|none|The unreferenced refund destination account holder's details.|
UnreferencedRefundRequestDestinationTypeCard
```json
{
"type": "string",
"number": "string",
"expiry_month": 0,
"expiry_year": 0,
"account_holder": {
"type": "individual",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"billing_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "str",
"zip": "string",
"country": "st"
},
"phone": {
"country_code": "string",
"number": "string"
},
"identification": {
"type": "passport",
"number": "string",
"issuing_country": "st",
"date_of_expiry": "stringstri"
},
"email": "string",
"date_of_birth": "stringstri",
"country_of_birth": "st"
}
}
```
card
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The unreferenced refund destination type.|
|number|string|true|none|The card number.|
|expiry_month|integer|true|none|The card's expiration month.|
|expiry_year|integer|true|none|The card's expiration year.|
|account_holder|[UnreferencedRefundRequestNameRequiredAccountHolder](#schemaunreferencedrefundrequestnamerequiredaccountholder)|true|none|The unreferenced refund destination account holder.|
UnreferencedRefundRequestDestinationTypeId
```json
{
"type": "string",
"id": "stringstringstringstringstring",
"account_holder": {
"type": "individual",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"billing_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "str",
"zip": "string",
"country": "st"
},
"phone": {
"country_code": "string",
"number": "string"
},
"identification": {
"type": "passport",
"number": "string",
"issuing_country": "st",
"date_of_expiry": "stringstri"
},
"email": "string",
"date_of_birth": "stringstri",
"country_of_birth": "st"
}
}
```
id
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The unreferenced refund destination type.|
|id|string|true|none|The payment source ID. This will be an ID with the prefix `src_`.|
|account_holder|[UnreferencedRefundRequestAccountHolder](#schemaunreferencedrefundrequestaccountholder)|false|none|The unreferenced refund destination account holder.|
UnreferencedRefundRequestDestinationTypeNetworkToken
```json
{
"type": "string",
"token": "4543474002249996",
"expiry_month": 6,
"expiry_year": 2025,
"token_type": "vts",
"cryptogram": "hv8mUFzPzRZoCAAAAAEQBDMAAAA=",
"eci": "05",
"account_holder": {
"type": "individual",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"billing_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "str",
"zip": "string",
"country": "st"
},
"phone": {
"country_code": "string",
"number": "string"
},
"identification": {
"type": "passport",
"number": "string",
"issuing_country": "st",
"date_of_expiry": "stringstri"
},
"email": "string",
"date_of_birth": "stringstri",
"country_of_birth": "st"
}
}
```
network_token
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The unreferenced refund destination type.|
|token|string|true|none|The network token's Primary Account Number (PAN).|
|expiry_month|integer|true|none|The network token's expiration month.|
|expiry_year|integer|true|none|The network token's expiration year.|
|token_type|string|true|none|The network token type.|
|cryptogram|string|false|none|The network token's Base64-encoded cryptographic identifier (TAVV).
The cryptogram is used by card schemes to validate the token verification result.|
|eci|string|false|none|The network token's Electronic Commerce Indicator (ECI) security level.|
|account_holder|[UnreferencedRefundRequestNameRequiredAccountHolder](#schemaunreferencedrefundrequestnamerequiredaccountholder)|true|none|The unreferenced refund destination account holder.|
#### Enumerated Values
|Property|Value|
|---|---|
|token_type|vts|
|token_type|mdes|
|token_type|applepay|
|token_type|googlepay|
UnreferencedRefundRequestDestinationTypeToken
```json
{
"type": "string",
"token": "stringstringstringstringstring",
"account_holder": {
"type": "individual",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"billing_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "str",
"zip": "string",
"country": "st"
},
"phone": {
"country_code": "string",
"number": "string"
},
"identification": {
"type": "passport",
"number": "string",
"issuing_country": "st",
"date_of_expiry": "stringstri"
},
"email": "string",
"date_of_birth": "stringstri",
"country_of_birth": "st"
}
}
```
token
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|The unreferenced refund destination type.|
|token|string|true|none|The Checkout.com card token ID. This will be an ID with the prefix `tok_`.|
|account_holder|[UnreferencedRefundRequestAccountHolder](#schemaunreferencedrefundrequestaccountholder)|false|none|The unreferenced refund destination account holder.|
UnreferencedRefundAcceptedResponse
```json
{
"id": "pay_g4blr3juzouutaijarea5hejd4",
"status": "Pending",
"reference": "REF-FQSGRB",
"instruction": {
"value_date": "2020-06-12T22:27:42.512594Z"
},
"destination": {
"account_holder": {
"id": "src_nwd3m4in3hkuddfpjsaevunhdy"
}
},
"_links": {
"self": {
"href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_g4blr3juzouutaijarea5hejd4"
},
"actions": {
"href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_g4blr3juzouutaijarea5hejd4/actions"
}
}
}
```
Unreferenced Refund
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|true|none|The payment's unique identifier.|
|status|string|true|none|The refund status.|
|reference|string|false|none|The reference you provided in the refund request.|
|instruction|[PaymentInstructionResponse](#schemapaymentinstructionresponse)|false|none|Instruction details for payouts to bank accounts.|
|destination|object|false|none|The refund destination.|
|» account_holder|object|false|none|The account holder details.|
|»» id|string|false|none|The payment destination identifier (e.g., a card source identifier)|
|_links|object|false|none|The links related to the refund.|
|» self|object|true|none|The refund URI.|
|»» href|string|false|none|The link URL|
|» actions|object|false|none|The refund actions URI.|
|»» href|string|false|none|The link URL|
#### Enumerated Values
|Property|Value|
|---|---|
|status|Accepted|
|status|Rejected|
|status|Pending|
UnreferencedRefundRequestDestination
```json
{
"type": "string",
"token": "stringstringstringstringstring",
"account_holder": {
"type": "individual",
"first_name": "string",
"middle_name": "string",
"last_name": "string",
"billing_address": {
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "str",
"zip": "string",
"country": "st"
},
"phone": {
"country_code": "string",
"number": "string"
},
"identification": {
"type": "passport",
"number": "string",
"issuing_country": "st",
"date_of_expiry": "stringstri"
},
"email": "string",
"date_of_birth": "stringstri",
"country_of_birth": "st"
}
}
```
The destination of the unreferenced refund.
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[UnreferencedRefundRequestDestinationTypeToken](#schemaunreferencedrefundrequestdestinationtypetoken)|false|none|The destination of the unreferenced refund.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[UnreferencedRefundRequestDestinationTypeId](#schemaunreferencedrefundrequestdestinationtypeid)|false|none|The destination of the unreferenced refund.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[UnreferencedRefundRequestDestinationTypeCard](#schemaunreferencedrefundrequestdestinationtypecard)|false|none|The destination of the unreferenced refund.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[UnreferencedRefundRequestDestinationTypeNetworkToken](#schemaunreferencedrefundrequestdestinationtypenetworktoken)|false|none|The destination of the unreferenced refund.|
UpdateCustomerRequest
```json
{
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"default": true
}
```
The customer's details
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|false|none|The identifier of an existing customer|
|default|boolean|false|none|If true, sets this instrument as the default for the customer|
ValidationError
```json
{
"request_id": "0HL80RJLS76I7",
"error_type": "request_invalid",
"error_codes": [
"payment_source_required"
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|request_id|string|false|none|none|
|error_type|string|false|none|none|
|error_codes|[string]|false|none|none|