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.
payment-method.paused and payment-method.resumed webhooks.
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.
