Payrails API Reference - Payrails Docs

Payrails class

Reference for the Payrails class and package exports. The Payrails class is the entry point of @payrails/web-sdk. You never construct it directly — call the static Payrails.init() with the SDK configuration returned by your server, then use the resulting instance to create UI elements, payment buttons, and to read data from the payment session.

import { Payrails } from "@payrails/web-sdk";

const payrails = await Payrails.init(initResponse);

The environment (TEST / PRODUCTION) and merchant identifier are sourced from the server-provided SDK configuration inside initResponse.data. There is no client-side override.

Initialization

`Payrails.init(initResponse, options?)` (static)

static init(initResponse: InitOptions, options?: PayrailsClientOptions): Promise<Payrails>

Creates the SDK instance from a server-side SDK configuration. init is asynchronous: it loads the SDK bundle and stylesheet from the Payrails CDN (assets.payrails.io — allow it in script-src and style-src if you set a Content-Security-Policy) and resolves once the instance is ready. It requires a DOM — call it in the browser, not during server-side rendering.

Parameter	Type	Description
`initResponse`	`InitOptions`	The object returned by the Payrails client-init API: `{ version: string; data: string }`, where `data` is the Base64-encoded SDK configuration.
`options`	`PayrailsClientOptions`	Optional client configuration (see below).

PayrailsClientOptions:

Field	Type	Description
`events`	`{ onClientInitialized? }`	Init-only callback that fires during construction. `onSessionExpired` and every other event moved to `payrails.on(...)`.
`redirectFor3DS`	`boolean`	When `true`, 3DS challenges navigate the page instead of opening a popup.
`returnInfo`	`ReturnInfo`	Redirect return URLs: `{ success?, cancel?, error?, pending? }`.
`telemetry`	`{ enabled?: boolean; logLevel?: 'debug' \| 'error'; collectMetadata?: boolean }`	SDK telemetry configuration.

Rejects with a PayrailsError (PAYRAILS_INIT_FAILED) when the configuration string is invalid or when the SDK bundle cannot be loaded (blocked CDN, offline, or a 15-second timeout).

`update(updateOptions)`

update(updateOptions: LookupUpdateOptions): void

Updates the payment session on the client after initialization.

Field	Type	Description
`value`, `currency`	`string`	New amount. Both must be provided together for the amount to change.
`meta`	`{ key: 'customer'; value: object }`	Merges execution metadata (customer name, email, phone, country, …).
`installmentConfig`	`object \| null`	Card-installment options per country and/or a `defaultInstallment` selection; propagated to a mounted card form or drop-in.

`setState({ instrument })`

setState(state: { instrument }): void

Sets the currently selected stored instrument in the SDK’s shared state, e.g. when your own UI (instead of cardList) lets the shopper pick a saved card. instrument is a stored instrument object as returned by getStoredInstruments().

UI elements

All elements returned by these methods expose mount(selector: string) and unmount().

`dropin(options)`

dropin(options: DropinOptions): Dropin

Creates the all-in-one drop-in element that renders every available payment method. DropinOptions:

Field	Description
`paymentMethodsConfiguration`	Per-method configuration (`cards`, `payPal`, `googlePay`, `applePay`, `lean`, `mercadoPago`, `revolutPay`, …) plus `preselectFirstPaymentOption` (default `true`) and `showPaymentMethodLogo`.
`translations`	Per-component label/text overrides, including `paymentResult` and `errorMessages`.
`appearance`	Per-component styling (`DropinAppearance`): root `rules` plus one slot per building block (`cardForm`, `cardPaymentButton`, `orderSummary`, …). Provider-drawn wallet chrome is configured via `paymentMethodsConfiguration.<method>.styles`.
`fonts`	Custom font descriptors for the secure card fields.
`returnInfo`	Redirect return URLs for methods that leave the page.
`configuration`	Extra behavior configuration (e.g. `authFailMsg`).

Subscribe to drop-in events via payrails.on(...) (instance-level events like success) and the drop-in’s own .on(...) (element-level events like paymentOptionSelected).

const dropin = payrails.dropin({});
dropin.mount("#dropin");
payrails.on("success", (event) => {
  console.log(event.paymentMethodCode);
});
dropin.on("paymentOptionSelected", (e) => console.log(e.paymentMethod));

`cardForm(options?)`

cardForm(options?: CardFormOptions): CardForm

Creates (or returns the already-created) secure card entry form. One card form exists per Payrails instance; a mounted paymentButton is wired to it automatically. Key CardFormOptions fields: showCardHolderName, showSingleExpiryDateField, layout (rows of ElementType field names), translations (placeholders, labels, error texts), appearance (CardFormAppearance), fonts, installmentConfig, and enrollInstrumentToNetworkOffers. Subscribe to events (change, ready, focus, blur, …) via cardForm.on(...).

const cardForm = payrails.cardForm({ showCardHolderName: true });
cardForm.mount("#card-form");
cardForm.on("change", (e) => render(e.isValid));
cardForm.on("ready", () => show());

`cardList(options?)`

cardList(options?: CardListOptions): CardList

Creates (or returns the already-created) list of the shopper’s saved cards. options.onCardChange(selectedCard) fires when the shopper selects a card; selection also enables a mounted paymentButton. options.appearance styles the list.

`apmForm(options)`

apmForm(options: ApmFormOptions): ApmForm

Creates the form for an alternative payment method that needs details from the shopper, such as a phone number or an IBAN. The fields are drawn inside a Payrails-hosted iframe from the payment method’s configuration, so they are never part of your page’s DOM. Pair it with an apmButton to pay. Options: paymentMethodCode (required), appearance, translations, id. The method throws a PayrailsError when the session has no form for that payment method. The id defaults to payrails-apm-form-<paymentMethodCode>; pass id only if you mount two forms for the same method.

const form = payrails.apmForm({ paymentMethodCode: "mbWay" });
await form.mount("#mbway-form");

const button = payrails.apmButton({
  form,
  translations: { label: "Pay with MB WAY" },
});
button.mount("#mbway-button");

form.on("change", (e) => setFormValid(e.isValid));

form.mount() returns a promise, so await it or attach a .catch. It rejects when the selector isn’t found, or when the form can’t be drawn, for example because a field has no label from the configuration or your translations. A form that can’t be drawn rejects with a PayrailsError whose context.reason is 'unrenderable-schema'. Branch on that to offer the shopper another way to pay:

form.mount("#mbway-form").catch((error) => {
  if (error?.context?.reason === "unrenderable-schema") {
    showOtherPaymentOptions();
  }
});

appearance takes the same rules as other elements, plus actionScreen for the screen the form shows while an approve-in-app method waits; see ApmFormAppearance.

`dynamicElement(options)`

dynamicElement(
  options: DynamicElementOptions & Required<Pick<DynamicElementOptions, 'paymentMethod'>>
): DynamicElementForm

Renders a form directly in the merchant page. To collect payment details, use apmForm instead, which renders in a Payrails-hosted frame. options.paymentMethod is required; the method throws a PayrailsError when the session has no form for that payment method. Other options: appearance, translations, fieldOverrides. Subscribe
to events via element.on(...) .

`collectContainer(containerOptions)`

collectContainer(containerOptions: CollectContainerOptions): FramesContainer

Low-level access to the secure-fields container used by cardForm. Lets you create and mount individual secure fields (createCollectElement), validate, and collect encrypted card data yourself. CollectContainerOptions: containerId, fonts. Each secure field styles itself via its own appearance option on createCollectElement.

Payment buttons

`apmButton(options)`

apmButton(options: ApmButtonOptions): ApmButton

Pays with an alternative payment method. Pass either the form from apmForm, or a paymentMethodCode on its own for a method with nothing to collect. Passing both, or neither, throws. Methods that redirect the shopper still use genericRedirectButton; apmButton stops at pending for them. With a form, a click validates it first. If a field is invalid, the form shows the error, the button emits validate with isValid: false, and nothing is submitted. Otherwise the button runs the buttonClicked and requestStart gates and submits the payment, the same as the card payment button. Options: form or paymentMethodCode (exactly one), translations.label, appearance, returnInfo, id, alwaysStoreInstrument. The id defaults to payrails-apm-button-<paymentMethodCode>. alwaysStoreInstrument (default false) saves the instrument for future payments. The button shows no save checkbox, so set it only when you already have the shopper’s consent, for example for a SEPA mandate. The SDK ignores it on a merchant of record workspace. See Save the instrument for future payments. Subscribe to outcomes via payrails.on('success' | 'failed' | 'pending', ...), and to validate via the returned button’s .on(...). See the event reference.

button.on("validate", (e) => {
  if (!e.isValid) scrollToPaymentForm();
});

payrails.on("success", (e) => showConfirmation(e.executionId));
payrails.on("failed", (e) => showError(e.data?.code));

Approve-in-app methods

Some methods, such as MB WAY, have the shopper approve the payment in another app. For these the button doesn’t stop at pending. The form switches to a wait screen with the payment method’s logo and instructions for the shopper, the button is removed, and the SDK waits for the shopper to approve:

Approved: the wait screen goes away and success fires. Show your own confirmation.
Declined, or not approved in time: the form comes back with what the shopper typed, the button comes back, sessionExpired fires, and then failed with AUTHORIZATION_ERROR. Return fresh init options from sessionExpired so the shopper’s retry starts a new payment.
The SDK couldn’t confirm the result, for example because the session expired during the wait: the same happens, but failed carries AUTHENTICATION_ERROR or UNKNOWN_ERROR. The shopper may still approve in their app, so check the payment’s status before letting them retry.

payrails.on("sessionExpired", async () => fetchNewInitResponse());

payrails.on("failed", async (e) => {
  const code = e.data?.code;
  if (code === "AUTHENTICATION_ERROR" || code === "UNKNOWN_ERROR") {
    await checkPaymentStatus(e.executionId);
  }
});

Your webhook or an execution lookup has the payment’s final status.

`paymentButton(options)`

paymentButton(options: CardPaymentButtonOptions): CardPaymentButton

Creates (or returns the already-created) pay button for card payments. It submits the card form or the instrument selected via cardList/setState. Options: translations.label, appearance, redirectFor3DS, and disabledByDefault (default true; the button enables once the card form is valid or a saved card is selected). Subscribe to payment outcomes via payrails.on(...) and to button-specific events (stateChanged, validate) via the returned button’s .on(...)

`googlePayButton(options)`

googlePayButton(options: GooglePayButtonOptions): GooglePayButton

Creates a Google Pay button. Options: merchantName (overrides the display name from the backend config; the merchant ID is always taken from the backend), redirectFor3DS, styles (buttonColor, buttonType, buttonSizeMode, locale), returnInfo, and store-instrument checkbox options. The environment is inherited from Payrails.init(...). Read await button.isAvailable (a Promise<boolean>) for wallet availability and subscribe to payrails.on(...) for payment outcomes.

`isGooglePayAvailable(merchantName?)`

isGooglePayAvailable(merchantName?: string): Promise<boolean>

Resolves true when the shopper’s browser/device can pay with Google Pay for the current session configuration. Pass merchantName to override the display name that Google Pay resolves during the availability check.

`applePayButton(options)`

applePayButton(options: ApplePayButtonOptions): ApplePayButton

Creates an Apple Pay button. Options: abortAfterAuthorizeFailed, translations, styles (type, e.g. 'buy'/'checkout'; style, e.g. 'black'; locale), and store-instrument checkbox options. Read await button.isAvailable (a Promise<boolean>) for wallet availability, subscribe to payrails.on('deliveryAddressChanged', …) for the express-checkout address sheet, and to payrails.on(...) for payment outcomes.

`isApplePayAvailable()`

isApplePayAvailable(): Promise<boolean>

Resolves true when the browser supports Apple Pay (ApplePaySession) and the Apple Pay SDK loads; false otherwise (never rejects).

`paypalButton(options?)`

paypalButton(options?: PaypalButtonOptions): PaypalButton

Creates a PayPal button. Options: styles (color, height, label, shape, tagline, locale), and store-instrument checkbox options. Read await button.isAvailable (a Promise<boolean>) for wallet availability, subscribe to payrails.on('deliveryAddressChanged', …) for express-checkout address changes (PayPal payload shape), and to payrails.on(...) for payment outcomes. In PayPal express mode the store-instrument checkbox is forced off.

`leanButton(options)`

leanButton(options: LeanButtonOptions): LeanButton

Creates a Lean (pay-by-bank) button. Options: id, translations.label, appearance (the button), dialogCustomization (the Lean-hosted dialog’s theme config), and returnInfo. Subscribe to payment outcomes via payrails.on(...).

`genericRedirectButton(options)`

genericRedirectButton(options: GenericRedirectButtonOptions): GenericRedirectButton

Creates a button for any redirect-based payment method. options.paymentMethod (the payment method configuration, required) selects the method; other options: translations.label, appearance (for Revolut Pay, pass revolutOptions — the RevolutPayStyles shape — instead), openInNewTab, and returnInfo. Subscribe to payment outcomes via payrails.on(...); the redirect itself can be intercepted via the actionRequired event (see events).

Stored instruments and payment methods

Stored instruments are plain objects with id, status, paymentMethod, displayName?, data? (e.g. bin, suffix, network for cards, email for PayPal), and default?.

`getSavedCreditCards()`

Returns the shopper’s stored card instruments.

`getSavedGooglePayAccounts()`

Returns the shopper’s stored Google Pay instruments with status enabled.

`getSavedApplePayAccounts()`

Returns the shopper’s stored Apple Pay instruments.

`getSavedPaypalAccounts()`

Returns the shopper’s stored PayPal instruments with status enabled, or [].

`getStoredInstruments()`

Returns stored instruments across all payment methods. Google Pay and PayPal instruments are included only when their status is enabled.

`getStoredInstrumentsByPaymentMethod(paymentMethod)`

getStoredInstrumentsByPaymentMethod(paymentMethod: string): object[]

Returns the result of getStoredInstruments() filtered to one payment method code (a PAYMENT_METHOD_CODES value such as 'card' or 'payPal').

`getAvailablePaymentMethods()`

getAvailablePaymentMethods(): string[]

Returns the payment method codes available in the current session (values of PAYMENT_METHOD_CODES).

Data and API

`api(config)`

api(config: {
  operation: 'deleteInstrument' | 'updateInstrument' | 'payout';
  resourceId?: string;
  body?: object;
}): Promise<object>

Calls a Payrails API operation authorized by the current session.

Operation	`resourceId`	`body`	Resolves with
`deleteInstrument`	instrument id (required)	—	`{ success: boolean }`
`updateInstrument`	instrument id (required)	instrument fields to update	the updated instrument
`payout`	—	payout request	the payout response

await payrails.api({
  operation: "deleteInstrument",
  resourceId: instrument.id,
});

`query(key, params?)`

query(key, params?: Record<string, any>)

Reads a value from the session configuration; returns null when the value or key is unknown. Supported keys: holderReference, amount, executionId, binLookup, instrumentDelete, instrumentUpdate (API links), paymentMethodConfig and paymentMethodInstruments (both require params.paymentMethodCode; paymentMethodConfig also accepts 'all' or 'redirect' to return arrays).

`binLookup()`

binLookup(): Promise<object | null | undefined>

Looks up the BIN currently entered in the mounted drop-in, card form, or collect container. Resolves with the lookup data — bin, network, and when available localNetwork (co-branded cards), issuer, issuerCountry, type. Logs a warning and resolves undefined when no container exists, and resolves null when BIN lookup is not enabled for the session.

Instance events

`on(name, handler)`

on<K extends PayrailsEventName>(name: K, handler: PayrailsEventHandler<K>): () => void

Subscribes to an SDK-level event (success, failed, pending, buttonClicked, requestStart, actionRequired, sessionExpired, deliveryAddressChanged) and returns an unsubscribe function.

`off(name, handler)`

off<K extends PayrailsEventName>(name: K, handler: PayrailsEventHandler<K>): void

Removes a handler previously registered with on.

Other package exports

Values and enums:

Export	Description
`PayrailsEnvironment`	`TEST \| PRODUCTION` — the environment resolved from `initResponse.data`. Read-only enum.
`PAYMENT_METHOD_CODES`	Enum of payment method codes (`card`, `googlePay`, `payPal`, `applePay`, `pix`, `revolutPay`, …).
`ElementType`	Secure-field types for card form layouts (`CARD_NUMBER`, `CARDHOLDER_NAME`, `CVV`, `EXPIRATION_MONTH`, `EXPIRATION_YEAR`, `EXPIRATION_DATE`, `CARD_FORM`).
`ACTION_REQUIRED_KIND`	Kinds of `actionRequired` events: `GENERIC_REDIRECT` (`'genericRedirect'`), `THREE_DS` (`'3ds'`).
`AuthorizationFailureReasons`	Failure codes on the `failed` event payload: `VALIDATION_FAILED`, `AUTHORIZATION_ERROR`, `AUTHENTICATION_ERROR`, `UNKNOWN_ERROR`, `USER_CANCELLED`.
`INTEGRATION_TYPE`	Payment method integration types: `API` (`'api'`), `HPP` (`'hpp'`).
`REVOLUT_PAY_DEFAULT_LABEL`, `REVOLUT_PAY_DEFAULT_THEME`	Default label (`'Pay with Revolut Pay'`) and theme (`'lightOutline'`) for the Revolut Pay button.

Types:

Export	Description
`InitOptions`	Argument of `Payrails.init`: `{ version: string; data: string }`.
`PayrailsClientOptions`	Options argument of `Payrails.init`.
`PayrailsAmount`	`{ value: string; currency: string; subTotal?: string }`.
`DropinOptions`, `CardFormOptions`, `CardListOptions`, `CardPaymentButtonOptions`	Option objects for the corresponding element factories.
`GooglePayButtonOptions`, `ApplePayButtonOptions`, `PaypalButtonOptions`, `LeanButtonOptions`, `GenericRedirectButtonOptions`	Option objects for the payment buttons.
`Appearance`, `AppearanceRules`, `AppearanceDeclarations`, `CardFormAppearance`, `DropinAppearance`	The `appearance` option shapes.
`RevolutPayStyles`, `RevolutPayButtonTheme`	Shape and theme values for the Revolut Pay button’s `revolutOptions`.
`CollectContainerOptions`, `PayrailsSecureField`, `PayrailsSecureFieldEvent`	Secure-fields container and field types.
`FramesContainer`	The container returned by `collectContainer()`.
`PayrailsEvents`, `PayrailsEventName`, `PayrailsEventHandler`, `ActionRequiredEvent`, `ActionRequiredKind`, `PaymentAttemptContext`	Event types.
`ReturnInfo`	Redirect return URLs: `{ success?, cancel?, error?, pending? }`.
`SaveInstrumentResponse`	Response of the save-instrument API for cards.
`CardScheme`	Card scheme entry emitted by the `preferredSchemeChanged` / `change` events.
`ExecutionMeta`, `ExecutionMetaCustomer`, `ExecutionMetaKey`	Execution metadata shapes used by `update({ meta })`.
`StorablePaymentCompositionOption`, `WorkflowExecutionResponse`	Payment method configuration and execution response shapes.

​Payrails class

​Initialization

​Payrails.init(initResponse, options?) (static)

​update(updateOptions)

​setState({ instrument })

​UI elements

​dropin(options)

​cardForm(options?)

​cardList(options?)

​apmForm(options)

​dynamicElement(options)

​collectContainer(containerOptions)

​Payment buttons

​apmButton(options)

​Approve-in-app methods

​paymentButton(options)

​googlePayButton(options)

​isGooglePayAvailable(merchantName?)

​applePayButton(options)

​isApplePayAvailable()

​paypalButton(options?)

​leanButton(options)

​genericRedirectButton(options)

​Stored instruments and payment methods

​getSavedCreditCards()

​getSavedGooglePayAccounts()

​getSavedApplePayAccounts()

​getSavedPaypalAccounts()

​getStoredInstruments()

​getStoredInstrumentsByPaymentMethod(paymentMethod)

​getAvailablePaymentMethods()

​Data and API

​api(config)

​query(key, params?)

​binLookup()

​Instance events

​on(name, handler)

​off(name, handler)

​Other package exports