Support Center

Card Payments and Authorization Holds

Last Updated: Jul 06, 2018 09:50AM CEST


● Authorisation Requests and Advices

● Financial Advices/Requests and Reversal Advices


In banking, there are specific and regulated processes which are used for verifying electronic transactions initiated with a debit or credit card.

In order to support card payments flow in Mambu, we have implemented Authorization Hold capabilities, which allow requesting a hold on amounts, settling them, reversing them, and so on.

All capabilities for configuring the flow between Mambu and your card processor are available via API only.

Authorization Holds functionality is available for Current Account type of deposit product.

------------------------------------------------------------------------------------------------------------------------- Back to top

 Authorisation Requests and Advices

Authorization Requests

An authorization hold amount is the amount awaiting authorization and as such is unavailable for further withdrawals for the end client, until either the merchant clears the transaction (i.e. settles it, or the hold expires).


An Authorization Request is therefore the means used to request holding a certain amount of money on customer's account. 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 Holds Balance (below) for more info.


Once an Authorization Hold is created, it has Pending status until it is settled, reversed, expired, etc.


In order to use this feature, "Cards" functionality must be enabled for your instance.


Card Token Reference

In order to make an Authorization Request, the Card Token Reference is required in the JSONPath expression when performing Authorization Requests.


As a security measure, a Card Token Reference is used for processing card transactions and is meant to identify the card itself, which maps back to sensitive information stored with your Card Issuer (e.g. a credit card number). The Card Token Reference must already be stored in Mambu for inter-referencing with the card issuer.


Holds 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 Authorization Request Rejection Reasons

Mambu authorizes holds requests based on various conditions such as:

  • The account must be active (not Pending Approval)
  • The account must have a sufficient balance
  • The Client must be active
  • The Client must not be blacklisted

Hold Expiration Date Configuration

Holds expire typically in 7 days, as a best business practice, however Mambu allows customising the Authorization Holds expiration period via Administration:


Mambu will accept an Authorization Request if the Hold Expiration Date is not provided and will apply the default period configured in Administration.


Cancelling an expired Authorization Hold

Authorization holds, which are more than 7 days old and have the status PENDING, will be updated to EXPIRED via a cron job that runs every 1 hour.


Holds 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






The overdraft limit is not taken into consideration when there is a positive locked balance (the account acts like it has overdraft disabled).










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


Authorization Advices - Offline Transactions

Authorization Advices are used to notify the issuer of an authorization that was executed without involvement of the issuer's system. Generically, Authorization Advices must be accepted as an Authorization Hold without validation.  


When an offline transaction is performed, an account may go into Technical Overdraft (Unauthorized Overdraft). See more under Technical Overdraft. Some examples of offline transactions are transactions made on an airplane while in flight, when the POS is not online, ATM transactions, which sometimes settle all transactions at the end of day, etc.


Retrieving Cards and Holds related data

Mambu allows retrieving:

  • All cards associated with an account via dedicated API endpoint. For more information, please review our API 2.0 documentation for Deposit accounts.
  • All the authorization holds for a deposit account
-------------------------------------------------------------------------------------------------------------------------------- Back to top

 Financial Advices / Requests and Reversal Advices

Financial advices are used to notify on the necessity to execute the financial transaction. The Financial Advice will usually be sent in relation to the original Hold Authorization request, effectively settling the authorization hold with a financial transaction.


Financial Advice - Settling Authorization Holds

Debiting funds for an existing original Authorization Hold can be made via Financial Advice.

Financial Advices typically follow a prior Authorization Hold and have the same amount as the original Authorization Hold request, but they can also be done:

  • For Less than original Authorization Hold amount
  • For More than original Authorization Hold amount
  • Without a prior Authorization Hold request

When a Financial Advice is made by the Card Acquirer, the amount included in the Financial Advice is debited from the account with the transaction domain code 'Payments', family code 'Merchant Card Transactions' and sub-family code 'Credit Card Payment'. If a prior Authorization Hold existed, prior to the Financial Advice, it is updated with the transaction ID of the debit transaction and its status is updated to "Settled".


When posted via Financial Advice or Request, withdrawal transactions will include card acceptor details in the API calls which return the deposit transactions details.


Reversal Advice - Reversing settled financial transaction fully or partially


Reversal Advices are used to partially or fully reverse (refund) a previous Financial Transaction or Authorization Hold, for example when a Card Acquirer wants to refund money that was debited from the cardholder's account.


Reversal Advices can be sent when:

  • A Full reversal (refund) is needed for an already Settled hold
  • A Partial reversal (refund) is needed for an already Settled hold (for example, if original Hold was for 100, a reversal of only 50 is also possible)
  • A Refund is needed for an original transaction that doesn't exist on customer's account
  • A hold amount (which, for pre-authorization purposes, was captured on the cardholder's account but is not settled yet) needs to be fully or partially released

A Reversal Advice can performed to release a Hold with any amount, it can be equal, higher, or lower than the original Authorization Hold request.

  • If the amount is lower, then Mambu releases the Hold for the lower amount only and the Authorization Hold amount is updated with the remaining amount difference. The Hold expiration date is also reset to 7 days (or whatever custom time period has been set) after the date of the Reversal Advice.

Example: Hold amount = 100 -> Reversal Advice = 75 -> New Hold amount = 25.

  • If the amount of the Reversal Advice is equal or higher, then Mambu reverses the entire Hold amount and the Authorization Hold status will be updated to "Reversed".  

Withdrawal reversal when the initial transaction is card-originated is not permitted via UI, and must be performed via Reversal Advice API.


Reversal Advices can be performed via API 2.0 only, via Cards, decrease endpoint: POST /cards/{token}/financial- transaction/{reference}:decrease.


Financial Requests - Account Financial Transactions


Financial requests are used to request authorization for a certain amount, as well as the subsequent execution of the debit / withdrawal transaction on the customer's account. These requests result in an actual Financial transaction. Common use cases for this type of request are PIN Debits and ATM Cash Withdrawals.


Debiting of funds is permitted via Financial Requests, only if there are sufficient funds available and if the account is not blocked.


Financial Requests are accepted only in the account currency.


-------------------------------------------------------------------------------------------------------------------------------- Back to top
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
Invalid characters found