Speed up customer checkout by using saved card details

You can offer a 1-click checkout experience by saving a customer's card details and displaying them during the checkout process. To do this, you first need to clarify and update your service's Terms and Conditions about how you handle personal and financial data to comply with local regulations.

Overview​

Check the following high-level procedure to implement a 1-click checkout process using the Revolut Checkout Widget and the Merchant API:

1. Save card details on Revolut
2. (Optional) Get card details from Revolut to be stored on your server
3. Display saved cards on the checkout page
4. Use the /payments endpoint to initiate payment
5. Handle 3DS challenge and track payment state
6. Handle payment completion

Step 1. Save card details on Revolut​

To save a customer's card details by completing an order, see: Save the card details of a customer.

There are two ways of saving a payment method, you can save it either for the customer or merchant by initialising the Revolut Checkout Widget with the savePaymentMethodFor parameter set to merchant or customer.

In case of a 1-click checkout process, the customer will initiate the payment, so you have to save the payment method for the customer (savePaymentMethodFor: "customer"). If you also plan to manage subscriptions or take merchant initiated transactions, you can use savePaymentMethodFor: "merchant" as it will serve both cases. For more information about subscription management, see: Manage subscriptions.

See an example with the createCardField instance:

RevolutCheckout("<token>").then(function (instance) {
  var card = instance.createCardField({
    target: document.getElementById("card-field"),
    onSuccess() {
      window.alert("Thank you!");
    },
    onError(message) {
      window.alert("Oh no :(");
    },
  });

  document
    .getElementById("button-submit")
    .addEventListener("click", function () {
      card.submit({
        savePaymentMethodFor: "customer",
      });
    });
});

(Optional) Step 2. Get card details from Revolut to be stored on your server​

Storing card details can be helpful when you have more websites, and you want to provide a faster checkout experience across all your sites. However, if you choose to store card details, you must ensure that these are in sync with the ones on the Merchant API.

Use the last paid order of the customer to retrieve a customer's card details stored on Revolut's server. Fetch and save the information from the response of the Retrieve payment list of an order endpoint.

See an example of a saved payment_method JSON object, returned by the endpoint:

[
  {
    "id": "64a28499-aa14-a504-ab1b-fb64dd38b342",
    "order_id": "64a28331-7d61-a4b0-b5f8-df0446ce4ca1",
    "state": "captured",
    "payment_method": {
      "type": "card",
      "id": "64a28499-05c5-af30-bbf9-9c1b028e00b8",
      "brand": "mastercard_credit",
      "last_four": "1234"
    }
  }
]

You can use this JSON object to retrieve and save a customer's payment details on your server.

Step 3. Display saved cards on the checkout page​

Based on whether you store customer's payment methods on your server (Step 2.), you have two main approaches to display saved cards during checkout:

• Display payment methods stored on your server
• Display payment methods by fetching the Retrieve all payment methods of a customer endpoint

Step 4. Use /payments endpoint to initiate payment​

To initiate a payment send a POST request to the Pay for an order endpoint, with the following payload:

{
  "saved_payment_method": {
      "type": "card",
      "id": "<ID of the saved payment method>",
      "initiator": "customer"
}

Step 5. Handle 3DS challenge and track payment state​

After your backend sends the request to the /payments endpoint, the response will have authentication_started or authorisation_started payment state. Set up an automated request, using the order_id from the response, that repeatedly checks the payment status to track the payment's state transitions.

For more information about this endpoint, see: Merchant API: Retrieve payment details.

When the payment state is authentication_challenge the response will have an authentication_challenge object. This object contains the URL (authentication_challenge.acs_url) where your customer can complete the 3DS challenge. See an example JSON of a payment response in authentication_challenge state:

{
  "id": "5e96b328-4054-41ed-b089-595ccc4d0870",
  "order_id": "a16718e0-077a-4942-89bc-23ac17a2e14c",
  "payment_method": {
    "type": "card"
  },
  "state": "authentication_challenge",
  "authentication_challenge": {
    "type": "three_ds",
    "acs_url": "https://authenticate.me"
  }
}

You can use a redirect page or a pop-up window to proceed with the challenge. Send a GET request to the acs_url to display it to your customer and continue polling the payment state.

Your backend should continue to check the payment state until the response contains a final payment state. Depending on the received final payment state, you need to do the following:

Step 6. Handle payment completion​

If the payment transitioned to one of the successful final states (captured, completed), the corresponding order transitions to completed state. You can stop polling the payment status, and redirect the customer to your confirmation page to inform your customers about the status of their purchase.

Send the receipt of the payment​

You have two options to check for order completion:

• Retrieve order information by using the Retrieve an order endpoint
• Use a webhook to track ORDER_COMPLETED events

When you confirmed that the order is completed, your system should send a notification (e.g. email) to the customer containing the following:

• Detailed receipt of the payment (including tax rates applied)
• Information about the payment method used and how to change it
• Date when the payment was collected
• Information about the refunding process

Troubleshooting​

The above-described process assumes that everything is working as expected. However, your system should be prepared to handle error cases. To test different payment errors, use the test cards for error cases in the Sandbox environment.

You have two options to check for error events:

• Use payment status polling to catch unsuccessful final states (declined, failure).
• Use a webhook to receive ORDER_PAYMENT_DECLINED, ORDER_PAYMENT_FAILED events.

When you catch an error, your system should send a notification (e.g. email) to the customer containing the following:

• Detailed information about the order (including tax rates applied).
• Information about the unsuccessfully charged payment method.
• Information about why the payment failed. You can retrieve this information from the payments.decline_reason field from the response of the Retrieve an order endpoint, using the unsuccessful order's id. To learn more, check our failure reasons.
• Information about how to resolve the issue:
  • Ask the customer to top up their saved payment method.
  • Ask the customer to provide another payment method. Redirect them to a page where you initialise the Revolut Checkout Widget, using the unsuccessful order's token and saving the new payment method.