- 01 Apr 2022
- 11 Minutes To Read
- Print
- DarkLight
- PDF
Card Transactions and Authorization Holds
- Updated On 01 Apr 2022
- 11 Minutes To Read
- Print
- DarkLight
- PDF
Most bank clients today expect to be able to function in a fully cashless way, using debit and credit cards to make and receive payments as well as make direct withdrawals from debit accounts and cash advances against credit.
Mambu fully supports industry standard authorization hold flows for card payments and allows you to request, adjust, reverse and settle holds against Current Account and Revolving Credit type products.
All capabilities for configuring the flow between Mambu and your card acquirer are available via API only.
Card authorization holds are separate from transaction holds, which may be applied to any deposit transaction. For more information, see Transaction Holds.
Requirements
- You will need to have the Cards functionality enabled for your instance.
- A card token reference must be associated with the account.
For more on how to link a debit card using a card token reference, go to the create card endpoint for Deposit Accounts. For linking a credit card, find out more at the create card endpoint for Loan Accounts.
Authorization
In the card payments ecosystem, an authorization - also known as a card authorization, pre-authorization or hold processing - is initiated when a card holder makes a purchase. The process involves:
- Confirming that the debit or credit card is valid.
- Confirming that the business rules are met.
- Confirming that the available balance on the cardholder's account is sufficient.
- Placing a temporary hold on funds in the account
The temporary hold ends when the merchant completes the transaction (clearing and settlement) or cancels it (reversal). The process starts with the merchant when the card holder makes the purchase, then the card acquirer processes the payment on behalf of the merchant and interacts with Mambu to do so.
The interaction between the card acquirer and Mambu happens through messages to transfer information about the transaction. There are two types of messages:
- Single-message transactions include all the information required to complete the transaction in one message.
- Dual-message transactions split the information: the initial message at the time of purchase will contain the information required to make an authorization decision and a second message is sent later with details to clear and settle the transaction.
Example: Authorization holds
A common example is an authorization hold for a card transaction, when renting a car or hotel room. This is lifted if no incidental charges are incurred during the rental period.
Industry best-practice recommends that authorization holds automatically expire if no action is taken after no more than seven days for debit card transactions and no more than 30 days for credit card transactions. See below for how to configure this for your Mambu instance.
Configuring authorization holds settings
We strongly recommend that you use an end-to-end test to test any configuration changes in your sandbox environment before implementing them in your production environment.
The end-to-end test should check that the hourly AUTHORIZATION_HOLDS_EXPIRATION
cron job expires the correct authorization holds. For more information, see Hourly authorization holds cron job below.
If, to perform your end-to-end test you have to set holds in the past, then please contact us through Mambu Support so that we can assist you with manipulating the data directly in the database.
The authorization holds configuration determines the expiration period for authorization holds in days. The default value is seven days however you may edit this value. You may also specify different expiry periods for specific merchant category codes (MCC).
You may configure authorization holds settings either through the Mambu UI (see below) or via the API. For more information, see Authorization Holds Configuration.
To change the default expiration period for authorization holds:
- On the main menu, go to Administration > Financial Setup > Authorization Holds.
- Next to Default period before expiration, enter the number of days after which you want the authorization holds to expire. The value must be between 1 and 36,525 days.
- Select Save.
To add an expiration period for an MCC:
- On the main menu, go to Administration > Financial Setup > Authorization Holds.
- Select Add.
- Enter a value for the Merchant Category Code.
- Enter a value for the Days to Expiration. The value must be between 1 and 36,525 days.
- Select Save.
Hourly authorization holds cron job
There is an hourly cron job called AUTHORIZATION_HOLDS_EXPIRATION
which runs automatically and expires any authorization hold requests on which a settlement action has not been taken before the expiration period has elapsed.
For example, if 14 days is the expiration period set for authorization holds, then any authorization holds created or updated 14 days ago are candidates to expire.
When an authorization hold expires, its status changes from PENDING
to EXPIRED
and the hold amount no longer affects a client's available balance. For more information about cron jobs at Mambu, see Automatic End of Day Actions and Hourly jobs.
If you change your authorization holds configuration, the new configuration will be considered by the following AUTHORIZATION_HOLDS_EXPIRATION
cron job run.
Holds made directly on deposit accounts via account ID do not expire. For more information, see Transaction Holds.
Card transaction message types
The table below describes the different types of messages that pass between the card issuer and Mambu depending on the type of authorization initiated. Each message type and how it is managed in Mambu is explained further in the text below the table.
Card message Type | Description | Debit Cards Availability | Credit Cards Availability |
---|---|---|---|
Authorization Hold Requests | A request to authorize a transaction and hold money on the cardholder's account in a dual-message system, after verifying if the client has enough available balance. | ✔ | ✔ |
Authorization Advice | This is a request containing details of an already confirmed transaction that results in holding money on the cardholder's account in a dual-message system, without verifying if the client has enough balance. | ✔ | ✘ |
Balance Inquiry | A request to obtain a cardholder's account balances. | ✔ | ✔ |
Financial Transaction Requests | A single-message request to authorize a transaction with a given amount and immediately debit (clear) the cardholder’s account with a single request if it has sufficient available balance, is active, and is not currently blocked. | ✔ | ✔ |
Financial Transaction Advice | A single-message request containing details of an already confirmed transaction that results in immediate debit (clearing) of the cardholder’s account, without verifying if the client has enough balance. | ✔ | ✔ |
Reversal Request | Request to authorize a full or partial cancellation of an existing transaction, with account balance verification. | ✔ | ✔ |
Reversal Advice | Request to authorize a full or partial cancellation of an existing transaction, without verifying the account balance. | ||
Refunds Authorization | Request to authorize a refund (credit) transaction. | ✔ | ✘ |
Authorization hold requests
Authorization requests can only be performed via API v2. Each authorization hold request in Mambu will have a reference number and will impact the account’s Available Balance. See Impact on Account Balance for more info. Once an authorization hold is created, it has the PENDING
status until it is settled, reversed, or expired.
Retrieving authorization holds
API requests can be used to retrieve either an array of all authorization holds for a given deposit account or details on a specific hold on a given card by its ID. Authorization holds will have one of four statuses: PENDING
, REVERSED
, SETTLED
or EXPIRED
.
Impact on account balance
When Authorization Requests are made and before they are settled (or not), the amounts under hold are accumulated under a Holds Balance. This balance is also used for calculating the Available Balance.
Hold balance vs. Locked and Blocked balance
Currently Mambu offers the option of locking a balance on a deposit account, when that balance is used as a guarantee for loans. This locked amount is no longer available for withdrawal. Similarly, you can create so called "Blocked Funds" that create a Blocked balance that can be seized by authorities. In such situations Mambu will not allow for a hold to be made over an already locked amount.
Example: Authorization request flow
For a deposit account with the following balances:
- Booked balance or totalBalance of USD1,000.00
- Overdraft limit of USD1,500.00
- Locked balance of USD200.00
- Blocked balance of USD300.00
- Holds balance of USD100.00
The available balance is USD400.00. Read more on the computational formula here.
When performing an authorization request, if the requested hold amount plus the existing hold balance exceeds the account's available balance, then the authorization request is not permitted and the holds balance is not updated.
Hold Amount Request | Authorization Request Response | Holds Balance | Available Balance | Notes |
---|---|---|---|---|
USD100.00 | success | USD200.00 | USD300.00 | The overdraft limit is not taken into consideration when there is a positive locked balance. |
USD400.00 | success | USD500.00 | USD0.00 | |
USD401.00 | fail | USD100.00 | USD400.00 | Despite the overdraft limit, the hold cannot be accepted as the booked balance may become lower than locked balance. So the locked balance is no longer covered and guarantees cannot be covered by an overdraft. |
Incremental authorization holds
Authorization holds with a PENDING
status can be increased or decreased by making an API request and supplying the Card Token Reference and Authorization Hold Request ID along with the amount with which to increase or decrease the held amount. A decrease of the same or more than the full amount of the hold will effectively reverse the hold.
Clearing and settling authorization holds
In dual-message networks, a clearing message from card acquirer updates authorization hold status and creates a financial transaction thereafter. In Mambu this request can be posted through createCardTransaction endpoint as financial advice and it always acts as a final clearing. Usually this message contains the request to debit or credit the full amount of a previously requested authorization hold from a cardholder’s account. However, It is possible that the final clearing amount will be different from the amount under the hold.
In single-message networks, a transaction comes without prior authorization hold having been made at all. Debits will be recorded with the transaction domain code Payments
, family code Merchant Card Transactions
and sub-family code Credit Card Payment
. Once the transaction has been completed, the authorization hold will be updated to include the transaction ID and have its status change to SETTLED
for Final Clearing. If your card processing network also requires Partial clearings of the authorization holds, we recommend contacting Mambu Support to further discuss this use case.
Authorization advice, Financial transaction advice, and Reversal advice
In certain situations, transactions may be processed without being able to communicate with a card issuer’s system at that moment. For example, a system with no internet connectivity, such as an airplane in flight or when transactions are processed in a batch at the end of a business day. Such transactions are commonly known as Offline Transactions.
These transactions are made using the same API request as a standard authorization hold, but with the Advice flag set to "TRUE"
. This will cause the authorization to be made without validating the available balance and as a result can allow a cardholder to make a transaction for an amount over any defined limits, as well as allow for usage without the normal balance checks - causing an account to go into Technical Overdraft.
Financial transaction requests
For transactions such as ATM withdrawals or PIN Debits, which are routed via a single-message network, financial requests are used to authorize an amount and immediately debit the cardholder’s account with a single request. Financial transaction requests can only be made in the base currency of an account given that it has sufficient available balance, is active, and not currently blocked.
Reversal request
You can reverse an authorization hold fully or partially using the decrease endpoint if the transaction is cancelled or the cardholder will be charged a lesser amount. A fully reversed authorization hold will receive the status REVERSED
and will no longer affect the cardholder’s available balance. Partially reversed authorization holds will retain the PENDING
status and their expiry period will be reset, effectively restarting it from the point at which the partial reversal was made.
PENDING
authorization hold by making a DELETE
request.Refunds authorization
Once an authorization hold has been settled and money has already been debited from a cardholder’s account, it can no longer be reversed. It must be refunded by posting a new transaction for the full amount charged or, in the case of a partial refund, less than the originally charged amount. Currently this process requires creating a new authorization hold with credit amount and clearing it by using the createCardTransaction endpoint. Original Credit transactions can be posted in the same manner.
Any interest applied before the refund has been made will not be affected and should be considered separately.