Upgrade to XPay Web SDK v5

Migrate a Web SDK v4 or v4.1 integration to v5. The upgrade changes package and script references, removes the HMAC secret from client configuration, renames the React hook, and changes confirmPayment() to an options object.

Before you begin#

Inventory every location that loads the XPay script, imports an XPay package, initializes the SDK, or calls confirmPayment(). Complete the upgrade in a test environment before changing the production integration.

Update the SDK artifact#

Replace v4 scripts with v5:

<!-- Test -->
<script src="https://js.xstak.com/v5/xpay-stage.js"></script>

<!-- Production -->
<script src="https://js.xstak.com/v5/xpay.js"></script>

For React or Next.js, install the matching package:

Test package:

npm install @xstak/xpay-element-stage-v5

Production package:

npm install @xstak/xpay-element-live-v5

Update React and Next.js#

Replace useXpay with useXPayClient:

import { useXPayClient } from "@xstak/xpay-element-stage-v5";

Remove hmacSecret from the XPay wrapper:

<XPay
  xpay={{
    publishableKey: "{{publishable_key}}",
    accountId: "{{account_id}}"
  }}
>
  <CheckoutForm />
</XPay>

Keep the merchant API signature secret on the backend.

Update Vanilla JavaScript#

The v5 global class uses the corrected XPay capitalization. Replace the legacy class and positional constructor arguments with an options object:

const xpay = new XPay({
  publishableKey: "{{publishable_key}}",
  accountId: "{{account_id}}"
});

Do not pass an HMAC secret to the constructor.

Update confirmPayment()#

Replace the v4 or v4.1 positional call:

await xpay.confirmPayment(
  "card",
  clientSecret,
  { name: "Ayesha Khan" },
  encryptionKey
);

with the v5 options object:

await xpay.confirmPayment({
  paymentMethodType: "card",
  clientSecret,
  customer: { name: "Ayesha Khan" },
  encryptionKey
});

Configure BIN discounts when used#

If the integration uses BIN-based discounts, pass the current PaymentIntent client secret as piClientSecret during SDK initialization:

const xpay = new XPay({
  publishableKey: "{{publishable_key}}",
  accountId: "{{account_id}}",
  piClientSecret: paymentIntent.pi_client_secret
});

Do not add piClientSecret when the integration does not need PaymentIntent-specific BIN discount results.

Verification checklist#

Before rollout, verify that:

• No page loads a v4 or v4.1 script.
• React imports use the v5 package and useXPayClient.
• Vanilla JavaScript uses XPay with an options object.
• No frontend configuration contains hmacSecret or the API signature secret.
• Every confirmPayment() call uses the v5 options object.
• PaymentIntent creation still occurs on the merchant backend.
• Payment confirmation and webhook reconciliation succeed in the test environment.
• Production uses only the production script, package, and credentials.

Rollout and rollback#

Deploy the script, package, initialization, and method changes together. Keep the last verified v4 deployment artifact available for rollback, but do not link it as the recommended integration path.

After verification, continue with the current XPay Web SDK guide.