Instance.createCardField

Create a card field, which is available on the Instance.

Options

Use the Options object to specify the pages where the customer should be redirected, any styling parameters and any additional information related to the payment of the customer:

type InstanceCreateCardField = (
  options: Options
) => {
  submit: (meta: Meta) => void;
  validate: () => void;
  destroy: () => void;
};

type RevolutCheckoutError = {
  type: string;
  message: string;
  code?: number;
}

type Options = {
  target: HTMLElement;
  onSuccess?: () => void;
  onError?: (error: RevolutCheckoutError) => void;
  onValidation?: (messages: string[]) => void;
  onCancel?: () => void;
  locale?: string;
  styles?: {
    default?: Object;
    focused?: Object;
    invalid?: Object;
    empty?: Object;
    autofilled?: Object;
    completed?: Object;
  };
  classes?: {
    default?: string;
    focused?: string;
    invalid?: string;
    empty?: string;
    autofilled?: string;
    completed?: string;
  };
};


type Meta = {
  name: string;
  email?: string;
  phone?: string;
  savePaymentMethodFor?: string;
  cardholderName?: string;
  billingAddress?: {
    countryCode: string;
    region?: string;
    city?: string;
    postcode: string;
    streetLine1?: string;
    streetLine2?: string;
  };
  shippingAddress?: {
    countryCode: string;
    region?: string;
    city?: string;
    postcode: string;
    streetLine1?: string;
    streetLine2?: string;
  };
};

Option	Description	Format
`onSuccess`	Callback is called when the payment is completed successfully.	Function
`onError`	Callback if the transaction fails to complete. The reason for the failure is available in the `message` parameter.	Function
`onValidation`	Callback called on validation of the status change. Function contains `messages` as first parameter (see below).	Function
`onValidation.messages`	Array of strings that contains validation errors (e.g. `Your card has expired`).	String
`onCancel`	Callback if a user did not complete the transaction and cancelled the authorisation or closed the checkout window.	Function
`locale`	Controls the language of the text in the widget. Possible values are: `auto` (default) - detect using browser locale, `en` (English), `en-US` (English - US), `es` (Spanish), `de` (German), `fr` (French), `it` (Italian), `nl` (Dutch), `pl` (Polish), `pt` (Portuguese), `cs` (Czech), `hu` (Hungarian), `sk` (Slovak), `ja` (Japanese), `sv` (Swedish), `bg` (Bulgarian), `el` (Greek), `ro` (Romanian), `lt` (Lithuanian), `hr` (Croatian)	String
`theme`	Controls the color scheme of the widget. Possible values are: `light` (default), `dark`	String
`target`	DOM element where secure iframe with the card field input is rendered.	HTML Element
`styles`	Object of styles for different state of card field input, used to customize different states inside the secure iframe.	Object
`styles.default`	Base styles that are always applied regardless of state.	Object
`styles.focused`	Applied when a user focuses inside the input with a mouse or a keyboard.	Object
`styles.invalid`	Applied on validation error.	Object
`styles.empty`	Applied when a user hasn't entered any amount.	Object
`styles.autofilled`	Applied when a user used autofilled card details from the browser.	Object
`styles.completed`	Applied if the card field input is completed without any errors.	Object
`classes`	Same as `styles` but used to apply styles with classes to the `target` element outside the secure `iframe`.	Object
`classes.default`	Set default to `'rc-card-field'`.	String
`classes.focused`	Set default to `'rc-card-field--focused'`.	String
`classes.invalid`	Set default to `'rc-card-field--invalid'`.	String
`classes.empty`	Set default to `'rc-card-field--empty'`.	String
`classes.autofilled`	Set default to `'rc-card-field--autofilled'`.	String
`classes.completed`	Set default to `'rc-card-field--completed'`.	String

Returns

Methods object:

Field	Description	Format
`methods.destroy`	Manually destroy card field if needed	Function
`methods.submit`	Submit the card details that a user entered and complete the payment with additional customer metadata. Accepts a single `meta` parameter (see below)	Function
`methods.validate`	Manually trigger validation of the card details that a user entered. By default, it's triggered only after a user starts to enter card details and on submit.	Function

Meta object:

Field	Description	Format
`meta.name`	Customer's name in the format of `FirstName LastName`. Used as Cardholder's name if it is not specified. This value is required.	String
`meta.email`	Customer's email. This is required if not set on the order via API.	String
`meta.phone`	Customer's phone number if available	String
`meta.savePaymentMethodFor`	Indicates in which case this saved payment method can be used for payments. Possible values: `customer`: This method is used only when the customer is on the checkout page. `merchant`: This method can be used without the customer being on the checkout page, and the merchant can initiate transactions (e.g. take payments for recurring transactions). This method is saved as the new default payment method for merchant initiated transactions, regardless of the number of saved payment methods stored against the customer.	Enum
`meta.cardholderName`	Cardholder's name in the format of `FirstName LastName`.	String
`meta.billingAddress`	Customer's billing address. This is required if not set on order via API.	Object
`meta.billingAddress.countryCode`	Country code (e.g. `GB`). If sending the `billingAddress`, this is required.	String
`meta.billingAddress.region`	State, county or region. For US states, the 2-digit abbreviation should be used (e.g. `AL` for Alabama)	String
`meta.billingAddress.city`	Name of the city (e.g. `London`)	String
`meta.billingAddress.postcode`	Postal code (e.g. `EC2V 6DN`). If sending the `billingAddress`, this is required.	String
`meta.billingAddress.streetLine1`	Address line 1 (e.g. `1 Canada Square`)	String
`meta.billingAddress.streetLine2`	Address line 2 (optional)	String
`meta.shippingAddress`	Same as `meta.billingAddress`, However, it is displayed only in the order details on the Merchant Dashboard](https://business.revolut.com/merchant).	Object

Examples

Example with minimal required parameters

The HTML that will sit in the checkout page:

<div id="card-field"></div>
<button id="button-submit">Submit</button>

The JS that controls the behaviour of the 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();
    });
});

Example with minimal required parameters, when billingAddress and email are not sent via API.

The HTML that will sit in the checkout page:

<form>
    <div>
    <label>Full name</label>
    <input name="full_name" placeholder="John Doe" />
  </div>
  <div>
    <label>Email</label>
    <input name="email" placeholder="customer@example.com" />
  </div>
  <div>
    <label>Card</label>
    <div name="card"></div>
  </div>
  <div>
    <label>Billing Address</label>


    <input name="country" placeholder="Country" />
    <input name="state" placeholder="State" />
    <input name="city" placeholder="City" />
    <input name="line1" placeholder="Address line 1" />
    <input name="line2" placeholder="Address line 2" />
    <input name="postal" placeholder="Postal" />
  </div>
  <button>Submit</button>
</form>

The JS that controls the behaviour of the instance:

RevolutCheckout("<token>").then(function (instance) {
  var form = document.querySelector("form");
  var card = instance.createCardField({
    target: document.querySelector("[name=card]"),
    onSuccess() {
      window.alert("Thank you!");
    },
    onError(message) {
      window.alert("Oh no :(");
    },
    locale: "es"
  });


  form.addEventListener("submit", function (event) {
    // Prevent browser form submission. You need to submit card details first.
    event.preventDefault();


    var data = new FormData(form);


    card.submit({
      name: data.get("full_name"),
      email: data.get("email"),
      billingAddress: {
        countryCode: data.get("country"),
        region: data.get("state"),
        city: data.get("city"),
        streetLine1: data.get("line1"),
        streetLine2: data.get("line2"),
        postcode: data.get("postal")
      }
    });
  });
});