Payrails Web SDK

Payrails Web provides you with the building blocks to create a checkout experience for your customers.

You can integrate Payrails Web in two ways:

• Dropin: all-in-one solution, the quickest but less customizable solution on how to accept payments on your website.
• Elements: One component for each payment method, credit card forms and more. Fully customizable solution.

Contents

• Installation
• Integration
• Quick Start
• v6 release notes
• v5 release notes

Installation

npm install @payrails/web-sdk

Browser support

| Browser | Minimum version | | --------------------- | --------------- | | Safari (macOS) | 12.1 | | Safari (iOS / iPadOS) | 12.2 | | Chrome | 73 | | Edge | 79 | | Firefox | 67 | | Opera | 60 | | Samsung Internet | 11.1 |

The SDK ships no ES built-in polyfills — to support browsers below this floor, load a polyfill such as core-js before the SDK.

Integration

The SDK supports multiple integration methods depending on your setup.

With a Bundler (Webpack, Vite, Rollup, esbuild, etc.)

If you use a bundler, import the SDK directly using ES module syntax:

import { Payrails, PayrailsEnvironment } from '@payrails/web-sdk';

Styles are injected automatically when the SDK loads — there is no separate CSS import.

Without a Bundler (Native ESM in the Browser)

If your project uses native ES modules (e.g. <script type="module"> or a "type": "module" package), the SDK works out of the box:

import { Payrails, PayrailsEnvironment } from '@payrails/web-sdk';

This resolves to the ESM build (index.mjs) automatically via the exports field in package.json.

CommonJS (Node.js / Legacy)

For CommonJS environments, use require:

const { Payrails, PayrailsEnvironment } = require('@payrails/web-sdk');

Quick Start

After installing, initialize the SDK with the response from the /merchant/client/init API. Payrails.init() is async — it loads the SDK runtime from the Payrails CDN and resolves once it is ready, so await it (or use .then()):

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

// 1. Initialize the SDK with the client init response
const payrails = await Payrails.init(clientInitResponse, {
  events: {
    onClientInitialized: () => console.log('SDK ready'),
  },
});

// 2. Subscribe to payment outcomes on the SDK instance
payrails.on('success', (event) =>
  console.log('Payment success', event.paymentMethodCode, event.data)
);
payrails.on('failed', (event) =>
  console.log('Payment failed', event.data?.code)
);

// 3a. Mount the dropin (all-in-one checkout)
const dropin = payrails.dropin({});
dropin.mount('#dropin');

// 3b. Or mount individual elements for full control
const cardForm = payrails.cardForm({ showCardHolderName: true });
cardForm.mount('#card-form');

const paymentButton = payrails.paymentButton({
  translations: { label: 'Pay Now' },
});
paymentButton.mount('#payment-button');

v6 release notes

See the v6 migration guide for before/after code and the upgrade checklist.

6.7.0

• FEATURE: The card form can collect a tax ID for cards issued in Argentina, Brazil, Chile and Mexico.
• FIX: The PayPal button now uses the new currency after update().
• FIX: Card brand tiles stack when brand names don't fit side by side.
• CHORE: The enrollInstrumentToNetworkOffers card form option was removed.

6.6.1

• FIX: The card brand selector now shows full co-branded card names.

6.6.0

• FEATURE: New apmForm() and apmButton() elements let shoppers pay with methods like MB WAY without a redirect.
• FIX: Klarna Pay Now, Pay Later and Pay Over Time now show the Klarna logo.
• FIX: The drop-in no longer collapses when a field inside a payment option changes.

6.5.0

• FEATURE: New "Instant Pay by Bank" payment method: shoppers select their bank and pay by bank transfer.
• FEATURE: updateClient() refreshes payment options when the amount changes
• CHORE: The bank-payment API was renamed from payrails.leanButton() to payrails.lean() (and its options and appearance types); update early integrations to the new name.

6.4.1

• BUGFIX: The pay button now leaves its loading state after a failed 3D Secure challenge, so shoppers can retry.
• BUGFIX: Fixed oversized rendering of the Google Pay button, card list rows and brand tiles.

6.4.0

• FEATURE: requestStart now fires for every payment method, including card, redirect and Lean payments, so one listener can observe or gate every payment attempt.
• BUGFIX: Google Pay now opens its payment sheet on iOS Safari when no buttonClicked listener is registered.

6.3.0

• FEATURE: Installment plans are now fetched at checkout, so shoppers see current rates, totals, and plan details.
• FEATURE: The drop-in now asks for the CVC of a saved card when the chosen installment plan requires it.
• BUGFIX: Custom fonts now load in the secure card fields, including fonts set through the drop-in's fonts option.

6.2.0

• FEATURE: The card form now highlights every invalid field as soon as you call validate(), instead of waiting for the shopper to leave each field.
• FEATURE: Card forms can now subscribe to installmentChanged to react when the shopper picks a different installment plan.
• FEATURE: Apple Pay merchant validation now uses your top-level page domain, with a new clientDomain option to override it.
• BUGFIX: The Google Pay sheet now shows the current amount and country instead of the values from when the button was mounted.
• BUGFIX: Secure fields no longer report a load timeout when the form is removed from the page before the fields finish loading.

6.1.2

• FEATURE: Merchants with more than one Stripe account now get the right Radar session on every payment. Each configured Stripe account's session is sent with the account it belongs to, so a payment routed to any of them is no longer rejected with No such radar session.

6.1.1

• FEATURE: Google Pay button corner radius and height can now be set through the Appearance API; the older styles option is deprecated in favor of appearance.settings.
• FEATURE: All configured fraud provider sessions are now sent when a payment is authorized.

6.1.0

• FEATURE: Each card form field (card number, expiry, CVV, cardholder name) can now be styled individually through the Appearance API.
• FEATURE: The Apple Pay button box (size, corner radius, padding) can now be styled through the Appearance API.
• BUGFIX: The drop-in now reliably preselects a wallet like Apple Pay that becomes available after the page loads.

6.0.3

• BUGFIX: Payment-method radio buttons in the drop-in now stay circular even when your page applies global input styles.

6.0.2

• BUGFIX: Return URLs set on Payrails.init now apply to Google Pay, Lean, and redirect payment methods, and merge field-by-field with drop-in and element-level return URLs.

6.0.1

• BUGFIX: Fixed a stuck loading state during redirect-based payment methods (e.g. Noon) that use the unified redirect action.
• BUGFIX: Fixed order summary and pay button amounts not reflecting the order total correctly in some checkout flows.
• BUGFIX: Fixed the pay button staying disabled in some checkout flows.
• FIX: Checkout styling is no longer affected by aggressive CSS resets on the host page.

6.0.0

• BREAKING: Payrails.init(...) is now asynchronous and returns a Promise of the SDK instance — add await.
• BREAKING: The SDK loads its bundle and stylesheet from the Payrails CDN at init, and the card form and wallets now render in a Payrails secure iframe; allow assets.payrails.io in your Content-Security-Policy (including frame-src).
• BREAKING: The manual payrails-styles.css import is removed; styles load automatically.
• BREAKING: Payrails.preloadCardForm() is removed; init preloads the card form assets automatically.
• BREAKING: The onClientInitialized callback now receives the workflow execution response object instead of the execution class instance.
• BREAKING: The drop-in, card form, payment buttons, and result screens ship a refreshed visual design; re-test any custom styling.
• BREAKING: The legacy events: {} callback bags are removed. Subscribe to events with the new typed .on(name, handler) API on the SDK instance and on elements (onClientInitialized stays a bag callback at init).
• BREAKING: Options deprecated in v5 are removed — environment and clientDomain on Payrails.init, showExistingCards (use showStoredInstruments), and setSavedCreditCard() (use setSavedInstrument()).
• FEATURE: New appearance API on every element — style through selector-scoped rules instead of the per-component styles object.

v5 release notes

5.49.1

• BUGFIX: Fixed the drop-in pay button disappearing when switching between payment options.
• BUGFIX: Fixed overlapping fields in the secure-fields card form.

5.49.0

• FIX: Improved card form rendering in narrow layouts.
• FIX: Design improvements to the co-branded card brand selector.

5.48.1

• BUGFIX: Co-branded cards now handle an empty or absent preferredSchemes list gracefully.
• FEATURE: Added Riskified and Signifyd fraud-provider assets.
• FIX: Corrected the Mastercard asset dark-mode stroke border.
• CHORE: Updated merchant logos.

5.48.0

• FIX: Improved error logging
• BUGFIX: Fixed card form disappearing on re-activation when switching between stored instruments and card.
• BUGFIX: Fixed stored instrument dropin unmounting shared payment button.

5.47.2

• FEATURE: Co-branded / co-badged card support (e.g. Cartes Bancaires + Visa, mada + Mastercard). The shopper chooses which scheme to pay with. Rolling out gradually.
• FEATURE: Added new payment-provider logo assets and refreshed existing ones.

5.47.1

• FEATURE: Improved card form performance with faster iframe load times.
• FEATURE: iDEAL is now presented as the co-brand "iDEAL | Wero" (logo and dropin label). Merchant-supplied label overrides are still respected; the iDeal payment method code is unchanged.
• FIX: Allow valid long card numbers (19-digit Visa V Pay cards, UnionPay 81 BIN range).
• FIX: Google Pay button no longer silently fails to start.

5.47.0

• FEATURE: Added an actionRequired event (payrails.on('actionRequired', ...)) that fires before action-required steps such as 3DS. Call preventDefault() on the event to take over the redirect instead of the default popup.
• FIX: Moved vitest-fetch-mock out of the SDK's runtime dependencies so it and its transitive vitest no longer install alongside the package.

5.46.1

• FEATURE: Host Google Pay on payrails domain
• FIX: Forward Apple Pay authorization failure reason (e.g. InsufficientBalance) to the onAuthorizeFailed callback, matching card behavior.

5.45.0

• FEATURE: Apple Pay express checkout now supports onDeliveryAddressChanged callback, allowing merchants to update shipping options and totals when the shopper switches delivery address in the payment sheet.
• FEATURE: Added Tabby logo assets for dropin payment method icon.
• FEATURE: Added Craftgate logo assets for dropin payment method icon.

5.44.1

• FIX: Handle 3-decimal currencies for Google Pay via NOT_CURRENTLY_KNOWN.

5.44.0

• FEATURE - Added Revolut Pay button assets in dark, white, and outline.
• FIX - Apple Pay script is loaded using SRI for enhanced security, with integrity hash and crossorigin attributes

5.43.2

• FIX: Fixed issue with secure fields update
• FIX: Honor save instrument settings in apple pay tokenization flow

5.43.1

• BUGFIX: Added new error PAYRAILS_CLIENT_APPLEPAY_MERCHANT_VALIDATION_FAILED
• BUGFIX: Adjusted ApplePayButton error logging / callback to include user intent events from AP

5.43.0

• FEATURE: support locale configuration for APMs

5.42.0

• FEATURE: Support esm and cjs outputs.

5.41.0

• FEATURE: Expose payment method configs through headless query API.
• FIX: PayPal loading error.

5.40.0

• FEATURE: Added lean payments support in web-sdk.

5.39.2

• FIX: Enforce exact CVV length by detected card network (AMEX = 4, others = 3).

5.39.1

• FIX: fix build leakages of internal types , Fix secure fields error states.

5.39.0

• FEATURE: Added support for tokenization of googlePay token via the Payrails googlePay button.

5.38.2

• FEATURE: extended update to also include meta field update
• FIX - extend the generic redirect button to support all redriection based payment methods.

5.37.9

• FIX: Apple pay onPaymentButtonClicked when merchant is not passing the callback.

5.37.8

• FEATURE: implement onValidate event from card payment button
• FEATURE - implement focus function that merchants can call manually to focus on card form.

5.37.7

• FIX: InvalidAccessError issue for apple pay.

5.37.6

• FIX: double click issue with GPAY
• FIX: stored instrument icon link fix

5.37.4

• FIX: PIX redirect

5.37.3

• FIX: double click issue with apple pay button

5.37.2

• package updates

5.37.1

• FIX: openInNewTab for Generic Redirect element in Safari

5.37.0

• FEATURE: Collect client context used by workflows automatically

5.36.2

• FIX: Missing fields in Stored Payment Instrument type

5.36.1

• FIX: Resolved generic redirect issue with slow loading pages

5.36.0

• FEATURE: Added support for tokenization of applePay token via the Payrails applePay button.

5.35.0

• FEATURE: Added support for passing returnInfo links for Generic Redirect element.
• FIX: Return Info links passed to droping element are now propagated to all payment methods.

5.34.0

• FEATURE: Added support to close Apple Pay payment sheet when authorization fails.

5.33.0

• FIX: trigger events when generic redirect is opened in a new tab

• FIX - SHA generation for SRI was incorrect, missing the algorithm prefix

5.32.0

• FIX: Installment amounts not updating after lookup and update

• FEATURE: Merchant should be able to configure default installment count using the SDK

5.31.2

• FIX: Fixed Amex CVV validation

• FIX: Limited CVV secure field maxLength

• FIX: Fixed validation bug after setError

• FIX: Fixed mount/unmount events accumulation bug

5.31.1

• FEATURE: Added openInNewTab option to GenericRedirectButton, allowing redirect payment pages to open in a new browser tab.