Authorization Holds

Authorization holds are the result of successful payment card authorizations.

There are two types of authorization holds:

• Debit (DBIT) holds: decrease the available balance of a card account.
• Credit (CRDT) holds: have no impact on the available balance.

You can process authorization requests, authorization advices, incremental authorizations, authorization reversals, and balance inquiries via the Cards API. For more information, see Cards in our API Reference.

For more information on the permissions needed to manage authorization holds setup, see the Permissions article. Authorization holds have no impact on the ledger or the total balance of a deposit account.

Authorization hold states

Authorization holds can be in one of the following statuses:
PENDING: Active hold, decreasing the available balance.
SETTLED: Not active, released during the processing of a related payment card transaction.
EXPIRED: Not active, marked as expired during automated cron job process.
REVERSED: Not active, marked as reversed as a result of the processing of a reversal instruction or a decline notification.

You can 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.

Card authorization holds are distinct from transaction holds, which may be applied to any deposit transaction. For more information, see Transaction Holds.

The following table describes the different types of messages that pass between the card issuer and Mambu, depending on the type of authorization initiated.

Authorization requests

Authorization requests are a part of the Dual Message Schema, the purpose of which is to perform an authorization before sending related clearing transaction. Debit authorization is used to check the card and the account, that there is enough account balance for a cash withdrawal, purchase of goods and services, or other debit type of operation. The request body parameter advice must be set to FALSE to enable balance check and separate the authorization request from the authorization advice. Credit authorization is used to check the card and the account in order to execute a refund, cashback or other type of credit operation.

Authorization requests can only be performed via Mambu API v2. Each authorization hold request in Mambu will have a reference number. Once an authorization hold is created, it has the status PENDING until it is settled, reversed, or expired.

Authorization advices

If authorization happens on behalf of the issuer, without checking whether the card holder has sufficient funds to cover a given transaction, third-party systems use authorization advice to inform about the result of such authorizations. There can be negative or positive advice. Mambu supports positive authorization advice. Authorization advice creates a hold on a card account without checking the available balance. The request body parameter advice must be set to TRUE to disable the available balance check.

The final authorization advice contains the final hold amount. Usually it is not clear whether the final hold amount is higher or lower than the initial amount. To resolve this porblem, you can change the hold amount while calling the dedicated cards PATCH authorization hold API.

Incremental authorization

Authorization holds with a PENDING status can be increased by making an API request and supplying the card token (cardReferenceToken) and the authorization hold reference (authorizationHoldExternalReferenceId) along with the amount used to raise the held amount.

Authorization reversals

Mambu supports both full and partial authorization reversals. After receiving a partial reversal, the referenced authorization hold with a PENDING status can be decreased by making an API request and supplying the card token (cardReferenceToken) and the authorization hold reference (authorizationHoldExternalReferenceId), along with the amount to decrease the held amount. If the amount used is equal to or larger than the held amount, the hold is fully reversed and the hold is given a REVERSED status.

You can also fully reverse a PENDING authorization hold by making a delete request and supplying the card token (cardReferenceToken) and the authorization hold reference (authorizationHoldExternalReferenceId).

Balance inquiry

Using a card token, you can also get account balances. The response of the Get account balances request contains the following information: the available balance, the total balance, the credit limit, the account currency, the account ID, and the card type.

The available balance and the ledger balance are also returned in the response of each successfully created authorization hold or card transaction.

Authorization Holds Configuration

The authorization holds configuration determines the expiration period for authorization holds in days. The default value is seven days but it can be changed. You may also specify different expiry periods for specific merchant category codes (MCC). You may configure authorization holds settings either through the Mambu UI 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.

Mambu authorization holds support the custom expiration period. You can set expiration period in days while creating a hold in the request body parameter customExpirationPeriod. The PENDING debit authorization hold can be updated using the Update authorization.

Hourly authorization holds cron job

The hourly cron job AUTHORIZATION_HOLDS_EXPIRATION runs automatically and marks any authorization hold requests on which a settlement action has not been taken before the expiration period has elapsed. For example, if the expiration period set for authorization holds is set to 14 days, then any authorization holds created or updated more than 14 days ago are candidates to be expired.

When an authorization hold expires, its state 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 take effect with the next AUTHORIZATION_HOLDS_EXPIRATION cron job to run. Holds made directly on deposit accounts via account ID do not expire. For more information, see Transaction Holds.