Checkout.com API logo

Checkout.com API Reference

URL: https://support.checkout.com License: Checkout.com Terms of Service

Get started

Checkout.com provides a collection of APIs that enable you to process and manage payments. Our APIs accept and return JSON in the HTTP body, and return standard HTTP response codes. You can consume the APIs directly using your favorite HTTP/REST library. We have a testing environment called sandbox, which you can sign up for to test API calls without affecting live data.

Authentication

When you sign up for an account, you can authenticate with either Access keys (OAuth 2.0), or Secret API keys. Unless explicitly stated, all endpoints require authentication using either your Access or Secret API Keys. Public keys should only be used in JavaScript or native applications.

  • Client-side authentication. Use your public key for client-side authentication. It only has access to a limited set of our APIs – mostly those called as part of your payment environment.
  • Server-to-server authentication. Use your secret key or OAuth for server-to-server communication. Support for API keys depends on the endpoint. Never share your OAuth credentials, API keys, or access tokens. Keep them guarded and secure.

ApiPublicKey

Public keys are used for client-side authentication, and should only be used in JavaScript or native applications.

Format

  • Sandbox pk_sbox_xxxxxxxxxxxxxxxxxxxxxxxxxx

  • Production pk_xxxxxxxxxxxxxxxxxxxxxxxxxx

When specifying your public key in the Authorization header, you must include the Bearer prefix. For example, Bearer {{public API key}}.

Security Scheme Type: API Key
Header parameter name: Authorization

ApiSecretKey

You can use your secret API key in the Authorization header of your API requests for supported endpoints.

Format

  • Sandbox sk_sbox_xxxxxxxxxxxxxxxxxxxxxxxxxx

  • Production sk_xxxxxxxxxxxxxxxxxxxxxxxxxx

curl --location --request POST 'https://api.checkout.com/{{path}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{AccessToken}}' \
--data-raw '{
"amount": 10000,
"currency": "USD",
"reference": "Visa-USD-Test",
...
}'

When specifying your secret key in the Authorization header, you must include the Bearer prefix. For example, Bearer {{secret API key}}.

Security Scheme Type: API Key
Header parameter name: Authorization

OAuth

Your OAuth credentials consist of an access key ID and an access key secret (corresponding to OAuth 2.0 client ID and client secret). You can exchange these for an access token by calling the request an access token endpoint. You will need to authenticate using basic authentication, using your access key ID and access key secret as your username and password:

curl --location --request POST 'https://access.checkout.com/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic dGVzdC1hY2Nlc3Mta2V5LWlkOnRlc3QtYWNjZXNzLWtleS1zZWNyZXQ=' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=gateway'

The token server will return a Bearer access_token in JSON Web Token (JWT) format which you should use in the Authorization header of your API requests:

curl --location --request POST 'https://api.checkout.com/{{path}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{AccessToken}}' \
--data-raw '{
  "amount": 10000,
  "currency": "USD",
  "reference": "Visa-USD-Test",
  ...
}'

Your access token will be valid for a length of time (in seconds) indicated by the expires_in field in the response. When it expires, you'll need to request a new one.

Depending on the Environment against which you're making your requests against you'll need to request the token from a different Authorization Server.

Environment Authorization Server
Sandbox https://access.sandbox.checkout.com/connect/token
Production https://access.checkout.com/connect/token
Security Scheme Type: OAuth2
Flow type: clientCredentials
Token URL: string
Scopes:
  • vault -

    Access to all Vault resources

  • vault:instruments -

    Create instruments

  • vault:tokenization -

    Tokenize payment instruments

  • gateway -

    Access to all Gateway resources

  • gateway:payment -

    Request payments

  • gateway:payment-details -

    Get payment details

  • gateway:payment-authorizations -

    Increment authorizations

  • gateway:payment-voids -

    Void payments

  • gateway:payment-captures -

    Capture payments

  • gateway:payment-refunds -

    Refund payments

  • fx -

    Foreign exchange services

  • payouts:bank-details -

    Get bank details

  • sessions:app -

    App-based authentication

  • sessions:browser -

    Browser-based authentication

  • disputes -

    Access to all Disputes resources

  • disputes:view -

    View disputes

  • disputes:provide-evidence -

    Provide dispute evidence

  • disputes:accept -

    Accept disputes

  • accounts -

    Manage sub-entities

  • flow -

    Access to all Flow resources

  • flow:workflows -

    Manage workflows

  • flow:events -

    Retrieve events

  • files -

    Access to all Files resources

  • files:retrieve -

    Retrieve files

  • files:upload -

    Upload files

  • files:download -

    Download files

  • balances -

    Access to all Balances resources

  • balances:view -

    View balances

  • transfers -

    Access to all Transfers resources

  • transfers:view -

    View transfers

  • transfers:create -

    Create transfers

  • middleware -

    Access to all Middleware resources

  • middleware:merchants-secret -

    Allows merchant identity and Middleware token exchange from a secure execution environment

  • middleware:merchants-public -

    Allows merchant identity and Middleware token exchange from an insecure execution environment

  • payment-sessions -

    Access to all Payment Sessions resources

  • reports -

    Access to all Reports resources

  • reports:view -

    View reports

  • financial-actions -

    Access to all Financial actions resources

  • financial-actions:view -

    View financial actions

  • card-management -

    Access to all Card management resources

  • issuing:card-management-read -

    Gives access to card management endpoints with GET operations

  • issuing:card-management-write -

    Gives access to card management endpoints with POST/ PUT / DELETE operations

  • issuing:controls-read -

    Gives access to card control endpoints with GET operations

  • issuing:controls-write -

    Gives access to card control endpoints with POST/ PUT / DELETE operations

  • transactions -

    Access to all transactions resources

  • issuing:transactions-read -

    Gives access to get and search transactions

  • issuing:transactions-write -

    Gives access to simulate transactions for testing purposes

SessionSecret

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.

Security Scheme Type: API Key
Header parameter name: Authorization

Access

Create an access token to begin using our APIs.

Request an access token

OAuth endpoint to exchange your access key ID and access key secret for an access token.

Request
Request Body schema: application/x-www-form-urlencoded
grant_type
string
Value: "client_credentials"
client_id
string

Access key ID

client_secret
string

Access key secret

scope
string

The access key scope

Responses
200

OK - A successful access token response as per RFC6749

400

Bad request - An unsuccessful access token response as per RFC6749

post/connect/token
Request samples
application/x-www-form-urlencoded
grant_type=client_credentials&client_id=ack_clckqmmnyfiupexjew7shh5ahe&client_secret=Pmg36sDWQ9WxtPR3
Response samples
application/json
{
  • "access_token": "2YotnFZFEjr1zCsicMWpAA",
  • "token_type": "example",
  • "expires_in": 3600
}

Payments

Process and manage payments from a variety of sources and to various destinations all within one integration.

Request a payment or payout

Send a payment or payout.

Note: successful payout requests will always return a 202 response.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
header Parameters
Cko-Idempotency-Key
string

An optional idempotency key for safely retrying payment requests

Request Body schema: application/json
One of:
currency
required
string = 3 characters

The three-letter ISO currency code

object

The source of the payment

amount
integer >= 0

The payment amount. Omit the amount or provide a value of 0 to perform a card verification.

The amount must be provided in the minor currency unit.

payment_type
string
Default: "Regular"

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

For MITs, this field must not be set to Regular.

Enum: "Regular" "Recurring" "MOTO" "Installment" "PayLater" "Unscheduled"
Recurring (object) or Installment (object)

The details of a recurring subscription or installment

merchant_initiated
boolean

Flags the payment as 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 <= 80 characters

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 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 alphanumerical value between 12 and 30-characters long, generated for every transaction.
  • For seQura payments, the reference is required and must be a unique value.
description
string <= 100 characters

A description of the payment.

authorization_type
string
Default: "Final"

The authorization type

Enum: "Final" "Estimated"
object (PartialAuthorization)

Required information to allow partial authorization

capture
boolean
Default: true

Whether to capture the payment (if applicable)

capture_on
string <date-time>

A timestamp (ISO 8601 code) that determines when the payment should be captured. Providing this field will automatically set capture to true

object (CustomerRequest)

The customer's details. Required if source.type is tamara

object (BillingDescriptor)

An optional description that is displayed on the customer's statement identifying a purchase.

object

The shipping details.

Integrated authentication (object) or Standalone authentication (object) or Third party authentication (object)

Information required for 3D Secure authentication payments.

object

Provides information required to authenticate payments.

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

The processing channel to be used for the payment

previous_payment_id
string <= 100 characters

An identifier that can link 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
object (RiskRequest)

Configures the risk assessment performed during the processing of the payment

success_url
string <uri> <= 1024 characters

For redirect payment methods, this overrides the default success redirect URL configured on your account

failure_url
string <uri> <= 1024 characters

For redirect payment methods, this overrides the default failure redirect URL configured on your account

payment_ip
string <ipv4> <= 45 characters

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

object (PaymentRequestSender)

Information about the sender of the payment's funds

object (PaymentRecipient)

Information about the recipient of the payment's funds. Relevant for Account Funding Transactions and VISA or Mastercard domestic UK transactions processed by financial institutions.

Array of objects (AmountAllocations) [ 1 .. 50 ] items

The sub-entities that the payment is being processed on behalf of

object

Use the processing object to influence or override the data sent during card processing

Array of objects (Items)

The order line items

object (RetryRequest)

Configuration relating to asynchronous retries

metadata
object

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 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 in your custom rules for Fraud Detection. For example, $coupon_code = '1234’.

object (Segment)

The dimension details about business segment for payment request. At least one dimension required.

object

Details about the payment instruction.

Responses
201

Payment processed successfully

202

Payment asynchronous or further action required

401

Unauthorized

422

Invalid data was sent

429

Too many requests or duplicate request detected

502

Bad gateway

post/payments
Request samples
application/json
{
  • "source": {
    },
  • "amount": 6540,
  • "currency": "USD",
  • "payment_type": "Recurring",
  • "reference": "ORD-5023-4E89",
  • "description": "Set of 3 masks",
  • "capture": true,
  • "capture_on": "2019-09-10T10:11:12Z",
  • "customer": {
    },
  • "billing_descriptor": {
    },
  • "shipping": {
    },
  • "3ds": {
    },
  • "previous_payment_id": "pay_fun26akvvjjerahhctaq2uzhu4",
  • "risk": {
    },
  • "success_url": "https://example.com/payments/success",
  • "failure_url": "https://example.com/payments/fail",
  • "payment_ip": "90.197.169.245",
  • "recipient": {
    },
  • "metadata": {
    },
  • "segment": {
    }
}
Response samples
application/json
{
  • "id": "pay_mbabizu24mvu3mela5njyhpit4",
  • "action_id": "act_mbabizu24mvu3mela5njyhpit4",
  • "amount": 6540,
  • "currency": "USD",
  • "approved": true,
  • "status": "Authorized",
  • "auth_code": "770687",
  • "response_code": "10000",
  • "response_summary": "Approved",
  • "3ds": {
    },
  • "risk": {
    },
  • "source": {
    },
  • "customer": {
    },
  • "processed_on": "2019-09-10T10:11:12Z",
  • "reference": "ORD-5023-4E89",
  • "processing": {
    },
  • "eci": "06",
  • "scheme_id": "489341065491658",
  • "_links": {}
}

Get payment lists

Beta

Returns a list of your business' payments that match the specified reference. Results are returned in reverse chronological order, with the most recent payments shown first.

This will only return payments initiated from June 2022 onwards. Payments initiated before this date may return a 404 error code if you attempt to retrieve them.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
query Parameters
reference
required
string

A reference, such as an order ID, that can be used to identify the payment

limit
integer [ 1 .. 100 ]
Default: 10

The numbers of results to retrieve

skip
integer >= 0
Default: 0

The number of results to skip

Responses
200

Payments retrieved successfully

401

Unauthorized

422

Unprocessable paging

get/payments
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-go
import (
	"github.com/checkout/checkout-sdk-go"
	"github.com/checkout/checkout-sdk-go/configuration"
	"github.com/checkout/checkout-sdk-go/payments"
)

// API Keys
api, err := checkout.
			Builder().
			StaticKeys().
			WithSecretKey("secret_key").
			WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
			Build()
if err != nil {
	return nil, err
}

// OAuth
api, err := checkout.
			Builder().
			OAuth().
			WithClientCredentials("client_id", "client_secret").
			WithScopes([]string{configuration.Gateway, configuration.GatewayPayment}).
			WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
			Build()
if err != nil {
	return nil, err
}

query := payments.QueryRequest{
	Limit:     10,
	Skip:      0,
	Reference: "reference",
}

response, err := api.Payments.RequestPaymentList(query)
if err != nil {
	return nil, err
}

return response, nil
Response samples
application/json
{
  • "limit": 10,
  • "skip": 10,
  • "total_count": 1,
  • "data": [
    ]
}

Get payment details

Returns the details of the payment with the specified identifier string.

If the payment method requires a redirection to a third party (e.g., 3D Secure), the redirect URL back to your site will include a cko-session-id query parameter containing a payment session ID that can be used to obtain the details of the payment, for example:

https://example.com/success?cko-session-id=sid_ubfj2q76miwundwlk72vxt2i7q.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
path Parameters
id
required
string^(pay|sid)_(\w{26})$

The payment or payment session identifier

Responses
200

Payment retrieved successfully

401

Unauthorized

404

Payment not found

get/payments/{id}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Payments.Response;

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Gateway)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    GetPaymentResponse response = await api.PaymentsClient().GetPaymentDetails("payment_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples
application/json
{
  • "id": "pay_mbabizu24mvu3mela5njyhpit4",
  • "requested_on": "2019-08-24T14:15:22Z",
  • "source": {
    },
  • "destination": {
    },
  • "amount": 6540,
  • "amount_requested": 6540,
  • "currency": "USD",
  • "payment_type": "Recurring",
  • "payment_plan": {
    },
  • "reference": "ORD-5023-4E89",
  • "description": "Set of 3 masks",
  • "approved": true,
  • "expires_on": "string",
  • "status": "Authorized",
  • "balances": {
    },
  • "3ds": {
    },
  • "authentication": {
    },
  • "risk": {
    },
  • "customer": {
    },
  • "billing_descriptor": {
    },
  • "shipping": {
    },
  • "payment_ip": "90.197.169.245",
  • "sender": {
    },
  • "amount_allocations": [
    ],
  • "recipient": {
    },
  • "processing": {
    },
  • "items": [
    ],
  • "metadata": {
    },
  • "eci": "06",
  • "scheme_id": "488341541494658",
  • "actions": [
    ],
  • "retry": {
    },
  • "pan_type_processed": "fpan",
  • "cko_network_token_available": false,
  • "instruction": {
    },
  • "_links": {}
}

Get payment actions

Returns all the actions associated with a payment ordered by processing date in descending order (latest first).

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
path Parameters
id
required
string^(pay)_(\w{26})$

The payment identifier

Responses
200

Payment actions retrieved successfully

401

Unauthorized

404

Payment not found

get/payments/{id}/actions
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Payments;

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Gateway)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    ItemsResponse<PaymentAction> response = await api.PaymentsClient().GetPaymentActions("payment_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Increment authorization

Request an incremental authorization to increase the authorization amount or extend the authorization's validity period.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
path Parameters
id
required
string^(pay)_(\w{26})$

The payment identifier

header Parameters
Cko-Idempotency-Key
string

An optional idempotency key for safely retrying payment requests

Request Body schema: application/json
amount
integer >= 0

The amount to increase the authorization by. Omit the amount or provide a value of 0 to extend the authorization validity period

reference
string

A reference you can later use to identify this authorization request

metadata
object

A set of key-value pairs that you can attach to the authorization request. This can be useful for storing additional information in a structured format. Note that this object only allows one level of depth, so cannot accept non-primitive data types such as objects or arrays.

Responses
201

Authorization processed successfully

401

Unauthorized

403

Incremental authorization not allowed

404

Payment not found

422

Invalid data was sent

502

Bad gateway

post/payments/{id}/authorizations
Request samples
application/json
{
  • "amount": 6540,
  • "reference": "ORD-5023-4E89",
  • "metadata": {
    }
}
Response samples
application/json
{}

Cancel a scheduled retry

Cancels an upcoming retry, if there is one scheduled

Cancellation requests are processed asynchronously. You can use workflows to be notified if the cancellation is successful.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
path Parameters
id
required
string^(pay)_(\w{26})$

The unique payment identifier.

header Parameters
Cko-Idempotency-Key
string

An optional idempotency key for safely retrying payment requests

Request Body schema: application/json
reference
string <= 80 characters

A reference you can later use to identify this cancellation request. You can use this value to identify the cancellation request later.

Responses
202

Cancellation accepted

401

Unauthorized

403

Cancellation not allowed

404

Payment not found

422

Invalid data sent

502

Bad gateway

post/payments/{id}/cancellations
Request samples
application/json
{
  • "reference": "ORD-5023-4E89"
}
Response samples
application/json
{}

Capture a payment

Captures a payment if supported by the payment method.

For card payments, capture requests are processed asynchronously. You can use workflows to be notified if the capture is successful.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
path Parameters
id
required
string^(pay)_(\w{26})$

The payment identifier

header Parameters
Cko-Idempotency-Key
string

An optional idempotency key for safely retrying payment requests

Request Body schema: application/json
amount
integer >= 0

The amount to capture. If not specified, the full payment amount will be captured.

capture_type
string
Default: "Final"

The type of capture. If set to Final, the remaining available-to-capture balance will be voided.

Enum: "NonFinal" "Final"
reference
string <= 80 characters

A reference you can later use to identify this capture request.
For Amex, the string limit is 30 characters.

object (CustomerRequest)

The customer's details. Required if source.type is tamara

description
string <= 100 characters

A description of the payment.

object (BillingDescriptor)

An optional description that is displayed on the customer's statement identifying a purchase.

object

The shipping details.

Array of objects (Items)

The order line items

Array of objects (AmountAllocations) [ 1 .. 50 ] items

The sub-entities that the payment is being processed on behalf of

object (CaptureRequestProcessingSettings)

Use the processing object to influence or override the data sent during card processing

metadata
object

A set of key-value pairs that you can attach to the capture request. This can be useful for storing additional information in a structured format. Note that this object only allows one level of depth, so cannot accept non-primitive data types such as objects or arrays.

Responses
202

Capture accepted

401

Unauthorized

403

Capture not allowed

404

Payment not found

422

Invalid data was sent

502

Bad gateway

post/payments/{id}/captures
Request samples
application/json
{
  • "amount": 6540,
  • "capture_type": "Final",
  • "reference": "ORD-5023-4E89",
  • "customer": {
    },
  • "description": "Set of 3 masks",
  • "billing_descriptor": {
    },
  • "shipping": {
    },
  • "items": [
    ],
  • "amount_allocations": [
    ],
  • "processing": {
    },
  • "metadata": {
    }
}
Response samples
application/json
{}

Refund a payment

Refunds a payment if supported by the payment method.

For card payments, refund requests are processed asynchronously. You can use workflows to be notified if the refund is successful.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
path Parameters
id
required
string^(pay)_(\w{26})$

The payment identifier

header Parameters
Cko-Idempotency-Key
string

An optional idempotency key for safely retrying payment requests

Request Body schema: application/json
amount
integer >= 0

The amount to refund. If not specified, the full payment amount will be refunded.

reference
string <= 80 characters

A reference you can later use to identify this refund request.
For Amex, the string limit is 30 characters.

Array of objects (AmountAllocations) [ 1 .. 50 ] items

The sub-entities that the payment is being processed on behalf of

capture_action_id
string

The Checkout.com action ID of the capture you want to refund. Only for PayPal and Riverty.

Array of objects (Items)

The order line items

object (RefundBankAccountDestination)

The destination of the refund.

This field is required for giropay and EPS refunds.

metadata
object

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 that this object only allows one level of depth, so cannot accept non-primitive data types such as objects or arrays.

Responses
202

Refund accepted

401

Unauthorized

403

Refund not allowed

404

Payment not found

422

Invalid data was sent

502

Bad gateway

post/payments/{id}/refunds
Request samples
application/json
{
  • "amount": 6540,
  • "reference": "ORD-5023-4E89",
  • "amount_allocations": [
    ],
  • "capture_action_id": "act_fd3h6evhpn3uxdoqbuu3lqnqbm",
  • "items": [
    ],
  • "destination": {
    },
  • "metadata": {
    }
}
Response samples
application/json
{}

Reverse a payment

Beta

You can reverse a payment to return funds back to the customer, without having to manage the appropriate action to take based on the payment's status.

Depending on the payment's current status, requesting a payment reversal will automatically perform one of the following actions:

  • Fully refund a captured payment.
  • Void an authorized payment.
  • Cancel retries on a payment with pending retries.
  • Refund partially captured funds and void any remaining authorization amount.
  • Refund all captured funds from a partial refund and void any remaining authorization amount.

You can only request a payment reversal for card authorizations, captures, or an authorisation attempt that has a retry scheduled.

You cannot reverse a payment that has already been fully refunded, voided, or cancelled. If you attempt to do so, you'll receive a 204 - No Content response code.

For card payments, reversal requests are processed asynchronously. You can use workflows to be notified when the reversal action completes. Note that the notification will depend on the reversal action taken; for example, for voided payments you will receive a payment_voided notification, and so on.

The reversal request will be rejected with a 403 - Forbidden response code if the payment cannot be reversed. This may happen if:

  • the payment is not a card payment
  • the payment is not authorized and is still in the process of 3D Secure (3DS) authentication
SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
path Parameters
id
required
string^(pay)_(\w{26})$

The unique identifier for the payment.

header Parameters
Cko-Idempotency-Key
string

An optional idempotency key for safely retrying payment requests

Request Body schema: application/json
reference
string <= 80 characters

An internal reference to identify the payment reversal.

For American Express payment reversals, there is a 30-character limit.

metadata
object

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.

Responses
202

Reversal accepted

204

Payment has already been reversed

401

Unauthorized

403

Reversals not supported for this payment

404

Payment not found

422

Invalid data was sent

502

Bad gateway

post/payments/{id}/reversals
Request samples
application/json
{
  • "reference": "ORD-5023-4E89",
  • "metadata": {
    }
}
Response samples
application/json
{}

Void a payment

Voids a payment if supported by the payment method.

For card payments, void requests are processed asynchronously. You can use workflows to be notified if the void is successful.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
path Parameters
id
required
string^(pay)_(\w{26})$

The payment identifier

header Parameters
Cko-Idempotency-Key
string

An optional idempotency key for safely retrying payment requests

Request Body schema: application/json
reference
string <= 80 characters

A reference you can later use to identify this void request.
For Amex, the string limit is 30 characters.

metadata
object

A set of key-value pairs that you can attach to the void request. It can be useful for storing additional information in a structured format. Note that this object only allows one level of depth, so cannot accept non-primitive data types such as objects or arrays.

Responses
202

Void accepted

401

Unauthorized

403

Void not allowed

404

Payment not found

422

Invalid data was sent

502

Bad gateway

post/payments/{id}/voids
Request samples
application/json
{
  • "reference": "ORD-5023-4E89",
  • "metadata": {
    }
}
Response samples
application/json
{}

Search payments

Beta

Search and filter through your payment data to retrieve payments that match your query."

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
Request Body schema: application/json
required

Search query.

query
string <= 1024 characters

The query string.

For more information on how to build out your query, see the Search and filter payments documentation.

limit
integer [ 1 .. 1000 ]
Default: 10

The number of results to return.

from
string

The UTC date and time for the query start in ISO 8601 format. Required if to is provided.

to
string

The UTC date and time for the query end in ISO 8601 format. Required if from is provided.

Responses
200

Successful search

400

Invalid input

401

Unauthorized

403

Forbidden

422

Query validation error

post/payments/search
Request samples
application/json
{
  • "query": "id:'pay_mbabizu24mvu3mela5njyhpit4'",
  • "limit": 10,
  • "from": "2023-08-24T14:15:22Z",
  • "to": "2023-08-24T14:15:22Z"
}
Response samples
application/json
{
  • "data": [
    ]
}

Flow

A Flow payment session contains the information required to display relevant payment methods and handle the payment flow.

To enable access to Flow, contact your Solutions Engineer or support@checkout.com.

Request a Payment Session

Creates a payment session.

The values you provide in the request will be used to determine the payment methods available to Flow. Some payment methods may require you to provide specific values for certain fields. Refer to our documentation for more information.

You must supply the unmodified response body when you initialize Flow.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
Request Body schema: application/json
amount
required
integer >= 0

The payment amount. Provide a value of 0 to perform a card verification.

The amount must be provided in the minor currency unit.

currency
required
string = 3 characters

The three-letter ISO currency code

required
object

The billing details.

success_url
required
string <uri> <= 1024 characters

Overrides the default success redirect URL configured on your account, for payment methods that require a redirect.

failure_url
required
string <uri> <= 1024 characters

Overrides the default failure redirect URL configured on your account, for payment methods that require a redirect.

payment_type
string
Default: "Regular"

Must be specified for card-not-present (CNP) payments. For example, a recurring mail order / telephone order (MOTO) payment.

Enum: "Regular" "Recurring" "MOTO" "Installment" "Unscheduled"
object

A description of the purchase, which is displayed on the customer's statement.

reference
string <= 50 characters

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 iDEAL payments, this is required and must be an alphanumeric value with a maximum length of 35 characters.
description
string <= 100 characters

A description for the payment.

object

The customer's details. Required if source.type is tamara.

object

The shipping details

object

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.

object

Modifies the data sent during card processing.

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

The processing channel to use for the payment.

expires_on
string <date-time>

A timestamp specifying when the PaymentSession should expire, as an ISO 8601 code. If no value is provided, expiry is set to 1 hour after the PaymentSession is created. You cannot set the session expiry to more than 60 days after the PaymentSession is created.

object

Configurations for payment method-specific settings.

enabled_payment_methods
Array of strings

Specifies which payment method options to present to the customer.

The values in this field override any equivalent values in disabled_payment_methods.

Items Enum: "alipay_cn" "alipay_hk" "applepay" "bancontact" "benefit" "card" "dana" "eps" "gcash" "googlepay" "ideal" "kakaopay" "klarna" "knet" "multibanco" "p24" "paypal" "qpay" "sepa" "sofort" "stcpay" "tng" "truemoney"
disabled_payment_methods
Array of strings

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.

Items Enum: "alipay_cn" "alipay_hk" "applepay" "bancontact" "benefit" "card" "dana" "eps" "gcash" "googlepay" "ideal" "kakaopay" "klarna" "knet" "multibanco" "p24" "paypal" "qpay" "sepa" "sofort" "stcpay" "tng" "truemoney"
Array of objects [ 1 .. 1000 ] items

The line items in the order.

Array of objects [ 1 .. 50 ] items

The sub-entities that the payment is being processed on behalf of.

object

Configures the risk assessment performed during payment processing.

object

Configuration for asynchronous retries.

display_name
string <= 255 characters

The merchant's display name.

metadata
object <= 18 properties

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 in your custom rules for Fraud Detection. For example, $coupon_code = '1234’.

locale
string
Default: "en-GB"

Creates a translated version of the page in the specified language.

Enum: "ar" "da-DK" "de-DE" "el" "en-GB" "es-ES" "fi-FI" "fil-PH" "fr-FR" "hi-IN" "id-ID" "it-IT" "ja-JP" "ms-MY" "nb-NO" "nl-NL" "pt-PT" "sv-SE" "th-TH" "vi-VN" "zh-CN" "zh-HK" "zh-TW"
object

Information required for 3D Secure authentication payments.

object

The sender of the payment.

capture
boolean
Default: true

Specifies whether to capture the payment, if applicable.

capture_on
string <date-time>

A timestamp specifying when to capture the payment, as an ISO 8601 code. If a value is provided, capture is automatically set to true.

ip_address
string <ipv4> <= 45 characters

The Customers IP address. Only IPv4 and IPv6 addresses are accepted.

Responses
201

A Payment Session.

401

Unauthorized (Empty Response).

422

Invalid data was sent.

429

Too many requests.

502

Bad gateway.

post/payment-sessions
Request samples
application/json
{
  • "amount": 1000,
  • "currency": "USD",
  • "payment_type": "Regular",
  • "billing": {
    },
  • "billing_descriptor": {
    },
  • "reference": "ORD-123A",
  • "description": "Payment for gold necklace",
  • "customer": {
    },
  • "shipping": {
    },
  • "recipient": {
    },
  • "processing": {
    },
  • "processing_channel_id": "string",
  • "expires_on": "2024-01-1T09:15:30Z",
  • "payment_method_configuration": {
    },
  • "enabled_payment_methods": [
    ],
  • "disabled_payment_methods": [
    ],
  • "items": [
    ],
  • "amount_allocations": [
    ],
  • "risk": {
    },
  • "customer_retry": {
    },
  • "display_name": "string",
  • "success_url": "https://example.com/payments/success",
  • "failure_url": "https://example.com/payments/failure",
  • "metadata": {
    },
  • "locale": "ar",
  • "3ds": {
    },
  • "sender": {
    },
  • "capture": true,
  • "capture_on": "2024-01-1T09:15:30Z",
  • "ip_address": "90.197.169.245"
}
Response samples
application/json
{
  • "id": "string",
  • "payment_session_token": "string",
  • "payment_session_secret": "string",
  • "_links": {
    }
}

Create a Payment Link

Create a Payment Link and pass through all the payment information, like the amount, currency, country and reference.

SecurityAPI Key: ApiSecretKey
Request
Request Body schema: application/json
required
amount
required
integer >= 1

The payment amount. The exact format depends on the currency.

currency
required
string = 3 characters

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.

required
object

The billing details.

payment_type
string
Default: "Regular"

This must be specified for card payments where the cardholder is not present (i.e., recurring or mail order / telephone order)

Enum: "Regular" "Recurring"
payment_ip
string <ipv4> <= 45 characters

The IP address used to make the payment. Used by our risk engine to check the customer's IP address – only accepts IPv4 addresses

object

An optional description that is displayed on the customer's statement identifying a purchase

reference
string <= 50 characters

A reference you can later use to identify this payment, such as an order number.
Required for PayPal payments.
For Amex, the string limit is 30 characters.

description
string <= 100 characters

A description of the payment.

display_name
string

The merchant name to display to customers on the checkout page.

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

The processing channel to be used for the payment

Array of objects (Amount Allocations) [ 1 .. 50 ] items

The sub-entities that the payment is being processed on behalf of

expires_in
integer [ 1 .. 5184000 ]
Default: 86400

The time for which the link remains valid, in seconds.

object

The customer's details.

object

The address any products are being sent to.

object (PaymentRecipient)

Information about the recipient of the payment's funds. Relevant for Account Funding Transactions and VISA or Mastercard domestic UK transactions processed by financial institutions.

object

Use the processing object to influence or override the data sent during card processing

allow_payment_methods
Array of strings

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.

Items Enum: "alipay_cn" "alipay_hk" "applepay" "bancontact" "benefit" "card" "dana" "eps" "gcash" "googlepay" "ideal" "kakaopay" "klarna" "knet" "multibanco" "p24" "paypal" "qpay" "sepa" "sofort" "stcpay" "tng" "truemoney"
disabled_payment_methods
Array of strings

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.

Items Enum: "alipay_cn" "alipay_hk" "applepay" "bancontact" "benefit" "card" "dana" "eps" "gcash" "googlepay" "ideal" "kakaopay" "klarna" "knet" "multibanco" "p24" "paypal" "qpay" "sepa" "sofort" "stcpay" "tng" "truemoney"
Array of objects [ 1 .. 1000 ] items

Contains details about the products in the order.

object (The Metadata Schema)

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.

object

Information required for 3D Secure payments.

object

Configures the risk assessment performed during payment processing.

object

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 performed in the back end by Checkout.com.

object

The sender of the payment.

return_url
string <uri> <= 255 characters

If provided, the success page will include a button that redirects your customer to the provided URL.

locale
string
Default: "en-GB"

Creates a translated version of the page in the specified language

Enum: "ar" "da-DK" "de-DE" "el" "en-GB" "es-ES" "fi-FI" "fil-PH" "fr-FR" "hi-IN" "id-ID" "it-IT" "ja-JP" "ms-MY" "nb-NO" "nl-NL" "pt-PT" "sv-SE" "th-TH" "vi-VN" "zh-CN" "zh-HK" "zh-TW"
capture
boolean

Whether to capture the payment (if applicable).

capture_on
string <date-time>

A timestamp (ISO 8601 code) that determines when the payment should be captured. Providing this field will automatically set capture to true.

Responses
201

Create Payment Link Page

401

Unauthorized

422

Invalid data was sent

post/payment-links
Request samples
application/json
{
  • "amount": 1000,
  • "currency": "GBP",
  • "payment_type": "Regular",
  • "payment_ip": "192.168.0.1",
  • "billing_descriptor": {
    },
  • "reference": "ORD-123A",
  • "description": "Payment for Gold Necklace",
  • "display_name": "The Jewelry Shop",
  • "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
  • "amount_allocations": [
    ],
  • "expires_in": 604800,
  • "customer": {
    },
  • "shipping": {
    },
  • "billing": {
    },
  • "recipient": {
    },
  • "processing": {
    },
  • "allow_payment_methods": [
    ],
  • "disabled_payment_methods": [
    ],
  • "products": [
    ],
  • "metadata": { },
  • "3ds": {
    },
  • "risk": {
    },
  • "customer_retry": {
    },
  • "sender": {
    },
  • "return_url": "https://example.com/success",
  • "locale": "ar",
  • "capture": true,
  • "capture_on": "2019-08-24T14:15:22Z"
}
Response samples
application/json
{}

Get Payment Link details

Retrieve details about a specific Payment Link using its ID returned when the link was created. In the response, you will see the status of the Payment Link.

For more information, see the Payment Links documentation.

SecurityAPI Key: ApiSecretKey
Request
path Parameters
id
required
string = 15 characters ^pl_[A-Za-z0-9_-]{12}$

The unique identifier for a Payment Link.

Responses
200

Payment Link details retrieved successfully

401

Unauthorized

404

Payment Link session not found

get/payment-links/{id}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Payments.Links;

ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    PaymentLinkDetailsResponse response = await api.PaymentLinksClient().Get("payment_link_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples
application/json
{
  • "id": "pl_ELqQJXdXzabU",
  • "status": "Active",
  • "payment_id": null,
  • "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": [
    ],
  • "customer": {
    },
  • "shipping": {
    },
  • "billing": {
    },
  • "products": [
    ],
  • "metadata": { },
  • "locale": "ar",
  • "return_url": "https://example.com/success",
  • "_links": {}
}

Hosted Payments Page

Create a Hosted Payments Page to accept and process payment details.

Create a Hosted Payments Page session

Create a Hosted Payments Page session and pass through all the payment information, like the amount, currency, country and reference.

To get started with our Hosted Payments Page, contact your Solutions Engineer or support@checkout.com.

SecurityAPI Key: ApiSecretKey
Request
Request Body schema: application/json
required
currency
required
string = 3 characters

The three-letter ISO currency code of the payment

required
object

The billing details

success_url
required
string <uri> <= 255 characters

For redirect payment methods, this overrides the default success redirect URL configured on your account

cancel_url
required
string <uri> <= 255 characters

The URL to which the customer should be directed if they cancel the payment

failure_url
required
string <uri> <= 255 characters

For redirect payment methods, this overrides the default failure redirect URL configured on your account

amount
integer >= 1

The payment amount. The exact format depends on the currency

payment_type
string
Default: "Regular"

This must be specified for card payments where the cardholder is not present (i.e., recurring or mail order / telephone order)

Enum: "Regular" "Recurring"
payment_ip
string <ipv4> <= 45 characters

The IP address used to make the payment. Used by our risk engine to check the customer's IP address – only accepts IPv4 addresses

object

An optional description that is displayed on the customer's statement identifying a purchase

reference
string <= 50 characters

A reference you can later use to identify this payment, such as an order number.
For Amex, the string limit is 30 characters.

description
string <= 100 characters

A description of the payment

display_name
string

The merchant name to display to customers on the checkout page.

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

The processing channel to be used for the payment

Array of objects (Amount Allocations) [ 1 .. 50 ] items

The sub-entities that the payment is being processed on behalf of

object

The customer's details

object

The address any products are being sent to.

object (PaymentRecipient)

Information about the recipient of the payment's funds. Relevant for Account Funding Transactions and VISA or Mastercard domestic UK transactions processed by financial institutions.

object

Use the processing object to influence or override the data sent during card processing.

allow_payment_methods
Array of strings

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.

Items Enum: "alipay_cn" "alipay_hk" "applepay" "bancontact" "benefit" "card" "dana" "eps" "gcash" "googlepay" "ideal" "kakaopay" "klarna" "knet" "multibanco" "p24" "paypal" "qpay" "sepa" "sofort" "stcpay" "tng" "truemoney"
disabled_payment_methods
Array of strings

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.

Items Enum: "alipay_cn" "alipay_hk" "applepay" "bancontact" "benefit" "card" "dana" "eps" "gcash" "googlepay" "ideal" "kakaopay" "klarna" "knet" "multibanco" "p24" "paypal" "qpay" "sepa" "sofort" "stcpay" "tng" "truemoney"
Array of objects [ 1 .. 1000 ] items

Contains details about the products in the order.

object

Configures the risk assessment performed during payment processing.

object

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 performed in the back end by Checkout.com.

object

The sender of the payment.

object (The Metadata Schema)

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
Default: "en-GB"

Creates a translated version of the page in the specified language

Enum: "ar" "da-DK" "de-DE" "el" "en-GB" "es-ES" "fi-FI" "fil-PH" "fr-FR" "hi-IN" "id-ID" "it-IT" "ja-JP" "ms-MY" "nb-NO" "nl-NL" "pt-PT" "sv-SE" "th-TH" "vi-VN" "zh-CN" "zh-HK" "zh-TW"
object

Information required for 3D Secure payments

capture
boolean

Whether to capture the payment (if applicable).

capture_on
string <date-time>

A timestamp (ISO 8601 code) that determines when the payment should be captured. Providing this field will automatically set capture to true.

Responses
201

Created Hosted Payments Page

401

Unauthorized

422

Invalid data was sent

post/hosted-payments
Request samples
application/json
{
  • "amount": 1000,
  • "currency": "GBP",
  • "payment_type": "Regular",
  • "payment_ip": "192.168.0.1",
  • "billing_descriptor": {
    },
  • "reference": "ORD-123A",
  • "description": "Payment for Gold Necklace",
  • "display_name": "The Jewelry Shop",
  • "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
  • "amount_allocations": [
    ],
  • "customer": {
    },
  • "shipping": {
    },
  • "billing": {
    },
  • "recipient": {
    },
  • "processing": {
    },
  • "allow_payment_methods": [
    ],
  • "disabled_payment_methods": [
    ],
  • "products": [
    ],
  • "risk": {
    },
  • "customer_retry": {
    },
  • "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": {
    },
  • "capture": true,
  • "capture_on": "2019-08-24T14:15:22Z"
}
Response samples
application/json
{}

Get Hosted Payments Page details

Retrieve details about a specific Hosted Payments Page using the ID returned when it was created. In the response, you will see the status of the Hosted Payments Page.

For more information, see the Hosted Payments Page documentation.

SecurityAPI Key: ApiSecretKey
Request
path Parameters
id
required
string = 16 characters ^hpp_[A-Za-z0-9_-]{12}$

The unique identifier for a Hosted Payments Page.

Responses
200

Hosted Payments Page details retrieved successfully

401

Unauthorized

404

Hosted Payments Page not found

get/hosted-payments/{id}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Payments.Hosted;

ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    HostedPaymentDetailsResponse response = await api.HostedPaymentsClient().GetHostedPaymentsPageDetails("hosted_payment_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples
application/json
{
  • "id": "hpp_xGQBg0AXl3cM",
  • "status": "Payment Pending",
  • "payment_id": null,
  • "amount": 100,
  • "currency": "GBP",
  • "reference": "ORD-123A",
  • "description": "Payment for Gold Necklace",
  • "customer": {
    },
  • "billing": {
    },
  • "products": [
    ],
  • "metadata": { },
  • "success_url": "https://example.com/success",
  • "cancel_url": "https://example.com/cancel",
  • "failure_url": "https://example.com/failure",
  • "amount_allocations": [
    ],
  • "_links": {}
}

Forex

Checkout.com Foreign Exchange services

Get FX rates

Use the Forex (FX) rates API to get the indicative foreign exchange rates that Checkout.com uses to process payments for card payouts or scheme acquiring. You can query the rates and the related source of rates (for example, Visa, Mastercard).

Note: Ensure that you have the corresponding product enabled when using this endpoint. Otherwise, you will receive a Forbidden error response.

SecurityOAuth2: OAuth
Request
query Parameters
product
required
string (ForexProduct)

The Checkout.com Forex product to return rates for

Enum: "card_payouts" "scheme_acquiring"
Example: product=card_payouts
source
required
string (ForexSource)

The source of provided rates

Enum: "visa" "mastercard"
Example: source=visa
currency_pairs
required
string

Comma-separated list of currency pairs

Example: currency_pairs=GBPEUR,USDNOK,JPNCAD
processing_channel_id
required
string (ForexProcessingChannelId) ^(pc)_(\w{26})$

The processing channel identifier

Example: processing_channel_id=pc_vxt6yftthv4e5flqak6w2i7rim
Responses
200

Rates retrieved successfully

401

Unauthorized

403

Forbidden. The client is not enabled for the requested product

422

Invalid data was sent

429

Too many requests or duplicate requests detected

502

Bad gateway

get/forex/rates
Request samples 
Response samples 
application/json
{
  • "product": "card_payouts",
  • "source": "visa",
  • "rates": [
    ],
  • "invalid_currency_pairs": [
    ]
}
Apple Pay
Manage your Apple Pay certificates in order to process payments via Apple Pay.


Upload a payment processing certificate
Upload a payment processing certificate. This will allow you to start processing payments via Apple Pay.


SecurityAPI Key: ApiPublicKey 
Request 
Request Body schema: application/json
content
string
The certificate content


 
Responses 
201
Certificate uploaded successfully


401
Unauthorized


422
Invalid data was sent


post/applepay/certificates
Request samples 
application/json
{
  • "content": "MIIBSDCB8AIBADCBjzELMAkGA1UEBhMCR0IxDzANBgNVBAgMBkxvbmRvbjEPMA0GA1UEBwwGTG9uZG9uMRUwEwYDVQQKDAxDaGVja291dC5jb20xCzAJBgNVBA8MAklUMRUwEwYDVQQDDAxjaGVja291dC5jb20xIzAhBgkqhkiG9w0BCQEWFHN1cHBvcnRAY2hlY2tvdXQuY29tMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXf/MDFRLSblykajGm0GE+lUNoOIEa0DbWc7Bv3s55bYtW1fJo2/MJIPojUKuKUx2VsEfGmmqXKbq4IhAr0bM8TAKBggqhkjOPQQDAgNHADBEAiAo1Dv4TXTacSeIfy4HDjzPMQY2+OxTW6szRJjGyfKgXQIgdHAX0BmI+1rozysjXv8MvoxehQIGACQ+UWJle+UZ2ms="
}
Response samples 
application/json
{
  • "id": "aplc_hefptsiydvkexnzzb35zrlqgfq",
  • "public_key_hash": "tqYV+tmG9aMh+l/K6cicUnPqkb1gUiLjSTM9gEz6Nl0=",
  • "valid_from": "2021-01-01T17:32:28Z",
  • "valid_until": "2025-01-01T17:32:28Z"
}
Generate a certificate signing request
Generate a certificate signing request. You'll need to upload this to your Apple Developer account to download a payment processing certificate.


SecurityAPI Key: ApiPublicKey 
Request 
Request Body schema: application/json
protocol_version
string
 Default:  "ec_v1"
The protocol version of the encryption type used.


 Enum: "ec_v1" "rsa_v1"  
Responses 
200
Generated signing request successfully


401
Unauthorized


422
Invalid data was sent


post/applepay/signing-requests
Request samples 
application/json
{
  • "protocol_version": "ec_v1"
}
Response samples 
application/json
{
  • "content": "-----BEGIN CERTIFICATE REQUEST-----MIIBSDCB8AIBADCBjzELMAkGA1UEBhMCR0IxDzANBgNVBAgMBkxvbmRvbjEPMA0GA1UEBwwGTG9uZG9uMRUwEwYDVQQKDAxDaGVja291dC5jb20xCzAJBgNVBA8MAklUMRUwEwYDVQQDDAxjaGVja291dC5jb20xIzAhBgkqhkiG9w0BCQEWFHN1cHBvcnRAY2hlY2tvdXQuY29tMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXf/MDFRLSblykajGm0GE+lUNoOIEa0DbWc7Bv3s55bYtW1fJo2/MJIPojUKuKUx2VsEfGmmqXKbq4IhAr0bM8TAKBggqhkjOPQQDAgNHADBEAiAo1Dv4TXTacSeIfy4HDjzPMQY2+OxTW6szRJjGyfKgXQIgdHAX0BmI+1rozysjXv8MvoxehQIGACQ+UWJle+UZ2ms=-----END CERTIFICATE REQUEST-----"
}
Transfers
Transfer funds while managing the entities to transfer money to recoup funds from a seller, return money from a refund or to make up the difference when running a promotion.


Initiate a transfer of funds
Initiate a transfer of funds from source entity to destination entity.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
header Parameters
Cko-Idempotency-Key
required
string
An idempotency key for safely retrying transfer requests


 
Request Body schema: application/json
required
The details of the transfer.


transfer_type
required
string (Transfer type) 
The type of transfer


 Enum: "commission" "promotion" "refund"  
required
object (Transfer source) 
The object representing the source of the funds involved in the transfer.


 
required
object (Transfer destination) 
The object representing the destination of the funds involved in the transfer.


 
reference
string  <= 50 characters 
A reference you can use later to identify this transfer


 
Responses 
201
Transfer successfully created.


400
Bad Request


401
Unauthorized


422
Invalid data was sent


post/transfers
Request samples 
application/json
{
  • "reference": "superhero1234",
  • "transfer_type": "commission",
  • "source": {
    },
  • "destination": {
    }
}
Response samples 
application/json
{}
Retrieve a transfer
Retrieve transfer details using the transfer identifier.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
id
required
string
The transfer identifier


 
 Example:  tra_y3oqhf46pyzuxjbcn2giaqnb4
Responses 
200
Transfer found


400
Bad Request


401
Unauthorized


404
Transfer not found


422
Invalid data was sent


get/transfers/{id}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Transfers;

ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Transfers)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

CreateTransferRequest createTransferRequest =
    new CreateTransferRequest
    {
        Source = new TransferSourceRequest {Amount = 100, Id = "entity_source_id"},
        Destination = new TransferDestinationRequest {Id = "entity_destination_id"},
        TransferType = TransferType.Commission
    };

try
{
    TransferDetailsResponse transferDetailsResponse = await api.TransfersClient().RetrieveATransfer("transfer_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples 
application/json
{
  • "id": "tra_y3oqhf46pyzuxjbcn2giaqnb4",
  • "reference": "superhero1234",
  • "status": "rejected",
  • "transfer_type": "commission",
  • "requested_on": "2021-12-15T09:15:02.3845763Z",
  • "reason_codes": [
    ],
  • "source": {
    },
  • "destination": {
    },
  • "_links": {}
}
Balances
View the balances for sub-accounts in an entity.


Retrieve entity balances
Use this endpoint to retrieve balances for each sub-account in an entity. 
Note: The sub-account is referred to as currency account in the API.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
id
required
string
The ID of the entity.


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
query Parameters
query
string
The query to apply to limit the currency accounts.


 
 Example:  query=currency:EUR
withCurrencyAccountId
boolean
 Default:  false
Specifies if the response should include the sub-account ID that corresponds to each set of balances.


 
Responses 
200
Balances retrieved successfully.


400
Query format not supported


401
Unauthorized


404
Entity not found


422
Invalid data was sent


get/balances/{id}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Balances;
using Checkout.Common;

ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Balances)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();


BalancesQuery query = new BalancesQuery {Query = "currency:" + Currency.GBP};

try
{
    BalancesResponse balances = await api.BalancesClient()
        .RetrieveEntityBalances("entitiy_id", query);
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples 
application/json
{
  • "data": [
    ]
}
Payment Context
Request a Payment Context
Send a Payment Context request.

Note: Successful Payment Context requests will always return a 201 response.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
header Parameters
Cko-Idempotency-Key
string
An optional idempotency key for safely retrying payment requests


 
Request Body schema: application/json
required
object (PaymentContextSource) 
The source of the payment.


 
currency
required
string  = 3 characters 
The three-letter ISO currency code.


 
amount
required
integer  >= 0 
The Payment Context Payment amount.
The amount must be provided in the minor currency unit.


 
payment_type
string
 Default:  "Regular"
"Recurring" must be specified if the payment is paid in multiple installments.


 Enum: "Regular" "Recurring"  
capture
boolean
 Default:  true
Whether to capture the later payment (if applicable).


 
object (PaymentContextDetailsCustomer) 
The customer details. 
 Required if source.type is StcPay or Tabby.


 
object
The shipping details.


 
object
Use the processing object to influence or override the data sent during card processing.


 
processing_channel_id
string^(pc)_(\w{26})$
The processing channel to be used for the payment.


 
reference
string  <= 50 characters 
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  <= 100 characters 
A description of the Payment Context.


 
success_url
string <uri>   <= 1024 characters 
For redirect payment methods, this overrides the default success redirect URL configured on your account.


 
failure_url
string <uri>   <= 1024 characters 
For redirect payment methods, this overrides the default failure redirect URL configured on your account.


 
Array of objects
The order line items. 


Required for Klarna payments.


 
Responses 
201
Payment Context Created.


401
Unauthorized


422
Invalid data was sent.


429
Too many requests or duplicate request detected.


502
Bad gateway


post/payment-contexts
Request samples 
application/json
{
  • "source": {
    },
  • "amount": 6540,
  • "currency": "USD",
  • "payment_type": "Recurring",
  • "capture": true,
  • "customer": {
    },
  • "shipping": {
    },
  • "processing": {
    },
  • "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": [
    ]
}
Response samples 
application/json
{
  • "id": "pct_y3oqhf46pyzuxjbcn2giaqnb44",
  • "amount": 0,
  • "processed_on": "2019-08-24T14:15:22Z",
  • "status": "Pending",
  • "response_code": 2000,
  • "response_summary": "Rejected",
  • "available_payment_types": [
    ],
  • "unavailable_payment_types": [
    ],
  • "partner_metadata": {
    },
  • "_links": {}
}
Get Payment Context details
Returns all the Payment Context details.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
id
required
string^(pct)_(\w{26})$
Payment Context's unique identifier.


 
 Example:  pct_y3oqhf46pyzuxjbcn2giaqnb44
Responses 
200
Payment Context retrieved successfully.


401
Unauthorized


404
Payment Context not found.


get/payment-contexts/{id}
Request samples 
Response samples 
application/json
{
  • "status": "Approved",
  • "payment_request": {
    },
  • "partner_metadata": {
    }
}
Payment Methods
Get available payment methods
Beta

Get a list of all available payment methods for a specific Processing Channel ID.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
query Parameters
processing_channel_id
required
string^(pc)_(\w{26})$
The processing channel to be used for payment methods retrieval.


 
 Example:  processing_channel_id=pc_q4dbxom5jbgudnjzjpz7j2z6uq
Responses 
200
Enabled payment methods retrieved successfully


401
Unauthorized


404
Processing channel not found


get/payment-methods
Request samples 
Response samples 
application/json
{
  • "methods": [
    ]
}
Tokens
Create a token that represents a card's credentials that you can later use to request a payment, without you having to process or store any sensitive information.


Request a token
Exchange card details for a reference token that can be used later to request a card payment. Tokens are single use and expire after 15 minutes.
To create a token, please authenticate using your public key.


Please note: You should only use the card type for testing purposes.


SecurityAPI Key: ApiPublicKey 
Request 
Request Body schema: application/json
type
required
string
The type of card details to be tokenized


 
number
required
string
The card number


 
expiry_month
required
integer  [ 1 .. 2 ] characters  >= 1 
The expiry month of the card


 
expiry_year
required
integer  = 4 characters 
The expiry year of the card


 
name
string
The cardholder's name


 
cvv
string  [ 3 .. 4 ] characters 
The card verification value/code. 3 digits, except for American Express (4 digits)


 
object
The payment source owner's billing address


 
object
The payment source owner's phone number


 
Responses 
201
Reference token created successfully


401
Unauthorized


422
Invalid data was sent


post/tokens
Request samples 
application/json
{
  • "type": "card",
  • "number": "4543474002249996",
  • "expiry_month": 6,
  • "expiry_year": 2025,
  • "name": "Bruce Wayne",
  • "cvv": "956",
  • "billing_address": {
    },
  • "phone": {
    }
}
Response samples 
application/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": {
    },
  • "phone": {
    },
  • "name": "Bruce Wayne"
}
Instruments
Create and manage your card and bank account payment instruments.


Create an instrument
Create a card or bank account payment instrument to use for future payments and payouts. 


The parameters you need to provide when creating a bank account payment instrument depend on the account's country and currency. See the payout formatting documentation, or use the GET /validation/bank-accounts/{country}/{currency} endpoint.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
Request Body schema: application/json
required
currency
required
string
The three-letter ISO currency code of the account's currency


 
country
required
string
The two-letter ISO country code of where the account is based


 
type
required
string
The type of instrument. bank_account payment instruments only support payouts.


 
account_type
string
The type of account


 Enum: "savings" "current" "cash"  
account_number
string
Number (which can contain letters) that identifies the account


 
bank_code
string
Code that identifies the bank


 
branch_code
string
Code that identifies the bank branch


 
iban
string
Internationally agreed standard for identifying bank account


 
bban
string
The combination of bank code and/or branch code and account number


 
swift_bic
string
8 or 11 character code which identifies the bank or bank branch


 
processing_channel_id
string
The ID of the primary processing channel this instrument is intended to be used for


 
object (AccountHolder) 
The bank account holder details. Having accurate and complete data improves payout performance (increases success rate and the prevents delays).


 
object (BankDetails) 
Details of the bank


 
object (StoreCustomerInstrumentRequest) 
The customer's details


 
Responses 
201
Instrument created successfully


401
Unauthorized


422
Invalid data was sent


500
Internal Error


post/instruments
Request samples 
application/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": {
    },
  • "bank": {
    },
  • "customer": {
    }
}
Response samples 
application/json
{
  • "type": "bank_account",
  • "id": "src_wmlfc3zyhqzehihu7giusaaawu",
  • "fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
  • "customer": {
    },
  • "bank": {
    },
  • "swift_bic": "37040044",
  • "account_number": "13654567455",
  • "bank_code": "123-456",
  • "iban": "HU93116000060000000012345676"
}
Get instrument details
Retrieve the details of a payment instrument.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
id
required
string^(src)_(\w{26})$
The instrument ID


 
Responses 
200
Instrument retrieved successfully


401
Unauthorized


404
Instrument not found


get/instruments/{id}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Instruments.Get;

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Vault)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    GetInstrumentResponse response = await api.InstrumentsClient().Get("instrument_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples 
application/json
{
  • "type": "bank_account",
  • "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": {
    },
  • "bank": {
    },
  • "customer": {
    }
}
Update an instrument
Update the details of a payment instrument.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
id
required
string^(src_)[a-z0-9]{26}$
The instrument ID


 
 Example:  src_ubfj2q76miwundwlk72vxt2i7q
Request Body schema: application/json
required
type
string
This field is used for illustration purposes and does not need to be provided in the request.


 
expiry_month
integer  [ 1 .. 2 ] characters  >= 1 
The expiry month of the card


 
expiry_year
integer  = 4 characters 
The expiry year of the card


 
name
string
Name of the cardholder


 
object (UpdateCardAccountHolder) 
The account holder details


 
object (UpdateCustomerRequest) 
The customer's details


 
Responses 
200
Instrument updated successfully


401
Unauthorized


404
Instrument not found or not associated with client


422
Invalid data was sent


500
Internal Error


patch/instruments/{id}
Request samples 
application/json
{
  • "type": "card",
  • "expiry_month": 6,
  • "expiry_year": 2025,
  • "name": "Mr. J Smith",
  • "account_holder": {
    },
  • "customer": {
    }
}
Response samples 
application/json
{
  • "type": "card",
  • "fingerprint": "smoua2sbuqhupeofwbe77n5nsm"
}
Delete an instrument
Delete a payment instrument.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
id
required
string^(src_)[a-z0-9]{26}$
The ID of the payment instrument to be deleted


 
 Example:  src_ubfj2q76miwundwlk72vxt2i7q
Responses 
204
Instrument deleted successfully


401
Unauthorized


404
Instrument not found or not associated with client


500
Internal Error


delete/instruments/{id}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Vault)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    EmptyResponse response = await api.InstrumentsClient().Delete("instrument_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Get bank account field formatting
Returns the bank account field formatting required to create bank account instruments or perform payouts for the specified country and currency.


SecurityOAuth2: OAuth 
Request 
path Parameters
country
required
string  = 2 characters 
The two-letter ISO country code


 
currency
required
string  = 3 characters 
The three-letter ISO currency code


 
query Parameters
account-holder-type
string
The type of account holder that will be used to filter the fields returned


 Enum: "individual" "corporate" "government"  
payment-network
string
The banking network that will be used to filter the fields returned


 Enum: "local" "sepa" "fps" "ach" "fedwire" "swift"  
Responses 
200
Bank account fields retrieved successfully


401
Unauthorized


404
Fields not found


422
Invalid data was sent


get/validation/bank-accounts/{country}/{currency}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Common;
using Checkout.Instruments.Get;


ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.PayoutsBankDetails)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

BankAccountFieldQuery request = new BankAccountFieldQuery
{
    AccountHolderType = AccountHolderType.Individual, PaymentNetwork = PaymentNetwork.Local
};

try
{
    BankAccountFieldResponse response = await api.InstrumentsClient()
        .GetBankAccountFieldFormatting(CountryCode.GB, Currency.GBP, request);
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples 
application/json
{
  • "sections": [
    ]
}
Customers
Create a customer
Store a customer's details in a customer object to reuse in future payments. When creating a customer, you can link payment instruments – the customer id returned can be passed as a source when making a payment. 

 NOTE: Specify a default instrument, otherwise the instruments array will not be saved on creation.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
Request Body schema: application/json
required
email
required
string <email>   <= 255 characters 
The customer's email address


 
name
string  <= 255 characters 
The customer's name


 
object
The customer's phone number


 
metadata
object
Allows you to store additional information about a customer. You can include a maximum of 10 key-value pairs. Each key and value can be up to 100 characters long.


 
default
string
The ID of the instrument you want to set as this customer's default instrument


 
Responses 
201
Customer created successfully


401
Unauthorized


422
Invalid data was sent


500
Internal Error


post/customers
Request samples 
application/json
{
  • "email": "brucewayne@gmail.com",
  • "name": "Bruce Wayne",
  • "phone": {
    },
  • "metadata": {
    },
  • "default": "src_wmlfc3zyhqzehihu7giusaaawu"
}
Response samples 
application/json
{
  • "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44"
}
Get customer details
Returns the details of a customer and their payment instruments.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
required
string or string
The customer's ID or email


 
Responses 
200
Customer retrieved successfully


401
Unauthorized


404
Customer not found


get/customers/{identifier}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Customers;

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Vault)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    CustomerDetailsResponse response = await api.CustomersClient().Get("customer_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples 
application/json
{
  • "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  • "email": "brucewayne@gmail.com",
  • "default": "src_wmlfc3zyhqzehihu7giusaaawu",
  • "name": "Bruce Wayne",
  • "phone": {
    },
  • "metadata": {
    },
  • "instruments": [
    ]
}
Update customer details
Update the details of a customer and link payment instruments to them.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
identifier
required
string^(cus)_(\w{26})$
The customer's ID


 
Request Body schema: application/json
required
email
string <email>   <= 255 characters 
The email address of the customer


 
name
string  <= 255 characters 
The name of the customer


 
object
The customer's phone number


 
metadata
object
Allows you to store additional information about a customer. You can include a maximum of 10 key-value pairs. Each key and value can be up to 100 characters long. Providing metadata in this request will replace any existing stored for this customer.


 
default
string
The ID of this customer's default instrument


 
Responses 
204
Customer updated successfully


401
Unauthorized


404
Customer not found


422
Invalid data was sent


patch/customers/{identifier}
Request samples 
application/json
{
  • "email": "brucewayne@gmail.com",
  • "name": "Bruce Wayne",
  • "phone": {
    },
  • "metadata": {
    },
  • "default": "src_wmlfc3zyhqzehihu7giusaaawu"
}
Response samples 
application/json
{
  • "request_id": "0HL80RJLS76I7",
  • "error_type": "request_invalid",
  • "error_codes": [
    ]
}
Delete a customer
Delete a customer and all of their linked payment instruments.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
identifier
required
string^(cus)_(\w{26})$
The customer's ID


 
Responses 
204
Customer deleted successfully


401
Unauthorized


404
Customer not found or not associated with client


delete/customers/{identifier}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Vault)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    EmptyResponse response = await api.CustomersClient().Delete("customer_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Forward
Forward an API request
Beta

Forwards an API request to a third-party endpoint.


For example, you can forward payment credentials you've stored in our Vault to a third-party payment processor.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
Request Body schema: application/json
required
required
object (ForwardRequestSource) 
The payment source to enrich the forward request with.


You can provide placeholder values in destination_request.body. The request will be enriched with the respective payment credentials from the token or payment instrument you specified. For example, {{card_number}}.


 
required
object
The parameters of the forward request.


 
reference
string  <= 80 characters 
The unique reference for the forward request.


 
processing_channel_id
string^(pc)_(\w{26})$
The processing channel ID to associate the billing for the forward request with.


 
object (ForwardRequestNetworkToken) 
Specifies if and how a network token should be used in the forward request.


 
Responses 
200
The request was successfully forwarded.


401
Unauthorized


422
Invalid data was sent.


500
Internal Error


post/forward
Request samples 
application/json
{
  • "source": {
    },
  • "reference": "ORD-5023-4E89",
  • "processing_channel_id": "pc_azsiyswl7bwe2ynjzujy7lcjca",
  • "network_token": {
    },
  • "destination_request": {
    }
}
Response samples 
application/json
{
  • "request_id": "fwd_01HK153X00VZ1K15Z3HYC0QGPN",
  • "destination_response": {
    }
}
Get forward request
Retrieve the details of a successfully forwarded API request.    


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


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
id
required
string^fwd_[A-Z0-9]{26}$
The unique identifier of the forward request.


 
Responses 
200
Forward request retrieved successfully


401
Unauthorized


404
Forward request not found


500
Internal Server Error


get/forward/{id}
Request samples 
Response samples 
application/json
{
  • "request_id": "fwd_01HK153X00VZ1K15Z3HYC0QGPN",
  • "reference": "ORD-5023-4E89",
  • "entity_id": "ent_lp6h57qskk6ubewfk3pq4f2c2y",
  • "destination_request": {
    },
  • "destination_response": {
    },
  • "created_on": "2024-01-02T15:04:05+00:00"
}
Standalone
Use Standalone Sessions to authenticate transactions with 3D Secure (3DS) and comply with Strong Customer Authentication (SCA) requirements.


Request a session
Create a payment session to authenticate a cardholder before requesting a payment.
Payment sessions can be linked to one or more payments (in the case of recurring and other merchant-initiated payments).


The next_actions object in the response tells you which actions can be performed next.


SecurityOAuth2: OAuth 
Request 
Request Body schema: application/json
currency
required
string  = 3 characters 
The three-letter ISO currency code


 
required
object (SessionSource) 
The source of the authentication.


 
required
object (CompletionInfo) 
The redirect information needed for callbacks or redirects after the payment is completed


 
amount
integer  <= 48 characters  >= 0 
The payment amount in the major currency.


This value is required for 3DS1 authentications. 


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 and renders the authentication as 3DS2 only.


 
processing_channel_id
string^(pc)_(\w{26})$
The processing channel to be used for the session. Required if this was not set in the request for the OAuth token.


 
object (SessionMarketplaceData) 
Information related to authentication for payfac payments


 
authentication_type
string (AuthenticationType) 
 Default:  "regular"
Indicates the type of payment this session is for. Please note the spelling of installment consists of two ls.


 Enum: "regular" "recurring" "installment" "maintain_card" "add_card"  
authentication_category
string (Category) 
 Default:  "payment"
Indicates the category of the authentication request


 Enum: "payment" "non_payment"  
object (CardholderAccountInfo) 
Additional information about the Cardholder's account.


 
challenge_indicator
string (ChallengeIndicator)   <= 50 characters 
 Default:  "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.


 Enum: "no_preference" "no_challenge_requested" "challenge_requested" "challenge_requested_mandate" "low_value" "trusted_listing" "trusted_listing_prompt" "transaction_risk_assessment" "data_share"  
object (SessionsBillingDescriptor) 
An optional dynamic billing descriptor.


 
reference
string (Reference)   <= 100 characters 
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


 
object (MerchantRiskInfo) 
Additional information about the cardholder's purchase.


 
transaction_type
string (TransactionType)   <= 50 characters 
 Default:  "goods_service"
Identifies the type of transaction being authenticated


 Enum: "goods_service" "check_acceptance" "account_funding" "quasi_card_transaction" "prepaid_activation_and_load"  
object (SessionAddress) 
The shipping address. Any special characters will be replaced.


 
shipping_address_matches_billing
boolean
Indicates whether the cardholder shipping address and billing address are the same.


 
object (ChannelData) 
The information gathered from the environment used to initiate the session


 
object (Recurring) 
Details of a recurring authentication. This property is needed only for a recurring authentication type. Value will be ignored in any other cases.


 
object (Installment) 
Details of an installment authentication. This property is needed only for an installment authentication type. Value will be ignored in any other cases.


 
object (Optimization) 
Optionally opt into request optimization


 
object (InitialTransaction) 
Details of a previous transaction


 
object
This object contains the Google SPA properties (non-hosted only)


 
preferred_experiences
Array of any (Experience) 
Indicates the chosen experience(s) for this session.
 
 Available experiences include: 
 • 3ds 
 • google_spa 


Items Enum: "3ds" "google_spa"  
Responses 
201
Session processed successfully


202
Session accepted and further action required


401
Unauthorized


403
Forbidden. This can happen when the OAuth token scope is sessions:app, but the channel_data property in the request is browser related.


422
Invalid data was sent


503
Service not available. A temporary server error.


post/sessions
Request samples 
application/json
{
  • "source": {
    },
  • "amount": 6540,
  • "currency": "USD",
  • "processing_channel_id": "string",
  • "marketplace": {
    },
  • "authentication_type": "regular",
  • "authentication_category": "payment",
  • "account_info": {
    },
  • "challenge_indicator": "no_preference",
  • "billing_descriptor": {
    },
  • "reference": "ORD-5023-4E89",
  • "merchant_risk_info": {
    },
  • "transaction_type": "goods_service",
  • "shipping_address": {
    },
  • "shipping_address_matches_billing": false,
  • "completion": {},
  • "channel_data": {
    },
  • "recurring": {
    },
  • "installment": {
    },
  • "optimization": {
    },
  • "initial_transaction": {
    },
  • "google_spa": {
    },
  • "preferred_experiences": [
    ]
}
Response samples 
application/json
{
  • "session_secret": "sek_Dal7UyiH8rIFXA4PfgiIk2jUyQkVDeEWgVBEL4TsRTE=",
  • "id": "sid_y3oqhf46pyzuxjbcn2giaqnb441",
  • "transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c",
  • "scheme": "visa",
  • "amount": 120,
  • "currency": "USD",
  • "completed": false,
  • "challenged": true,
  • "authentication_type": "regular",
  • "authentication_category": "payment",
  • "certificates": {
    },
  • "status": "challenged",
  • "status_reason": "ares_status",
  • "approved": false,
  • "protocol_version": "2.2.0",
  • "account_info": {
    },
  • "merchant_risk_info": {
    },
  • "reference": "ORD-5023-4E89",
  • "transaction_type": "goods_service",
  • "next_actions": [
    ],
  • "ds": {
    },
  • "acs": {
    },
  • "response_code": "Y",
  • "response_status_reason": "01",
  • "cryptogram": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
  • "eci": "05",
  • "xid": "XSUErNftqkiTdlkpSk8p32GWOFA",
  • "cardholder_info": "Card declined. Please contact your issuing bank.",
  • "card": {
    },
  • "recurring": {
    },
  • "installment": {
    },
  • "initial_transaction": {
    },
  • "customer_ip": "192.168.1.1",
  • "_links": {},
  • "authentication_date": "2019-08-24T14:15:22Z",
  • "exemption": {
    },
  • "flow_type": "challenged",
  • "challenge_indicator": "no_preference",
  • "optimization": {
    },
  • "scheme_info": {
    },
  • "3ds": {
    },
  • "preferred_experiences": {
    },
  • "experience": "3ds",
  • "google_spa": {
    }
}
Get session details
Returns the details of the session with the specified identifier string.


SecurityOAuth2: OAuth or API Key: SessionSecret 
Request 
path Parameters
id
required
string
Session ID


 
header Parameters
channel
string
Optionally provide the type of channnel so you only get the relevant actions


 Enum: "browser" "app"  
 Example:  browser
Responses 
200
Session retrieved successfully


401
Unauthorized


403
Forbidden. This can happen when the OAuth token scope is sessions:app, but the session was initiated with the scope sessions:browser.


404
Session not found


502
Bad gateway


get/sessions/{id}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-go
import (
	"github.com/checkout/checkout-sdk-go"
	"github.com/checkout/checkout-sdk-go/configuration"
)

// API Keys
api, err := checkout.
			Builder().
			StaticKeys().
			WithSecretKey("secret_key").
			WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
			Build()
if err != nil {
	return nil, err
}

// OAuth
api, err := checkout.
			Builder().
			OAuth().
			WithClientCredentials("client_id", "client_secret").
			WithScopes([]string{configuration.SessionsApp, configuration.SessionsBrowser}).
			WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
			Build()
if err != nil {
	return nil, err
}

response, err := api.Sessions.GetSessionDetails("session_id", "session_secret") // "session_secret" is optional
if err != nil {
	return nil, err
}

return response, nil
Response samples 
application/json
{
  • "id": "sid_y3oqhf46pyzuxjbcn2giaqnb441",
  • "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": {
    },
  • "status": "challenged",
  • "status_reason": "ares_status",
  • "approved": false,
  • "protocol_version": "2.2.0",
  • "account_info": {
    },
  • "merchant_risk_info": {
    },
  • "reference": "ORD-5023-4E89",
  • "transaction_type": "goods_service",
  • "next_actions": [
    ],
  • "ds": {
    },
  • "acs": {
    },
  • "response_code": "Y",
  • "response_status_reason": "01",
  • "cryptogram": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
  • "eci": "05",
  • "xid": "XSUErNftqkiTdlkpSk8p32GWOFA",
  • "cardholder_info": "Card declined. Please contact your issuing bank.",
  • "card": {
    },
  • "recurring": {
    },
  • "installment": {
    },
  • "initial_transaction": {
    },
  • "customer_ip": "192.168.1.1",
  • "_links": {},
  • "authentication_date": "2019-08-24T14:15:22Z",
  • "exemption": {
    },
  • "flow_type": "challenged",
  • "challenge_indicator": "no_preference",
  • "optimization": {
    },
  • "scheme_info": {
    },
  • "3ds": {
    },
  • "preferred_experiences": {
    },
  • "experience": "3ds",
  • "google_spa": {
    }
}
Update a session
Update a session by providing information about the environment.


SecurityOAuth2: OAuth or API Key: SessionSecret 
Request 
path Parameters
id
required
string
Session ID


 
Request Body schema: application/json
required
channel
required
string
 Default:  "browser"
Indicates the type of channel interface being used to initiate the transaction.


 
accept_header
required
string  <= 2048 characters 
Exact content of the HTTP accept headers as sent to the 3DS Requestor from the cardholder’s browser


 
java_enabled
required
boolean
Boolean that represents the ability of the cardholder's browser to execute Java. Value is returned from the navigator.javaEnabled property.


 
javascript_enabled
required
boolean
 Default:  true
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
required
string  [ 1 .. 12 ] characters 
Value representing the browser language as defined in IETF BCP47. Returned from the navigator.language property.


 
color_depth
required
string  [ 1 .. 2 ] characters 
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
required
string  [ 1 .. 6 ] characters 
Total height of the cardholder’s screen in pixels. Value is returned from the screen.height property.


 
screen_width
required
string  [ 1 .. 6 ] characters 
Total width of the cardholder’s screen in pixels. Value is returned from the screen.width property.


 
timezone
required
string  [ 1 .. 5 ] characters 
Time difference between UTC time and the local time of the cardholder's browser, in minutes.


 
user_agent
required
string  <= 2048 characters 
Exact content of the HTTP user-agent header


 
ip_address
required
string  <= 45 characters 
IP address of the browser as returned by the HTTP headers to the 3DS Requestor


 
three_ds_method_completion
string  = 1 characters 
 Default:  "U"
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 preperation response (PRes) message data for the card range associated with the cardholder's account number)


 Enum: "Y" "N" "U"  
iframe_payment_allowed
boolean
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
The raw Sec-CH-UA header value. This can improve Google SPA support.


 
Responses 
200
Session updated successfully


401
Unauthorized


403
Forbidden


404
Session not found


422
Unprocessable channel information


put/sessions/{id}/collect-data
Request samples 
application/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": "U",
  • "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"
}
Response samples 
application/json
{
  • "id": "sid_y3oqhf46pyzuxjbcn2giaqnb441",
  • "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": {
    },
  • "status": "challenged",
  • "status_reason": "ares_status",
  • "approved": false,
  • "protocol_version": "2.2.0",
  • "account_info": {
    },
  • "merchant_risk_info": {
    },
  • "reference": "ORD-5023-4E89",
  • "transaction_type": "goods_service",
  • "next_actions": [
    ],
  • "ds": {
    },
  • "acs": {
    },
  • "response_code": "Y",
  • "response_status_reason": "01",
  • "cryptogram": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
  • "eci": "05",
  • "xid": "XSUErNftqkiTdlkpSk8p32GWOFA",
  • "cardholder_info": "Card declined. Please contact your issuing bank.",
  • "card": {
    },
  • "recurring": {
    },
  • "installment": {
    },
  • "initial_transaction": {
    },
  • "customer_ip": "192.168.1.1",
  • "_links": {},
  • "authentication_date": "2019-08-24T14:15:22Z",
  • "exemption": {
    },
  • "flow_type": "challenged",
  • "challenge_indicator": "no_preference",
  • "optimization": {
    },
  • "scheme_info": {
    },
  • "3ds": {
    },
  • "preferred_experiences": {
    },
  • "experience": "3ds",
  • "google_spa": {
    }
}
Complete a session
Completes a session by posting the following request to the callback URL. This step is optional and only applies to non-hosted sessions:


{
   "session_id": "sid_llraltf4jlwu5dxdtprcv7ba5i",
   "amount" : 6540,
   "currency": "USD",
   "status": "approved",
   "authentication_type": "regular",
   "authentication_category": "payment",
   "reference": "ORD-5023-4E89",
   "approved": true,
   "protocol_version": "2.2.0",
   "response_code": "Y",
   "response_reason": "01",
   "cryptogram": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
   "eci": "05",
   "xid": "XSUErNftqkiTdlkpSk8p32GWOFA",
   "cardholder_info": "Card declined. Please contact your issuing bank.",
   "challenged": true
}




The fields of the above are the same as they would be in a GET session response. If the callback URL fails, we recommend that you use a GET call as a fallback.

SecurityOAuth2: OAuth or API Key: SessionSecret 
Request 
path Parameters
id
required
string
Session ID


 
Responses 
204
Session completed successfully


401
Unauthorized


403
Forbidden


404
Session not found


post/sessions/{id}/complete
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-go
import (
	"github.com/checkout/checkout-sdk-go"
	"github.com/checkout/checkout-sdk-go/configuration"
)

// API Keys
api, err := checkout.
			Builder().
			StaticKeys().
			WithSecretKey("secret_key").
			WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
			Build()
if err != nil {
	return nil, err
}

// OAuth
api, err := checkout.
			Builder().
			OAuth().
			WithClientCredentials("client_id", "client_secret").
			WithScopes([]string{configuration.SessionsApp, configuration.SessionsBrowser}).
			WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
			Build()
if err != nil {
	return nil, err
}

response, err := api.Sessions.CompleteSession("session_id", "session_secret") // "session_secret" is optional
if err != nil {
	return nil, err
}

return response, nil
Response samples 
application/json
{
  • "request_id": "5342217f-7fa2-4626-a6c9-c979a04671a6",
  • "error_type": "operation_not_allowed",
  • "error_codes": [
    ]
}
Update session 3DS Method completion indicator
Update the session's 3DS Method completion indicator based on the result of accessing the 3DS Method URL.


SecurityOAuth2: OAuth or API Key: SessionSecret 
Request 
path Parameters
id
required
string
Session ID


 
Request Body schema: application/json
required
three_ds_method_completion
required
string  = 1 characters 
The result of the 3DS method URL.
  Default to U if a response is not received from the 3DS Method URL within 10 seconds.


 Enum: "Y" "N" "U"  
Responses 
200
Session updated successfully


401
Unauthorized


403
Forbidden


404
Session not found


422
Unprocessable channel information


put/sessions/{id}/issuer-fingerprint
Request samples 
application/json
{
  • "three_ds_method_completion": "Y"
}
Response samples 
application/json
{
  • "id": "sid_y3oqhf46pyzuxjbcn2giaqnb441",
  • "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": {
    },
  • "merchant_risk_info": {
    },
  • "reference": "ORD-5023-4E89",
  • "transaction_type": "goods_service",
  • "initial_transaction": {
    },
  • "next_actions": [
    ],
  • "ds": {
    },
  • "acs": {
    },
  • "response_code": "Y",
  • "response_status_reason": "01",
  • "cryptogram": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
  • "eci": "05",
  • "xid": "XSUErNftqkiTdlkpSk8p32GWOFA",
  • "preferred_experiences": {
    },
  • "experience": "3ds",
  • "google_spa": {
    },
  • "card": {
    },
  • "_links": {},
  • "3ds": {
    }
}
Disputes
Keep track of and act on your open disputes (also known as chargebacks) to submit the best possible response.


Get disputes
Returns a list of all disputes against your business. The results will be returned in reverse chronological order, showing the last modified dispute (for example, where you've recently added a piece of evidence) first. You can use the optional parameters below to skip or limit results.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
query Parameters
limit
integer  [ 1 .. 250 ] 
 Default:  50
The numbers of results to return


 
skip
integer  >= 0 
 Default:  0
The number of results to skip


 
from
string <date-time> 
The date and time from which to filter disputes, based on the dispute's last_update field


 
to
string <date-time> 
The date and time until which to filter disputes, based on the dispute's last_update field


 
id
string
The unique identifier of the dispute


 
entity_ids
string
One or more comma-separated client entities. This works like a logical OR operator


 
 Example:  entity_ids=ent_wxglze3wwywujg4nna5fb7ldli,ent_vkb5zcy64zoe3cwfmaqvqyqyku
sub_entity_ids
string
One or more comma-separated sub-entities. This works like a logical OR operator


 
 Example:  sub_entity_ids=ent_uzm3uxtssvmuxnyrfdffcyjxeu,ent_hy5wtzwzeuwefmsnjtdhw4scfi
processing_channel_ids
string
One or more comma-separated processing channels. This works like a logical OR operator.


 
 Example:  processing_channel_ids=pc_uzm3uxtssvmuxnyrfdffcyjxeu,pc_hy5wtzwzeuwefmsnjtdhw4scfi
segment_ids
string
One or more comma-separated segments. This works like a logical OR operator.


 
statuses
string
One or more comma-separated statuses. This works like a logical OR operator


 
 Example:  statuses=evidence_required,evidence_under_review
payment_id
string
The unique identifier of the payment


 
payment_reference
string
An optional reference (such as an order ID) that you can use later to identify the payment. Previously known as TrackId


 
payment_arn
string
The acquirer reference number (ARN) that you can use to query the issuing bank


 
payment_mcc
string
The merchant category code (MCC) of the payment (ISO 18245)


 
this_channel_only
boolean
If true, only returns disputes of the specific channel that the secret key is associated with. Otherwise, returns all disputes for that business


 
Responses 
200
Disputes retrieved successfully


401
Unauthorized


422
Unprocessable paging


get/disputes
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Disputes;

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Disputes)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

DisputesQueryFilter request = new DisputesQueryFilter
{
    Limit = 250,
    To = DateTime.Now,
};

try
{
    DisputesQueryResponse response = await api.DisputesClient().Query(request);
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples 
application/json
{
  • "limit": 10,
  • "skip": 10,
  • "from": "2018-08-12T01:15:56Z",
  • "to": "2018-08-13T11:09:01Z",
  • "id": "dsp_rbhwd2qrg13uhrp2newf",
  • "entity_ids": "ent_wxglze3wwywujg4nna5fb7ldli,ent_vkb5zcy64zoe3cwfmaqvqyqyku",
  • "sub_entity_ids": "ent_uzm3uxtssvmuxnyrfdffcyjxeu,ent_hy5wtzwzeuwefmsnjtdhw4scfi",
  • "processing_channel_ids": "pc_uzm3uxtssvmuxnyrfdffcyjxeu,pc_hy5wtzwzeuwefmsnjtdhw4scfi",
  • "segment_ids": "string",
  • "statuses": "evidence_required,evidence_under_review",
  • "payment_id": "pay_88cb4e671m1da22e9bbbyx",
  • "payment_reference": "th7zxa1kcnqmes8",
  • "payment_arn": "74548998294293193445538",
  • "payment_mcc": "5021",
  • "this_channel_only": true,
  • "total_count": 1,
  • "data": [
    ]
}
Get dispute details
Returns all the details of a dispute using the dispute identifier.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
dispute_id
required
string^(dsp)_(\\w{26})$
The dispute identifier


 
Responses 
200
Dispute retrieved successfully


401
Unauthorized


404
Dispute not found


get/disputes/{dispute_id}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Disputes;

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Disputes)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    DisputeDetailsResponse response = await api.DisputesClient().GetDisputeDetails("disputes_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples 
application/json
{
  • "id": "dsp_rbhwd2qrg13uhrp2newf",
  • "entity_id": "ent_wxglze3wwywujg4nna5fb7ldli",
  • "sub_entity_id": "ent_uzm3uxtssvmuxnyrfdffcyjxeu",
  • "reference": "dispute-09",
  • "category": "fraudulent",
  • "amount": 999,
  • "currency": "GBP",
  • "reason_code": "10.4",
  • "status": "evidence_required",
  • "resolved_reason": "already_refunded",
  • "relevant_evidence": [
    ],
  • "evidence_required_by": "2018-08-21T00:00:00Z",
  • "received_on": "2018-08-01T04:00:10Z",
  • "last_update": "2018-08-04T10:53:13Z",
  • "is_ce_candidate": true,
  • "payment": {
    },
  • "evidence_list": [
    ],
  • "evidence_bundle": [
    ],
  • "segment_id": "string",
  • "_links": {}
}
Accept dispute
If a dispute is legitimate, you can choose to accept it. This will close it for you and remove it from your list of open disputes. There are no further financial implications.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
dispute_id
required
string^(dsp)_(\w{26})$
The dispute identifier


 
Responses 
204
Dispute accepted successfully


401
Unauthorized


404
Dispute not found


post/disputes/{dispute_id}/accept
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Disputes)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    EmptyResponse response = await api.DisputesClient().Accept("disputes_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Provide dispute evidence
Adds supporting evidence to a dispute. Before using this endpoint, you first need to upload your files using the file uploader. You will receive a file id (prefixed by file_) which you can then use in your request. Note that this only attaches the evidence to the dispute, it does not send it to us. Once ready, you will need to submit it. You must provide at least one evidence type in the body of your request.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
dispute_id
required
string^(dsp)_(\w{26})$
The dispute identifier.


 
Request Body schema: application/json
proof_of_delivery_or_service_file
string
A file containing proof of delivery of goods or services.


 
proof_of_delivery_or_service_text
string  <= 500 
A brief description of the file provided in proof_of_delivery_or_service_file. 


Alternatively, you can provide a link to an externally-hosted file containing the description.


 
proof_of_delivery_or_service_date_file
string
A file showing the delivery date of the provided service or merchandise.


 
proof_of_delivery_or_service_date_text
string  <= 500 
A brief description of the file provided in proof_of_delivery_or_service_date_file. 


Alternatively, you can provide a link to an externally-hosted file containing the description.


 
invoice_or_receipt_file
string
A file containing an invoice or receipt.


 
invoice_or_receipt_text
string  <= 500 
A brief description of the file provided in invoice_or_receipt_file. 


Alternatively, you can provide a link to an externally-hosted file containing the description.


 
invoice_showing_distinct_transactions_file
string
A file containing invoice showing two distinct transactions.


 
invoice_showing_distinct_transactions_text
string  <= 500 
A brief description of the file provided in invoice_showing_distinct_transactions_file. 


Alternatively, you can provide a link to an externally-hosted file containing the description.


 
customer_communication_file
string
A file containing customer communication.


 
customer_communication_text
string  <= 500 
A brief description of the file provided in customer_communication_file. 


Alternatively, you can provide a link to an externally-hosted file containing the description.


 
refund_or_cancellation_policy_file
string
A file containing refund/cancellation policy


 
refund_or_cancellation_policy_text
string  <= 500 
A brief description of the file provided in refund_or_cancellation_policy_file. 


Alternatively, you can provide a link to an externally-hosted file containing the description.


 
recurring_transaction_agreement_file
string
A file containing the recurring transaction agreement


 
recurring_transaction_agreement_text
string  <= 500 
A brief description of the file provided in recurring_transaction_agreement_file. 


Alternatively, you can provide a link to an externally-hosted file containing the description.


 
additional_evidence_file
string
A file containing additional supporting documents.


 
additional_evidence_text
string  <= 500 
A brief description of the file provided in additional_evidence_file. 


Alternatively, you can provide a link to an externally-hosted file containing the description.


 
arbitration_no_review_files
Array of strings
The evidence to submit directly to the scheme when you escalate the dispute to arbitration.


Evidence you provide with this field is submitted directly to the scheme.


 
arbitration_no_review_text
string  <= 500 
A brief description of the file provided in arbitration_no_review_files. 


Alternatively, you can provide a link to an externally-hosted file containing the description.


 
arbitration_review_required_files
Array of strings
The evidence to submit to the Checkout.com Dispute Resolution team for review. 


You'll be advised on the likelihood of success if you choose to escalate the dispute to arbitration.


 
arbitration_review_required_text
string  <= 500 
A brief description of the file provided in arbitration_review_required_files. 


Alternatively, you can provide a link to an externally-hosted file containing the description.


 
object
Used to resolve friendly fraud with merchant historical transactions.


 
object
 
Responses 
204
Dispute evidence provided successfully


400
Unprocessable


401
Unauthorized


404
Dispute not found


422
Unprocessable entity


put/disputes/{dispute_id}/evidence
Request samples 
application/json
{
  • "proof_of_delivery_or_service_file": "file_jmbfgkjromvcrn9t4qu4",
  • "proof_of_delivery_or_service_text": "Description of evidence available at: http://checkout.com/evidenceDocument.pdf",
  • "proof_of_delivery_or_service_date_file": "file_jmbfgkjromvcrn9t4qu4",
  • "proof_of_delivery_or_service_date_text": "Copy of the customer receipt showing the merchandise was delivered on 2018-12-20",
  • "invoice_or_receipt_file": "file_jmbfgkjromvcrn9t4qu4",
  • "invoice_or_receipt_text": "Copy of the invoice",
  • "invoice_showing_distinct_transactions_file": "file_jmbfgkjromvcrn9t4qu4",
  • "invoice_showing_distinct_transactions_text": "Copy of invoice #1244 showing two transactions",
  • "customer_communication_file": "file_jmbfgkjromvcrn9t4qu4",
  • "customer_communication_text": "Copy of an email exchange with the cardholder",
  • "refund_or_cancellation_policy_file": "file_jmbfgkjromvcrn9t4qu4",
  • "refund_or_cancellation_policy_text": "Copy of the refund policy",
  • "recurring_transaction_agreement_file": "file_jmbfgkjromvcrn9t4qu4",
  • "recurring_transaction_agreement_text": "Copy of the recurring transaction agreement",
  • "additional_evidence_file": "file_jmbfgkjromvcrn9t4qu4",
  • "additional_evidence_text": "Scanned document",
  • "arbitration_no_review_files": [
    ],
  • "arbitration_no_review_text": "Evidence for arbitration",
  • "arbitration_review_required_files": [
    ],
  • "arbitration_review_required_text": "Evidence for arbitration",
  • "compelling_evidence": {
    },
  • "_links": {}
}
Response samples 
application/json
{
  • "request_id": "string",
  • "error_type": "string",
  • "error_codes": [
    ]
}
Get dispute evidence
Retrieves a list of the evidence submitted in response to a specific dispute.


SecurityOAuth2: OAuth 
Request 
path Parameters
dispute_id
required
string^(dsp)_(\w{26})$
The dispute identifier.


 
Responses 
200
Dispute evidence retrieved successfully


401
Unauthorized


404
Dispute not found


get/disputes/{dispute_id}/evidence
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Disputes;

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Disputes)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    DisputeEvidenceResponse response = await api.DisputesClient().GetEvidence("disputes_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples 
application/json
{
  • "proof_of_delivery_or_service_file": "file_jmbfgkjromvcrn9t4qu4",
  • "proof_of_delivery_or_service_text": "Description of evidence available at: http://checkout.com/evidenceDocument.pdf",
  • "proof_of_delivery_or_service_date_file": "file_jmbfgkjromvcrn9t4qu4",
  • "proof_of_delivery_or_service_date_text": "Copy of the customer receipt showing the merchandise was delivered on 2018-12-20",
  • "invoice_or_receipt_file": "file_jmbfgkjromvcrn9t4qu4",
  • "invoice_or_receipt_text": "Copy of the invoice",
  • "invoice_showing_distinct_transactions_file": "file_jmbfgkjromvcrn9t4qu4",
  • "invoice_showing_distinct_transactions_text": "Copy of invoice #1244 showing two transactions",
  • "customer_communication_file": "file_jmbfgkjromvcrn9t4qu4",
  • "customer_communication_text": "Copy of an email exchange with the cardholder",
  • "refund_or_cancellation_policy_file": "file_jmbfgkjromvcrn9t4qu4",
  • "refund_or_cancellation_policy_text": "Copy of the refund policy",
  • "recurring_transaction_agreement_file": "file_jmbfgkjromvcrn9t4qu4",
  • "recurring_transaction_agreement_text": "Copy of the recurring transaction agreement",
  • "additional_evidence_file": "file_jmbfgkjromvcrn9t4qu4",
  • "additional_evidence_text": "Scanned document",
  • "arbitration_no_review_files": [
    ],
  • "arbitration_no_review_text": "Evidence for arbitration",
  • "arbitration_review_required_files": [
    ],
  • "arbitration_review_required_text": "Evidence for arbitration",
  • "compelling_evidence": {
    }
}
Submit dispute evidence
With this final request, you can submit the evidence that you have previously provided. Make sure you have provided all the relevant information before using this request. You will not be able to amend your evidence once you have submitted it.


SecurityOAuth2: OAuth 
Request 
path Parameters
dispute_id
required
string^(dsp)_(\w{26})$
The dispute identifier.


 
Responses 
204
Dispute evidence submitted successfully


401
Unauthorized


404
Dispute not found


422
Unprocessable Entity


post/disputes/{dispute_id}/evidence
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Disputes)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    EmptyResponse response = await api.DisputesClient().SubmitEvidence("disputes_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples 
application/json
{
  • "request_id": "string",
  • "error_type": "string",
  • "error_codes": [
    ]
}
Submit dispute arbitration evidence
Submits the previously provided arbitration evidence to the scheme.


You cannot amend evidence after you submit with this endpoint. Ensure you have provided all of the required information.


SecurityOAuth2: OAuth 
Request 
path Parameters
dispute_id
required
string^(dsp)_(\w{26})$
The dispute identifier.


 
Responses 
204
Dispute arbitration evidence submitted successfully


401
Unauthorized


404
Dispute not found


422
Unprocessable Entity


post/disputes/{dispute_id}/evidence/arbitration
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Disputes)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    EmptyResponse response = await api.DisputesClient().SubmitArbitrationEvidence("disputes_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples 
application/json
{
  • "request_id": "string",
  • "error_type": "string",
  • "error_codes": [
    ]
}
Get dispute submitted arbitration evidence
Retrieves the unique identifier of the PDF file containing all of the evidence submitted to escalate the dispute to arbitration.


To retrieve the file's download link, call the GET /files/{file_id} endpoint with the returned file ID.


SecurityAPI Key: ApiSecretKey 
Request 
path Parameters
dispute_id
required
string^(dsp)_(\w{26})$
The dispute identifier.


 
Responses 
200
Dispute retrieved successfully


403
Forbidden


404
Resource not found


500
Internal error


get/disputes/{dispute_id}/evidence/arbitration/submitted
Request samples 
Response samples 
application/json
{}
Get dispute submitted evidence
Retrieves the unique identifier of the PDF file containing all the evidence submitted to represent the dispute case.


To retrieve the file's download link, call the GET /files/{file_id} endpoint with the returned file ID.


Evidence submitted before February 2024 cannot be retrieved using this endpoint.


SecurityAPI Key: ApiSecretKey 
Request 
path Parameters
dispute_id
required
string^(dsp)_(\w{26})$
The dispute identifier.


 
Responses 
200
Dispute retrieved successfully


403
Forbidden


404
Resource not found


500
Internal error


get/disputes/{dispute_id}/evidence/submitted
Request samples 
Response samples 
application/json
{}
Get dispute scheme files
Returns all of the scheme files of a dispute using the dispute identifier. Currently available only for VISA disputes.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
dispute_id
required
string^(dsp)_(\w{26})$
The dispute identifier


 
Responses 
200
Dispute retrieved successfully


401
Unauthorized


404
Dispute not found


get/disputes/{dispute_id}/schemefiles
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-go
import (
	"github.com/checkout/checkout-sdk-go"
	"github.com/checkout/checkout-sdk-go/configuration"
)

// API Keys
api, err := checkout.
			Builder().
			StaticKeys().
			WithSecretKey("secret_key").
			WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
			Build()
if err != nil {
	return nil, err
}

// OAuth
api, err := checkout.
			Builder().
			OAuth().
			WithClientCredentials("client_id", "client_secret").
			WithScopes([]string{configuration.Disputes}).
			WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
			Build()
if err != nil {
	return nil, err
}

response, err := api.Disputes.GetDisputeSchemeFiles("dispute_id")
if err != nil {
	return nil, err
}

return response, nil
Response samples 
application/json
{}
Upload file
Upload a file to use as evidence in a dispute. Your file must be in either JPEG/JPG, PNG or PDF format, and be no larger than 4MB.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
Request Body schema: multipart/form-data
file
required
string
The path of the file to upload, and its type. 
This must be a local path.


 
purpose
required
string
The purpose of the file upload. 


If the file is a supporting document for a dispute, set this to dispute_evidence. If the file is a supporting document for arbitration, set this to arbitration_evidence.


 
Responses 
201
File uploaded successfully


401
Unauthorized


422
Unprocessable


429
Too many requests


post/files
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Common;

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Disputes)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    IdResponse response = await api.DisputesClient().SubmitFile("file_path", "dispute_evidence");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples 
application/json
{}
Get file information
Retrieve information about a file that was previously uploaded.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
file_id
required
string
The file identifier. It is always prefixed by file_.


 
Responses 
200
File information retrieved successfully


401
Unauthorized


404
File not found


429
Too many requests or duplicate request detected


get/files/{file_id}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Files;

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Disputes)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    FileDetailsResponse response = await api.DisputesClient().GetFileDetails("file_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples 
application/json
{}
Workflows
Use Workflows to start receiving webhook notifications for your payments, disputes, and sub-entities.


Get all workflows
Get all workflows


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Responses 
200
Workflows retrieved successfully


401
Unauthorized


500
Internal Error


get/workflows
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Workflows;

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Flow)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    GetWorkflowsResponse response = await api.WorkflowsClient().GetWorkflows();
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples 
application/json
{}
Add a workflow
Add a new Flow workflow


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
Request Body schema: application/json
required
name
string
A name you can use to describe your workflow


 
active
boolean
 Default:  true
Indicates whether the workflow is currently active


 
Array of objects (workflow-condition)   non-empty 
Only one condition of the same type is permitted


 
Array of objects (workflow-action)   non-empty 
One or more workflow actions


 
Responses 
201
Workflow added successfully


401
Unauthorized


422
Invalid data was sent


500
Internal Error


post/workflows
Request samples 
application/json
{
  • "name": "Webhooks workflow",
  • "active": true,
  • "conditions": [
    ],
  • "actions": [
    ]
}
Response samples 
application/json
{}
Get a workflow
Get the details of a workflow


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
workflowId
required
string^wf_[a-z0-9]{26}$
The workflow identifier


 
 Example:  wf_c7svxlvo2bbuva4f6s3xu4f7wm
Responses 
200
Workflow retrieved successfully


401
Unauthorized


404
Workflow not found


500
Internal Error


get/workflows/{workflowId}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Workflows;

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Flow)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    GetWorkflowResponse response = await api.WorkflowsClient().GetWorkflow("workflow_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples 
application/json
{}
Remove a workflow
Removes a workflow so it is no longer being executed.
Actions of already executed workflows will be still processed.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
workflowId
required
string^wf_[a-z0-9]{26}$
The workflow identifier


 
 Example:  wf_c7svxlvo2bbuva4f6s3xu4f7wm
Responses 
204
Workflow removed successfully


401
Unauthorized


404
Workflow not found


500
Internal Error


delete/workflows/{workflowId}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Flow)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    EmptyResponse response = await api.WorkflowsClient().RemoveWorkflow("workflow_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Patch a workflow
Update a workflow.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
workflowId
required
string^wf_[a-z0-9]{26}$
The workflow identifier


 
 Example:  wf_c7svxlvo2bbuva4f6s3xu4f7wm
Request Body schema: application/json
required
name
string
A name to describe the workflow


 
active
boolean
Indicates whether the workflow is currently active


 
Array of objects (workflow-condition)   non-empty 
One or more workflow conditions


 
Array of objects (patch-workflow-action)   non-empty 
One or more workflow actions


 
Responses 
200
Workflow updated successfully


401
Unauthorized


404
Workflow not found


422
Invalid data was sent


500
Internal Error


patch/workflows/{workflowId}
Request samples 
application/json
{
  • "name": "Webhooks workflow",
  • "active": true,
  • "conditions": [
    ],
  • "actions": [
    ]
}
Response samples 
application/json
{
  • "id": "wf_c7svxlvo2bbuva4f6s3xu4f7wm",
  • "name": "Webhooks workflow",
  • "active": true,
  • "conditions": [
    ],
  • "actions": [
    ],
  • "_links": {}
}
Add a workflow action
Adds a workflow action. Actions determine what the workflow will do when it is triggered.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
workflowId
required
string^wf_[a-z2-7]{26}$
The workflow identifier


 
 Example:  wf_c7svxlvo2bbuva4f6s3xu4f7wm
Request Body schema: application/json
required
url
required
string <uri> 
Your webhook endpoint URL


 
type
required
string
The type of workflow action


 
object
Optional HTTP headers added to the request


 
object
Used to produce a signature of the webhook contents that will be included in the Cko-Signature header. This value can be computed by you on receipt of a webhook to validate its authenticity.


 
Responses 
201
Workflow action added successfully


401
Unauthorized


404
Workflow not found


422
Invalid data was sent


500
Internal Error


post/workflows/{workflowId}/actions
Request samples 
application/json
{}
Response samples 
application/json
{}
Update a workflow action
Update a workflow action.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
workflowId
required
string^wf_[a-z0-9]{26}$
The workflow identifier


 
 Example:  wf_c7svxlvo2bbuva4f6s3xu4f7wm
workflowActionId
required
string^wfa_[a-z0-9]{26}$
The workflow action identifier


 
 Example:  wfa_d5estuyxzshubhly2wu3hloehi
Request Body schema: application/json
required
url
required
string <uri> 
Your webhook endpoint URL


 
type
required
string
The type of workflow action


 
object
Optional HTTP headers added to the request


 
object
Used to produce a signature of the webhook contents that will be included in the Cko-Signature header. This value can be computed by you on receipt of a webhook to validate its authenticity.


 
Responses 
200
Workflow action updated successfully


401
Unauthorized


404
Workflow or workflow action not found


422
Invalid data was sent


500
Internal Error


put/workflows/{workflowId}/actions/{workflowActionId}
Request samples 
application/json
{}
Response samples 
application/json
{
  • "request_id": "0HL80RJLS76I7",
  • "error_type": "request_invalid",
  • "error_codes": [
    ]
}
Remove a workflow action
Removes a workflow action. Actions determine what the workflow will do when it is triggered.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
workflowId
required
string^wf_[a-z2-7]{26}$
The workflow identifier


 
 Example:  wf_c7svxlvo2bbuva4f6s3xu4f7wm
workflowActionId
required
string^wfa_[a-z2-7]{26}$
The workflow action identifier


 
 Example:  wfa_c7svxlvo2bbuva4f6s3xu4f7wm
Responses 
204
Workflow action removed successfully


401
Unauthorized


404
Workflow or workflow action not found


422
Invalid data was sent


500
Internal Error


delete/workflows/{workflowId}/actions/{workflowActionId}
Request samples 
Response samples 
application/json
{
  • "request_id": "0HL80RJLS76I7",
  • "error_type": "request_invalid",
  • "error_codes": [
    ]
}
Add a workflow condition
Adds a workflow condition. Conditions determine when the workflow will trigger.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
workflowId
required
string^wf_[a-z2-7]{26}$
The workflow identifier


 
 Example:  wf_c7svxlvo2bbuva4f6s3xu4f7wm
Request Body schema: application/json
required
required
object (source-events-hashmap) 
 
type
required
string
The type of the workflow condition


 
Responses 
201
Workflow condition added successfully


401
Unauthorized


404
Workflow not found


422
Invalid data was sent


500
Internal Error


post/workflows/{workflowId}/conditions
Request samples 
application/json
{
  • "type": "event",
  • "events": {
    }
}
Response samples 
application/json
{}
Update a workflow condition
Update a workflow condition.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
workflowId
required
string^wf_[a-z0-9]{26}$
The workflow identifier


 
 Example:  wf_c7svxlvo2bbuva4f6s3xu4f7wm
workflowConditionId
required
string^wfc_[a-z0-9]{26}$
The workflow condition identifier


 
 Example:  wfc_d5estuyxzshubhly2wu3hloehi
Request Body schema: application/json
required
required
object (source-events-hashmap) 
 
type
required
string
The type of the workflow condition


 
Responses 
200
Workflow condition updated successfully


401
Unauthorized


404
Workflow or workflow condition not found


422
Invalid data was sent


500
Internal Error


put/workflows/{workflowId}/conditions/{workflowConditionId}
Request samples 
application/json
{
  • "type": "event",
  • "events": {
    }
}
Response samples 
application/json
{
  • "request_id": "0HL80RJLS76I7",
  • "error_type": "request_invalid",
  • "error_codes": [
    ]
}
Remove a workflow condition
Removes a workflow condition. Conditions determine when the workflow will trigger.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
workflowId
required
string^wf_[a-z2-7]{26}$
The workflow identifier


 
 Example:  wf_c7svxlvo2bbuva4f6s3xu4f7wm
workflowConditionId
required
string^wfc_[a-z2-7]{26}$
The workflow condition identifier


 
 Example:  wfc_c7svxlvo2bbuva4f6s3xu4f7wm
Responses 
204
Workflow condition removed successfully


401
Unauthorized


404
Workflow or workflow condition not found


500
Internal Error


delete/workflows/{workflowId}/conditions/{workflowConditionId}
Request samples 
Test a workflow
Validate a workflow in our Sandbox environment.


SecurityOAuth2: OAuth 
Request 
path Parameters
workflowId
required
string^wf_[a-z2-7]{26}$
The workflow identifier


 
 Example:  wf_c7svxlvo2bbuva4f6s3xu4f7wm
Request Body schema: application/json
required
event_types
Array of strings
Event types for which the workflow will execute


 
Responses 
204
Workflow test initiated


401
Unauthorized


404
Workflow not found


422
Invalid data was sent


500
Internal Error


post/workflows/{workflowId}/test
Request samples 
application/json
{
  • "event_types": [
    ]
}
Response samples 
application/json
{
  • "request_id": "0HLHPN8802NUF:00000003",
  • "error_type": "request_invalid",
  • "error_codes": [
    ]
}
Get event types
Get a list of sources and their events for building new workflows


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Responses 
200
Event types retrieved successfully


401
Unauthorized


500
Internal Error


get/workflows/event-types
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Workflows.Events;

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Flow)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    ItemsResponse<EventTypesResponse> response = await api.WorkflowsClient().GetEventTypes();
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples 
application/json
[
  • {
    }
]
Get an event
Get the details of an event


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
eventId
required
string^evt_[a-z0-9]{26}$
The event identifier


 
 Example:  evt_x5zm2po6kimubhlfitgt2mfwgi
Responses 
200
Event retrieved successfully


401
Unauthorized


404
Event not found


500
Internal Error


get/workflows/events/{eventId}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Workflows.Events;

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Flow)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    GetEventResponse response = await api.WorkflowsClient().GetEvent("event_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples 
application/json
{
  • "id": "evt_az5sblvku4ge3dwpztvyizgcau",
  • "source": "gateway",
  • "type": "payment_approved",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "version": "1.0.0",
  • "data": {
    },
  • "action_invocations": [],
  • "_links": {}
}
Get action invocations
Get the details of a workflow action executed for the specified event.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
eventId
required
string^evt_[a-z0-9]{26}$
The event identifier


 
 Example:  evt_x5zm2po6kimubhlfitgt2mfwgi
workflowActionId
required
string^wfa_[a-z0-9]{26}$
The workflow action identifier


 
 Example:  wfa_uzkxpffkvpiu5fe3h5ira7sqpa
Responses 
200
Workflow action retrieved successfully


401
Unauthorized


404
Event not found


500
Internal Error


get/workflows/events/{eventId}/actions/{workflowActionId}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Workflows.Actions.Response;

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Flow)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    WorkflowActionInvocationsResponse response = await api.WorkflowsClient().GetActionInvocations("event_id", "action_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples 
application/json
{
  • "workflow_id": "wf_c7svxlvo2bbuva4f6s3xu4f7wm",
  • "event_id": "evt_az5sblvku4ge3dwpztvyizgcau",
  • "workflow_action_id": "wfa_uzkxpffkvpiu5fe3h5ira7sqpa",
  • "action_type": "webhook",
  • "status": "successful",
  • "action_invocations": [
    ],
  • "_links": {}
}
Reflow by event
Reflows a past event denoted by the event ID and triggers the actions of any workflows with matching conditions.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
eventId
required
string^evt_[a-z0-9]{26}$
The unique identifier for the event to be reflowed.


 
 Example:  evt_x5zm2po6kimubhlfitgt2mfwgi
Responses 
202
Event reflow initiated successfully


401
Unauthorized


404
Events for reflow not found


500
Internal Error


post/workflows/events/{eventId}/reflow
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Workflows.Reflows;

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Flow)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    ReflowResponse response = await api.WorkflowsClient().ReflowByEvent("event_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Reflow by event and workflow
Reflows a past event by event ID and workflow ID. Triggers all the actions of a specific event and workflow combination if the event denoted by the event ID matches the workflow conditions.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
eventId
required
string^evt_[a-z0-9]{26}$
The unique identifier for the event to be reflowed.


 
 Example:  evt_x5zm2po6kimubhlfitgt2mfwgi
workflowId
required
string^wf_[a-z0-9]{26}$
The identifier of the workflow whose actions you want to trigger.


 
 Example:  wf_c8zm2po6kimubhlfitgt2mferf
Responses 
202
Event reflow initiated successfully


401
Unauthorized


404
Events for reflow not found


500
Internal Error


post/workflows/events/{eventId}/workflow/{workflowId}/reflow
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Workflows.Reflows;

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Flow)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    ReflowResponse response = await api.WorkflowsClient().ReflowByEventAndWorkflow("event_id", "workflow_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Reflow
Reflow past events attached to multiple event IDs and workflow IDs, or to multiple subject IDs and workflow IDs. If you don't specify any workflow IDs, all matching workflows will be retriggered.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
Request Body schema: application/json
required
One of:
events
required
Array of strings
A list of IDs for the events you want reflowed.


 
workflows
Array of strings
A list of IDs for the workflows whose actions you want to retrigger.


 
Responses 
202
Event reflow initiated successfully


401
Unauthorized


404
Events for reflow not found


422
Invalid data was sent


500
Internal Error


post/workflows/events/reflow
Request samples 
application/json
{
  • "events": [
    ],
  • "workflows": [
    ]
}
Response samples 
application/json
{
  • "request_id": "0HL80RJLS76I7",
  • "error_type": "request_invalid",
  • "error_codes": [
    ]
}
Get subject events
Get all events that relate to a specific subject


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
subjectId
required
string
The event identifier


 
 Example:  pay_wlu3wxc26jounofs5iez75qaqa
Responses 
200
Events retrieved successfully


401
Unauthorized


404
Subject not found


500
Internal Error


get/workflows/events/subject/{subjectId}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Workflows.Events;

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Flow)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    SubjectEventsResponse response = await api.WorkflowsClient().GetSubjectEvents("subject_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples 
application/json
{}
Reflow by subject
Reflows the events associated with a subject ID (for example, a payment ID or a dispute ID) and triggers the actions of any workflows with matching conditions.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
subjectId
required
string^[a-z]{3}_[a-z0-9]{26}$
The subject identifier (for example, a payment ID or a dispute ID). The events associated with these subjects will be reflowed.


 
 Example:  pay_x5zm2po6kimubhlfitgt2mfwgi
Responses 
202
Event reflow initiated successfully


401
Unauthorized


404
Events for reflow not found


500
Internal Error


post/workflows/events/subject/{subjectId}/reflow
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Workflows.Reflows;

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Flow)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    ReflowResponse response = await api.WorkflowsClient().ReflowBySubject("subject_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Reflow by subject and workflow
Reflows the events associated with a subject ID (for example, a payment ID or a dispute ID) and triggers the actions of the specified workflow if the conditions match.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
subjectId
required
string^[a-z]{3}_[a-z0-9]{26}$
The subject identifier (for example, a payment ID or a dispute ID). The events associated with these subjects will be reflowed.


 
 Example:  pay_x5zm2po6kimubhlfitgt2mfwgi
workflowId
required
string^wf_[a-z0-9]{26}$
The identifier of the workflow whose actions you want to trigger.


 
 Example:  wf_c8zm2po6kimubhlfitgt2mferf
Responses 
202
Event reflow initiated successfully


401
Unauthorized


404
Events for reflow not found


500
Internal Error


post/workflows/events/subject/{subjectId}/workflow/{workflowId}/reflow
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Workflows.Reflows;

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Flow)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    ReflowResponse response = await api.WorkflowsClient().ReflowBySubjectAndWorkflow("subject_id", "workflow_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Platforms
Manage all your sub-entities (also known as sub-merchants) through one integration, globally.


Onboard an entity
Onboard an entity so they can start using Checkout services.


SecurityOAuth2: OAuth 
Request 
header Parameters
Accept
required
string
Used to describe the type of content the client can interpret.
Use the schema_version value to specify the payload format. The latest version is 3.0.


 
 Example:  application/json;schema_version=3.0
Request Body schema: application/json
required
The entity to be onboarded. Use the relevant format for the platform type, region and payload version.


One of:
Beta

Create a sub-entity and send an invite to the seller to onboard with Checkout.com. The seller will receive an email with a link to the Dashboard, where they can complete their onboarding application. Only one user can be invited to onboard the sub-entity through Hosted Onboarding.


To enable the Hosted Onboarding feature, contact your Account Manager.


reference
required
string  [ 1 .. 50 ] characters 
A unique reference you can later use to identify the sub-entity.


 
required
object (Contact details) 
The contact details of the members invited to onboard the sub-entity


 
is_draft
required
boolean
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.


 
Responses 
201
Entity onboarded successfully


400
Bad Request


401
Unauthorized


409
Entity onboarding request conflicted with an existing entity


422
Invalid data was sent


post/accounts/entities
Request samples 
application/json
{
  • "reference": "superhero1234",
  • "is_draft": true,
  • "contact_details": {
    }
}
Response samples 
application/json
{}
Get sub-entity Members
Beta

Retrieve information on all users of a sub-entity that has been invited through Hosted Onboarding. Only one user can be invited to onboard the sub-entity through Hosted Onboarding.


To enable the Hosted Onboarding feature, contact your Account Manager.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
entityId
required
string
The ID of the sub-entity


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
Responses 
200
Sub-Entity member retrieved successfully


401
Unauthorized


404
Sub-entity not found


get/accounts/entities/{entityId}/members
Request samples 
Response samples 
application/json
{
  • "data": [
    ]
}
Reinvite a sub-entity member
Beta

Resend an invitation to the user of a sub-entity. The user will receive another email to continue their Hosted Onboarding application. An invitation can only be resent to the user originally registered to the sub-entity.


To enable the Hosted Onboarding feature, contact your Account Manager.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
entityId
required
string
The ID of the sub-entity


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
userId
required
string
The ID of the invited user.


 
 Example:  usr_eyk754cqieqexfh6u46no5nnha
Request Body schema: application/json
required
object (Reinvite sub-entity member) 
 
Responses 
200
Sub-entity member retrieved successfully


401
Unauthorized


404
Sub-entity not found


put/accounts/entities/{entityId}/members/{userId}
Request samples 
application/json
{ }
Response samples 
application/json
{
  • "id": "usr_eyk754cqieqexfh6u46no5nnha"
}
Get entity details
Use this endpoint to retrieve an entity and its full details.


SecurityOAuth2: OAuth 
Request 
path Parameters
id
required
string
The ID of the entity.


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
header Parameters
Accept
required
string
Used to describe the type of content the client can interpret.
Use the schema_version value to specify the payload format. The latest version is 3.0.


 
 Example:  application/json;schema_version=3.0
Responses 
200
Entity retrieved successfully


401
Unauthorized


404
Entity not found


422
Invalid data was sent


get/accounts/entities/{id}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Accounts;

ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Accounts)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    OnboardEntityDetailsResponse response = await api.AccountsClient().GetEntity("entity_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples 
application/json
{
  • "reference": "string",
  • "status": "string",
  • "profile": {
    },
  • "contact_details": {
    },
  • "capabilities": { },
  • "requirements_due": [
    ],
  • "company": {
    },
  • "processing_details": {
    },
  • "documents": {
    }
}
Update entity details
Update an entity.


Note: when you update a entity we may conduct further due diligence checks when necessary. During these checks, your payment capabilities will remain the same.


SecurityOAuth2: OAuth 
Request 
path Parameters
id
required
string
The ID of the entity.


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
header Parameters
Accept
required
string
Used to describe the type of content the client can interpret.
Use the schema_version value to specify the payload format. The latest version is 3.0.


 
 Example:  application/json;schema_version=3.0
Request Body schema: application/json
required
The entity to be updated. Use the relevant format for the platform type, region and payload version.


One of:
reference
required
string (Unique reference)   [ 1 .. 50 ] characters 
A unique reference you can later use to identify the sub-entity.


 
required
object (Company) 
Information about the company represented by the sub-entity.


 
required
object (Profile) 
Information about the profile of the sub-entity, primarily regarding the products/services offered.


 
required
object (Contact Details) 
Contact details of this sub-entity.


 
required
object (Documents) 
The documents used to support the verification of company details.


 
required
object (Processing Details) 
Seller processing details.


 
is_draft
boolean
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.


 
Responses 
200
Entity updated successfully


401
Unauthorized


404
Entity not found


422
Invalid data was sent


put/accounts/entities/{id}
Request samples 
application/json
{
  • "reference": "string",
  • "is_draft": true,
  • "profile": {
    },
  • "contact_details": {
    },
  • "company": {
    },
  • "processing_details": {
    },
  • "documents": {
    }
}
Response samples 
application/json
{}
Upload a file
Our Platforms solution provides an easy way to upload documentation required for full due diligence.


Use this endpoint to generate a file upload link, which you can then upload a file to using a data-binary type request.


See the documentation for more information.


Please note that the sub-domain – https://files.checkout.com – is slightly different to Checkout.com's other endpoints. See the documentation for more information.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
entityId
required
string
The ID of the sub-entity


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
Request Body schema: application/json
purpose
required
string
The purpose of the file upload.


 Enum: "additional_document" "articles_of_association" "bank_verification" "certified_authorised_signatory" "company_ownership" "company_verification" "financial_verification" "identity_verification" "proof_of_legality" "proof_of_principal_address" "shareholder_structure" "tax_verification" "proof_of_residential_address" "proof_of_registration"  
Responses 
200
File uploaded successfully


401
Unauthorized


422
Unprocessable


429
Too many requests


post/entities/{entityId}/files
Request samples 
application/json
{
  • "purpose": "identity_verification"
}
Response samples 
application/json
{}
Retrieve a file
Retrieve information about a previously uploaded file.


Please note that the sub-domain – https://files.checkout.com – is slightly different to Checkout.com's other endpoints. See the documentation for more information.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
entityId
required
string
The ID of the sub-entity


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
fileId
required
string
The ID of the file. The value is always prefixed with file_.


 
 Example:  file_w4jelhppkaskd0dnatam37wrfc4
Responses 
200
OK


401
Unauthorized


404
File not found


get/entities/{entityId}/files/{fileId}
Request samples 
Response samples 
application/json
{}
Payment instruments
Manage bank account payment instruments for your sub-entities.


Get payment instrument details
Retrieve the details of a specific payment instrument used for sub-entity payouts.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
entityId
required
string
The sub-entity's ID.


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
id
required
string
The payment instrument's ID.


 
 Example:  ppi_qn4nis4k3ykpzzu7cvtuvhqqga
Responses 
200
Payment instrument details


400
Bad Request


401
Unauthorized


get/accounts/entities/{entityId}/payment-instruments/{id}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-go
import (
	"github.com/checkout/checkout-sdk-go"
	"github.com/checkout/checkout-sdk-go/configuration"
)

// API Keys
api, err := checkout.
			Builder().
			StaticKeys().
			WithSecretKey("secret_key").
			WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
			Build()
if err != nil {
	return nil, err
}

// OAuth
api, err := checkout.
			Builder().
			OAuth().
			WithClientCredentials("client_id", "client_secret").
			WithScopes([]string{configuration.Accounts}).
			WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
			Build()
if err != nil {
	return nil, err
}

response, err := api.Accounts.RetrievePaymentInstrumentDetails("entity_id", "payment_instrument_id")
if err != nil {
	return nil, err
}

return response, nil
Response samples 
application/json
{
  • "id": "ppi_qn4nis4k3ykpzzu7cvtuvhqqga",
  • "label": "Bob's Bank Account",
  • "type": "bank_account",
  • "currency": "GBP",
  • "country": "GB",
  • "document": {
    },
  • "status": "verified",
  • "default": true,
  • "instrument_id": "src_pdasnoaxrtoevpyh3opgaxcrti"
}
Update payment instrument details
Set an existing payment instrument as default. This will make it the destination instrument when a scheduled payout is made. You can also update the label of a payment instrument.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
entityId
required
string
The sub-entity's ID.


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
id
required
string
The payment instrument's ID.


 
 Example:  ppi_qn4nis4k3ykpzzu7cvtuvhqqga
Request Body schema: application/json
required
label
string (Label)   [ 1 .. 50 ] characters 
A reference that you can use to identify the payment instrument.


 
default
boolean (Default) 
 Deprecated 
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.


 
object
 
Responses 
200
Payment instrument updated successfully


401
Unauthorized


422
Unprocessable entity


428
Precondition required


patch/accounts/entities/{entityId}/payment-instruments/{id}
Request samples 
application/json
{
  • "label": "Peter's Personal Account",
  • "default": true,
  • "headers": {
    }
}
Response samples 
application/json
{}
Add a payment instrument
Create a bank account payment instrument for your sub-entity. You can use this payment instrument as a payout destination.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
id
required
string
The sub-entity's ID.


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
Request Body schema: application/json
required
A JSON payload containing the payment instrument details.


label
required
string (Label)   [ 1 .. 50 ] characters 
A reference that you can use to identify the payment instrument


 
type
required
string (Type) 
The instrument type


 
currency
required
string <ISO 4217>  (Currency)   = 3 characters 
The account's currency, as a 3-letter ISO currency code


 
required
object
Details of the payment instrument being created


 
Responses 
201
Created


400
Bad Request


401
Unauthorized


422
Invalid data was sent


post/accounts/entities/{id}/payment-instruments
Request samples 
application/json
{
  • "label": "Bob's Bank Account",
  • "type": "bank_account",
  • "currency": "GBP",
  • "country": "GB",
  • "default": true,
  • "instrument_details": {
    },
  • "document": {
    }
}
Response samples 
application/json
{
  • "id": "ppi_qn4nis4k3ykpzzu7cvtuvhqqga"
}
Query payment instruments
Fetch all of the payment instruments for a sub-entity. You can filter by status to identify verified instruments that are ready to be used for Payouts.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
id
required
string
The sub-entity's ID.


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
query Parameters
status
string (Status) 
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.


 Enum: "pending" "verified" "unverified"  
 Example:  status=verified
Responses 
200
OK


400
Bad Request


401
Unauthorized


get/accounts/entities/{id}/payment-instruments
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-go
import (
	"github.com/checkout/checkout-sdk-go"
	"github.com/checkout/checkout-sdk-go/accounts"
	"github.com/checkout/checkout-sdk-go/configuration"
)

// API Keys
api, err := checkout.
	Builder().
	StaticKeys().
	WithSecretKey("secret_key").
	WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
	Build()
if err != nil {
	return nil, err
}

// OAuth
api, err := checkout.
	Builder().
	OAuth().
	WithClientCredentials("client_id", "client_secret").
	WithScopes([]string{configuration.Accounts}).
	WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
	Build()
if err != nil {
	return nil, err
}

query := accounts.PaymentInstrumentsQuery{Status: "pending"}

response, err := api.Accounts.QueryPaymentInstruments("entity_id", query)
if err != nil {
	return nil, err
}

return response, nil
Response samples 
application/json
{
  • "data": [
    ]
}
Payout schedules
View and manage payout schedules for your sub-entities.


Retrieve a sub-entity's payout schedule
You can schedule when your sub-entities receive their funds using our Platforms solution. Use this endpoint to retrieve information about a sub-entity's schedule.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
id
required
string
The ID of the sub-entity


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
Responses 
200
Schedule retrieved successfully


401
Unauthorized.


404
Sub-entity not found, or scheduled payouts are not available to the sub-entity.


422
Invalid data sent.


429
Too many requests.


get/accounts/entities/{id}/payout-schedules
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Accounts.Payout.Response;

ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Accounts)
    .Environment(Environment.Sandbox)
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    GetScheduleResponse response = await api.AccountsClient().RetrievePayoutSchedule("entity_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples 
application/json
{}
Update a sub-entity's payout schedule
You can schedule when your sub-entities receive their funds using our Platforms solution. Use this endpoint to update a sub-entity's schedule.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
id
required
string
The ID of the sub-entity


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
Request Body schema: application/json
required
object <ISO 4217>   = 3 characters 
The three-letter ISO currency code of the account's currency.


 
Responses 
200
Schedule updated successfully


401
Unauthorized


422
Unprocessable entity


429
Too many requests


put/accounts/entities/{id}/payout-schedules
Request samples 
application/json
{
  • "ISO": {
    }
}
Response samples 
application/json
{}
Reserve rules
View and manage reserve rules for your sub-entities.


Get reserve rule details
Retrieve the details of a specific reserve rule.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
entityId
required
string
The sub-entity's ID.


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
id
required
string
The reserve rule ID.


 
 Example:  rsv_qn4nis4k3ykpzzu7cvtuvhqqga
Responses 
200
Reserve rule details.


400
Bad Request


401
Unauthorized


get/accounts/entities/{entityId}/reserve-rules/{id}
Request samples 
Response samples 
application/json
{
  • "id": "rsv_qn4nis4k3ykpzzu7cvtuvhqqga",
  • "type": "rolling",
  • "valid_from": "2001-01-01T13:33:00.000Z",
  • "rolling": {
    }
}
Update reserve rule
Update an upcoming reserve rule. Only reserve rules that have never been active can be updated.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
entityId
required
string
The sub-entity's ID.


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
id
required
string
The reserve rule ID.


 
 Example:  rsv_qn4nis4k3ykpzzu7cvtuvhqqga
header Parameters
If-Match
required
string
Identifies a specific version of a reserve rule to update.


 
 Example:  Y3Y9MCZydj0w
Request Body schema: application/json
required
type
required
string
 
 Value:  "rolling"
required
object (RollingReserveRule) 
 
Responses 
200
Reserve rule updated successfully.


401
Unauthorized


412
Precondition failed. An invalid ETag value was provided in the If-Match header.


422
Unprocessable entity


428
Precondition required. The If-Match header is required.


put/accounts/entities/{entityId}/reserve-rules/{id}
Request samples 
application/json
{
  • "type": "rolling",
  • "rolling": {
    }
}
Response samples 
application/json
{
  • "id": "rsv_qn4nis4k3ykpzzu7cvtuvhqqga",
  • "_links": {
    }
}
Add a reserve rule
Create a sub-entity reserve rule.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
id
required
string
The sub-entity's ID.


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
Request Body schema: application/json
required
A JSON payload containing the reserve rule details.


type
required
string
 
 Value:  "rolling"
required
object (RollingReserveRule) 
 
valid_from
required
string <date-time> 
The date and time the reserve rule will come into effect. This must be at least 15 minutes in the future.


 
Responses 
201
Created


400
Bad Request


401
Unauthorized


422
Invalid data was sent


post/accounts/entities/{id}/reserve-rules
Request samples 
application/json
{
  • "type": "rolling",
  • "valid_from": "2001-01-01T13:33:00.000Z",
  • "rolling": {
    }
}
Response samples 
application/json
{
  • "id": "rsv_qn4nis4k3ykpzzu7cvtuvhqqga",
  • "_links": {
    }
}
Query reserve rules
Fetch all of the reserve rules for a sub-entity.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
id
required
string
The sub-entity's ID.


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
Responses 
200
OK


400
Bad Request


401
Unauthorized


get/accounts/entities/{id}/reserve-rules
Request samples 
Response samples 
application/json
{
  • "data": [
    ]
}
Cardholders
Create new cardholders to issue cards to, and manage your existing cardholders.


Create a cardholder
Create a new cardholder that you can issue a card to at a later point.


SecurityOAuth2: OAuth 
Request 
Request Body schema: application/json
required
first_name
required
string  [ 1 .. 40 ] characters 
The cardholder's first name.


 
last_name
required
string  [ 1 .. 40 ] characters 
The cardholder's last name.


 
required
object (IssuingAddress) 
 
type
required
string
The type of cardholder to create.


 
entity_id
required
string (IssuingEntityId)   = 30 characters ^ent_[a-z0-9]{26}$
The entity's unique identifier.


 
reference
string (IssuingReference)   <= 256 characters 
Your reference.


 
middle_name
string  [ 1 .. 40 ] characters 
The cardholder's middle name.


 
email
string <email>  (IssuingEmail)   [ 3 .. 254 ] characters 
The cardholder's email. 


Emails are validated against the rfc6530 standard.


 
object (IssuingPhoneNumber) 
The cardholder's phone number.


 
date_of_birth
string <date> 
The cardholder's date of birth, in the format YYYY-MM-DD.


 
object (IssuingAddress) 
 
object (IdentificationDocument) 
A legal document used to verify the cardholder's identity.


 
Responses 
201
Cardholder created successfully


401
Unauthorized


422
Invalid data was sent


500
Internal Server Error


post/issuing/cardholders
Request samples 
application/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": {
    },
  • "date_of_birth": "1985-05-15",
  • "billing_address": {
    },
  • "residency_address": {
    },
  • "document": {
    }
}
Response samples 
application/json
{}
Get cardholder details
Retrieve the details for a cardholder you created previously.


SecurityOAuth2: OAuth 
Request 
path Parameters
cardholderId
required
string (IssuingCardholderId)   = 30 characters ^crh_[a-z0-9]{26}$
The cardholder's unique identifier.


 
 Example:  crh_d3ozhf43pcq2xbldn2g45qnb44
Responses 
200
Cardholder returned successfully


401
Unauthorized


404
Cardholder not found


500
Internal Server Error


get/issuing/cardholders/{cardholderId}
Request samples 
Response samples 
application/json
{
  • "id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
  • "type": "individual",
  • "first_name": "John",
  • "middle_name": "Fitzgerald",
  • "last_name": "Kennedy",
  • "email": "john.kennedy@myemaildomain.com",
  • "phone_number": {
    },
  • "date_of_birth": "1985-05-28",
  • "billing_address": {
    },
  • "residency_address": {
    },
  • "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": {}
}
Update a cardholder
Updates the details of an existing cardholder.


Request 
path Parameters
cardholderId
required
string (IssuingCardholderId)   = 30 characters ^crh_[a-z0-9]{26}$
The cardholder's unique identifier.


 
 Example:  crh_d3ozhf43pcq2xbldn2g45qnb44
Request Body schema: application/json
required
first_name
string  [ 1 .. 40 ] characters 
The cardholder's first name.


 
middle_name
string  [ 1 .. 40 ] characters 
The cardholder's middle name. To set this field to null, pass null in your request.


 
last_name
string  [ 1 .. 40 ] characters 
The cardholder's last name.


 
date_of_birth
string <date> 
The cardholder's date of birth in the YYYY-MM-DD format. To set this field to null, pass null in your request.


 
object (IssuingPhoneNumber) 
The cardholder's phone number.


 
email
string <email>  (IssuingEmail)   [ 3 .. 254 ] characters 
The cardholder's email. 


Emails are validated against the rfc6530 standard.


 
object (IssuingAddress) 
 
object (IssuingAddress) 
 
object (IdentificationDocument) 
A legal document used to verify the cardholder's identity.


 
Responses 
200
Cardholder updated successfully


401
Unauthorized


404
Cardholder not found


422
Invalid data was sent


500
Internal Server Error


patch/issuing/cardholders/{cardholderId}
Request samples 
application/json
{
  • "first_name": "John",
  • "middle_name": null,
  • "last_name": "Kennedy",
  • "date_of_birth": "1985-05-15",
  • "phone_number": {
    },
  • "email": "john.kennedy@myemaildomain.com",
  • "billing_address": {
    },
  • "residency_address": {
    },
  • "document": {
    }
}
Response samples 
application/json
{}
Get a cardholder's cards
Retrieves the cards issued to the specified cardholder.


Card credentials are not returned in the response.


SecurityOAuth2: OAuth 
Request 
path Parameters
cardholderId
required
string (IssuingCardholderId)   = 30 characters ^crh_[a-z0-9]{26}$
The cardholder's unique identifier.


 
 Example:  crh_d3ozhf43pcq2xbldn2g45qnb44
Responses 
200
Cardholder's cards returned successfully


401
Unauthorized


404
Cardholder not found


500
Internal Server Error


get/issuing/cardholders/{cardholderId}/cards
Request samples 
Response samples 
application/json
{}
Cards
Issue new cards to your cardholders, and manage cards you've already issued.


Create a card
Creates a physical or virtual card and issues it to the specified cardholder.


SecurityOAuth2: OAuth 
Request 
header Parameters
Cko-Idempotency-Key
string  [ 1 .. 256 ] characters 
An optional idempotency key for safely retrying Issuing requests.


 
Request Body schema: application/json
required
type
required
string
The card type.


 
cardholder_id
required
string (IssuingCardholderId)   = 30 characters ^crh_[a-z0-9]{26}$
The cardholder's unique identifier.


 
card_product_id
required
string  = 30 characters ^pro_[a-z0-9]{26}$
The card product's unique identifier. This field is required if there are multiple card products associated with the entity.


 
object (CardLifetime) 
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
string (IssuingReference)   <= 256 characters 
Your reference.


 
object (IssuingCardMetadata) 
User's metadata.


 
revocation_date
string (IssuingRevocationDate) 
Date for the card to be automatically revoked. Must be after the current date and date only in the form yyyy-mm-dd.


 
display_name
string (DisplayName)   [ 2 .. 26 ] characters ^[0-9a-zA-Z.\- ]{2,26}$
The name to display on the card.


 
is_single_use
boolean
 Default:  false
Sets whether the virtual card should expire after a single use.


 
activate_card
boolean
 Default:  true
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
Array of strings
The credentials to retrieve on card creation.


Items Enum: "number" "cvc2"  
control_profiles
Array of arrays
The control profiles to which this card will be added as a target.


 
Array of objects (add-virtual-card-control-request) 
The controls that will be set on the card.


 
Responses 
201
Card created successfully


401
Unauthorized


422
Invalid data was sent


500
Internal Server Error


503
Service Unavailable


post/issuing/cards
Request samples 
application/json
{
  • "type": "virtual",
  • "cardholder_id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
  • "lifetime": {
    },
  • "reference": "X-123456-N11",
  • "metadata": {
    },
  • "revocation_date": "2027-03-12",
  • "card_product_id": "pro_7syjig3jq3mezlc3vjrdpfitl4",
  • "display_name": "JOHN KENNEDY",
  • "is_single_use": false,
  • "activate_card": true,
  • "return_credentials": [
    ],
  • "control_profiles": [
    ],
  • "controls": [
    ]
}
Response samples 
application/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",
  • "created_date": "2019-09-10T10:11:12Z",
  • "_links": {},
  • "credentials": {
    },
  • "controls": [
    ]
}
Get card details
Retrieves the details for a card you issued previously.


The card's credentials are not returned in the response.


SecurityOAuth2: OAuth 
Request 
path Parameters
cardId
required
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The card's unique identifier.


 
 Example:  crd_fa6psq242dcd6fdn5gifcq1491
Responses 
200
Card returned successfully


401
Unauthorized


404
Card not found


500
Internal Server Error


get/issuing/cards/{cardId}
Request samples 
Response samples 
application/json
{}
Update card details
Update the details of an issued card.


Only the fields for which you provide values will be updated. If you pass null, the existing value will be removed.


SecurityOAuth2: OAuth 
Request 
path Parameters
cardId
required
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The card's unique identifier.


 
 Example:  crd_fa6psq242dcd6fdn5gifcq1491
Request Body schema: application/json
required
reference
string (IssuingReference)   <= 256 characters 
Your reference.


 
object (IssuingCardMetadata) 
User's metadata.


 
expiry_month
integer <int32>  (ExpiryMonth)   [ 1 .. 12 ] 
The card's expiration month.


 
expiry_year
integer <int32>  (ExpiryYear)   = 4 characters 
The card's expiration year.


 
Responses 
200
Card updated successfully


401
Unauthorized


404
Card not found


422
Invalid data was sent


500
Internal Server Error


patch/issuing/cards/{cardId}
Request samples 
application/json
{
  • "reference": "X-123456-N11",
  • "metadata": {
    },
  • "expiry_month": 5,
  • "expiry_year": 2025
}
Response samples 
application/json
{}
Enroll a card in 3DS
Enrolls a card in 3D Secure (3DS). Additional information is requested from the cardholder through a 3DS challenge when performing a transaction.


Two-factor authentication (2FA) is supported. For maximum security, we recommend using a combination of a one-time password (OTP) sent via SMS, along with a password or question and answer security pair.


SecurityOAuth2: OAuth 
Request 
path Parameters
cardId
required
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The card's unique identifier.


 
 Example:  crd_fa6psq242dcd6fdn5gifcq1491
Request Body schema: application/json
required
One of:
required
object (3dsSecurityPair) 
The question and answer security pair used to support knowledge-based 3DS authentication.


Security pairs are set per-card, not per-cardholder.


 
required
object (3dsPhoneNumber) 
The phone number to send the one-time password (OTP) for 3DS authentication to.


This phone number is independent of the cardholder's phone number on file.


 
locale
string <language-COUNTRY>  (3dsLocale)   = 5 characters ^[a-z]{2}-[A-Z]{2}$
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. 


 Enum: "en-US" "fr-FR"  
Responses 
202
3DS card enrollment completed successfully


401
Unauthorized


404
Card not found


422
Invalid data was sent


500
Internal Server Error


post/issuing/cards/{cardId}/3ds-enrollment
Request samples 
application/json
{
  • "security_pair": {
    },
  • "locale": "en-US",
  • "phone_number": {
    }
}
Response samples 
application/json
{}
Update a card's 3DS details
Updates a card's 3DS enrollment details. At least one of the fields is required.


SecurityOAuth2: OAuth 
Request 
path Parameters
cardId
required
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The card's unique identifier.


 
 Example:  crd_fa6psq242dcd6fdn5gifcq1491
Request Body schema: application/json
required
One of:
object (3dsSecurityPair) 
The question and answer security pair used to support knowledge-based 3DS authentication.


Security pairs are set per-card, not per-cardholder.


 
locale
string <language-COUNTRY>  (3dsLocale)   = 5 characters ^[a-z]{2}-[A-Z]{2}$
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. 


 Enum: "en-US" "fr-FR"  
object (3dsPhoneNumber) 
The phone number to send the one-time password (OTP) for 3DS authentication to.


This phone number is independent of the cardholder's phone number on file.


 
Responses 
202
Card 3DS details updated successfully


401
Unauthorized


404
Card not found


422
Invalid data was sent


500
Internal Server Error


patch/issuing/cards/{cardId}/3ds-enrollment
Request samples 
application/json
{
  • "security_pair": {
    },
  • "locale": "en-US",
  • "phone_number": {
    }
}
Response samples 
application/json
{}
Get a card's 3DS enrollment details
Retrieves a card's 3DS enrollment details.


SecurityOAuth2: OAuth 
Request 
path Parameters
cardId
required
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The card's unique identifier.


 
 Example:  crd_fa6psq242dcd6fdn5gifcq1491
Responses 
200
Card 3DS enrollment details retrieved successfully


401
Unauthorized


404
Card not found


500
Internal Server Error


get/issuing/cards/{cardId}/3ds-enrollment
Request samples 
Response samples 
application/json
{}
Activate a card
Activates an inactive or suspended card so that incoming authorizations can be approved. 


Activating a renewed card will schedule the parent card for revocation the following day, and transfer all configurations to the newly activated card. This includes 3DS enrollment, card controls, control profiles and tokenisation.


SecurityOAuth2: OAuth 
Request 
path Parameters
cardId
required
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The card's unique identifier.


 
 Example:  crd_fa6psq242dcd6fdn5gifcq1491
Responses 
200
Card activated successfully


401
Unauthorized


404
Card not found


422
Invalid data was sent


post/issuing/cards/{cardId}/activate
Request samples 
Response samples 
application/json
{}
Get the card credentials
Retrieves the credentials for a card you issued previously.


SecurityOAuth2: OAuth 
Request 
path Parameters
cardId
required
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The card's unique identifier.


 
 Example:  crd_fa6psq242dcd6fdn5gifcq1491
query Parameters
credentials
string
The credentials to retrieve.


You can either specify number or cvc2 to retrieve the specified credential, or both as a comma-separated list. For example, to retrieve both the CVC and PAN:


"credentials": "number, cvc2"



 Enum: "number" "cvc2"  
 Example:  credentials=number,cvc2
Responses 
200
Card credentials returned successfully


401
Unauthorized


404
Card not found


422
Invalid data was sent


500
Internal Server Error


503
Service Unavailable


get/issuing/cards/{cardId}/credentials
Request samples 
Response samples 
application/json
{
  • "number": 4242424242424242,
  • "cvc2": 604
}
Renew a card
Renew an active, inactive, or suspended card. A card cannot be renewed if it is revoked, expired, or is a single use virtual card. 


The renewed card will have a different, nonconsecutive number (PAN), expiry date, and CVV. 


Any configuration set on the parent card will be copied to the renewed card when the renewed card is activated. This includes 3DS enrollment, card controls, control profiles, and tokenisation.


Request 
path Parameters
cardId
required
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The card's unique identifier.


 
 Example:  crd_fa6psq242dcd6fdn5gifcq1491
Request Body schema: application/json
required
One of:
display_name
string (DisplayName)   [ 2 .. 26 ] characters ^[0-9a-zA-Z.\- ]{2,26}$
The name to display on the card.


 
object (IssuingShippingInstruction) 
 
reference
string (IssuingReference)   <= 256 characters 
Your reference.


 
object (IssuingCardMetadata) 
User's metadata.


 
Responses 
200
Card renewed successfully


401
Unauthorized


404
Card not found


422
Invalid data was sent


post/issuing/cards/{cardId}/renew
Request samples 
application/json
{
  • "display_name": "JOHN KENNEDY",
  • "shipping_instructions": {
    },
  • "reference": "X-123456-N11",
  • "metadata": {
    }
}
Response samples 
application/json
{}
Revoke a card
Revokes an inactive, active, or suspended card to permanently decline all incoming authorizations.


This is a permanent action. Revoked cards cannot be reactivated.


SecurityOAuth2: OAuth 
Request 
path Parameters
cardId
required
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The card's unique identifier.


 
 Example:  crd_fa6psq242dcd6fdn5gifcq1491
Request Body schema: application/json
required
reason
string
The reason why the card is being revoked.


 Enum: "expired" "reported_lost" "reported_stolen"  
Responses 
200
Card revoked successfully


401
Unauthorized


404
Card not found


422
Invalid data was sent


post/issuing/cards/{cardId}/revoke
Request samples 
application/json
{
  • "reason": "reported_lost"
}
Response samples 
application/json
{}
Schedule card revocation
Schedules a card to be revoked at 00:00(UTC) on a specified date.


SecurityOAuth2: OAuth 
Request 
Request Body schema: application/json
required
revocation_date
required
string (IssuingRevocationDate) 
Date for the card to be automatically revoked. Must be after the current date and date only in the form yyyy-mm-dd.


 
Responses 
200
Revocation scheduled successfully


401
Unauthorized


422
Invalid data was sent


500
Internal Server Error


503
Service Unavailable


post/issuing/cards/{cardId}/schedule-revocation
Request samples 
application/json
{
  • "revocation_date": "2027-03-12"
}
Response samples 
application/json
{}
Delete scheduled revocation
Delete a card's scheduled revocation.


SecurityOAuth2: OAuth 
Responses 
200
Scheduled revocation deleted successfully


401
Unauthorized


500
Internal Server Error


503
Service Unavailable


delete/issuing/cards/{cardId}/schedule-revocation
Request samples 
Response samples 
application/json
{}
Suspend a card
Suspends an active or inactive card to temporarily decline all incoming authorizations.


A suspended card can be reactivated.


SecurityOAuth2: OAuth 
Request 
path Parameters
cardId
required
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The card's unique identifier.


 
 Example:  crd_fa6psq242dcd6fdn5gifcq1491
Request Body schema: application/json
required
reason
string
The reason why the card is being suspended.


 Enum: "suspected_lost" "suspected_stolen"  
Responses 
200
Card suspended successfully


401
Unauthorized


404
Card not found


422
Invalid data was sent


post/issuing/cards/{cardId}/suspend
Request samples 
application/json
{
  • "reason": "suspected_lost"
}
Response samples 
application/json
{}
Controls
Set spending controls to limit how much can be spent over a given period of time.


Create a control
Creates a control and applies it to the specified target.


SecurityOAuth2: OAuth 
Request 
header Parameters
Cko-Idempotency-Key
string  [ 1 .. 256 ] characters 
An optional idempotency key for safely retrying Issuing requests.


 
Request Body schema: application/json
required
required
object (VelocityLimit) 
The velocity limit, which determines how much a target card can spend over a given timeframe.


 
control_type
required
string (IssuingControlType) 
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
required
string (IssuingTargetIdForAdd)   = 30 characters ^(crd|cpr)_[a-z0-9]{26}$
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.


 
description
string  <= 256 characters 
A description for the control.


 
Responses 
201
Control created successfully


401
Unauthorized


404
Target not found


422
Invalid data was sent


500
Internal Server Error


503
Service Unavailable


post/issuing/controls
Request samples 
application/json
{
  • "description": "Maximum spend of 500€ per week for restaurants",
  • "control_type": "velocity_limit",
  • "target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
  • "velocity_limit": {
    }
}
Response samples 
application/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": {},
  • "velocity_limit": {
    }
}
Get controls by target
Retrieves a list of spending controls applied to the specified target.


SecurityOAuth2: OAuth 
Request 
query Parameters
target_id
required
string (IssuingTargetId)   = 30 characters ^(crd|cpr)_[a-z0-9]{26}$
The ID of the card or control profile.


 
 Example:  target_id=crd_fa6psq42dcdd6fdn5gifcq1491
Responses 
200
Target's controls returned successfully


401
Unauthorized


404
Target not found


422
Invalid data was sent


500
Internal Server Error


get/issuing/controls
Request samples 
Response samples 
application/json
{
  • "controls": [
    ]
}
Get control details
Retrieves the details of an existing control.


SecurityOAuth2: OAuth 
Request 
path Parameters
controlId
required
string (IssuingControlId)   = 30 characters ^ctr_[a-z0-9]{26}$
The control's unique identifier.


 
 Example:  ctr_gp7vkmxayztufjz6top5bjcdra
query Parameters
cardId
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The unique identifier for the card you want to get the remaining cascading velocity control for.


 
 Example:  cardId=crd_fa6psq242dcd6fdn5gifcq1491
Responses 
200
Control returned successfully


401
Unauthorized


404
Control not found


500
Internal Server Error


get/issuing/controls/{controlId}
Request samples 
Response samples 
application/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": {
    }
}
Update a control
Updates an existing control.


SecurityOAuth2: OAuth 
Request 
path Parameters
controlId
required
string (IssuingControlId)   = 30 characters ^ctr_[a-z0-9]{26}$
The control's unique identifier.


 
 Example:  ctr_gp7vkmxayztufjz6top5bjcdra
Request Body schema: application/json
required
One of:
The control you want to update.


You can update only one control per request.


description
string  <= 256 characters 
A description for the control.


 
object (MccLimit) 
The merchant category code (MCC) rule, which determines the types of businesses transactions can be processed from.


 
Responses 
200
Control updated successfully


401
Unauthorized


404
Control not found


422
Invalid data was sent


500
Internal Server Error


503
Service Unavailable


put/issuing/controls/{controlId}
Request samples 
application/json
{
  • "description": "Allow the card to be used only in restaurants and supermarkets",
  • "mcc_limit": {
    }
}
Response samples 
application/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": {
    }
}
Remove a control
Removes an existing control from the target it was applied to.


If you want to reapply an equivalent control to the target, you must create a new control.


SecurityOAuth2: OAuth 
Request 
path Parameters
controlId
required
string (IssuingControlId)   = 30 characters ^ctr_[a-z0-9]{26}$
The control's unique identifier.


 
 Example:  ctr_gp7vkmxayztufjz6top5bjcdra
Responses 
200
Control removed successfully


401
Unauthorized


404
Control not found


422
Invalid data was sent


500
Internal Server Error


503
Service Unavailable


delete/issuing/controls/{controlId}
Request samples 
Response samples 
application/json
{
  • "id": "ctr_gp7vkmxayztufjz6top5bjcdra"
}
Control profiles
Creates a control profile and applies it to the specified target.


Create a control profile
Creates a control profile.


SecurityOAuth2: OAuth 
Request 
Request Body schema: application/json
required
name
required
string
Control profile name.


 
Responses 
201
Control profile created successfully


401
Unauthorized


422
Invalid data was sent


500
Internal Server Error


503
Service Unavailable


post/issuing/controls/control-profiles
Request samples 
application/json
{
  • "name": "Low Risk MCC Profile"
}
Response samples 
application/json
{}
Get all control profiles
Retrieves a list of control profiles for the currently authenticated client, or for a specific card if a card ID is provided.


SecurityOAuth2: OAuth 
Request 
query Parameters
target_id
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The card's unique identifier.


 
 Example:  target_id=crd_fa6psq242dcd6fdn5gifcq1491
Responses 
200
Control profiles returned successfully


401
Unauthorized


404
Client not found


422
Invalid data was sent


500
Internal Server Error


get/issuing/controls/control-profiles
Request samples 
Response samples 
application/json
{
  • "control_profiles": [
    ]
}
Get control profile details
Retrieves the details of an existing control profile.


SecurityOAuth2: OAuth 
Request 
path Parameters
controlProfileId
required
string (IssuingControlProfileId)   = 30 characters ^cpr_[a-z0-9]{26}$
The control profile's unique identifier.


 
 Example:  cpr_j4mvlui5qotufgvaeqwhvlbfna
Responses 
200
Control profile returned successfully


401
Unauthorized


404
Control profile not found


500
Internal Server Error


get/issuing/controls/control-profiles/{controlProfileId}
Request samples 
Response samples 
application/json
{}
Update a control profile
Update the control profile


SecurityOAuth2: OAuth 
Request 
path Parameters
controlProfileId
required
string (IssuingControlProfileId)   = 30 characters ^cpr_[a-z0-9]{26}$
The control profile's unique identifier.


 
 Example:  cpr_j4mvlui5qotufgvaeqwhvlbfna
Request Body schema: application/json
required
name
string  <= 256 characters 
The control profile name.


 
Responses 
200
Control profile updated successfully


401
Unauthorized


404
Control profile not found


500
Internal Server Error


503
Service Unavailable


patch/issuing/controls/control-profiles/{controlProfileId}
Request samples 
application/json
{
  • "name": "Low Risk MCC Profile"
}
Response samples 
application/json
{}
Remove a control profile
Removes the control profile. A control profile cannot be removed if it is used by a control.


SecurityOAuth2: OAuth 
Request 
path Parameters
controlProfileId
required
string (IssuingControlProfileId)   = 30 characters ^cpr_[a-z0-9]{26}$
The control profile's unique identifier.


 
 Example:  cpr_j4mvlui5qotufgvaeqwhvlbfna
Responses 
200
Control profile removed successfully


401
Unauthorized


404
Control profile not found


500
Internal Server Error


503
Service Unavailable


delete/issuing/controls/control-profiles/{controlProfileId}
Request samples 
Add target to control profile
Adds a target to an existing control profile.


SecurityOAuth2: OAuth 
Request 
path Parameters
controlProfileId
required
string (IssuingControlProfileId)   = 30 characters ^cpr_[a-z0-9]{26}$
The control profile's unique identifier.


 
 Example:  cpr_j4mvlui5qotufgvaeqwhvlbfna
targetId
required
string (IssuingTargetIdToAddToControlProfile)   = 30 characters ^crd_[a-z0-9]{26}$
The ID of the card to apply the control profile to.


 
 Example:  crd_fa6psq42dcdd6fdn5gifcq1491
Responses 
200
Target added successfully


401
Unauthorized


404
Control profile not found


500
Internal Server Error


post/issuing/controls/control-profiles/{controlProfileId}/add/{targetId}
Request samples 
Response samples 
application/json
{}
Remove target from control profile
Removes a target from an existing control profile.


SecurityOAuth2: OAuth 
Request 
path Parameters
controlProfileId
required
string (IssuingControlProfileId)   = 30 characters ^cpr_[a-z0-9]{26}$
The control profile's unique identifier.


 
 Example:  cpr_j4mvlui5qotufgvaeqwhvlbfna
targetId
required
string (IssuingTargetIdToRemoveFromControlProfile)   = 30 characters ^crd_[a-z0-9]{26}$
The ID of the card the control profile should no longer apply to.


 
 Example:  crd_fa6psq42dcdd6fdn5gifcq1491
Responses 
200
Target removed successfully


401
Unauthorized


404
Control profile not found


500
Internal Server Error


post/issuing/controls/control-profiles/{controlProfileId}/remove/{targetId}
Request samples 
Response samples 
application/json
{}
Cardholder access tokens
Create a cardholder-specific access token for secure data access with our Card Issuing SDK for Android or iOS, by exchanging your access key ID and access key secret.


Request an access token
OAuth endpoint to exchange your access key ID and access key secret for an access token.


Request 
Request Body schema: application/x-www-form-urlencoded
grant_type
string
 Value: "client_credentials"  
client_id
string
Access key ID.


 
client_secret
string
Access key secret.


 
cardholder_id
string (IssuingCardholderId)   = 30 characters ^crh_[a-z0-9]{26}$
The cardholder's unique identifier.


 
single_use
bool
Specifies if the request is for a single-use token.
Single-use tokens are required for sensitive endpoints.


 
Responses 
200
OK - A successful access token response


422
Invalid request - An unsuccessful access token response


post/issuing/access/connect/token
Request samples 
application/x-www-form-urlencoded
grant_type=client_credentials&client_id=ack_clckqmmnyfiupexjew7shh5ahe&client_secret=Pmg36sDWQ9WxtPR3&cardholder_id=crh_d3ozhf43pcq2xbldn2g45qnb44&single_use=true
Response samples 
application/json
{
  • "access_token": "2YotnFZFEjr1zCsicMWpAA",
  • "token_type": "example",
  • "expires_in": 3600,
  • "scope": "issuing:cards-read issuing:cards-write"
}
Transactions
Get a list of transactions
Beta

Returns a list of transactions based on the matching input parameters in reverse chronological order, with the most recent transactions shown first.


SecurityOAuth2: OAuth 
Request 
query Parameters
limit
integer
The maximum number of transactions returned (between 10-100). The default is 10.


 
skip
integer
The number of transactions to skip. The default is 0.


 
cardholder_id
string (IssuingCardholderId)   = 30 characters ^crh_[a-z0-9]{26}$
The cardholder's unique identifier.


 
 Example:  cardholder_id=crh_d3ozhf43pcq2xbldn2g45qnb44
card_id
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The card's unique identifier.


 
 Example:  card_id=crd_fa6psq242dcd6fdn5gifcq1491
entity_id
string (IssuingEntityId)   = 30 characters ^ent_[a-z0-9]{26}$
The entity's unique identifier.


 
 Example:  entity_id=ent_fa6psq242dcd6fdn5gifcq1491
status
string
An optional filter for the transaction lifecycle status.


 Enum: "authorized" "declined" "canceled" "cleared" "refunded" "disputed"  
 Example:  status=disputed
from
string <datetime> 
An optional start date filter for transactions, in ISO 8601 format.


 
 Example:  from=2023-08-15T17:30:09Z
to
string <datetime> 
An optional end date filter for transactions, in ISO 8601 format.


 
 Example:  to=2023-09-15T17:30:09Z
Responses 
200
Transactions returned successfully.


401
Unauthorized.


422
Matching parameters not valid.


429
Too many requests.


get/issuing/transactions
Request samples 
Response samples 
application/json
{
  • "limit": 5,
  • "skip": 10,
  • "total_count": 100,
  • "data": [
    ]
}
Get a single transaction
Beta

Get the details of a transaction using its ID.


SecurityOAuth2: OAuth 
Request 
path Parameters
transactionId
required
string (IssuingTransactionId)   = 30 characters ^trx_[a-z0-9]{26}$
The transaction's unique identifier.


 
 Example:  trx_aayhhfwbdyxwcaeyhhfwbd4xga
Responses 
200
Transaction returned successfully.


401
Unauthorized.


404
Transaction not found.


429
Too many requests.


get/issuing/transactions/{transactionId}
Request samples 
Response samples 
application/json
{
  • "id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
  • "created_on": null,
  • "status": "authorized",
  • "transaction_type": "purchase",
  • "client": {
    },
  • "entity": {
    },
  • "card": {
    },
  • "digital_card": {
    },
  • "cardholder": {
    },
  • "amounts": {
    },
  • "merchant": {
    },
  • "reference_transaction": {
    },
  • "messages": [
    ],
  • "_links": {
    }
}
Card testing
Simulate transactions using a card on the sandbox environment.


Simulate authorization
Simulate an authorization request with a card you issued previously.


Request 
Request Body schema: application/json
required
object (IssuingSimulateCard) 
The card to simulate an authorization with.


 
object (IssuingSimulateTransaction) 
The transaction to simulate with the specified card. For example, a purchase.


 
Responses 
201
Authorization processed successfully


401
Unauthorized


422
Invalid data was sent


500
Internal Server Error


post/issuing/simulate/authorizations
Request samples 
application/json
{
  • "card": {
    },
  • "transaction": {
    }
}
Response samples 
application/json
{
  • "id": "trx_aaqc4uaaybigcaaqc4uaayfiga",
  • "status": "Authorized"
}
Simulate incrementing an authorization
Simulate an incremental authorization request for an existing approved transaction.


Incremental authorizations increase the total authorized amount of the transaction. For example, adding a restaurant bill to an existing hotel booking.


Request 
path Parameters
id
required
string (IssuingTransactionId)   = 30 characters ^trx_[a-z0-9]{26}$
The transaction's unique identifier.


 
 Example:  trx_aayhhfwbdyxwcaeyhhfwbd4xga
Request Body schema: application/json
required
amount
integer  >= 0 
You must provide the amount in the transaction currency's minor currency units.


 
Responses 
201
Authorization processed successfully


401
Unauthorized


404
Authorization not found


422
Invalid data was sent


500
Internal Server Error


post/issuing/simulate/authorizations/{id}/authorizations
Request samples 
application/json
{
  • "amount": 3500
}
Response samples 
application/json
{
  • "status": "Authorized"
}
Simulate clearing
Simulate the clearing of an existing approved authorization.


Request 
path Parameters
id
required
string (IssuingTransactionId)   = 30 characters ^trx_[a-z0-9]{26}$
The transaction's unique identifier.


 
 Example:  trx_aayhhfwbdyxwcaeyhhfwbd4xga
Request Body schema: application/json
required
amount
integer  >= 0 
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.


 
Responses 
202
Presentment accepted


401
Unauthorized


404
Authorization not found


422
Invalid data was sent


500
Internal Server Error


post/issuing/simulate/authorizations/{id}/presentments
Request samples 
application/json
{
  • "amount": 2500
}
Response samples 
application/json
{
  • "request_id": "0HLHPN8802NUF:00000003",
  • "error_type": "request_invalid",
  • "error_codes": [
    ]
}
Simulate refund
Simulate the refund of an existing approved authorization, after it has been cleared.


Request 
path Parameters
id
required
string (IssuingTransactionId)   = 30 characters ^trx_[a-z0-9]{26}$
The transaction's unique identifier.


 
 Example:  trx_aayhhfwbdyxwcaeyhhfwbd4xga
Request Body schema: application/json
required
amount
integer  >= 0 
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 .


 
Responses 
202
Refund accepted


401
Unauthorized


404
Presentment not found


422
Invalid data was sent


500
Internal Server Error


post/issuing/simulate/authorizations/{id}/refunds
Request samples 
application/json
{
  • "amount": 2500
}
Response samples 
application/json
{
  • "request_id": "0HLHPN8802NUF:00000003",
  • "error_type": "request_invalid",
  • "error_codes": [
    ]
}
Simulate reversal
Simulate the reversal of an existing approved authorization.


Request 
path Parameters
id
required
string (IssuingTransactionId)   = 30 characters ^trx_[a-z0-9]{26}$
The transaction's unique identifier.


 
 Example:  trx_aayhhfwbdyxwcaeyhhfwbd4xga
Request Body schema: application/json
required
amount
integer  >= 0 
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.


 
Responses 
201
Reversal processed successfully


401
Unauthorized


404
Authorization not found


422
Invalid data was sent


500
Internal Server Error


post/issuing/simulate/authorizations/{id}/reversals
Request samples 
application/json
{
  • "amount": 2500
}
Response samples 
application/json
{
  • "status": "Reversed"
}
Applicants
Create an applicant
Create and manage identity verification applicants.


Request 
Request Body schema: application/json
external_applicant_id
string
 
email
string <email> 
 
Responses 
201
Applicant successfully created.


400
Bad request.


post/applicants
Request samples 
application/json
{
  • "external_applicant_id": "ext_osdfdfdb4hryu5cei5vwoabrk5k",
  • "email": "david.vincent@courriel.ml"
}
Response samples 
application/json
{}
Retrieve an applicant
Retrieve an identity verification applicant.


Request 
path Parameters
applicant_id
required
string (ApplicantId) ^aplt_\w+$
The unique identifier of the applicant to retrieve.


 
 Example:  aplt_tkoi5db4hryu5cei5vwoabr7we
Responses 
200
Applicant retrieved successfully.


404
Applicant not found.


get/applicants/{applicant_id}
Request samples 
Response samples 
application/json
{}
Update an applicant
Update an identity verification applicant.


Request 
path Parameters
applicant_id
required
string (ApplicantId) ^aplt_\w+$
The unique identifier of the applicant to update.


 
 Example:  aplt_tkoi5db4hryu5cei5vwoabr7we
Request Body schema: application/json
external_applicant_id
string
 
email
string <email> 
 
Responses 
200
Applicant updated successfully.


400
Bad request. One or more input parameters are invalid.


404
Applicant not found.


500
Internal server error.


patch/applicants/{applicant_id}
Request samples 
application/json
{
  • "external_applicant_id": "ext_osdfdfdb4hryu5cei5vwoabrk5k",
  • "email": "david.vincent@courriel.ml"
}
Response samples 
application/json
{}
Anonymize an applicant
Anonymize the personal data of an identity verification applicant.


Request 
path Parameters
applicant_id
required
string
The unique identifier of the applicant to anonymize.


 
Responses 
200
Applicant anonymized successfully.


400
Bad request. The applicant cannot be anonymized.


404
Identity verification not found.


500
Internal server error.


post/applicants/{applicant_id}/anonymize
Request samples 
Response samples 
application/json
{}
Identity verifications
Create and open an identity verification
Beta

Create an identity verification and an initial attempt with a single API call.


If successful, you'll receive a 201 response and the identity verification resource which contains the _links.verification_url.


Request 
Request Body schema: application/json
required
required
object (IdvDeclaredData) 
Identity declared by the user.


 
redirect_url
required
string <uri> 
 
user_journey_id
string^usj_\w+$
User journey's unique identifier.


 
applicant_id
string^aplt_\w+$
The unique identifier of the applicant.


 
object (IdvPhoneNumber) 
Phone number of the user.


 
Responses 
201
Identity verification created.


post/create-and-open-idv
Request samples 
application/json
{}
Response samples 
application/json
{}
Create an identity verification
Beta

Creates an identity verification.


When this request is successful, you'll get a 201 response with the identity verification resource.


Request 
Request Body schema: application/json
required
applicant_id
required
string^aplt_\w+$
The unique identifier of the applicant.


 
required
object (IdvDeclaredData) 
Identity declared by the user.


 
user_journey_id
string^usj_\w+$
User journey's unique identifier.


 
object (IdvPhoneNumber) 
Phone number of the user.


 
Responses 
201
Identity verification created successfully


400
Bad request.


401
Unauthorized


422
Unprocessable entity


500
Internal server error.


503
Service unavailable


post/identity-verifications
Request samples 
application/json
{}
Response samples 
application/json
{}
Retrieve an identity verification
Beta

Retrieves details of an existing identity verification.


Request 
path Parameters
identity_verification_id
required
string (IdvIdentityVerificationId) ^idv_\w+$
The identity verification's unique identifier.


 
 Example:  idv_tkoi5db4hryu5cei5vwoabr7we
Responses 
200
Identity verification retrieved successfully


401
Unauthorized.


500
Internal server error.


503
Service unavailable.


get/identity-verifications/{identity_verification_id}
Request samples 
Response samples 
application/json
{}
Anonymize an identity verification
Beta

Anonymizes the personal data of an identity verification with the specified identifier.


Request 
path Parameters
identity_verification_id
required
string
The identity verification's unique identifier.


 
Responses 
200
Identity verification anonymization requested successfully


401
Unauthorized.


404
Identity verification not found.


422
Unprocessable entity.


500
Internal server error.


503
Service unavailable.


post/identity-verifications/{identity_verification_id}/anonymize
Request samples 
Response samples 
application/json
{}
Create an attempt
Beta

Create a new identity verification attempt.


To create a new attempt, the current identity verification status must be one of the following:


    

  • created
    • 

  • pending
    • 

  • capture_in_progress
    • 

  • retry_required
    • 



Request 
path Parameters
identity_verification_id
required
string
The unique identifier of the identity verification.


 
Request Body schema: application/json
redirect_url
required
string <uri> 
 
object (PhoneNumber) 
A phone number


 
object (ClientInformation) 
Details about the user.


 
Responses 
201
Attempt created.


404
The identity verification ID provided was not valid.


409
The current identity verification status does not allow a new attempt to be created.


To create a new attempt, the current identity verification status must be one of the following:


    

  • created
    • 

  • pending
    • 

  • capture_in_progress
    • 

  • retry_required
    • 



500
An error occurred while retrying the verification.


post/identity-verifications/{identity_verification_id}/attempts
Request samples 
application/json
{}
Response samples 
application/json
{}
List attempts
Beta

This endpoints allows you to fetch all the attempt of a given identity verification


Request 
path Parameters
identity_verification_id
required
string
The unique identifier of the identity verification.


 
Responses 
200
List attempts.


404
The identity verification ID provided was not valid.


500
An error occurred while retrying the attempts.


get/identity-verifications/{identity_verification_id}/attempts
Request samples 
Response samples 
application/json
{}
Retrieve attempt
Beta

Retrieve the details of an identity verification attempt.


Request 
path Parameters
identity_verification_id
required
string
The unique identifier of the identity verification.


 
attempt_id
required
string
The unique identifier of the identity verification attempt.


 
Responses 
200
Attempt retrieved successfully.


404
The identity verification or attempt ID provided was not valid.


500
An error occurred while retrying the attempt.


get/identity-verifications/{identity_verification_id}/attempts/{attempt_id}
Request samples 
Response samples 
application/json
{
  • "id": "iatp_tkoi5db4hryu5cei5vwoabrPoQ",
  • "created_on": "2017-07-21T17:32:28Z",
  • "modified_on": "2017-07-21T17:40:32Z",
  • "phone_number": {
    },
  • "redirect_url": "https://myweb.site?query-param=hello",
  • "status": "capture_in_progress",
  • "client information": {
    },
  • "applicant_session_information": {
    },
  • "response_codes": [ ],
  • "_links": {}
}
Retrieve PDF report of an identity verification
Beta

Retrieves a PDF report with all the identity verification details.


Please note that this report is only available for verifications in statuses
declined and approved once you receive the report_created event.


Request 
path Parameters
identity_verification_id
required
string
The identity verification's unique identifier.


 
Responses 
200
PDF retrieved successfully


404
PDF unavailable.


500
Internal server error.


503
Service unavailable.


get/identity-verifications/{identity_verification_id}/pdf-report
Request samples 
Response samples 
application/json
{}
AML verifications
Create an AML verification
Beta

 Creates an Anti-Money Laundering (AML) verification.


If the request is successful, you'll receive a 201 response with the AML verification resource.


Request 
Request Body schema: application/json
required
applicant_id
required
string^aplt_\w+$
The unique identifier of the applicant.


 
required
object (SearchParameters) 
The ComplyAdvantage search inputs.


 
monitored
boolean
 
Responses 
201
AML verification created.


post/aml-verifications
Request samples 
application/json
{
  • "search_parameters": {
    },
  • "monitored": true
}
Response samples 
application/json
{}
Retrieve an AML verification
Retrieve detailed results of an Anti-Money Laundering verification.


Request 
path Parameters
aml_verification_id
required
string (AmlVerificationId) ^amlv_\w+$
The unique identifier of the AML verification.


 
 Example:  amlv_tkoi5db4hryu5cei5vwoabr7we
Responses 
200
AML verification retrieved.


get/aml-verifications/{aml_verification_id}
Request samples 
Response samples 
application/json
{}
Reports
Retrieve your reconciliation reports programmatically with the Reports API.


Get all reports
Returns the list of reports and their details.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
query Parameters
created_after
string <date-time> 
Filters reports to those that were created on or after the specified timestamp.


 
 Example:  created_after=2022-02-17T00:00:00
created_before
string <date-time> 
Filters reports to those that were created before the specified timestamp.


 
 Example:  created_before=2022-02-19T00:00:00
entity_id
string^(ent)_(\w{26})$
Filters reports to those that match the specified client entity ID. Sub-entity IDs are not supported.


 
 Example:  entity_id=ent_znj4ih5kn4fuxiaquoudv5mvwy
limit
integer <int32>   [ 1 .. 100 ] 
 Default:  100
The number of results you want to retrieve per page. 
 For example, if the total result count is 50 and you use limit=10, you will need to iterate over 5 pages containing 10 elements each to be able to retrieve all of the reports that match your query.


 
 Example:  limit=5
pagination_token
string
A token used for pagination when a response contains results across multiple pages.


 
Responses 
200
Reports retrieved succesfully


401
Unauthorized. Likely cause is that access token is not valid or was not specified.


422
Unprocessable entity


get/reports
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-go
import (
	"github.com/checkout/checkout-sdk-go"
	"github.com/checkout/checkout-sdk-go/configuration"
	"github.com/checkout/checkout-sdk-go/reports"
)

// API Keys
api, err := checkout.
			Builder().
			StaticKeys().
			WithSecretKey("secret_key").
			WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
			Build()
if err != nil {
	return nil, err
}

// OAuth
api, err := checkout.
			Builder().
			OAuth().
			WithClientCredentials("client_id", "client_secret").
			WithScopes([]string{configuration.Reports}).
			WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
			Build()
if err != nil {
	return nil, err
}

query := reports.QueryFilter{
	CreatedAfter:  time.Parse("2006-01-02", time.Now().AddDate(0, 0, -10).Format("2006-01-02")),
	CreatedBefore: time.Parse("2006-01-02", time.Now().Format("2006-01-02")),
	EntityId:      "entity_id",
	Limit:         20,
}

response, err := api.Reports.GetAllReports(query)
if err != nil {
	return nil, err
}

return response, nil
Response samples 
application/json
{}
Get report details
Use this endpoint to retrieve a specific report using its ID.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
id
required
string^(rpt)_(\w{26})$
The ID of the report to retrieve.


 
 Example:  rpt_lmmldzousk7etoqijqundqexa4
Responses 
200
Report details retrieved succesfully


401
Unauthorized. Likely causes include an invalid or unspecified access token.


404
No report with the specified ID was found.


get/reports/{id}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-go
import (
	"github.com/checkout/checkout-sdk-go"
	"github.com/checkout/checkout-sdk-go/configuration"
)

// API Keys
api, err := checkout.
			Builder().
			StaticKeys().
			WithSecretKey("secret_key").
			WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
			Build()
if err != nil {
	return nil, err
}

// OAuth
api, err := checkout.
			Builder().
			OAuth().
			WithClientCredentials("client_id", "client_secret").
			WithScopes([]string{configuration.Reports}).
			WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
			Build()
if err != nil {
	return nil, err
}

response, err := api.Reports.GetReportDetails("report_id")
if err != nil {
	return nil, err
}

return response, nil
Response samples 
application/json
{}
Get report file
Use this endpoint to retrieve a specific file from a given report using their respective IDs.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
id
required
string^(rpt)_(\w{26})$
The ID of the report that the file belongs to.


 
 Example:  rpt_lmmldzousk7etoqijqundqexa4
fileId
required
string^(file)_(\w{26})$
The ID of the file to retrieve.


 
 Example:  file_7ysmgfkj4ipunduud22uf73iey
Responses 
302
Redirect to the report file download location.


401
Unauthorized. Likely causes include an invalid or unspecified access token.


404
No report with the specified ID was found.


get/reports/{id}/files/{fileId}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-go
import (
	"github.com/checkout/checkout-sdk-go"
	"github.com/checkout/checkout-sdk-go/configuration"
)

// API Keys
api, err := checkout.
			Builder().
			StaticKeys().
			WithSecretKey("secret_key").
			WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
			Build()
if err != nil {
	return nil, err
}

// OAuth
api, err := checkout.
			Builder().
			OAuth().
			WithClientCredentials("client_id", "client_secret").
			WithScopes([]string{configuration.Reports}).
			WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
			Build()
if err != nil {
	return nil, err
}

response, err := api.Reports.GetReportFile("report_id", "file_id")
if err != nil {
	return nil, err
}

return response, nil
Response samples 
application/json
{
  • "request_id": "0HMJGFVAQ35TL:00000117",
  • "error_type": "not_found",
  • "error_codes": [
    ]
}
Financial actions
Returns all the processed financial actions associated with your given filter. The results are ordered by processing date in descending order (latest first).


Get financial actions
Returns the list of financial actions and their details.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
query Parameters
payment_id
string
The ID of the payment you want to retrieve financial actions for. Required if action_id or reference are not used.


 
 Example:  payment_id=pay_qqufsd3rfnqufngwklghlxrzpm
action_id
string
The ID of the action you want to retrieve financial actions for. Required if payment_id or reference are not used.


 
 Example:  action_id=act_wsnyzbzmr2huxcekoj7qqhxwuy
reference
string
An optional ID you submit in the gateway request to retrieve financial actions for. Required if payment_id or action_id are not used.


 
 Example:  reference=8f13507d-60e1-455d-b700-4f1b39a35e23
limit
integer <int32>   [ 1 .. 100 ] 
 Default:  100
The number of results to retrieve per page. 
 For example, if the total result count is 50, and you use limit=10, you will need to iterate over 5 pages containing 10 results each to retrieve all of the reports that match your query.


 
 Example:  limit=5
pagination_token
string
A token used for pagination when a response contains results across multiple pages.


 
Responses 
200
Financial actions retrieved successfully


401
Unauthorized. Likely cause is that access token is not valid or was not specified.


422
Unprocessable entity


get/financial-actions
Request samples 
curl -i -X GET \
'https://api.sandbox.checkout.com/financial-actions?payment_id=pay_qqufsd3rfnqufngwklghlxrzpm&limit=5' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Response samples 
application/json
{
  • "count": 1,
  • "limit": 5,
  • "data": [
    ],
  • "_links": {}
}
Card metadata
Get card metadata
Beta

Returns a single metadata record for the card specified by the Primary Account Number (PAN), Bank Identification Number (BIN), token, or instrument supplied.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
Request Body schema: application/json
object (CardMetadataRequestSource) 
The source object


 
format
string
 Default:  "basic"
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.


 Enum: "basic" "card_payouts"  
Responses 
200
Metadata for the card number, BIN, token, or instrument ID provided


401
Unauthorized


404
Card Metadata not found


415
Unsupported Media Type


422
Invalid data was sent


500
Internal Server Error


502
Bad Gateway


504
Gateway Timeout


post/metadata/card
Request samples 
application/json
{
  • "source": {
    },
  • "format": "basic"
}
Response samples 
application/json
{
  • "bin": "45434720",
  • "scheme": "visa",
  • "local_schemes": [
    ],
  • "card_type": "CREDIT",
  • "card_category": "CONSUMER",
  • "currency": "MUR",
  • "issuer": "STATE BANK OF MAURITIUS",
  • "issuer_country": "MU",
  • "issuer_country_name": "Mauritius",
  • "product_id": "F",
  • "product_type": "Visa Classic",
  • "subproduct_id": "VA",
  • "regulated_indicator": false
}
Network Tokens
Provision network tokens and cryptograms.


Provision a Network Token
Beta
 Provisions a network token synchronously. If the merchant stores their cards with Checkout.com, then source ID can be used to request a network token for the given card. If the merchant does not store their cards with Checkout.com, then card details have to be provided.


SecurityOAuth2: OAuth 
Request 
Request Body schema: application/json
required
object (NetworkTokensRequestSource) 
The source object


 
Responses 
200
Responding with existing network token


201
Network token provisioned


401
Unauthorized


403
Forbidden


415
Unsupported Media Type


422
Invalid data was sent


500
Internal Server Error


502
Bad Gateway


504
Gateway Timeout


post/network-tokens
Request samples 
application/json
{
  • "source": {
    }
}
Response samples 
application/json
{}
Get Network Token
Beta
 Given network token ID, this endpoint returns network token details: DPAN, expiry date, state, TRID and also card 
details like last four and expiry date.


SecurityOAuth2: OAuth 
Request 
path Parameters
network_token_id
required
string
Unique token ID assigned by Checkout.com for each token


 
 Example:  nt_xgu3isllqfyu7ktpk5z2yxbwna
Responses 
200
Network Token details


401
Unauthorized


403
Forbidden


404
Network Token not found


500
Internal Server Error


502
Bad Gateway


504
Gateway Timeout


get/network-tokens/{id}
Request samples 
Response samples 
application/json
{}
Request a cryptogram
Beta

Using network token ID as an input, this endpoint returns token cryptogram.


SecurityOAuth2: OAuth 
Request 
path Parameters
network_token_id
required
string
Unique token ID assigned by Checkout.com for each token


 
 Example:  nt_xgu3isllqfyu7ktpk5z2yxbwna
Request Body schema: application/json
transaction_type
required
string
Transaction type the cryptogram is requested for.


 Enum: "ecom" "recurring" "pos" "aft"  
Responses 
201
Cryptogram from the network token


401
Unauthorized


403
Forbidden


404
Network Token not found


422
Invalid data was sent


500
Internal Server Error


502
Bad Gateway


504
Gateway Timeout


post/network-tokens/{id}/cryptograms
Request samples 
application/json
{
  • "transaction_type": "ecom"
}
Response samples 
application/json
{}
Permanently deletes a network token
Beta
 This endpoint is for permanently deleting a network token.  A network token should be deleted when a payment instrument it is associated with is removed from file or if the security of the token has been compromised.


SecurityOAuth2: OAuth 
Request 
path Parameters
network_token_id
required
string
Unique token ID assigned by Checkout.com for each token


 
 Example:  nt_xgu3isllqfyu7ktpk5z2yxbwna
Request Body schema: application/json
initiated_by
required
string
Who initiated/requested the deletion of the token.


 Enum: "cardholder" "token_requestor"  
reason
required
string
The reason for deleting the token.


 Enum: "fraud" "other"  
Responses 
204
Ok


400
Bad Request


401
Unauthorized


403
Forbidden


404
Network token not found


422
Invalid data was sent


500
Internal Server Error


502
Bad Gateway. Error from scheme


504
Timeout while waiting for a scheme response


patch/network-tokens/{id}/delete
Request samples 
application/json
{
  • "initiated_by": "token_requestor",
  • "reason": "other"
}
Response samples 
application/json
{
  • "request_id": "0HL80RJLS76I7",
  • "error_type": "request_invalid",
  • "error_codes": [
    ]
}