Introduction#

XPay Element SDK v4.1 includes breaking API changes. This guide explains what you must update to migrate from v4.

Who this guide is for:

Section 1: React & Next.js#

What changed for React/Next users#

For React npm package, need to change:

1. Update npm package version
2. XPay script URL in your HTML/layout
3. Remove HMAC ( APi Signature Key) from Wrapper
4. confirmPayment — positional args → object
5. (Optional) piClientSecret on <XPay /> If you use BIN discount

Step 1: Update npm package#

Install the v4.1 package:

// Staging
npm install @xstak/xpay-element-stage-v4.1

// Production
npm install @xstak/xpay-element-live-v4.1

Update your imports as well in files.

Step 2 : Update script in index.html or layout#

The Element SDK still loads via a script tag. Point it to the v4.1 bundle (replace URL).

v4.1 Script

// Staging
<script src="https://js.xstak.com/v4.1/xpay-stage.js"></script>

// Production
<script src="https://js.xstak.com/v4.1/xpay.js"></script>

Next.js: update this in _document.tsx, layout.tsx, or wherever you inject the script.

Step 3: Update confirmPayment#

confirmPayment no longer accepts positional arguments. Pass a single object.

await xpay.confirmPayment({
	paymentMethodType: 'card',
	clientSecret: 'xpay_pi_..._cs_...',
	customer: {
		name: 'John Doe',
		token: '',  *// required when paymentMethodType is 'token'*
	},
	encryptionKey: 'your-encryption-key',
});

Step 4: BIN discount (optional)#

If you are using BIN-based card discounts, pass piClientSecret in the xpay prop of <XPay /> wrapper. This allows pre-calculated discount details to be returned along with the BIN information. If piClientSecret is not passed, only BIN data will be returned.

<XPay
xpay={{
	publishableKey: storePK,
	accountId: user_id,
	customerName: customer?.name || null,
	email: customer?.email || null,
	piClientSecret: pi_client_secret,
}}
>
	{*/* checkout children */*}
</XPay>

React / Next.js checklist#

1. Install npm v4.1 package
2. Update script tag to v4.1 in index.html / layout
3. Remove HMAC from <XPay xpay={{ ... }} />
4. Change all confirmPayment calls to object syntax
5. Add piClientSecret to <XPay xpay={{ ... }} /> if using BIN discount

Section 2: Vanilla JavaScript#

What changed for vanilla users#

Vanilla integrators load the SDK via script tag and use XPay | window.XPayElement directly. All of the following are breaking changes:

v4.1 Script:

// Staging
<script src="https://js.xstak.com/v4.1/xpay-stage.js"></script>

// Production
<script src="https://js.xstak.com/v4.1/xpay.js"></script>

Change 1: Class rename#

v4

const xpay = new Xpay(/* ... */);

v4.1

const xpay = new XPay({ /* ... */ });

After script loads, global is XPay | window.XPay  (not Xpay | window.Xpay).

Change 2: Constructor uses an options object#

v4 — positional arguments

new Xpay(
	publishableKey,    *// required*
	accountId,         *// required*
	hmacSecret,        *// required in v4 — REMOVED in v4.1*
	email,             *// optional*
	customerName       *// optional*
);

v4.1 — options object

new XPay({
	publishableKey: 'xpay_pk_test_...',  *// required*
	accountId: 'your-account-id',         *// required*
	email: '',                            *// optional*
	customerName: '',                     *// optional*
	piClientSecret: '',                   *// optional — see Change 4*

});

Change 3: HMAC / API signature key removed#

In v4, the third argument was hmacSecret (API signature key).

In v4.1 it is removed. Do not pass it in the constructor, or frontend config.

The SDK no longer sends hmacSecret into the payment iframe. Authentication uses publishable key, account ID, and pi_client_secret where needed.

Change 4: piClientSecret for BIN discount (optional)#

Pass the payment intent client secret when creating the SDK if you want BIN-based discounts evaluated against the current payment intent.

const xpay = new XPay({
	publishableKey: 'xpay_pk_test_...',
	accountId: 'your-account-id',
	piClientSecret: 'xpay_pi_..._cs_...',
});

When the customer enters a card number, the SDK calls the BIN config API. What you receive in the binDiscount event depends on whether you passed piClientSecret:

Change 5: confirmPayment uses an options object#

v4 — positional arguments

await xpay.confirmPayment(
	'card',                              *// paymentMethodType*
	clientSecret,                        *// PI client secret*
	{ name: 'John Doe', token: '...' },  *// customer*
	encryptionKey,                       *// encryption key*
);

v4.1 — options object

await xpay.confirmPayment({
	paymentMethodType: 'card',
	clientSecret: 'xpay_pi_..._cs_...',
	customer: {
		name: 'John Doe',
		token: '',  *// required when paymentMethodType is 'token'*
	},
	encryptionKey: 'your-encryption-key',
});

Vanilla checklist#

1. Load v4.1 script
2. Replace Xpay with XPay
3. Refactor constructor to options object
4. Remove hmacSecret everywhere
5. Add piClientSecret if using BIN discount
6. Refactor confirmPayment to options object