> ## Documentation Index
> Fetch the complete documentation index at: https://wpay-feat-edp-guide.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Vault a redirect payment method

> Store an alternative payment instrument like PayPal or GoCardless for future use.

At the moment, our API allows you to vault payment methods for the services
below.

* GoCardless
* PayPal

A redirect payment method can be stored by calling the
[`POST /payment-methods`][api] API. The call requires a `method`, a
`redirect_url`, a `country` (optional) and a `currency` (optional).
Additionally, the API call accepts a `buyer_id` or `buyer_external_identifier`
which can be used to associate a card to a previously created [buyer].

<Warning>
  **2-step process**

  Storing a redirect payment method is a 2-step process that requires a
  buyer-redirect to get explicit authorization.
</Warning>

## Step 1. Initialize a new redirect payment method

The first step is to initialize a new redirect payment method. A `redirect_url`
needs to be provided to redirect the user back to your application after they
have approved access to their account. However, `country` and `currency` are
optional and depend on the service to be used to vault the payment method.

In this example, we will use GoCardless to create a payment method.

<CodeGroup>
  ```bash cURL
  curl -i -X POST "https://api.example.gr4vy.app/payment-methods" \
      -H "Authorization: Bearer [JWT_TOKEN]" \
      -H "Content-Type: application/json" \
      -d '{
          "method": "paypal",
          "redirect_url": "https://example.com/complete",
          "buyer_external_identifier": "user-789123",
          "country": "AU",
          "currency": "AUD"
        }'
  ```

  ```js Node
  const fetch = require("node-fetch");

  fetch("https://api.example.gr4vy.app/payment-methods", {
    method: "POST",
    headers: {
      Authorization: "Bearer [JWT_TOKEN]",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      method: "paypal",
      redirect_url: "https://example.com/complete",
      buyer_external_identifier: "user-789123",
      country: "AU",
      currency: "AUD",
    }),
  });
  ```
</CodeGroup>

The API returns a new `payment-method` resource for which the `status` is set to
`buyer_approval_required`.

```json POST /payment-methods
{
  "type": "payment-method",
  "id": "12f246af-ed06-48e7-b235-3379dcf5a21f",
  "status": "buyer_approval_required",
  "method": "paypal",
  "external_identifier": null,
  "buyer": {
    "type": "buyer",
    "id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
    "external_identifier": "user-789123",
    "display_name": "John L.",
    "created_at": "2021-11-03T17:47:24.623364+00:00",
    "updated_at": "2021-11-03T17:47:24.623364+00:00"
  },
  "created_at": "2021-11-03T17:47:24.623364+00:00",
  "updated_at": "2021-11-03T17:47:29.705446+00:00",
  "label": null,
  "scheme": null,
  "expiration_date": null,
  "approval_url": "https://pay-sandbox.paypal.com/billing/static/flow?id=BRF00003ZFH392FD9541FSK2X0Q7Z5N6"
}
```

## Step 2. Redirect the user

For the next step, you will need to redirect the buyer to the URL specified in
the `approval_url` field of the response.

The buyer then logs in to their account and authorizes it to be used by Gr4vy.
After this, the buyer is redirected back to the `redirect_url` you specified
earlier. For example:

```
http://localhost:3000?complete?payment_method_id=77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5&payment_method_status=succeeded
```

The `payment_method_id` query parameter represents the ID of the payment method
that this account has been stored as. The `status` represents the status of the
payment method, which in most cases should be `stored`.

## (Optional) Step 3. Confirm the authorization

Finally, you could make an optional API call to confirm the payment method has
been fully stored.

<CodeGroup>
  ```bash cURL
  curl -i -X GET "https://api.example.gr4vy.app/payment-methods/12f246af-ed06-48e7-b235-3379dcf5a21f" \
      -H "Authorization: Bearer [JWT_TOKEN]"
  ```

  ```js Node
  const fetch = require("node-fetch");

  fetch(
    "https://api.example.gr4vy.app/payment-methods/12f246af-ed06-48e7-b235-3379dcf5a21f",
    {
      method: "GET",
      headers: {
        Authorization: "Bearer [JWT_TOKEN]",
      },
    }
  );
  ```
</CodeGroup>

The API will return the same `payment-method` resource with its updated status.

```json GET /payment-methods/77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5/authorize
{
  "type": "payment-method",
  "id": "12f246af-ed06-48e7-b235-3379dcf5a21f",
  "status": "succeeded",
  "method": "paypal",
  "external_identifier": null,
  "buyer": {
    "type": "buyer",
    "id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
    "external_identifier": "user-789123",
    "display_name": "John L.",
    "created_at": "2021-11-03T17:47:24.623364+00:00",
    "updated_at": "2021-11-03T17:47:24.623364+00:00"
  },
  "created_at": "2021-11-03T17:47:24.623364+00:00",
  "updated_at": "2021-11-03T17:52:14.323223+00:00",
  "label": null,
  "scheme": null,
  "expiration_date": null,
  "approval_url": null
}
```

[api]: /reference/payment-methods/new-payment-method

[buyer]: /guides/api/resources/buyers/add