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.
It's your responsibility as a merchant to meet local legislation requirements and be PCI DSS compliant.
Check the following high-level procedure to implement a 1-click checkout process using the Revolut Checkout Widget and the Merchant API:
/payments
endpoint to initiate paymentTo 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",
});
});
});
You can also use the payWithPopup
instance of the Revolut Checkout Widget to save a customer's payment method.
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.
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:
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"
}
For this checkout process, only use requests with initiator: customer
. Revolut will ensure that the payment is PDS2 compliant by initiating a 3DS challenge. For more information about Revolut's 3DS solution, see: 3D Secure overview.
For more information about Revolut's 3DS solution, see: 3D Secure overview.
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:
Payment state | Description |
---|---|
captured | You can handle captured payments as completed and continue with Step 6. It usually takes 24 hours to settle payments on your Merchant Account (except in case of instant settlement). |
completed | In case of instant settlements, captured payments instantly get settled to your Merchant Account, so the payment transitions to completed state. Continue with Step 6. |
authorised | In case you capture payments manually, payments stay in authorised state until you capture them, to learn more about the process, see: Authorise an amount to capture later. After you captured the payment, continue with Step 6. |
declined | The payment was declined for some reason, check the Troubleshooting section to learn more about how to resolve the issue. For more information about specific decline reasons, see: Decline reasons. |
failed | The payment failed for some reason, check the Troubleshooting section to learn more about how to resolve the issue. For more information about specific decline reasons, see: Decline reasons. |
cancelled | If you capture payments manually, a payment in authorised state can be cancelled via the Cancel an order endpoint. If you want to reinitiate the payment, a new order has to be created. Restart the checkout process from creating the order. |
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.
Optionally, you can also set up webhooks to track order completion. However, Revolut only sends webhook events when a final order state is reached (ORDER_COMPLETED
, ORDER_PAYMENT_DECLINED
, ORDER_PAYMENT_FAILED
).
If you only rely on webhook events, your system cannot react to intermediate payment state transitions. For more information about using webhooks, see: Using webhooks to keep track of the payment lifecycle.
You have two options to check for order completion:
ORDER_COMPLETED
eventsWhen you confirmed that the order is completed, your system should send a notification (e.g. email) to the customer containing the following:
Local regulations may differ in what is required for such notification. It is your responsibility to consider the requirements of local regulators and comply with the relevant laws.
You've successfully implemented a 1-click checkout process using the Revolut Checkout Widget and the Merchant API.
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:
declined
, failure
).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:
payments.decline_reason
field from the response of the Retrieve an order endpoint, using the unsuccessful order's id
. To learn more, check our decline reasons.token
and saving the new payment method.