Payments.paymentRequest

Display the Payment request button to allow your customers to make a payment with Apple Pay and Google Pay.

How to mount the Payment request button

To mount the Payment request button on your website:

First, import the RevolutCheckout package.
Call the .payments() method, to get the Payments object.
Define the relevant options including the asynchronous createOrder function.
Call the payments.paymentsRequest() to instantiate the Payment request object.
Call the .canMakePayment() method, to check if Apple Pay and Google Pay is available.
Render the Payment request button to allow your customers to make payments with Apple Pay and Google Pay.
Listen to relevant events.

import RevolutCheckout from "@revolut/checkout"

const { paymentRequest } = await RevolutCheckout.payments({
  locale: "en", // Optional, defaults to "auto"
  publicToken: "<yourPublicApiKey>", // Merchant public API key 
})

const options = {
  currency: "USD", // 3-letter currency code
  amount: 1000, // In lowest denomination e.g., cents

  createOrder: async () => {
    // Call your backend here to create an order
    // For more information, see: https://developer.revolut.com/docs/merchant/create-order
    const order = await yourServerSideCall()
    return { publicId: order.token }
  },
  onSuccess() { },
  onError(error) { },
  onCancel() { },

  // You can put other optional parameters here
}

const instance = paymentRequest(target, options)
const method = await instance.canMakePayment()
if (method) {
  instance.render()
} else {
  instance.destroy()
}

Options

Payment request accepts two arguments:

paymentRequest(target, options)

Use the target to define where the Payment request button will be rendered on your page.

Use the Options object to define Payment request checkout options, such as shipping information, and customize the display of the Payment request button:

paymentRequest(target: HTMLElement, options: Options): PaymentRequestInstance 

interface PaymentRequestInstance {
  destroy: () => void
  render: () => Promise<void>
  canMakePayment: () => Promise<PaymentRequestPaymentMethod | null>
}

interface Options {
  amount: number
  currency: string
  createOrder: () => Promise<{ publicId: string }>
  validate?: (payload: PaymentValidationPayload) => void | Promise<void>
  preferredPaymentMethod?:
    | PaymentRequestPaymentMethod
    | PaymentRequestPaymentMethod[]
  buttonStyle?: {
    height?: string
    radius?: "none" | "small" | "large" | "round"
    size?: "none" | "small" | "large"
    variant?: "light" | "dark" | "light-outlined"
    action?: "subscribe" | "donate" | "pay" | "buy"
  }

  requestPayerName?: boolean
  requestShipping?: boolean
  shippingOptions?: ShippingOption[]
  onShippingOptionChange?: (shippingOption: ShippingOption) => Promise<{
    status: "fail" | "success"
    total: {
      amount: number
      label?: string
    }
  }>
  onShippingAddressChange?: (shippingAddress: Address) => Promise<{
    status: "fail" | "success"
    shippingOptions?: ShippingOption[]
    total: {
      amount: number
      label?: string
    }
  }>
}

type PaymentRequestPaymentMethod = "applePay" | "googlePay"

type PaymentValidationPayload = {
  email?: string
  shippingAddress?: W3CPaymentAddress
  billingAddress?: W3CPaymentAddress
}

interface PaymentAddress {
  addressLine: ReadonlyArray<string>
  city: string
  country: string
  dependentLocality: string
  phone: string
  postalCode: string
  recipient: string
  region: string
  sortingCode: string
}

interface ShippingOption {
  id: string
  label: string
  amount: number
  description?: string
}

type Address =
  | {
      city: string
      phone: string
      region: string
      country: string
      recipient: string
      postalCode: string
      sortingCode: string
      addressLine: string[]
      dependentLocality: string
    }
  | {
    city: string
    region: string
    country: string
    postalCode: string
  }

Parameter	Description	Format	Required
`target`	Determines where the Payment request button will be rendered on your site (e.g., a DOM node like, `document.getElementById("kiwi")`).	HTML Element	Yes

Options object:

Parameter	Description	Format	Required
`currency`	ISO 4217 currency code in upper case. info For more information about the supported currencies, see: Help Center.	String	Yes
`amount`	The amount to be paid by the customer, given in the lowest denomination (e.g. cents).	Number	Yes
`createOrder`	Callback function handling the order creation operation, and returning the `token`. For more information, see: Merchant API: Create an order.	Function	Yes
`onSuccess`	Callback when the payment is successfully completed	Function
`onError`	Callback if a transaction fails, and the reason is available in the `error` parameter.	Function
`onCancel`	Callback if a user did not complete the transaction and cancelled the authorisation, or closed the payment pop-up window.	Function
`preferredPaymentMethod`	Specify preferred method (`applePay` or `googlePay`) or an array of methods in order of preference	String or Array of strings
`validate`	You can define an asynchronous function that needs to be fulfilled before payment is processed. The function should throw an error in case the validation failed.	Function	No
`requestPayerName`	If `true`, the customer is required to provide the payer name on the payment sheet of the payment request. Default: `true`.	Boolean	No
`requestShipping`	If `true`, the shipping address and delivery method are quickly collected through Apple Pay or Google Pay from the user. Default: `false`.	Boolean	No
`shippingOptions`	An array of `ShippingOption` objects that define the shipping options that will be available to the user	Array
`onShippingOptionChange`	Function to determine the behaviour of the widget when shipping options change.	Function
`onShippingAddressChange`	Function to determine the behaviour of the widget when shipping address changes.	Function
`buttonStyle`	Dictionary that controls the style of the button.	Dictionary	No

buttonStyle object:

Parameter	Description	Format	Required
`action`	Replace the default display text for the payment action. For example, `Buy with Apple Pay`. This can be useful depending on the context of the button. Default: `null` Possible values `subscribe` `donate` `pay` `buy`	Enum	No
`size`	Controls whether the button should occupy the full width of the division it is in (`large`) or not (`small`). Default: `large` Possible values `large` `small`	Enum	No
`radius`	Controls the size of the border radius. Default: `small` Possible values `none` `large` `small`	Enum	No
`variant`	Control the colour theme of the button. Default: `dark` Possible values `dark` `light` `light-outlined`	Enum	No
`height`	Controls the height of the button. Accepts actual CSS values, for example: `10px`	String	No

Returns

Methods object:

Parameter	Description	Format	Required
`render`	Render the payment request button.	Function	No
`canMakePayment`	Check if the user has support for a payment method e.g., Apple Pay or Google Pay.	Function	No
`destroy`	Manually destroy the button if needed.	Function	No

Listen to events

Use the following callbacks to listen to relevant Payment request events:

Event	Description
`onSuccess`	The payment is successful.
`onError`	The payment fails, called with an `error` object.
`onCancel`	The payment is cancelled, for example, the user closed the pop-up window.

Examples

Insert the following DOM element into your webpage where you want to render the Payment request button, and pass the element as the first argument to the paymentRequest:

your-page.html
<div id="payment-request"></div>

Example with minimal required values

your-page.js
import RevolutCheckout from "@revolut/checkout"

const { paymentRequest } = await RevolutCheckout.payments({
  publicToken: "<yourPublicApiKey>" // Merchant public API key
})

const options = {
  currency: "USD", // 3-letter currency code
  amount: 1000, // In lowest denomination e.g., cents
    
  createOrder: async () => {
    // Call your backend here to create an order
    // For more information, see: https://developer.revolut.com/docs/merchant/create-order
    const order = await yourServerSideCall()
    return { publicId: order.token }
  },
  onSuccess() { },
  onError(error) {
    console.error(error)
  },
  onCancel() {
    console.log("Payment was cancelled.")
  },

  // You can put other optional parameters here
}

const target = document.getElementById("payment-request")

const paymentRequestInstance = paymentRequest(target, options)
const method = await instance.canMakePayment()
if (method) {
  paymentRequestInstance.render()
} else {
  paymentRequestInstance.destroy()
}

Example with additional parameters

my-app.js
import RevolutCheckout from "@revolut/checkout"

const target = document.getElementById("payment-request")

const shippingOptions = [
  {
    id: "standard-shipping",
    label: "Standard shipping",
    amount: 200,
    description: "Standard delivery in 5-7 business days"
  }
]

const { paymentRequest } = await RevolutCheckout.payments({
  locale: "en", // Optional, defaults to "auto"
  publicToken: "<yourPublicApiKey>", // Merchant public API key 
})

const paymentRequestInstance = paymentRequest(target, {
  currency: "USD", // 3-letter currency code
  amount: 1000, // In lowest denomination e.g., cents
  createOrder: async () => {
    // Call your backend here to create an order
    // For more information, see: https://developer.revolut.com/docs/merchant/create-order
    const order = await yourServerSideCall()
    return { publicId: order.token }
  },
  requestPayerName: false,
  requestShipping: true,
  shippingOptions,
  onShippingOptionChange: (selectedShippingOption) => {
    // Calculate new total price. This could involve server-side logic to validate and calculate costs
    return Promise.resolve({
      status: "success",
      total: {
        amount: 777 + selectedShippingOption.amount, // Recalculate total cost
      },
    });
  },
  onShippingAddressChange: (selectedShippingAddress) => {
    // Introduce a new shipping option based on the changed address
    // This could involve server-side logic to validate the new address, fetch shipping option details, and calculate costs
    const newShippingOption = {
      id: "ultra-fast",
      label: "Ultra-fast shipping",
      amount: 500, // Additional cost for the new shipping method
      description: "Ultra-fast delivery in 1-2 business days",
    };

    return Promise.resolve({
      status: "success",
      shippingOptions: [newShippingOption, ...shippingOptions], // Add the new shipping option to the list
      total: {
        amount: 777 + newShippingOption.amount, // Recalculate total cost
      },
    });
  },
  buttonStyle: {
    radius: "small",
    size: "small",
    variant: "light-outline",
    action: "buy"
  },
  onSuccess() {
    // Do something to handle successful payments
    window.alert("Thank you!")
  },
  onError(error) {
    // Do something to handle payment errors
    window.alert(`Something went wrong. ${error}`)
  }
})

const method = await paymentRequestInstance.canMakePayment()
if (method) {
  paymentRequestInstance.render()
} else {
  paymentRequestInstance.destroy()
}

PreviousPayments.revolutPay

NextThe upsell object

How to mount the Payment request button
Options
Returns
Listen to events
Examples
- Example with minimal required values
- Example with additional parameters

Payments.paymentRequest

How to mount the Payment request button​

Options​

Returns​

Listen to events​

Examples​

Example with minimal required values​

Example with additional parameters​