Skip to main content
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.

​
Charge a stored payment method

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.

​
How a stored payment method fails

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.resumed webhooks.

​
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.

​
State diagram

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.