Merchant Web SDKs
Instance.createCardField
doc

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;
};
};
OptionDescriptionFormat
onSuccessCallback is called when the payment is completed successfully.Function
onErrorCallback if the transaction fails to complete. The reason for the failure is available in the message parameter.Function
onValidationCallback called on validation of the status change.
Function contains messages as first parameter (see below).
Function
onValidation.messagesArray of strings that contains validation errors (e.g. Your card has expired).String
onCancelCallback if a user did not complete the transaction and cancelled the authorisation or closed the checkout window.Function
localeControls 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
themeControls the color scheme of the widget. Possible values are: light (default), darkString
targetDOM element where secure iframe with the card field input is rendered.HTML Element
stylesObject of styles for different state of card field input, used to customize different states inside the secure iframe.Object
styles.defaultBase styles that are always applied regardless of state.Object
styles.focusedApplied when a user focuses inside the input with a mouse or a keyboard.Object
styles.invalidApplied on validation error.Object
styles.emptyApplied when a user hasn't entered any amount.Object
styles.autofilledApplied when a user used autofilled card details from the browser.Object
styles.completedApplied if the card field input is completed without any errors.Object
classesSame as styles but used to apply styles with classes to the target element outside the secure iframe.Object
classes.defaultSet default to 'rc-card-field'.String
classes.focusedSet default to 'rc-card-field--focused'.String
classes.invalidSet default to 'rc-card-field--invalid'.String
classes.emptySet default to 'rc-card-field--empty'.String
classes.autofilledSet default to 'rc-card-field--autofilled'.String
classes.completedSet default to 'rc-card-field--completed'.String

Returns

Methods object:

FieldDescriptionFormat
methods.destroyManually destroy card field if neededFunction
methods.submitSubmit the card details that a user entered and complete the payment with additional customer metadata. Accepts a single meta parameter (see below)Function
methods.validateManually 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:

FieldDescriptionFormat
meta.nameCustomer's name in the format of FirstName LastName. Used as Cardholder's name if it is not specified. This value is required.String
meta.emailCustomer's email. This is required if not set on the order via API.String
meta.phoneCustomer's phone number if availableString
meta.savePaymentMethodForIndicates 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.cardholderNameCardholder's name in the format of FirstName LastName.String
meta.billingAddressCustomer's billing address. This is required if not set on order via API.Object
meta.billingAddress.countryCodeCountry code (e.g. GB). If sending the billingAddress, this is required.String
meta.billingAddress.regionState, county or region. For US states, the 2-digit abbreviation should be used (e.g. AL for Alabama)String
meta.billingAddress.cityName of the city (e.g. London)String
meta.billingAddress.postcodePostal code (e.g. EC2V 6DN). If sending the billingAddress, this is required.String
meta.billingAddress.streetLine1Address line 1 (e.g. 1 Canada Square)String
meta.billingAddress.streetLine2Address line 2 (optional)String
meta.shippingAddressSame 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")
}
});
});
});

For a more in-depth example, see the card field integration example.

Was this page helpful?