Skip to main content
Most card payments happen in two stages. First, an authorization reserves the funds with the customer’s bank, but no money moves. Then, a capture requests those funds for settlement. An authorization is only valid for a limited period. If you capture after that period has passed, the capture can be declined because the authorization is no longer valid. Reauthorization solves this by creating a new authorization at capture time and capturing that instead, so funds can still be claimed against a stored payment method.

​
How it works

When a capture request is made, Gr4vy checks whether reauthorization applies before attempting the capture:
  1. Check that reauthorization is enabled for your account.
  2. Check the request. The capture request body must contain "reauthorize_if_authorization_expired": true.
  3. Check the payment method. The transaction must have a stored payment method.
  4. Check the authorization’s validity. Gr4vy checks whether the authorization being captured has passed its validity period, based on the card scheme and environment. See Validity periods below.
  5. Check the transaction. The transaction must meet the conditions in Eligibility below.
If the validity period has passed and the transaction is eligible, Gr4vy creates a new transaction based on the previous transaction and authorizes again. The new authorization is for the amount still available to capture, which is the authorized amount minus anything already captured. For a transaction with no captures, this is the full authorized amount. The new transaction is created on the same payment service as the previous transaction. Your routing rules are not evaluated again, so the reauthorization always follows the original transaction rather than being routed afresh. When the previous transaction has captures, line item and monetary breakdown data is not copied to the new transaction, because it no longer reconciles with the smaller reauthorized amount. Your own references, such as the purchase order number, are still copied. Gr4vy then handles the outcome as follows:
  • If the new authorization succeeds, Gr4vy captures the new authorization and returns the new transaction. A new transaction ID is returned in the capture response, and the new transaction has a reauthorized_from_transaction_id field set to the ID of the previous transaction. If the previous transaction has no captures, Gr4vy also schedules an asynchronous void of the previous authorization. If it has captures, whether the remaining authorization is voided depends on the payment service. See Connections for the behavior of your payment service.
  • If the reauthorization is declined, Gr4vy continues to attempt to capture the previous authorization and returns the old transaction in the response.
  • If the new authorization is left processing, Gr4vy voids the new authorization and the capture request fails.

​
Eligibility

A transaction is only reauthorized when all of the following are true:
  • The transaction is authorized and not yet captured, or it is partially captured with an amount still available to capture. Partially captured transactions are only reauthorized in the multi captures flow.
  • The transaction has no final capture. After a final capture, no further captures are possible, so reauthorizing serves no purpose.
  • The transaction has no pending capture. When a capture is pending, the capture request continues against the existing authorization and no error is returned, so a reauthorization that you expected can silently not happen.
  • The transaction was created to authorize funds, rather than to authorize and capture in a single step.
  • The card scheme is one of the schemes listed in Validity periods. Cards on any other scheme are never reauthorized.

​
Validity periods

The validity period of an authorization depends on the card scheme and the environment. If the authorization being captured is older than the period shown below, it is treated as expired and reauthorization is attempted.

​
Production

​
Sandbox

Sandbox uses the same validity periods as production, except for Mastercard and Visa, which expire almost immediately. This lets you test the reauthorization flow without waiting for the production validity period to pass.

​
Refunds after reauthorization

When a partially captured transaction is reauthorized, the previous transaction keeps the amount it already captured and the new transaction captures the remainder. A single order is then represented by two transactions, each holding part of the captured total.
Refunding the full amount of a reauthorized partial capture requires two refund requests, one against each transaction ID. Refunding only the new transaction does not return the amount captured by the previous transaction.
This does not apply to a transaction that had no captures before it was reauthorized. In that case the previous authorization holds no money, and the new transaction alone represents the order.

​
Examples

Both examples start from an authorization of 1000 that has passed its validity period, captured with "reauthorize_if_authorization_expired": true.

​
Reauthorizing an authorization with no captures

Nothing has been captured, so the full 1000 is still available. Gr4vy reauthorizes for 1000, captures the new authorization, and schedules a void of the previous one. The order is represented by the new transaction alone, and a full refund is a single refund of 1000 against it.

​
Reauthorizing a partially captured authorization

A capture of 400 has already succeeded with "final": false, leaving 600 available. Gr4vy reauthorizes for 600, not 1000, and captures the new authorization. The previous transaction keeps its 400. The order is now represented by two transactions. A full refund of 1000 is two refunds: 400 against the previous transaction, and 600 against the new one.