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.

Authorization hold states

Authorization holds can be in one of the following states:
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.

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

There are credit card flows that we currently do not support, but we are working on achieving parity.

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, cash-back or other credit type of operation.

Authorization requests can only be performed via 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 authorization. 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.

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 used to decrease the held amount. If the used amount is equal or larger than the held amount, such hold is fully reversed and the hold is given the 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.

Authorization Holds Configuration

The authorization holds configuration determines the expiration period for authorization holds in days. The default value is seven days but you can change it. 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.

Hourly authorization holds cron job

There is an hourly cron job called AUTHORIZATION_HOLDS_EXPIRATION which runs automatically and marks any authorization hold requests on which a settlement action has not been taken before the expiration period has elapsed as expired.

For example, if the expiration period set for authorization holds is set to 14 days, then any authorization holds created or updated 14 days ago are candidates to expire.

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 be take effect with the next AUTHORIZATION_HOLDS_EXPIRATION cron job to run.