Configure authorization relay

Last updated: April 11, 2024

The authorization relay service provides you with complete control over whether to accept or decline any incoming authorization requests. This enables you to:

handle account balances
perform additional third-party checks before making a decision
make decisions based on your business and fraud logic
receive authorization details in real-time

Once you've configured the authorization relay service, you'll receive authorization requests for your cardholders' transactions.

If you do not enable the authorization relay service, the responsibility of approving or declining your cardholders' transactions remains with Checkout.com.

When a cardholder uses their issued card to make a payment, an authorization request is initiated and sent to our Issuing service.

A message containing information about the authorization request is then forwarded to the client-side authorization relay service with an HTTPS request.

You must then:

validate the request’s authenticity
process the payload
decide to approve or decline the authorization
respond to the request

Checkout.com then forwards your authorization response to the merchant or acquirer.

By default, you must respond to authorization requests within 2000 milliseconds, unless you've configured a custom time limit in your timeout settings.

If you do not respond within the time limit, the authorization request times out and is automatically declined.

To configure authorization relay on the Dashboard, you must 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 Issuing service can call when relaying an authorization to you. The endpoint must be configured in such a way that it:
- accepts JSON input
- can handle hash-based message authentication code (HMAC)
  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 client. Checkout.com 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 can use your keys to decode the message.
- has an open TCP port for HTTPS traffic on port 443, or on another custom port of your choice
- is idempotent - meaning if Checkout.com sends the same request multiple times due to network failures or timeouts, your endpoint will use the IDs provided to ensure the requests does not result in duplicate outcomes

Information

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

Go to Developers > Authorization relay in the Dashboard.
Select Configure.
In the Configure authorization relay page that opens, enter the endpoint URL you've exposed and select Confirm.
Copy the App ID and Secret API key that are generated. For security reasons, the secret API key will not be shown again. Ensure that you've copied it before proceeding.
Select Done. In the Authorization relay page that opens, the authorization relay is disabled by default.
Add the generated keys to your code and enable authorization relay using the toggle when you're ready.

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.

If you'd like to update any of the advanced settings, contact your Account Manager. The available advanced settings are:

Request timeout before decline - The number of milliseconds within which you're required to respond to a relayed authorization request. If we do not receive a response within this time, the transaction will be declined. The maximum you can set this to is 2,500 milliseconds.
User agent in headers - Indicates if we include information about the user agent in request headers.
Full auth. messages - Indicates if we pass the full decoded authorization message we receive from Mastercard (ISO 8583 messages) in our authorization relay payload.

Note

When you generate new keys, the authorization relay is disabled. This ensures that transactions aren't declined automatically when you're implementing new keys. Until you've enabled authorization relay again, Checkout.com will approve or decline the card transactions.

To update the keys used in the configuration, go to Developers > Authorization relay in the Dashboard.
Select Replace keys.
In the Generate replacement keys popup that opens, select the key you want to replace.
Select Generate new keys.
Copy the App ID and Secret API key that are generated. For security reasons, the secret API Key will not be shown again. Ensure that you've copied it before proceeding.
Select Done.
In the Authorization relay page that opens, enable authorization relay using the toggle when you're ready.

Use the keys you've generated in the previous step to validate the HMAC header. 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 app ID you've copied from the Dashboard
{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 your endpoint from the relay service contains the following:

cko-correlation-id: contains the unique Checkout.com correlation ID that you can use to identify the authorization relay request if you need to reach out to your Account Manager
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.
`client` object	Information about the client received in the authorization request. See the Client section for more details.
`digital_card` object	Information associated with the digital card. See the Digital card information section for more details.
`ecb_conversion_rate` double	The European Central Bank (ECB) comparative rate that will be communicated to the cardholder in case of a currency conversion.
`entity` object	Information about the entity received in the authorization request. See the Entity section for more details.
`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`
`id` string	The unique 30 characters alphanumeric ID of the message received from the scheme.
`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
`point_of_sale_transaction_date` string	The transaction date when the customer used the card at the point of sale.
`pos` object	Information about the conditions at the point of sale at the time of the transaction. See the POS section for more details.
`three_d_secure` object	Information related to 3DS. See our ThreeDSecure section for more details.
`transaction_amount` uint64	The authorization's transaction amount, in minor currency units. See our documentation on calculating currency amounts 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 card 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.

client

object

Information about the client received in the authorization request. See the Client section for more details.

digital_card

object

Information associated with the digital card. See the Digital card information section for more details.

ecb_conversion_rate

double

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

entity

object

Information about the entity received in the authorization request. See the Entity section for more details.

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

id

string

The unique 30 characters alphanumeric ID of the message received from the scheme.

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

point_of_sale_transaction_date

string

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

pos

object

Information about the conditions at the point of sale at the time of the transaction. See the POS section for more details.

three_d_secure

object

Information related to 3DS. See our ThreeDSecure section for more details.

transaction_amount

uint64

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

See our documentation on calculating currency amounts 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 card transactions.

Client

Field name Description

Field name	Description
`id` string	The client's unique Checkout.com identifier.

id

string

The client's unique Checkout.com identifier.

Digital card information

Field name Description

Field name	Description
`id` string	The card's unique Checkout.com identifier.
`wallet_type` string	(Optional) Type of wallet. This can be one of: `other` `googlepay` `applepay` `remote_commerce_programs`
`device_type` string	(Optional) Type of cardholder device used to initiate the transaction. This can be one of: `phone` `wearable` `pc` `vehicle` `tablet` `card` `other`

id

string

The card's unique Checkout.com identifier.

wallet_type

string

(Optional) Type of wallet. This can be one of:

other
googlepay
applepay
remote_commerce_programs

device_type

string

(Optional) Type of cardholder device used to initiate the transaction. This can be one of:

phone
wearable
pc
vehicle
tablet
card
other

Entity

Field name Description

Field name	Description
`id` string	The entity's unique Checkout.com identifier.

id

string

The entity's unique Checkout.com identifier.

POS

Field name Description

Field name	Description
`country_code` string	The country code where the PoS is located.
`postal_code` string	The postal code where the PoS is located.
`card_present` string	Indicates if the card was present to initiate the transaction. This can be one of: - `present` - `not_present` - `unspecified`
`cardholder_present` string	Indicates if the cardholder was present to initiate the transaction. This can be one of: `present` `not_present` `unspecified`
`entry_mode` string	The method by which a card initiates a transaction at a terminal. This can be one of: `contact_chip` `contactless_chip` `contactless_magstripe` `ecommerce` `magstripe` `manual` `optical_character_recognition` `optical_code` `server` `other`

country_code

string

The country code where the PoS is located.

postal_code

string

The postal code where the PoS is located.

card_present

string

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

cardholder_present

string

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

present
not_present
unspecified

entry_mode

string

The method by which a card initiates a transaction at a terminal. This can be one of:

contact_chip
contactless_chip
contactless_magstripe
ecommerce
magstripe
manual
optical_character_recognition
optical_code
server
other

Field name Description

Field name	Description
`requested_exemption_or_exclusion` string	The exemption or exclusion from Strong Customer Authentication. This can be one of: `other` `merchant_initiated_transaction` `acquirer_transaction_risk_analysis` `recurring_payment` `low_value_payment` `strong_customer_authentication_delegation` `secure_corporate_payment` `authentication_outage_exception`
`sca_not_required_reason` string	Indicates the reason for not requiring Strong Customer Authentication. This can be one of: `issuer_secure_corporate_payment` `authentication_outage_exception` `merchant_initiated_transaction` `low_value_payment` `recurring_payment` `secure_corporate_payment` `strong_customer_authentication_delegation` `acquirer_transaction_risk_analysis` `one_leg_out` `zero_amount_asi` `issuer_secure_corporate_payment` `mail_order_telephone_order` `other`

requested_exemption_or_exclusion

string

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

other
merchant_initiated_transaction
acquirer_transaction_risk_analysis
recurring_payment
low_value_payment
strong_customer_authentication_delegation
secure_corporate_payment
authentication_outage_exception

sca_not_required_reason

string

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

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


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": "Merchant name",
34    "city": "London",
35    "state": "",
36    "country": "GBR",
37    "category_code": "5499",
38    "merchant_id": "031860687",
39    "street_address": "Wenlock Works, Shepherdess Walk"
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  "fees": {
47    "transaction_fee": {
48      "fee_type": "debit",
49      "fee_category": "blended",
50      "amount": 10,
51      "currency": "GBP"
52    }
53  },
54  "address_verification": {
55    "address": "West Street",
56    "postal_code": "90150",
57    "address_verification_result": "no_match"
58  },
59
60  "transit_information": {
61    "transaction_type": "authorized_aggregated_split_clearing",
62    "transportation_mode": "urban_bus"
63  },
64  "point_of_sale_transaction_date": "2023-04-25"
65}

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.

Ensure that your response contains a relevant HTTP code and response body:

HTTP 200: Indicates you have everything you need to provide a decision about the transaction
HTTP 4XX: Indicates you're unable to provide a decision because you do not have the required data from Checkout.com
HTTP 5XX: Indicates you're unable to provide a decision because of an issue at your end, possibly due to server errors

Note

A message relay is not initiated for PIN change, PIN unblock, or account status inquiry card transactions.

To approve the transaction, respond with an HTTP 200 OK status code and an appropriate value for the approved field. All other values are optional.


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

Field	Description
`address_verification_result` string optional	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 optional	The card's available balance, in minor units.
`balance_currency` string optional	The alphabetic currency code for the balance amount.
`metadata` key/value pair optional	Optional set of key-value pairs containing additional information.

To decline the transaction, respond with an HTTP 200 OK status code and with "approved": false. All other values are optional.


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

Field Description

Field	Description
`address_verification_result` string optional	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	Optional set of key-value pairs containing additional information.
`reason_code` string optional	The reason for declining the transaction, as one of the following values: `InsufficientFunds` `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

optional

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

Optional set of key-value pairs containing additional information.

reason_code

string

optional

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

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

Configure authorization relay

How the authorization relay service works

Before you begin

Information