XPay Fusion
XPay Fusion is a PCI DSS-compliant payment solution to collect payments from your customers in your web/mobile app without them having to redirect to a third-party payment page.
Payment Integration Guide
Integration has two main steps:
- Create a Payment Intent — from your server (backend)
- Confirm the payment — from your frontend using the XPay SDK
Before you start, make sure you have the following from your XPay dashboard:
- x-api-key — your secret API key
- x-account-id — your account ID
- API Signature Key — used to generate the HMAC signature
Step 1 — Create a Payment Intent (Server Side)
Call this API only from your server. It initializes the payment session and returns two values your frontend will need: pi_client_secret and encryptionKey.
API Endpoint
POST /public/v1/payment/intentcurl--location'{{base_url}}/public/v1/payment/intent' \
--header'x-api-key: {{x-api-key}}' \ //Secret key of your account
--header'x-account-id: {{x-account-id}}' \ //Account ID of your account
--header'x-signature: {{x-signature}}' \ //SHA-256 signature
--header'Content-Type: application/json' \
--data'{
"amount": 500,
"currency": "PKR",
"customer": {
"name": "Necibe Mirzai",
"email": "necibe.mirzai@xstak.com",
"phone": "905374182171",
"vip_customer": "No", // optional
"previous_customer": "false" // optional
},
"shipping": {
// Omit the entire `shipping` object if billing details are not required
"address1": "123 Main Street", // optional
"address2": "Apartment 4B", // optional
"city": "Lahore", // optional
"country": "Pakistan", // optional
"first_name": "Amir", // optional
"last_name": "Ghafoor", // optional
"province": "Punjab", // optional
"zip": "54000", // optional
"phone": "+923001234567", // optional
"shipping_method": "Standard Delivery" // optional
},
"billingAddress": {
// Omit the entire `billingAddress` object if billing details are not required
"address1": "456 Business Street", // optional
"address2": "Suite 12A", // optional
"city": "Karachi", // optional
"country": "Pakistan", // optional
"firstName": "Amir", // optional
"lastName": "Ghafoor", // optional
"province": "Sindh", // optional
"provinceCode": "SD", // optional
"company": "Tech Solutions Pvt Ltd", // optional
"zip": "74000", // optional
"phone": "+923001234567", // optional
"shipping_method": "Express Delivery" // optional
},
"product": {
// Omit the entire `product` object if product details are not required
"product_category": "Transport", // optional
"product_name": "Intercity Travel", // optional
"no_of_items": "2" // optional
},
"gateway_instance_id": "gateway_pk_01", // Add when routing payment through a specific gateway instance
"metadata": {
"order_reference": "3242424234r23er",
"check_network_blocklist": false, // Add to check whether the user/network is blocked at XPay level
"skip_blocklist": true, // Add when blocklist is enabled but should be skipped
"continue_payment": true // Add when token limit is exceeded but payment should continue
}
}'To authorize an amount and capture it later, add the following in the PI API payload.
"capture_method": "manual"Parameters
HMAC signature
Generate using your API Signature Key + JSON.stringify(requestBody) with SHA-256. Pass the result as the x-signature header. For more details, refer to:
Response Fields
The API returns a large object. You only need two fields — extract them and pass them to your frontend:
Example Response
Step 2 — Confirm the Payment (Frontend)
Once your frontend has pi_client_secret and encryptionKey from your server, call confirmPayment() SDK method. The SDK handles card encryption and submits the payment.
Below is a sample method for the Web SDK. Other methods are documented in their respective SDK documentation sections. You can use the methods according to the SDK you are integrating.
const { message, error } = await xpay.confirmPayment(
"card", // payment method type
payment_intent.pi_client_secret, // from your server
{
name:"Dane Joe" // Customer object with at least name
},
payment_intent.encryptionKey // from your server
);Step 3 — Handle Payment Status
After confirmPayment() resolves, check the pi_status to decide what to show the user.
Step 4 — Capture the Payment (Optional)
Only needed if you passed capture_method: manual in Step 1. Call this from your server when you're ready to charge the customer.
curl--location--globoff'{{base_url}}/public/v1/payment/intent/capture?pi_client_secret={{pi_client_secret}}' \
--header'x-api-key: {{x-api-key}}' \ //Secret key of your account
--header'x-account-id: {{x-account-id}}' \ //Account ID of your account
--header'x-signature: {{x-signature}}' \ //SHA-256 signature
--header'Content-Type: application/json' \
--data'{
"amount": 10 //must match or be less than the authorized amount
}'SDK Events
Below is a sample event for the Web SDK. Other events are documented in their respective SDK documentation sections. You can use the events according to the SDK you are integrating.
// React
<PaymentElement options={options} onReady={(event) => {
console.log("ready event", event);
}} />
// Veniala Js
xpay.on("ready", function (event) {
console.log(event, "onready");
});XPay Webhooks
Webhooks can also be configured to receive asynchronous payment status updates from XPay.
XPay Webhooks IntegrationAPI Responses
Below are the sample Payment API responses for both successful and failed payment scenarios.
API ResponsesXPay Payment API
An easy-to-integrate API to enable fully embedded payments for your website.
XPay Payment UsecasesXPay Payment Intent StatusesXPay SDKs
Select your tech stack below and enable a fully embedded payments UX in your web/mobile app.
XPay Web SDKXPay React Native SDKXPay Android Native SDKXPay Flutter SDKXPay Swift SDKRendering Card, JazzCash, Easypaisa, and Google Pay, Baadmay Element Separately3DS Authentication & Token Enablement on New GatewayXPay Plugins
Install the WooCommerce plugin below for a fully embedded payment experience on your WooCommerce store.
WooCommerce PluginBin Discount
A feature on XPay that allows merchants to configure discounts based on card BINs.
Bin DiscountXPay Subscriptions API
An easy-to-integrate API to enable subscription payments for your business.
XPay SubscriptionUsage-based BillingXPAY Jazzcash Subscription