status value can be one of the following depending on the
state within the system and the status within the used payment service.
State diagram
The following state diagram serves as an overview of all the differentstatus
values and how they relate to each other.
Separate authorization and capture
Transactions where the originalintent is authorize.
Direct capture
Transactions where the originalintent is capture.
In some cases, a transaction with
intent set to capture is internally split
into a separate authorization and capture. When this happens, the transaction may
pass through authorization_succeeded and capture_pending before reaching a
terminal state such as capture_succeeded, or before being voided or declined.
See split authorization and capture
for more details.Timeouts
When Gr4vy forwards a payment request to a connector, network conditions can occasionally cause the request to time out before a response is received. In these cases, the outcome of the request is unknown — the connector may or may not have processed it. Rather than failing immediately or requiring you to re-submit, Gr4vy automatically retries these requests in the background when the connection supports idempotent requests. This guarantees the connector can return the result of the original request without creating a duplicate charge. Not every connection supports idempotent requests. When it doesn’t, Gr4vy can’t safely retry, and the request fails instead. See Timeouts without a retry.Transaction timeouts
When aPOST /transactions request to a connector times out, Gr4vy queues a background task to retry that transaction.
The transaction moves to processing status while Gr4vy resolves the outcome. No action is required on your side — in particular, do not re-submit the transaction while it is in processing.
Retries stop after a maximum of 24 hours from the original request, at which point the transaction is resolved to a final status.
Possible outcomes
In all cases a webhook event is sent when the outcome is known. Gr4vy recommends relying on webhooks rather than polling the transaction status.
Capture timeouts
When a capture request to a connector times out, and the connection supports idempotent requests, Gr4vy queues a background task to retry the capture. The capture moves topending status while Gr4vy resolves the outcome.
Retries stop after a maximum of 24 hours from the original request, at which point the transaction is resolved to a final status.
For a capture you request, Gr4vy only retries a capture that times out. A capture that’s declined or fails for another reason isn’t retried. To try again, call the capture endpoint again.
When Gr4vy splits a transaction with intent set to capture into a separate authorization and capture, and the capture fails without being declined, Gr4vy can make another capture attempt in the background. The transaction’s events can then show a failed capture followed by a successful one. A declined capture isn’t retried.
Possible outcomes
A webhook event is sent as soon as the outcome is known.
Refund timeouts
When a refund request to a connector times out, Gr4vy queues a background task to retry the refund. The refund moves topending status while Gr4vy resolves the outcome.
Retries stop after a maximum of 24 hours from the original request, at which point the transaction is resolved to a final status.
Possible outcomes
A webhook event is sent as soon as the outcome is known.
Timeouts without a retry
When a connection doesn’t support idempotent requests, a transaction whose request to the payment service times out ends asauthorization_failed with error_code set to timeout. Gr4vy doesn’t fail over to another connection in the Flow rule for a timed-out attempt.
The payment service may still have processed the payment. Gr4vy doesn’t apply results that arrive from the payment service after the transaction failed, and syncing the transaction doesn’t change its final status.
Before you charge the buyer again, check the payment at the payment service, for example, in its dashboard. If the payment went through, reverse it there.
Recommendations
- Listen for webhooks. The webhook event is the authoritative signal that a timeout has been resolved. Prefer it over polling.
- Do not re-submit. A resource with a
processingorpendingstatus is still being resolved. Re-submitting may risk duplicate charges. - Allow up to 24 hours. The resolution window for create timeouts is bounded at 24 hours. For captures the window depends on the connector.
- Contact support if nothing arrives. If 24 hours have passed and you have not received a webhook, contact Gr4vy support with the transaction ID.