Relay authorization requests
Beta
Last updated: June 7, 2023
You can respond to incoming authorization requests from your cardholders using the authorization relay service.
This gives you full control over whether to accept or decline any given request, and makes it easier to manage your cardholders’ balances on your end.
When a cardholder uses their card to make a payment, an authorization request is initiated and forwarded to our Issuing service.
A message containing information about the authorization request is then relayed to the client-side authorization relay service with an HTTPS request.
You can then approve or decline the transaction by responding to the request. If no response is received within 2000 milliseconds, the request times out and the transaction is automatically declined.

Before you can receive authorization relay messages, you will need to expose a new endpoint on your API that our Issuing service will call when relay an authorization to you. The endpoint must be configured in such a way that it:
- Can receive a JSON object
- Can handle hash-based message authentication code (HMAC)
- Has an open TCP port for HTTPS traffic on port 443, or on another custom port of your choice
- Is idempotent
Information
Hash-based message authentication code (HMAC) provides a server and a client with a private secret key known only to that specific server and that client. The request initiator creates a unique HMAC, or hash, per request to the server by hashing the request data with the private keys and sending it as part of a request in a header.
You, acting as the server, must generate 2 keys and share them once with Checkout.com, the client, so that we can initiate requests. These keys are:
- the app ID: a UUID shared using a secure channel - for example, through email
- an API Key: a 256-bit key generated using a Symmetric Key Cryptographic Algorithm, exchanged secretly and securely
To allow you to authenticate incoming requests, we will generate a unique HMAC signature using the SHA-256 algorithm, containing the HTTP request data and all the information required for you to validate the header value.
The HMAC signature is sent in the authorization header in the following format:
Authorization: <scheme> <authorization-parameters>
The <scheme>
value is always HMAC, while the <authorization-parameters>
value is a colon-delimited field with the following format:
{AppId}:{RequestSignatureBase64}:{Nonce}:{RequestTimeStamp}
{AppId}
: the UUID that you provided to Checkout.com{RequestSignatureBase64}
: the request's signature, in Base64 format{Nonce}
: a random number generated per request, using a UUID{RequestTimeStamp}
: the request's timestamp, in UNIX time
The signature used to calculate the final value of RequestSignatureBase64
is obtained by concatenating the following values, in this exact order:
- App ID
- HTTP method
- Request absolute URI, as a URL-encoded, lower case string representation
- Request timestamp
- Nonce
- Standard Base64 string representation of the HTTP request content, hashed using SHA-1
Lastly, hash the signature's bytes using the HMAC SHA-256 algorithm and the API Key and convert the result to a standard Base64 string.
Note
The API Key bytes should be retrieved using UTF8 encoding.
The resulting RequestSignatureBase64
value is included in the authorization parameter, as described previously:
{AppId}:{RequestSignatureBase64}:{Nonce}:{RequestTimeStamp}
The message sent to the client endpoint from the relay service contains the following:
cko-correlation-id
: contains the Checkout.com correlation IDUser-Agent
: contains the valueCKO-Issuing
Field | Description |
---|---|
| The address verification information in the authorization request, including any combination of the following values:
|
enum | The authorization type, as one of the following values:
|
uint64 | The authorization's billing amount, in minor currency units. In case of a currency conversion, this will be based on Mastercard rates. See our documentation on calculating currency values for more information. |
double | The scheme conversion rate used to convert the transaction amount to the billing amount. |
string | The currency in which the issuer will bill the cardholder, as an ISO 4217 code. |
string | The unique ID of the card, as stored by Checkout.com. |
string | The unique ID of the cardholder, as stored by Checkout.com. |
double | The European Central Bank (ECB) comparative rate that will be communicated to the cardholder in case of a currency conversion. |
| The fees information received in the authorization request, including any combination of the following values:
|
| An object containing merchant information, including:
|
string | The unique 19-digit ID of the message received from the scheme. |
string | The transaction date when the customer used the card at the point of sale. |
enum | The requested exemption, as one of the following values:
|
uint64 | The authorization's transaction amount, in minor currency units. See our documentation on calculating currency values for more details. |
string | The acquirer’s local currency, or the local currency of the transaction’s source location, as an ISO 4217 code. |
string | The ID of the transaction, which links together all related authorization, reversal, and clearing messages. |
enum | The transaction type, as one of the following values defined by Checkout.com:
|
string | The date and time that a message is entered into the Scheme Network, in UTC format. |
| The information (for example, transaction or transportation type) used to identify transit transactions. |
1{2"message_id": "1203626248540000021",3"card_id": "crd_eejbb5ohopoehdd7tevu7bxg3i",4"cardholder_id": "crh_urdihafyo75evcr55s62jmwwhy",5"transaction_id": "trx_zupv6ou4tyfevapshlrpwd5nb4",6"transaction_type": "Purchase",7"transaction_amount": 100,8"transaction_currency": "GBP",9"billing_amount": 90,10"billing_currency": "EUR",11"billing_conversion_rate": 0.9,12"transmission_date_time": "2020-01-01T16:51:47Z",13"ecb_conversion_rate": 0.34,14"merchant": {15"name": "Merchant name",16"city": "London",17"state": "",18"country": "GBR",19"category_code": "5499",20"merchant_id": "031860687"21},22"authorization_type": "final_authorization",23"fees": {24"transaction_fee": {25"fee_type": "debit",26"fee_category": "blended",27"amount": 10,28"currency": "GBP"29}30},31"address_verification": {32"address": "West Street",33"postal_code": "90150",34"address_verification_result": "no_match"35},36"requested_exemption_type": "recurring_payment",37"transit_information": {38"transaction_type": "authorized_aggregated_split_clearing",39"transportation_mode": "urban_bus"40},41"point_of_sale_transaction_date": "2023-04-25"42}
When an authorization request is relayed to you, you have the option to approve or decline the transaction by responding to the relay within 2000 milliseconds (or within your equivalent configured timeout settings).
If the request times out, or an error status code is received, the authorization will be automatically declined.
Note
A message relay is not initiated for PIN change, PIN unblock, or account status inquiry transactions.
To approve the transaction, respond with an HTTP 200 OK status code, along with the following:
Field | Description |
---|---|
string | The address verification result for the address information data, sent as one of the following values:
|
boolean | Authorization relay decision for the authorization request. Set to |
uint64 | The card's available balance, in minor units. |
string | The alphabetic currency code for the balance amount. |
key/value pair | Optional set of key-value pairs containing additional information. |
To decline the transaction, respond with an HTTP 200 OK status code, along with the following:
Field | Description |
---|---|
string | The address verification result for the address information data sent, as one of the following values:
|
boolean | Authorization relay decision for the authorization request. Set to |
key/value pair | Optional set of key-value pairs containing additional information. |
string | The reason for declining the transaction, as one of the following values:
If no value is supplied, or a value not listed above is sent, the default scheme reason code |