Learn what each payment method status means, which stored payment methods you can charge, how a stored payment method can fail, and how to tell whether a transaction stored its payment method.
A payment method’s 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 payment method is stored but isn’t ready to use yet. Gr4vy is waiting for the payment service to confirm the setup, for example through a notification after the buyer completes a redirect.
buyer_approval_required
Storing the payment method needs approval from the buyer. Send the buyer to the approval_url to continue. This mainly applies to alternative payment methods like PayPal, where the buyer is redirected to approve.
succeeded
The payment method is stored and can be used to create transactions.
paused
The payment service paused the agreement or mandate behind the stored payment method. The payment method can’t be used until the payment service resumes it.
failed
The payment method couldn’t be stored, or the payment service reported that it’s no longer valid.
Only a payment method with the status succeeded can be used to create a
transaction with the id method. For any other status, the
new transaction request fails with an HTTP 400 error.
The error detail points to /payment_method/id and includes the current status, for example
Payment method has not been successfully stored. Current status: failed.Before you create a merchant-initiated transaction with a stored payment method,
get the payment method and check that its
status is succeeded. If it isn’t, ask the buyer to provide a payment method again.
A payment method moves to failed in the following cases.
The payment service doesn’t confirm the setup in time. Each payment service has a time limit for a payment method that is processing or buyer_approval_required. When the limit passes, the payment method moves to failed.
The payment service reports that the setup failed.
The payment service reports that a payment method that already succeeded is no longer valid, for example because the provider canceled the agreement behind it. This applies to payment methods other than cards and digital wallets. A stored card or digital wallet keeps the status succeeded once it reaches it.
If you store a card as part of a transaction and that transaction doesn’t succeed,
the card isn’t kept for later use.
Gr4vy doesn’t send a webhook when a stored payment method moves to failed.
Check the payment method’s status before you charge it.
When the payment service pauses or resumes a stored payment method, Gr4vy sends the
payment-method.paused and payment-method.resumedwebhooks.
Check whether a transaction stored its payment method
To find out if a transaction stored its payment method, get the transaction
and look at payment_method.id.
If payment_method.id is null, the payment method was never stored. Either the transaction wasn’t created
with store: true, or it was and the transaction didn’t succeed.
If payment_method.id has a value, the transaction used or stored that payment method.
The ID stays on the transaction after you delete the payment method.
To check whether a stored payment method still exists, get the payment method
with that ID. An HTTP 404 response means it’s deleted.Don’t use payment_source, merchant_initiated, or is_subsequent_payment for this check. These fields describe
the payment, not whether the payment method was stored.In the dashboard, the Usage row in the Payment method panel of a transaction shows the same information.
It reads Transient when the payment method was never stored, Stored when it’s stored, and
Stored & Deleted when it was stored and has since been deleted.
The following state diagram serves as an overview of all the different status
values and how they relate to each other. A card or bank account stored directly
through the API starts as succeeded.
