XPay Jazzcash BNPL API Integration

This API initializes a BNPL (Buy Now Pay Later) payment flow using the JazzCash wallet as the payment method. It is intended to be called server-to-server to create a wallet setup session before redirecting the customer to complete the payment.

All of the following fields are mandatory, except for the customer object, which is optional.

Mandatory fields

json

{
"wallet_type": "jazzcash",
"amount": 100,
"order_reference": "bnpl-50",
"success_redirect_url": "https://webhook.site/0fd65fa3-3bb2-4924-981c-3785e8173cc6",
"failure_redirect_url": "https://webhook.site/0fd65fa3-3bb2-4924-981c-3785e8173cc6",
"payment_method_types": "wallet",
"description": "bnpl txns"
}

The optional customer object, if provided, may include "name", "email", and "phone".

API Curl

json

Stage base URL: 'https://xstak-pay-stg.xstak.com'
Live base URL: 'https://xstak-pay.xstak.com'

bash

curl --location -g --request POST '{{base_url}}/public/v1/bnpl/wallet/setup' \
--header 'x-api-key: {{x-api-key-sk}}' \
--header 'x-account-id: {{x-account-id}}' \
--header 'User-Agent: Apidog/1.0.0 (https://apidog.com)' \
--header 'Content-Type: application/json' \
--header 'x-signature: {{x-signature}}' \
--data-raw '{
    "wallet_type": "jazzcash",
    "amount":100,
    "order_reference":"bnpl-50",
    "success_redirect_url":"https://webhook.site/0fd65fa3-3bb2-4924-981c-3785e8173cc6",
    "failure_redirect_url":"https://webhook.site/0fd65fa3-3bb2-4924-981c-3785e8173cc6",
    "payment_method_types":"wallet",
    "description":"bnpl txns",
    "customer":{
        "name":"user name",
        "email":"user@gmail.com",
        "phone":"03417894561" /* customer obj is optional*/
    }
}'

API Response

json

{
    "success": true,
    "responseStatus": "OK",
    "message": "Request processed successfully.",
    "data": {
        "wallet_id": "xpay_wallet_299e9fc15fd44db79da8e56b9c7a459d",
        "wallet_type": "jazzcash",
        "amount": 100,
        "order_reference": "bnpl-withhhPIkkI",
        "success_redirect_url": "https://webhook.site/3721c232-b7cf-44cd-a512-efad271a6c86",
        "failure_redirect_url": "https://www.google.com",
        "payment_method_types": "wallet",
        "description": "bnpl txns",
        "customer": {
            "name": "user name",
            "email": "user@gmail.com",
            "phone": "03417894561"
        },
        "payment_intent_id": "xpay_pi_0dbc66ad121f92da238438496e00bbbe27ef7850f7e57d35f2fbc06c1dba106e",
        "redirect_url": "https://xpay-checkout.postexglobal.com/wallet/payment-setup?id=656f316b3298ff9b5165fea4&payment_setup_id=xpay_wallet_299e9fc15fd44db79da8e56b9c7a459d&type=BNPL"
    }
}

After clicking the redirect URL, the client will enter their CNIC and phone number, which must be whitelisted beforehand.
The client will then enter the OTP and confirm the payment from the JazzCash app.
A transaction will be created on the XAP portal.
Two webhooks will be triggered after either a success or a failure scenario.

XPay URLs to be whitelisted by the Jazzcash team.

json

Staging Environment
https://xstak-pay-stg.xstak.com/public/v1/subscription/jazzcash/wallet/setup/webhook

Live Environment
https://xstak-pay.xstak.com/public/v1/subscription/jazzcash/wallet/setup/webhook

Webhook JAZZCASH_BNPL_NOTFICATION

json

{
  "event": "JAZZCASH_BNPL_NOTFICATION",
  "_id": "69047f658373e35be3df4953",
  "wallet_id": "xpay_wallet_d6a46d46151441e0909874d6865204b3",
  "account_id": "5645f0fe251d63ed",
  "store_id": "6780f3bac15a96a4c1fb81cf",
  "mode": "live",
  "customer": {
    "name": "Basit Munir",
    "email": "user@gmail.com",
    "phone": "03011266254"
  },
  "state": "succeeded",
  "wallet_type": "bnpl-jazzcash",
  "success_redirect_url": "https://webhook.site/3721c232-b7cf-44cd-a512-efad271a6c86",
  "failure_redirect_url": "https://www.google.com/",
  "amount": 100,
  "order_reference": "bnpl-185",
  "description": "bnpl txns",
  "payment_intent_id": "xpay_pi_a444aad2edc4ef997fceedef828acb105b4e1ad9d1b730b96fe0c802b7b5db42",
  "createdAt": "2025-10-31T09:20:37.095Z",
  "updatedAt": "2025-10-31T09:22:30.910Z",
  "__v": 0,
  "metadata": {},
  "transaction_reference": "20251031092045",
  "gateway_response": "Your purchase is successful! To avail Buy Now, Pay Later again, use JazzCash to repay your installments on time.",
  "payment_intent": "xpay_pi_a444aad2edc4ef997fceedef828acb105b4e1ad9d1b730b96fe0c802b7b5db42"
}

Webhook PAYMENT_INTENT_NOTIFICATION

json

{
  "type": "PAYMENT_INTENT_NOTIFICATION",
  "payment_intent_id": "xpay_pi_a444aad2edc4ef997fceedef828acb105b4e1ad9d1b730b96fe0c802b7b5db42",
  "refund_id": null,
  "amount": 100,
  "currency": "PKR",
  "status": "succeeded",
  "customer": {
    "name": "Basit Munir",
    "email": "user@gmail.com",
    "phone": "03011266254"
  },
  "shipping": {},
  "payment_method_types": "bnpl",
  "product": {},
  "transaction_details": {
    "_id": "69047f6d8373e35be3df4991",
    "order": {
      "customer": {
        "name": "Basit Munir",
        "email": "user@gmail.com",
        "phone": "03011266254"
      },
      "name": "bnpl-185",
      "type": "headless"
    },
    "status": "CAPTURED",
    "secure": null,
    "refunded_amount": 0,
    "gateway": "jazzcash-wallet",
    "response_from_bank": "Your purchase is successful! To avail Buy Now, Pay Later again, use JazzCash to repay your installments on time.",
    "status_code_from_bank": "000",
    "status_message_from_bank": "Completed",
    "activity": [
      {
        "status": "CAPTURED",
        "wallet": {},
        "processing": { "reference": "20251031092045" }
      }
    ]
  },
  "metadata": { "order_reference": "bnpl-185" },
  "store_id": "6780f3bac15a96a4c1fb81cf",
  "mode": "live",
  "account_id": "5645f0fe251d63ed"
}