- Updated On 12 Feb 2021
- 7 Minutes To Read
Most bank customers 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 processor are available via API only.
- “Cards” functionality must be enabled for your instance.
- There must be a Card Token Reference associated with the account.
- You must be using API 2.0.
|Card Settlement Type||Debit Cards (Current Accounts)||Credit Cards (Revolving Credit Accounts)|
Authorization Hold Flow
Authorization Hold (also Card Authorization or Pre-authorization) is the practice of authorizing electronic transactions processed with a debit or a credit card and holding this balance as unavailable for the card-holder until either the merchant clears the transaction (settlement) or cancels it.
A common example is when a hold is made for a card transaction when renting a car or hotel room, which will be lifted if no incidental charges are incurred during the rental period.
Industry best practices suggest that Authorization Holds should automatically expire if no action is taken after no more than 7 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.
An Authorization Request is the means used to request holding a certain amount of money on a customer's account. An authorization hold amount is the amount awaiting authorization and as such is unavailable for further withdrawals for the end client, until the merchant clears the transaction (either settles it, or the hold expires).
Authorization requests can be performed via API 2.0 only.
Each Authorization Hold request in Mambu will have a reference number and will impact the account’s Available Balance. See Impact on Account Balance (below) for more info.
Once an Authorization Hold is created, it has
PENDING status until it is settled, reversed, or expired.
Retrieving Authorization Holds
Authorization holds will have one of four statuses;
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, see here.
Hold Balance vs. Locked 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.
In such situations Mambu will not allow for a hold to be made over an already locked amount.
For a deposit account with current data:
- Booked Balance of 1000
- Overdraft limit of 1500(*)
- Locked Balance of 500
- Holds Balance of 100
Available Balance of 400 (computational formula here)
(*)The overdraft limit is not taken into consideration when there is a positive locked balance (the account acts like it has overdraft disabled).
When performing an Authorization Request, if the requested Hold Amount plus the existing Hold Balance exceeds the account 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|
|100||success||200||300||The overdraft limit is not taken into consideration when there is a positive locked balance (the account acts like it has overdraft disabled).|
|401||fail||100||400||Despite the overdraft limit, cannot accept hold since the booked balance may become lower than locked balance, so the locked balance is no longer covered (guarantees cannot be covered by an overdraft).|
Setting an expiration date to Authorization Holds
By default, Authorization Holds will expire after a period of 7 days, although this can be changed to reflect your bank’s policies.
To set an expiration date for Authorization Holds:
- On the main menu, go to Administration > General Setup > Authorization Holds.
- Next to Default period before expiration, enter the number of days after which you want the authorization holds to expire.
- Click on Save.
You can also set different expiry periods for specific Merchant Categories, in which case, this period will be used for Holds requested for that specific Merchant Category code.
Every hour, a scheduled job will run to automatically cancel any Authorization Hold Requests on which no action has been taken before the expiration you have set.
When a hold has expired, its status will change to
EXPIRED and the hold amount will no longer influence the end user’s available balance.
Adjusting 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 (see below).
Reversing Authorization Holds
You can reverse an Authorization Hold either fully or partially using the decrease endpoint either if the transaction is aborted 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.
Hold amount = 100 -> Decrease = 75 -> New Hold amount = 25.
PENDINGAuthorization Hold by making a
Settling Authorization Holds
Notification to settle an Authorization Hold and create an actual transaction will come as Financial Advice from a card acquirer. Usually this Advice will be to debit the full amount of a previously requested Authorization Hold from a cardholder’s account. It is possible, however, that the Advice will be for more or less than the amount under Hold, or that it comes without any 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
Refunding Previously Settled Authorization Holds
Once an Authorization Hold has been settled and money is already debited from a cardholder’s account it can no longer be reversed and must be refunded by way of a new transaction for the full amount charged or, in the case of a partial refund, less than the originally charged amount.
Any interest applied before the refund has been made will not be affected and should be considered separately.
Other Card Payment Operations
In certain situations, transactions may be made without the possibility to communicate with a card issuer’s system. For example, a system with no internet connectivity, such as an airplane while in flight or when transactions are processed in a batch at a set time period like 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 request to be made without validation and as a result can both 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 not routed via a credit card processing network, Financial Requests are used to authorize an amount and immediately debit the cardholder’s account with a single request.
Financial Requests can only be made in the base currency of an account given that it has sufficient Available Balance and is active and not currently blocked.
* If you don't already have an account you will be prompted to create one when you first visit the site.