Configure authorization relay

Last updated: February 26, 2025

The authorization relay service gives you complete control over whether to accept or decline incoming authorization requests for your cardholders' transactions.

This enables you to do the following:

Make decisions based on your own business and fraud logic.
Perform additional third-party checks before making decisions.
Manage ledgers.
Receive authorization details in real time.

If you do not enable this service, Checkout.com remains responsible for approving or declining authorization requests.

When a cardholder uses their issued card to make a payment, the card scheme initiates an authorization request and sends it to Checkout.com's Card Issuing service.
We send a message containing information about the authorization request to your client-side authorization relay service with an HTTPS request.
You validate the authorization request’s authenticity, and process the message payload.
Decide to approve or decline the authorization, and respond to Checkout.com with your decision within the timeout limit, or the authorization is automatically declined.
We forward your authorization response to the merchant or acquirer.

The flow of the authorization relay service is as follows:

Information

No authorization requests are relayed for the following types of transaction:

Account-status inquiry
PIN change
PIN unblock

To configure authorization relay service in the Dashboard, ensure you have one of the following user roles:

The Admin or Developer user role
A custom role with the Edit Issuing authorization relay settings permission

Expose a new endpoint on your API that our Card Issuing service can call to relay your authorization requests. The endpoint must be configured to:

Accept JSON input.
Have an open TCP port for HTTPS traffic on port 443, or a custom port of your choice.
Be idempotent so that, if Checkout.com relays the same request multiple times due to network failures or timeouts, your endpoint uses the IDs provided to avoid duplicate responses.
Handle HMAC format.

Hash-based message authentication code (HMAC, or hash) provides a client-server pair with a private secret key known only to that pair.

For each authorization request, Checkout.com generates a unique HMAC signature, using the SHA-256 algorithm and the secret key. In the request header, we hash the HTTP request data and all the information you need to validate the header value. We then send it to the server, where you decode the message using your key.

Information

We recommend that you first configure and test the authorization relay service in your sandbox environment. When the service is working as expected, you can configure it in your live environment.

Sign in to the Dashboard.
Go to Developers > Authorization relay, and then select Configure.
In the Configure authorization relay page that opens, enter your endpoint URL and select Confirm.
Copy the App ID and Secret API key that are generated, and ensure they're on your clipboard.
Caution: For security reasons, the secret API key is never shown again.
Select Done.
In the Authorization relay page that opens, add the keys to your code.
Enable the authorization relay (disabled by default) using the toggle.

You can configure and test the authorization relay in the sandbox environment.

For instructions, see Simulate an authorization.

Information

To configure any of the following advanced settings, contact your Account Manager.

Specify the time limit for your server to respond to authorization requests before they are automatically declined.
Format – Milliseconds
Default – 2000
Maximum value – 2500

You can increase the timeout limit above the usual maximum value while testing in the sandbox environment. When you go live, your configured limit applies.

Have Checkout.com specify in each request header the User-Agent – Our Card Issuing service CKO-Issuing.

To maintain service availability and business continuity if your server is down or fails to respond within the timeout limit, you can use stand-in mode to respond in the meantime.

You can configure stand-in mode to automatically approve either all authorizations, or only up to a specified limit. If you set a limit, this is reset when your server starts responding again and has approved at least one transaction.

You receive information about transactions handled by stand-in mode in the webhook notifications.

If you use the authorization relay for ledger management, ensure that enabling stand-in mode is within your risk margin and financial exposure limits. Use the webhook notifications to update the ledger for transactions approved by stand-in mode.

Information

To enable stand-in mode, contact your Account Manager or [email protected].

Use your secret API key to validate the HMAC signature in the authorization request header, which has the following format:

Authorization: <scheme> <authorization-parameters>

Field name	Description
`<scheme>` string	The format of the header. This value is always `HMAC`.
`<authorization-parameters>` string	A colon-delimited field with the following format: `{AppId}:{RequestSignatureBase64}:{Nonce}:{RequestTimeStamp}`
`{AppId}` string	The app identifier you copied from the Dashboard.
`{RequestSignatureBase64}` Base64	The request signature.
`{Nonce}` integer	A random number generated per request. Format – UUID
`{RequestTimeStamp}` string	The timestamp for the request. Format – UNIX timestamp

To get the signature you need to calculate the final value of RequestSignatureBase64, concatenate the following values in this exact order:
a. App ID
b. HTTP method
c. Request absolute URI, as a URL-encoded, lower-case string representation
d. Request timestamp
e. Nonce
f. Standard Base64 string representation of the HTTP request content, hashed using SHA-1
Retrieve your secret API key bytes using UTF8 encoding.
Hash the signature's bytes using the HMAC SHA-256 algorithm and your secret API Key.
Convert the result to a standard Base64 string, which is the RequestSignatureBase64 value from the authorization header.

The relay message Checkout.com sends to your endpoint contains the following:

Field name Description

Field name	Description
`cko-correlation-id` string	Checkout.com's unique correlation identifier. Use this as a reference for the authorization request if contacting your Account Manager.
`User-Agent` string optional	The user agent for the request. This value is always `CKO-Issuing`.

cko-correlation-id

string

Checkout.com's unique correlation identifier.

Use this as a reference for the authorization request if contacting your Account Manager.

User-Agent

string

optional

The user agent for the request.

This value is always CKO-Issuing.

Field Description

Field	Description
`address_verification` string	The Address Verification Service (AVS) information, which can be any combination of the following values: Address Postal code Address verification result: `no_match` `postal_code_match`
`authorization_type` enum	The authorization type. This can be one of: `authorization` `deferred_authorization` `final_authorization` `incremental_pre_authorization` `pre_authorization`
`billing_amount` uint64	The authorization's billing amount, in the minor currency unit. Currency conversion, if required, is based on current Mastercard rates.
`billing_conversion_rate` double	The Mastercard conversion rate used to convert the transaction amount to the billing amount.
`billing_currency` string	The currency for billing the cardholder. Format – ISO 4217 code
`card_id` string	The unique identifier for the card used for the transaction.
`cardholder_id` string	The unique identifier for the cardholder.
`client` object	Contains information about you from the card scheme.
`client.id` string	Your unique identifier as a Checkout.com client.
`digital_card` object	Contains information about the digital card used for the transaction.
`digital_card.id` string	The unique identifier for the digital card.
`digital_card.wallet_type` string optional	The type of wallet. This can be one of: `applepay` `googlepay` `other` `remote_commerce_programs`
`digital_card.device_type` string optional	The type of device the cardholder used to initiate the transaction. This can be one of: `card` `other` `pc` `phone` `tablet` `vehicle` `wearable`
`ecb_conversion_rate` double	The European Central Bank (ECB) comparative rate that is communicated to the cardholder if currency conversion is required.
`entity` object	Contains information about your entity from the card scheme.
`entity.id` string	The unique identifier for your Checkout.com entity.
`id` string	The card scheme's unique identifier for the authorization request. Format – 30-character alphanumeric string
`merchant` object	Contains information about the merchant.
`merchant.name` string	The merchant's company name.
`merchant.city` string	The city where the merchant is located.
`merchant.country` string	The country where the merchant is located. Format – ISO-3 country code
`merchant.state` string	For US merchants, the state where they are located. For merchants not located in the US, this value is `null`.
`merchant.category_code` string	The merchant's four-digit category code (MCC). Merchants can have multiple category codes. For example, "0763, 0780".
`merchant.merchant_id` string	The unique identifier for the merchant at the point of interaction. This may vary per acquirer.
`point_of_sale_transaction_date` string	The transaction date when the customer used the card at the point of sale (PoS).
`pos` object	Contains information about the conditions at the point of sale at the time of the transaction.
`pos.country_code` string	The country where the point of sale (PoS) is located. Format – ISO-3 country code
`pos.postal_code` string	The postal code where the PoS is located.
`pos.card_present` string	Indicates if the card was present to initiate the transaction. This can be one of: `not_present` `present` `unspecified`
`pos.cardholder_present` string	Indicates if the cardholder was present to initiate the transaction. This can be one of: `not_present` `present` `unspecified`
`pos.entry_mode` string	The way the card initiated the transaction at the PoS terminal. This can be one of: `contact_chip` `contactless_chip` `contactless_magstripe` `ecommerce` `magstripe` `manual` `optical_character_recognition` `optical_code` `server` `other`
`three_d_secure` object	Contains information about 3D Secure (3DS).
`three_d_secure.` `requested_exemption_or_exclusion` string	The exemption or exclusion from Strong Customer Authentication (SCA). This can be one of: `acquirer_transaction_risk_analysis` `authentication_outage_exception` `low_value_payment` `merchant_initiated_transaction` `other` `recurring_payment` `secure_corporate_payment` `strong_customer_authentication_delegation` For definitions, see Possible SCA exemptions.
`three_d_secure.` `sca_not_required_reason` string	The reason for not requiring Strong Customer Authentication. This can be one of: `acquirer_transaction_risk_analysis` `authentication_outage_exception` `issuer_secure_corporate_payment` `low_value_payment` `mail_order_telephone_order` `merchant_initiated_transaction` `one_leg_out` `other` `recurring_payment` `secure_corporate_payment` `strong_customer_authentication_delegation` `zero_amount_asi`
`transaction_amount` uint64	The transaction amount, in the minor currency unit.
`transaction_currency` string	The acquirer's local currency or the local currency where the transaction took place. Format – ISO 4217 code
`transaction_id` string	The unique identifier for the transaction, which links together all related authorization, reversal, and clearing messages.
`transaction_type` enum	The transaction type. This can be one of: `balance_inquiry` – An inquiry by the cardholder about the available balance on the card `cashback` – A cashback transaction `purchase` – A payment for a purchase `refund` – A full or partial refund for a purchase `remittance_funding` – An amount sent to a third party, usually in another country `withdrawal` – A withdrawal of funds from the card
`transmission_date_time` datetime	The date and time when the authorization request was entered into the card scheme network in UTC. Format – ISO 8601 Example – `yyyy-mm-ddThh:mm:ss.sss`
`transit_information` string	The information used to identify transit card transactions. Example – Transaction type or transportation type

address_verification

string

The Address Verification Service (AVS) information, which can be any combination of the following values:

Address
Postal code
Address verification result:
- no_match
- postal_code_match

authorization_type

enum

The authorization type. This can be one of:

authorization
deferred_authorization
final_authorization
incremental_pre_authorization
pre_authorization

billing_amount

uint64

The authorization's billing amount, in the minor currency unit.

Currency conversion, if required, is based on current Mastercard rates.

billing_conversion_rate

double

The Mastercard conversion rate used to convert the transaction amount to the billing amount.

billing_currency

string

The currency for billing the cardholder.
Format – ISO 4217 code

card_id

string

The unique identifier for the card used for the transaction.

cardholder_id

string

The unique identifier for the cardholder.

client

object

Contains information about you from the card scheme.

client.id

string

Your unique identifier as a Checkout.com client.

digital_card

object

Contains information about the digital card used for the transaction.

digital_card.id

string

The unique identifier for the digital card.

digital_card.wallet_type

string

optional

The type of wallet. This can be one of:

applepay
googlepay
other
remote_commerce_programs

digital_card.device_type

string

optional

The type of device the cardholder used to initiate the transaction. This can be one of:

card
other
pc
phone
tablet
vehicle
wearable

ecb_conversion_rate

double

The European Central Bank (ECB) comparative rate that is communicated to the cardholder if currency conversion is required.

entity

object

Contains information about your entity from the card scheme.

entity.id

string

The unique identifier for your Checkout.com entity.

id

string

The card scheme's unique identifier for the authorization request.
Format – 30-character alphanumeric string

merchant

object

Contains information about the merchant.

merchant.name

string

The merchant's company name.

merchant.city

string

The city where the merchant is located.

merchant.country

string

The country where the merchant is located.
Format – ISO-3 country code

merchant.state

string

For US merchants, the state where they are located.

For merchants not located in the US, this value is null.

merchant.category_code

string

The merchant's four-digit category code (MCC).

Merchants can have multiple category codes. For example, "0763, 0780".

merchant.merchant_id

string

The unique identifier for the merchant at the point of interaction.

This may vary per acquirer.

point_of_sale_transaction_date

string

The transaction date when the customer used the card at the point of sale (PoS).

pos

object

Contains information about the conditions at the point of sale at the time of the transaction.

pos.country_code

string

The country where the point of sale (PoS) is located.
Format – ISO-3 country code

pos.postal_code

string

The postal code where the PoS is located.

pos.card_present

string

Indicates if the card was present to initiate the transaction. This can be one of:

not_present
present
unspecified

pos.cardholder_present

string

Indicates if the cardholder was present to initiate the transaction. This can be one of:

not_present
present
unspecified

pos.entry_mode

string

The way the card initiated the transaction at the PoS terminal. This can be one of:

contact_chip
contactless_chip
contactless_magstripe
ecommerce
magstripe
manual
optical_character_recognition
optical_code
server
other

three_d_secure

object

Contains information about 3D Secure (3DS).

three_d_secure.
requested_exemption_or_exclusion

string

The exemption or exclusion from Strong Customer Authentication (SCA). This can be one of:

acquirer_transaction_risk_analysis
authentication_outage_exception
low_value_payment
merchant_initiated_transaction
other
recurring_payment
secure_corporate_payment
strong_customer_authentication_delegation

For definitions, see Possible SCA exemptions.

three_d_secure.
sca_not_required_reason

string

The reason for not requiring Strong Customer Authentication. This can be one of:

acquirer_transaction_risk_analysis
authentication_outage_exception
issuer_secure_corporate_payment
low_value_payment
mail_order_telephone_order
merchant_initiated_transaction
one_leg_out
other
recurring_payment
secure_corporate_payment
strong_customer_authentication_delegation
zero_amount_asi

transaction_amount

uint64

The transaction amount, in the minor currency unit.

transaction_currency

string

The acquirer's local currency or the local currency where the transaction took place.
Format – ISO 4217 code

transaction_id

string

The unique identifier for the transaction, which links together all related authorization, reversal, and clearing messages.

transaction_type

enum

The transaction type. This can be one of:

balance_inquiry – An inquiry by the cardholder about the available balance on the card
cashback – A cashback transaction
purchase – A payment for a purchase
refund – A full or partial refund for a purchase
remittance_funding – An amount sent to a third party, usually in another country
withdrawal – A withdrawal of funds from the card

transmission_date_time

datetime

The date and time when the authorization request was entered into the card scheme network in UTC.
Format – ISO 8601
Example – yyyy-mm-ddThh:mm:ss.sss

transit_information

string

The information used to identify transit card transactions.
Example – Transaction type or transportation type


1{
2  "id": "msg_aayaps43eoaweagmyhzomsfada",
3  "card_id": "crd_eejbb5ohopoehdd7tevu7bxg3i",
4  "cardholder_id": "crh_urdihafyo75evcr55s62jmwwhy",
5  "transaction_id": "trx_zupv6ou4tyfevapshlrpwd5nb4",
6  "entity":{
7    "id": "ent_urdihafyo75evcr55s62jmwwhy"
8  },
9  "client":{
10    "id": "cli_urdihafyo75evcr55s62jmwwhy"
11  },
12  "transaction_type": "Purchase",
13  "transaction_amount": 100,
14  "transaction_currency": "GBP",
15  "billing_amount": 90,
16  "billing_currency": "EUR",
17  "billing_conversion_rate": 0.9,
18  "transmission_date_time": "2020-01-01T16:51:47Z",
19  "ecb_conversion_rate": 0.34,
20  "digital_card": {
21    "id": "dcr_urdihafyo75evcr55s62jmwwhy",
22    "device_type": "phone",
23    "wallet_type": "applepay"
24  },
25  "pos": {
26    "country_code": "GBR",
27    "postal_code": "SE100ER",
28    "card_present": "present",
29    "cardholder_present": "not_present",
30    "entry_mode": "ecommerce"
31  },
32  "merchant": {
33    "name": "Software Company",
34    "city": "London",
35    "state": "",
36    "country": "GBR",
37    "category_code": "5734",
38    "merchant_id": "031860687",
39    "street_address": "261 Example Street"
40  },
41  "three_d_secure": {
42    "requested_exemption_or_exclusion": "recurring_payment",
43    "sca_not_required_reason": "recurring_payment"
44  },
45  "authorization_type": "final_authorization",
46  "address_verification": {
47    "address": "West Street",
48    "postal_code": "90150",
49    "address_verification_result": "no_match"
50  },
51
52  "transit_information": {
53    "transaction_type": "authorized_aggregated_split_clearing",
54    "transportation_mode": "urban_bus"
55  },
56  "point_of_sale_transaction_date": "2023-04-25"
57}

When you receive an authorization request, you must respond to approve or decline it within the timeout limit.

If you don't respond within the timeout limit, the authorization is automatically declined. To change this behavior, configure stand-in mode with your own business logic.

If the request times out or you receive an error response code from Checkout.com, the authorization is automatically declined.

Your response must contain a relevant HTTP response code and response body:

HTTP code	Description
`200`	You have all the data you need to provide a decision about the authorization.
`4XX`	You cannot provide a decision because you do not have the required data from Checkout.com.
`5XX`	You cannot provide a decision because of an issue at your end. For example, a server error.

To approve an authorization, respond with an HTTP 200 OK response code and set the approved field to true.


1{
2  "approved": true,
3  "address_verification_result" : "PostalCodeAndAddressMatch"
4}

Field	Description
`approved` boolean required	Your decision on the authorization request. Set to `true`.
`address_verification_result` enum optional	The result of the Address Verification Service (AVS) check. Set to one of the following values: `AddressMatch` `PostalCodeAndAddressMatch` `PostalCodeMatch` `NoMatch`
`balance_amount` uint64 optional	The available balance on the card, in the minor currency unit.
`balance_currency` string optional	The currency for the available balance on the card. Format – ISO 4217 code
`metadata` key/value pair optional	Contains any additional information.

To decline an authorization, respond with an HTTP 200 OK response code and and set the approved field to false.


1{
2  "approved": false,
3  "reason_code": "InsufficientFunds",
4  "address_verification_result" : "NoMatch",
5  "metadata": [{"reference": "xYhUq"}]
6}

Field Description

Field	Description
`approved` boolean required	Your decision on the authorization request. Set to `false`.
`address_verification_result` enum optional	The result of the Address Verification Service (AVS) check. Set to one of the following values: `AddressMatch` `PostalCodeAndAddressMatch` `PostalCodeMatch` `NoMatch`
`metadata` key/value pair optional	Contains any additional information.
`reason_code` enum optional	The reason for declining the transaction. This can be one of: `FailedControl` `InsufficientFunds` `Other` If you provide an invalid value or no value, Checkout.com returns to the card scheme the default scheme reason code `Do Not Honour (05)`.

approved

boolean

required

Your decision on the authorization request.
Set to false.

address_verification_result

enum

optional

The result of the Address Verification Service (AVS) check.
Set to one of the following values:

AddressMatch
PostalCodeAndAddressMatch
PostalCodeMatch
NoMatch

metadata

key/value pair

optional

Contains any additional information.

reason_code

enum

optional

The reason for declining the transaction. This can be one of:

FailedControl
InsufficientFunds
Other

If you provide an invalid value or no value, Checkout.com returns to the card scheme the default scheme reason code Do Not Honour (05).

If you've configured your webhook receiver, you receive the following notifications for relayed authorizations handled by your server or stand-in mode:

authorization_approved – See the authorization_relay object.
authorization_declined – See the authorization_relay object.

Note

When you generate a new key, the authorization relay service is disabled. This ensures that authorizations are not automatically declined while you're implementing new keys. Until you re-enable the service, Checkout.com decides whether to approve or decline authorizations.

Sign in to the Dashboard.
Go to Developers > Authorization relay, and select Replace keys.
In the Generate replacement keys popup that opens, select the key you want to replace, and then select Generate new keys.
Copy the App ID and Secret API key that are generated – ensure they are on your clipboard – and select Done.
For security reasons, the secret API key is never shown again.
In the Authorization relay page that opens, add the keys to your code.
Re-enable the authorization relay using the toggle.

Configure authorization relay

How it works

Information

Before you begin

Hash-based message authentication code

Configure the authorization relay

Information

Testing

Advanced settings

Information

Request timeout before decline

User agent in headers

Configure stand-in mode

Information

Receive authorization requests

1. Validate the HMAC header value

2. Calculate the RequestSignatureBase64 value

Relayed message format

Additional headers

Body

Relayed message example

Respond to authorization requests

Approve an authorization

Approval example

Response fields

Decline an authorization

Decline example

Response fields

Authorization webhook notifications

Update your API key

Note