Create a JazzCash buy now, pay later (BNPL) wallet session from the merchant backend, redirect the customer to complete the wallet flow, and reconcile the result through two independent XPay webhook events.
Before you begin
Configure XPay API authentication and the merchant's JazzCash provider credentials. The customer CNIC and phone number used during the wallet flow must meet the applicable JazzCash requirements.
Ask the JazzCash team to allowlist the XPay provider callback URL for the merchant's environment:
{{base_url}}/public/v1/subscription/jazzcash/wallet/setup/webhookCreate the BNPL wallet session
Send an authenticated server-to-server request to:
POST {{base_url}}/public/v1/bnpl/wallet/setupAll fields except customer are required. When provided, customer can contain name, email, and phone.
The BNPL wallet-setup endpoint uses payment_method_types: "wallet". Keep this request contract separate from the jazzcash-bnpl PaymentIntent method value documented for other payment flows.
Store the generated identifiers and redirect
The response below is shortened to the fields required for the next step:
{
"success": true,
"data": {
"wallet_id": "{{xpay_wallet_id}}",
"payment_intent_id": "{{xpay_payment_intent_id}}",
"redirect_url": "https://{{xpay_checkout_host}}/wallet/payment-setup?{{redirect_parameters}}"
}
}XPay generates wallet_id and payment_intent_id. Store both identifiers against order_reference, then redirect the customer to redirect_url.
The customer enters the required CNIC and phone number, completes the OTP step, and confirms the payment through JazzCash.
Handle both webhook events independently
XPay sends both of the following events independently for the BNPL outcome:
JAZZCASH_BNPL_NOTIFICATIONcommunicates the JazzCash wallet-session result.PAYMENT_INTENT_NOTIFICATIONcommunicates the related PaymentIntent result through the standard payment webhook contract.
Do not make processing one event dependent on receiving the other. Verify each delivery and reconcile it using wallet_id, payment_intent_id, and the merchant's order_reference.
A shortened JazzCash BNPL notification contains:
{
"event": "JAZZCASH_BNPL_NOTIFICATION",
"wallet_id": "{{xpay_wallet_id}}",
"state": "succeeded",
"payment_intent_id": "{{xpay_payment_intent_id}}",
"transaction_reference": "{{jazzcash_transaction_reference}}"
}Use Payment webhook events for the canonical PAYMENT_INTENT_NOTIFICATION payload and Integrate XPay webhooks for shared signature-verification and processing guidance.
Test the flow
Test successful and failed JazzCash BNPL outcomes before production. For each outcome, confirm that:
- The wallet session returns both generated XPay identifiers.
- The customer reaches the correct merchant redirect URL.
- The merchant accepts and reconciles both webhook events independently.
- The final PaymentIntent result matches the merchant order state.