# Authorization Holds
Source: https://docs.mambu.com/docs/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](/api/api-v2/cards/cards) in our API Reference.

For more information on the permissions needed to manage authorization holds setup, see the [Permissions](/docs/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](/api/api-v2/deposits/get-all-authorization-holds/) for a given deposit account or [details on a specific hold](/api/api-v2/cards/get-authorization-hold-by-id) 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](/docs/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.

| Card message Type | Debit Cards Availability | Credit Cards Availability |
| --- | :---: | :---: |
|Debit Authorization Request | YES | YES |
| Credit Authorization Request | YES | NO |
| Debit Authorization Advice | YES | NO |
| Credit Authorization Advice | YES | NO |
| Balance Inquiry | YES | YES |
| Full Authorization Reversal | YES | YES |
| Partial Authorization Reversal | YES | YES |

### 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](/api/api-v2/cards/create-authorization-hold) can only be performed via [Mambu API v2](/api/api-v2/cards/cards). 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](/api/api-v2/cards/create-authorization-hold) 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 problem, you can change the hold amount while calling the [dedicated cards PATCH authorization hold API](/api/api-v2/cards/patch-authorization-hold).

### Incremental authorization

Authorization holds with a `PENDING` status can be [increased](/api/api-v2/cards/increase-authorization-hold) 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](/api/api-v2/cards/decrease-authorization-hold) 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](/api/api-v2/cards/reverse-authorization-hold) 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](/api/api-v2/cards/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.

### Pin debit refund holds

Mambu supports a fraud prevention strategy for PIN debit refunds that addresses "double dipping" fraud. Instead of processing a `pindebit.refund` event as an immediate refund, Mambu places an internal hold on the incoming credit until the configured settlement window passes.

#### Mechanism
When a `pindebit.refund` event is received, Mambu creates an authorization hold in `PENDING` status if:
- The `com.mambu.allowRefundHold` tenant feature toggle is enabled for your tenant.
- The savings product associated with the account has the PIN debit refund hold setting enabled.

The funds are excluded from the available balance, preventing the client from spending the same funds twice before the refund is fully settled.

Refund holds are excluded from the standard authorization hold expiration flow — they are never expected to expire, and are settled exclusively by the `SETTLE_REFUND_HOLDS` job (see [Hourly authorization holds cron job](#hourly-authorization-holds-cron-job)).

#### Configuration
You can configure the behavior of PIN debit refund holds at the savings product level:
- **Enablement**: Whether PIN debit refunds should be converted to holds for accounts using this product.
- **Duration**: The number of hours before a refund hold is automatically settled. There is no default value — this must be explicitly configured.

These settings are managed via the [Create card savings product settings](/api/api-v2/cards/create-card-savings-product-settings) and [Get active card savings product settings](/api/api-v2/cards/get-active-card-savings-product-settings) API endpoints. Calling these endpoints requires the `CardsResource.allowRefundHold` API feature toggle to be enabled, along with the **Create Card Savings Product Settings** / **View Card Savings Product Settings** permissions under the Cards area.

:::note
`com.mambu.allowRefundHold` is a whitelist-type tenant feature toggle. To turn it on for a tenant, add the tenant to the `com.mambu.allowRefundHold.whitelist`.
:::

#### Settlement
PIN debit refund holds are settled by an hourly automated job, `SETTLE_REFUND_HOLDS`, which only runs if `com.mambu.allowRefundHold` is enabled for the tenant. This job settles any refund hold that has reached its configured duration and sets its status to `SETTLED`.

#### Reversals
If a `pindebit.refund.reversal` event is received, Mambu looks for a matching `PENDING` refund hold and triggers a reversal via the [Reverse authorization hold](/api/api-v2/cards/reverse-authorization-hold) endpoint. The hold is marked as `REVERSED` and the funds are released. If no PENDING refund hold is found (refund hold is already settled), the operation falls back to the regular financial transaction reversal flow.

#### Locked accounts
Refund hold operations (creation, settlement, and reversal) would normally fail if the deposit account linked to the card is `LOCKED`. To prevent held funds from lingering, or from being skipped during end-of-day processing, Mambu automatically and temporarily unlocks the account immediately before the operation and re-locks it immediately after, so the operation can proceed.

This temporary unlock behavior is controlled by the `com.mambu.temporaryUnlockForRefundHold` feature toggle. Disabling it reverts to the previous behavior, where refund hold operations fail on a locked account. This toggle only takes effect if `com.mambu.allowRefundHold` is also enabled.

### Authorization Holds Configuration

:::warning
We strongly recommend that you use an end-to-end test to test any configuration changes in your sandbox environment before implementing them in your production environment. The test should check that the hourly `AUTHORIZATION_HOLDS_EXPIRATION` cron job correctly sets authorization holds to expired. To perform a test on holds in the past contact us through [Mambu Support](/docs/mambu-support) so that we can assist you with manipulating the data in the database.
:::

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](/docs/configuration-as-code-for-authorization-holds). 

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

![Setting-an-expiration-date-for-authorization-holds](@site/static/img/support/authorization-holds-add-catogory-code.png)

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](/api/api-v2/cards/patch-authorization-hold).

### Hourly authorization holds cron job

The following hourly cron jobs run automatically to manage authorization holds:

* `AUTHORIZATION_HOLDS_EXPIRATION`: 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 more than 14 days ago are candidates to be expired. PIN debit refund holds are excluded from this job — see [Settlement](#settlement).
* `SETTLE_REFUND_HOLDS`: Automatically settles PIN debit refund holds that have reached their configured duration. Only runs if `com.mambu.allowRefundHold` is enabled for the tenant. For more information, see [Pin debit refund holds](#pin-debit-refund-holds).

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](/docs/automatic-end-of-day-actions) and [Hourly jobs](/docs/automatic-end-of-day-actions#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](/docs/transaction-holds).