> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment method statuses

> Learn what each payment method status means, which stored payment methods you can charge, and how a stored payment method can fail.

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

## 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](/reference/transactions/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](/reference/payment-methods/get-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.

<Warning>
  Gr4vy doesn't send a webhook when a stored payment method moves to `failed`.
  Check the payment method's `status` before you charge it.
</Warning>

When the payment service pauses or resumes a stored payment method, Gr4vy sends the
`payment-method.paused` and `payment-method.resumed` [webhooks](/guides/features/webhooks/events).

# 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`.

```mermaid theme={"system"}
flowchart LR
    start(( )) --> processing
    start --> succeeded
    processing --> buyer_approval_required
    processing --> failed
    buyer_approval_required --> failed
    buyer_approval_required --> succeeded
    processing --> succeeded
    succeeded --> paused
    paused --> succeeded
    succeeded -->|Not cards or digital wallets| failed
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.