Pre-authorization
A normal payment collects money in a single step. Pre-authorization splits that into two: first you place a hold on the customer's funds at checkout, then later you decide whether to capture the hold (collect the money) or void it (release it). It suits any business where the decision to charge — or the final amount — comes after checkout: hotels and car rentals confirming at check-in, marketplaces charging once a seller accepts, or anyone reserving funds at booking and settling at fulfillment.
The most important idea up front: an authorized payment is held, not paid. Nothing is collected until you capture it.
What Is Pre-authorization
The Two-Step Model
With pre-authorization enabled on a sub-merchant, eligible payments stop at a hold instead of being collected:
- Authorize — the customer completes checkout and the funds are reserved on their instrument. No money has moved.
- Capture or Void — later, from your server or Command Center, you either capture the hold (collect the funds) or void it (release them).
A normal sale does both at once and goes straight to Succeeded; a pre-authorization pauses at the authorized step and waits for your decision.
The Authorized State
When a hold is placed, the payment enters the Authorized state — the funds are reserved but not collected. The order, meanwhile, sits at Lapsed with a lapsed reason of Payment Authorized: this is not a failure, it signals the order is holding an authorization and awaiting your decision. Capturing moves the order to Completed.
| Stage | Payment status | Order status | Order lapsed reason |
|---|---|---|---|
| Hold placed | Authorized | Lapsed | Payment Authorized |
| Captured | Succeeded | Completed | — |
| Voided or expired | Reversed | Lapsed | Authorization Voided / Authorization Expired |
Do not fulfill an order, ship goods, or treat a payment as complete while it is Authorized — the funds are only held. Fulfil only after you capture it and see a capture_success. A checkout response can look like a success even when the payment is merely authorized, so always confirm via the payment_authorized webhook or the Transaction Enquiry API before acting.
The Pre-authorization Lifecycle
A captured authorization ends as Succeeded — from there it behaves like any normal payment. A voided or expired authorization ends as Reversed (see How an Authorization Ends).
The Authorization Timeline
Two timers govern a pre-authorization, and they run one after the other:
Authorization Confirmation Period
This is the window for the payment partner to confirm the authorization after checkout. Partners don't always respond instantly, so Nimbbl allows a short grace period before deciding the confirmation is too late. If the partner confirms within the window, the payment becomes Authorized; if it confirms too late, Nimbbl reverses the payment, because by then the order may have moved on. This window applies to every payment, pre-authorized or not — see the Payments guide for the underlying delayed-authorization setting.
Authorization Expiry Period
Once a hold exists, this is your window to capture or void it. It ends at the expiry time carried on the payment (authorization_details.expiry_time) — act before then. There is no separate "expired" state: Nimbbl always resolves the hold itself at the deadline, according to the expiry action set for your account.
The expiry action is configured with Nimbbl for your sub-merchant at onboarding — it is a required setting for any manual-capture sub-merchant, and there is no platform default. It has two values:
| Expiry action | What Nimbbl does at the deadline | Outcome |
|---|---|---|
void | Releases the hold — nothing is collected | Payment Reversed |
capture | Automatically collects the authorized amount | Payment Succeeded |
Confirm with Nimbbl which value your account carries before relying on inaction to do anything in particular: with void, inaction releases the funds; with capture, inaction collects them. The length of this window is the capture period configured for your account, capped by how long the payment partner keeps the hold open — so always rely on the expiry time you receive rather than a fixed duration.
There is no default — your account is configured for either void or capture at onboarding. If it's set to capture, letting an authorization reach its deadline charges the customer automatically. Confirm which expiry action applies to your account before relying on "doing nothing" to release a hold — and prefer an explicit capture or void over waiting for the deadline.
Capturing and Voiding
- Capture collects the held funds and triggers settlement. Capture is always for the full authorized amount — partial capture is not currently supported. The payment moves to Succeeded.
- Void releases the hold without charging the customer. The payment moves to Reversed. Once voided, an authorization cannot be captured.
You perform both from your server (see Pre-auth and Capture) or from Command Center.
How an Authorization Ends
An authorization ends in one of two ways. It can be captured — by you, or automatically at the deadline if your expiry action is capture — in which case the payment Succeeds. Otherwise the hold is released and the payment becomes Reversed, for one of three reasons:
| What happened | How it's delivered |
|---|---|
| You (or an operator in Command Center) voided the hold. | A void_success webhook. |
The expiry period passed and your expiry action is void, so Nimbbl released the hold automatically. | A void_success webhook — same shape as a merchant-initiated void. Use the comment field to check whether the void was done by you or an auto-void happened; see Pre-auth and Capture for the full picture. |
| The payment partner confirmed the authorization too late, during the confirmation period (not the expiry period). | A payment-level reversal, not a void — see Payment Reversed rather than the void events. |
Refunds After Capture
Once captured, a pre-authorized payment behaves like any Succeeded payment — you can refund it through the normal Refunds flow. The refundable amount is the captured amount, not the original authorized hold.
A payment is held only when it is processed as a pre-authorization. A payment processed as a normal sale is collected immediately and returns Succeeded, with no hold to capture or void. Your integration should handle both outcomes and can tell them apart from the payment status and the presence of authorization_details — see Sale vs Pre-authorization.
One Interface, Every Payment Partner
Nimbbl exposes a single capture and void interface and absorbs each payment partner's behaviour on the backend. You call capture or void the same way for every partner — you don't write partner-specific logic, and Nimbbl translates each call into whatever the underlying partner requires.