> ## Documentation Index > Fetch the complete documentation index at: https://nextgen-docs.enfuce.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://nextgen-docs.enfuce.com/api/transaction-lifecycle/authorisation-control/authorisation-request-openapi). * 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. ## 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](https://nextgen-docs.enfuce.com/guides/transaction-lifecycle/authorisation/authorisation-types-transaction-flows). * **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](/guides/transaction-lifecycle/authorisation/authorisation-types-transaction-flows). | | `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` :
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](https://nextgen-docs.enfuce.com/api/transaction-lifecycle/authorisation-control/authorisation-request-openapi#response-auth-response-code).
| |
  • `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](https://nextgen-docs.enfuce.com/api/transaction-lifecycle/authorisation-control/authorisation-request-openapi#response-auth-response-code).
| | `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](https://nextgen-docs.enfuce.com/api/transaction-lifecycle/authorisation-control/authorisation-request-openapi#response-auth-response-code).To avoid any risk, do not credit the cardholder's account until the credit is cleared.
|
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](https://nextgen-docs.enfuce.com/api/transaction-lifecycle/authorisation-control/authorisation-request-openapi#response-auth-response-code).
| |
  • `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](https://nextgen-docs.enfuce.com/api/transaction-lifecycle/authorisation-control/authorisation-request-openapi#response-auth-response-code).
|
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](https://nextgen-docs.enfuce.com/api/transaction-lifecycle/authorisation-control/authorisation-request-openapi#response-auth-response-code).
| | `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](https://nextgen-docs.enfuce.com/api/transaction-lifecycle/authorisation-control/authorisation-request-openapi#response-auth-response-code).
|

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](https://nextgen-docs.enfuce.com/api/transaction-lifecycle/authorisation-control/authorisation-request-openapi#response-auth-response-code).
 ## 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. ## Related Endpoints POST /auth POST /auth