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.

Installation

npm install @payrails/web-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';
import '@payrails/web-sdk/payrails-styles.css';

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:

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

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

// 2a. Mount the dropin (all-in-one checkout)
const dropin = payrails.dropin({
  events: {
    onAuthorizeSuccess: (action, result) =>
      console.log('Payment success', result),
    onAuthorizeFailed: (action, error) => console.log('Payment failed', error),
  },
});
dropin.mount('#dropin');

// 2b. 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' },
  events: {
    onAuthorizeSuccess: () => console.log('Payment authorized'),
    onAuthorizeFailed: (e) => console.log('Payment failed', e),
  },
});
paymentButton.mount('#payment-button');

Release Notes

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.