Card Transactions and Authorization Holds

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.

Requirements

• You will need to have the Cards functionality enabled for your instance.
• A card token reference must be associated with the account.

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

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:

1. On the main menu, go to Administration > Financial Setup > Authorization Holds.
2. 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.
3. Select Save.

To add an expiration period for an MCC:

1. On the main menu, go to Administration > Financial Setup > Authorization Holds.
2. Select Add.
3. Enter a value for the Merchant Category Code.
4. Enter a value for the Days to Expiration. The value must be between 1 and 36,525 days.
5. 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.

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.

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.

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.

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.