Card Transactions
  • 12 Feb 2021
  • 7 Minutes To Read
  • Print
  • Share
  • Dark

Card Transactions

  • Print
  • Share
  • Dark


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.
Please Note
A Card Token Reference is used to identify a Credit or Debit card without needing to always provide sensitive information such as the card number and, as such, is a shared reference between your instance and your card issuer’s system.


Card Settlement Type Debit Cards (Current Accounts) Credit Cards (Revolving Credit Accounts)
Authorization Requests
Authorization Advices
Financial Requests
Financial Advices
Reversal Advices
Return Authorizations

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.

Authorization Requests

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

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, 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).
400 success 500 0
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).
Please Note
As a loan can not be used as a guarantee for another loan, when an account has a Locked Balance, it acts as if the overdraft facility has been disabled. This means that the overdraft limit is no longer taken into account for the calculation of the Available Balance.

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:

  1. On the main menu, go to Administration > General Setup > Authorization Holds.
  2. Next to Default period before expiration, enter the number of days after which you want the authorization holds to expire.
  3. 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.

Please Note
You can also fully reverse a PENDING Authorization Hold by making a DELETE request.

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

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

Offline transactions

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.

Please Note
ATM withdrawals can also be reversed using the dedicated API request.

Ask the Mambu Community

If you have a question about how anything works or have come across something you haven't seen explained here, get in touch with our community of fellow users and Mambuvians where someone will lend a hand.

Ask a question about Cards

* If you don't already have an account you will be prompted to create one when you first visit the site.

Was This Article Helpful?