status value can be one of the following depending on the
state within the system and the status within the used payment service.
status | Description |
|---|---|
processing | The transaction record has been created in the system and is now being processed with payment services. |
buyer_approval_pending | The transaction was created but needs approval from the buyer either by redirecting them to a hosted page or their bank for 3DS. |
authorization_succeeded | The transaction has been successfully authorized but not yet captured. |
authorization_failed | The transaction could not be authorized with any payment service due to technical issues or limitations of the payment service. |
authorization_declined | The transaction was declined by the payment service. |
capture_pending | The transaction has successfully been submitted for capture with a payment service and is now pending with them. |
capture_succeeded | The transaction has been successfully authorized and captured. |
authorization_void_pending | The transaction authorized transaction is in the process of being voided. |
authorization_voided | The transaction was successfully authorized but has since been voided before it was captured. |
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 idempotent requests are supported. This guarantees the connector can return the result of the original request without creating a duplicate charge.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
| Outcome | Transaction status | Webhook event |
|---|---|---|
| Authorization succeeded | authorization_succeeded | transaction.authorized |
| Authorization failed | authorization_failed | transaction.failed |
| Unresolved after 24 hours | authorization_failed | transaction.failed |
Capture timeouts
When a capture request to a connector times out, 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.
Possible outcomes
| Outcome | Capture status | Webhook event |
|---|---|---|
| Capture succeeded | succeeded | capture.succeeded |
| Capture failed | failed | capture.failed |
| Capture declined | declined | capture.declined |
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
| Outcome | Refund status | Webhook event |
|---|---|---|
| Refund succeeded | succeeded | refund.succeeded |
| Refund failed | failed | refund.failed |
| Refund declined | declined | refund.declined |
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.