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

2-step process

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

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.

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"
      }'

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

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.

cURL

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

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

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
}