Payment Lifecycle

Every card payment moves through the same small set of states. Almost everything you are allowed to do next — and every question about which endpoint to call — depends on one thing: whether the payment has been captured yet.

Authorization

An authorization is a temporary hold on a customer's funds. It confirms that the customer has the necessary funds or credit for a purchase, without moving money from their account. By default Authorizations are captured immediately unless they have been configured to be manually captured or captured after a delay.

Manual capturing of Authorizations is often used in scenarios where the merchant needs to verify payment availability before finalizing the sale, such as in hospitality, car rentals, or e-commerce pre-orders.

Transaction

A transaction represents the final step in the payment process, where funds are moved from the customer’s account to the merchant’s account. This occurs when an authorization is captured by the merchant, confirming the sale and triggering the transfer of money.

Once an authorization is captured, it becomes a transaction, meaning that the funds are no longer just reserved; they’re actually transferred to the merchant, making the sale official.

Which modification is legal when

There are five modification endpoints. Which of them you can use depends on whether the payment is still an authorization or has already been captured into a transaction.

Action	Endpoint	While AUTHORIZED	Once CAPTURED
Adjust	/adjust	✅ Change the authorized amount	❌ Use refund instead
Capture	/capture	✅ Full or partial — this is the money move	❌ Already captured
Cancel	/cancel	✅ Releases the hold	❌ Use refund instead
Refund	/refund	❌ Nothing has moved yet	✅ Full or partial, with an optional reason
Reverse	/reverse	✅ Releases the hold	✅ Refunds the full amount

When in doubt, reverse

If you want to return the money and you do not want to track whether the capture has already happened, use Reverse. It releases the hold if the payment has not been captured, and refunds it in full if it has.

A few consequences of the table worth calling out:

• Partial captures and partial refunds are both allowed. A payment can sit part-captured or part-refunded for as long as you need. You may capture repeatedly until the authorized total is reached.
• Adjust is not a refund. Adjust re-sizes a hold that has not moved yet — send the new total, not the difference. Once the money has moved, a partial refund is the equivalent tool.
• Every modification is asynchronous. These endpoints answer Received, which means the request has been accepted and queued. The outcome arrives afterwards on a webhook — do not treat the API response as confirmation that the modification succeeded. Each modification gets its own payfacReference; the webhook names the authorization it applies to in originalPayfacReference — see Reference fields.

Key Authorization Concepts

Pre-Authorization vs. Final Authorization

Pre Auth

This is an initial hold placed on a customer’s funds when they initiate a payment. The funds are reserved but not yet transferred.

It’s used to confirm payment capacity and customer intent.

Example: A hotel might pre-authorize funds upon check-in to cover estimated charges.

Final Auth

This confirms the exact amount that will be charged, replacing the initial hold with the final amount to be captured.

A final-auth may be necessary if the total amount changes after the pre-auth (e.g., adding room charges in a hotel).

Authorization Duration

The hold duration varies by bank but typically lasts 28 days.

If the funds are not captured before the hold expires, the authorization will be released, and the funds will return to the customer’s account.

warning

There is no webhook for an expired authorization. If you use manual capture, track your uncaptured authorizations yourself and either capture or cancel them deliberately — otherwise the hold lapses quietly and the sale is lost.

When does an Authorization become a Transaction?

An authorization becomes a transaction when the merchant initiates a capture.

Immediate Capture:

In most cases, the capture happens automatically right after authorization, converting the hold into a transaction.

Delayed or Manual Capture

Merchants can choose to delay capture, especially when the final amount isn’t determined immediately (e.g., in services where additional charges may apply).