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 ID
User-Agent: contains the value CKO-Issuing

Field Description

Field	Description
`address_verification`	The address verification information in the authorization request, including any combination of the following values: Address Postal code Address verification result (`no_match` or `postal_code_match`)
`authorization_type` enum	The authorization type, as one of the following values: `authorization` `deferred_authorization` `final_authorization` `incremental_pre_authorization` `pre_authorization`
`billing_amount` 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.
`billing_conversion_rate` double	The scheme conversion rate used to convert the transaction amount to the billing amount.
`billing_currency` string	The currency in which the issuer will bill the cardholder, as an ISO 4217 code.
`card_id` string	The unique ID of the card, as stored by Checkout.com.
`cardholder_id` string	The unique ID of the cardholder, as stored by Checkout.com.
`ecb_conversion_rate` double	The European Central Bank (ECB) comparative rate that will be communicated to the cardholder in case of a currency conversion.
`fees`	The fees information received in the authorization request, including any combination of the following values: `fee_type` (debit or credit) `fee_category` (blended, indicating the fee amount is included in the transaction amount, or additional) `amount` `currency`
`merchant`	An object containing merchant information, including: `name` `city` `country`, as an ISO-3 country code `state`, if `country` is `USA` `category_code`, as a 4-digit ISO 18245 merchant category code (MCC) `merchant_id`, to identify the merchant at the point of interaction
`message_id` string	The unique 19-digit ID of the message received from the scheme.
`point_of_sale_transaction_date` string	The transaction date when the customer used the card at the point of sale.
`requested_exemption_type` enum	The requested exemption, as one of the following values: `merchant_initiated_transaction` `acquirer_transaction_risk_analysis` `recurring_payment` `low_value_payment` `secure_customer_authentication_delegation` `secure_corporate_payment` `authentication_outage_exception`
`transaction_amount` uint64	The authorization's transaction amount, in minor currency units. See our documentation on calculating currency values for more details.
`transaction_currency` string	The acquirer’s local currency, or the local currency of the transaction’s source location, as an ISO 4217 code.
`transaction_id` string	The ID of the transaction, which links together all related authorization, reversal, and clearing messages.
`transaction_type` enum	The transaction type, as one of the following values defined by Checkout.com: `balance_inquiry` `cashback` `purchase` `refund` `remittance_funding` `withdrawal`
`transmission_date_time` string	The date and time that a message is entered into the Scheme Network, in UTC format.
`transit_information`	The information (for example, transaction or transportation type) used to identify transit transactions.

address_verification

The address verification information in the authorization request, including any combination of the following values:

Address
Postal code
Address verification result (no_match or postal_code_match)

authorization_type

enum

The authorization type, as one of the following values:

authorization
deferred_authorization
final_authorization
incremental_pre_authorization
pre_authorization

billing_amount

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.

billing_conversion_rate

double

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

billing_currency

string

The currency in which the issuer will bill the cardholder, as an ISO 4217 code.

card_id

string

The unique ID of the card, as stored by Checkout.com.

cardholder_id

string

The unique ID of the cardholder, as stored by Checkout.com.

ecb_conversion_rate

double

The European Central Bank (ECB) comparative rate that will be communicated to the cardholder in case of a currency conversion.

fees

The fees information received in the authorization request, including any combination of the following values:

fee_type (debit or credit)
fee_category (blended, indicating the fee amount is included in the transaction amount, or additional)
amount
currency

merchant

An object containing merchant information, including:

name
city
country, as an ISO-3 country code
state, if country is USA
category_code, as a 4-digit ISO 18245 merchant category code (MCC)
merchant_id, to identify the merchant at the point of interaction

message_id

string

The unique 19-digit ID of the message received from the scheme.

point_of_sale_transaction_date

string

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

requested_exemption_type

enum

The requested exemption, as one of the following values:

merchant_initiated_transaction
acquirer_transaction_risk_analysis
recurring_payment
low_value_payment
secure_customer_authentication_delegation
secure_corporate_payment
authentication_outage_exception

transaction_amount

uint64

The authorization's transaction amount, in minor currency units.

See our documentation on calculating currency values for more details.

transaction_currency

string

The acquirer’s local currency, or the local currency of the transaction’s source location, as an ISO 4217 code.

transaction_id

string

The ID of the transaction, which links together all related authorization, reversal, and clearing messages.

transaction_type

enum

The transaction type, as one of the following values defined by Checkout.com:

balance_inquiry
cashback
purchase
refund
remittance_funding
withdrawal

transmission_date_time

string

The date and time that a message is entered into the Scheme Network, in UTC format.

transit_information

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
`address_verification_result` string	The address verification result for the address information data, sent as one of the following values: `PostalCodeMatch` `AddressMatch` `PostalCodeAndAddressMatch` `NoMatch`
`approved` boolean	Authorization relay decision for the authorization request. Set to `true` to approve.
`balance_amount` uint64	The card's available balance, in minor units.
`balance_currency` string	The alphabetic currency code for the balance amount.
`metadata` 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

Field	Description
`address_verification_result` string	The address verification result for the address information data sent, as one of the following values: `PostalCodeMatch` `AddressMatch` `PostalCodeAndAddressMatch` `NoMatch`
`approved` boolean	Authorization relay decision for the authorization request. Set to `false` to decline.
`metadata` key/value pair	Optional set of key-value pairs containing additional information.
`reason_code` string	The reason for declining the transaction, as one of the following values: `InsufficientFund` `FailedControl` `Other` If no value is supplied, or a value not listed above is sent, the default scheme reason code `Do Not Honour (05)` will be used instead.

address_verification_result

string

The address verification result for the address information data sent, as one of the following values:

PostalCodeMatch
AddressMatch
PostalCodeAndAddressMatch
NoMatch

approved

boolean

Authorization relay decision for the authorization request. Set to false to decline.

metadata

key/value pair

Optional set of key-value pairs containing additional information.

reason_code

string

The reason for declining the transaction, as one of the following values:

InsufficientFund
FailedControl
Other

If no value is supplied, or a value not listed above is sent, the default scheme reason code Do Not Honour (05) will be used instead.

We've made some changes to our API

Relay authorization requests
Beta

How the authorization relay service works

Configure the API endpoint

Information

Configure the HMAC signature

Validate the HMAC header value

Calculate the `RequestSignatureBase64` value

Note

Relay message content

Additional headers

Body

Relay message example

Respond to a relayed authorization request

Note

Approve the transaction

Decline the transaction

How the authorization relay service works

Configure the API endpoint

Information

Configure the HMAC signature

Validate the HMAC header value

Calculate the RequestSignatureBase64 value

Note

Relay message content

Additional headers

Body

Relay message example

Respond to a relayed authorization request

Note

Approve the transaction

Decline the transaction

Calculate the `RequestSignatureBase64` value