Authorisation Request API Endpoint

💡

Disclaimer: The Authorisation Request API was previously referred to as Authorisation Control API. This API name change does not impact any existing integration.

After we receive an authorisation request from the card Scheme, we validate the authenticity of the transaction. If we approve the request, we forward a synchronous message to the ledger as they must approve/decline/partially approve the request — the message is sent to the registered endpoint through the outgoing Authorisation Request API Endpoint.

For initial and incremental authorisations, the ledger must check whether the cardholder has sufficient account balance to cover the transaction amount.
For balance enquiry and PIN related services, the ledger must check whether any fees are applicable. If yes, they must verify the cardholder’s account and adjust the balance.

This provides you with a more controlled authorisation process, where you can participate in real-time decision-making.

To receive the messages, you must provide your customer success manager with the specific endpoint URLs and the HTTP basic authentication credentials required to access the endpoints.
Enfuce uses another interface to transmit transaction lifecycle events — Transaction Event Webhook. The transaction event webhook sends asynchronous notifications to the ledger.
If Enfuce determines that the authorisation request, as received from the card Scheme, must be declined before reaching the ledger (for example, due to incorrect PIN), the message is then sent via the Transaction Event Webhook.

Authorisation Hold

If the request is approved, the ledger must reserve the amount as an authorisation hold. The amount is reserved in the cardholder’s account balance, until the transaction is cleared, reversed, or has expired.

Benefits of Authorisation Request API

In addition to controlling the transactions you want to approve, you can use the data received in the authorisation request endpoint to create rules that provide a customised experience for your cardholders.

Supported Message Categories and Message Function

Message Categories: The Authorisation Request API endpoint informs the ledger about the following authorisation message categories:
- INITIAL_AUTHORIZATION
- INCREMENTAL_AUTHORIZATION
- BALANCE_INQUIRY
- PIN_MANAGEMENT
For detailed information on each message category, see Authorisation Message Types.
Message Function: The messageFunction in an authorisation request message is always sent as a REQUEST, as we are awaiting a decision from the ledger to approve/decline/partially approve the authorisation request, and make adjustments to the cardholder’s account balance.

Message Contents

The Authorisation Request API endpoint includes rich information about a transaction. The following lists the minimum data you require to arrive at a decision:

Parameter	Description
`card.id`	Unique identifier of the card assigned by Enfuce, used for the specific transaction.
`card.accountId`	Unique identifier of the account assigned by the ledger, associated with the specific card used for the transaction.
`id`	Unique identifier of the message being sent. This is referenced only by `VOID_AUTHORIZATION`.
`transactionId`	Enfuce generated unique ID to identify each card transaction. Related messages contain the same transaction ID to indicate association with the same transaction.
`messageCategory`	Categorises the authorisation message, based on the current processing state, for example, `INITIAL_AUTHORIZATION` or `INCREMENTAL_AUTHORIZATION`. For more information on authorisation message categories, see Authorisation Types.
`merchant.partialApprovalCapable`	Indicates whether the merchant accepts partial approval — if this flag is set, you can partially approve a request (the decision depends on the cardholder’s account balance).
`transaction.transactionType`	Indicates the type of transaction, for example, `RETAIL` or `CREDIT`.
`transaction.approvedAmount`	Indicates the amount that can be approved after spend control limiters have been applied. If the merchant accepts partial authorisations, the approved amount can be less than the billing amount; otherwise, the value in the `transaction.approvedAmount` parameter is equivalent to the `billingAmount`.

Ledger’s Actions

The following section explains the actions that you must take when you receive a message via the the Authorisation Request API interface for any of the following messageCategory :

INITIAL_AUTHORIZATION

This is the most common authorisation request, frequently used for retail payments and withdrawals.

Conditions	Actions
`transactionType`: any value, except `CREDIT` `partialApprovalCapable`: `FALSE`	Validate that the `transaction.approvedAmount` can be debited from the cardholder’s account. Hold the amount represented in the `transaction.approvedAmount` parameter. If you approve the request, return `APPROVED` in the `authResponseCode` attribute. If you decline the request, return an appropriate response in the `authResponseCode` attribute.
`transactionType`: any value, except `CREDIT` `partialApprovalCapable`: `TRUE`	Check the maximum amount that can be debited from the cardholder’s account. Create an authorisation hold of the same amount. If you approve the request, respond `APPROVED` in the `authResponseCode` attribute. If you partially approve the request, return `PARTIALLY_APPROVED` in the `authResponseCode` attribute, and specify the amount in the `partialApprovalAmount` attribute. If you decline the request, return an appropriate response in the `authResponseCode` attribute.
`transactionType`: `CREDIT`	Validate that `transaction.approvedAmount` can be credited to the cardholder’s account. If you approve the request, return `APPROVED` in the `authResponseCode` attribute. If you decline the request, return an appropriate response in the `authResponseCode` attribute. To avoid any risk, do not credit the cardholder’s account until the credit is cleared.

INCREMENTAL_AUTHORIZATION

This is an additional request submitted occasionally to increase the initial authorised amount, for example, car rentals or hotel bookings.

Conditions	Actions
`transactionType`: any value, except `CREDIT` `partialApprovalCapable`: `FALSE`	Find the associated previous authorisations, based on the `transactionId`, and persist this relationship. Validate that `transaction.approvedAmount` can be debited from the cardholder’s account. Note that this is an increment to the total amount of previous authorisations linked to this message. Hold the amount represented in the `transaction.approvedAmount` parameter. If you approve the request, return `APPROVED` in the `authResponseCode` attribute. If you decline the request, return an appropriate response in the `authResponseCode` attribute.
`transactionType`: any value, except `CREDIT` `partialApprovalCapable`: `TRUE`	Identify the initial authorisation request, based on the `transactionId` Validate that the maximum amount, which is less or equal to the `transaction.approvedAmount` can be debited from the cardholder’s account. This is an increment to the total amount of previous authorisations linked to this message. The cardholder’s account balance is already adjusted, based on the `transaction.approvedAmount` approved in the previous authorisation request. Hold the amount represented in the `transaction.approvedAmount` parameter. If you approve the request, return `APPROVED` in the `authResponseCode` attribute. If you partially approve the request, return `PARTIALLY_APPROVED` in the `authResponseCode` attribute and specify the amount in the `partialApprovalAmount` attribute. If you decline the request, return an appropriate response in the authResponseCode attribute.

BALANCE_ENQUIRY

This occurs mostly in ATMs to check the account balance. Based on how you have configured this capability, there may be a fee involved for a balance check. If the balance check incurs any fee, you must return the available balance and check whether the cardholder has sufficient funds to cover the fee.

Conditions	Actions
`transaction.approvedAmount` is greater than `0`	Validate whether the amount represented in the `transaction.approvedAmount` can be debited from the cardholder’s account. Hold the amount represented in the `transaction.approvedAmount` parameter. If you approve the request, return `APPROVED` in the `authResponseCode` attribute and specify the remaining balance in the `availableBalance` attribute. If you decline the request, return an appropriate response in the `authResponseCode` attribute.
`transaction.approvedAmount` is equal to `0`	If you approve the request, return `APPROVED` in the `authResponseCode` attribute and specify the remaining balance in the `availableBalance` attribute. If you decline the request, return an appropriate response in the `authResponseCode` attribute.

PIN_MANAGEMENT

We send this request via the authorisation request API interface, when PIN related services involve a fee.

Actions

Validate whether the amount represented in the transaction.approvedAmount can be debited from the cardholder’s account.
Hold the amount represented in the transaction.approvedAmount parameter.
If you approve the request, return APPROVED in the authResponseCode attribute and specify the remaining balance in the availableBalance attribute.
If you decline the request, return an appropriate response in the authResponseCode attribute.

Ledger’s Platform Requirements

Successful authorisation of a transaction is crucial to the payment processing workflow. If responses are not returned on time, the cardholder has to wait longer at the checkout. Hence, responses are time-sensitive. The ledger must have high availability and high-performance systems:

A rules engine that would evaluate the Enfuce-provided authorisation control message and approve or decline the transactions instantly.
Uptime > 99% (24/7/365).
Response to Enfuce within 5 seconds, measured from the time the request leaves Enfuce to when a response is received. This includes network trip duration, which is generally minimal under normal conditions.
Capability to process multiple transactions per second during peak times.