Whish Pay QR

Integration flow

1. 1
   Create a session. Call Create a payment session with the amount, currency, your externalId, and optionally a callbackUrl. You receive a qr_payload, a six-digit code, and a pending status.
2. 2
   Present the QR or code. Show the customer the QR payload or the six-digit code. They scan the QR or type the code and pay from their Whish balance.
3. 3
   Receive the callback. If you set a callbackUrl, Whish sends it an HTTP POST with a JSON body after every payment attempt, whether it succeeded or failed. A failed attempt does not close the session: it stays payable until it is either paid or expires.
4. 4
   Confirm before fulfilling. Verify the outcome with Get payment status before releasing the order. Poll it as the fallback if a callback did not arrive, or as your primary signal if you did not set a callback.

Authentication & headers

Every request must include the HTTP headers below, plus Content-Type: application/json on requests that send a body.

Environments

The cURL examples on this page target Sandbox. To go live, swap the host for the Production base URL above.

Response format

All endpoints return HTTP 200 with Content-Type: application/json and a shared envelope. Always branch on the status and code fields in the body, never on the HTTP status code.

The two fields move together, so read them as a pair. There are only these combinations:

A status: true is never accompanied by a code, and a code never reports how far a payment has progressed. The payment's own lifecycle is data.status on a session, collectStatus on Get payment status, and status in the callback body; a QR session returns status: true with data.status: "pending", which is a successful call for a payment nobody has made yet.

Get account balance

Returns the real balance of the merchant account. Pass currency as a query-string parameter on the request URL to choose which balance to return.

curl 'https://partner.api.sbx.whish.money/itel-service/api/payment/account/balance?currency=USD' \
  -H 'channel: YOUR_CHANNEL' \
  -H 'secret: YOUR_SECRET' \
  -H 'websiteUrl: https://yoursite.com' \
  -H 'User-Agent: AcmeStore/2.1 (https://acme.example; dev@acme.example)'

{
  "status": true,
  "code": null,
  "dialog": null,
  "actions": null,
  "extra": null,
  "data": {
    "balance": 10439.0
  }
}

Create a payment session

Creates a Whish Pay payment session from your backend. A successful response returns a session identifier, a six-digit payment code, a QR payload, the expiry time, and the initial session status.

curl -X POST 'https://partner.api.sbx.whish.money/itel-service/api/payment/whish/session' \
  -H 'channel: YOUR_CHANNEL' \
  -H 'secret: YOUR_SECRET' \
  -H 'websiteUrl: https://yoursite.com' \
  -H 'User-Agent: AcmeStore/2.1 (https://acme.example; dev@acme.example)' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 10.0,
  "currency": "USD",
  "externalId": "ORDER-2026-0001",
  "invoice": "INV-2026-0001",
  "callbackUrl": "https://merchant.example/api/whish/payment-success?orderId=ORDER-2026-0001",
  "expiry": 10
}'

Request body

{
  "amount": 10.0,
  "currency": "USD",
  "externalId": "ORDER-2026-0001",
  "invoice": "INV-2026-0001",
  "callbackUrl": "https://merchant.example/api/whish/payment-success?orderId=ORDER-2026-0001",
  "expiry": 10
}

{
  "status": true,
  "code": null,
  "dialog": null,
  "actions": null,
  "extra": null,
  "retrieved": false,
  "data": {
    "session_id": 123456789,
    "code": "583921",
    "qr_payload": "https://api.sandbox.whish.money/pay/AbC123xY",
    "expiry_time": "2026-06-30T12:10:00Z",
    "status": "pending"
  }
}

Session data

Get payment status

Returns the collect status of the session. Use it to confirm the outcome when a callback did not arrive, and to tell a settled outcome from an open one: a failure callback reports one failed attempt and leaves the session payable, so this endpoint is what confirms a session finally failed.

curl -X POST 'https://partner.api.sbx.whish.money/itel-service/api/payment/collect/status' \
  -H 'channel: YOUR_CHANNEL' \
  -H 'secret: YOUR_SECRET' \
  -H 'websiteUrl: https://yoursite.com' \
  -H 'User-Agent: AcmeStore/2.1 (https://acme.example; dev@acme.example)' \
  -H 'Content-Type: application/json' \
  -d '{ "currency": "USD", "externalId": "ORDER-2026-0001" }'

Request body

{
  "currency": "USD",
  "externalId": "ORDER-2026-0001"
}

{
  "status": true,
  "code": null,
  "dialog": null,
  "actions": null,
  "extra": null,
  "data": {
    "collectStatus": "success",
    "payerPhoneNumber": "96170123456"
  }
}

Response fields

Session behavior

QR and code

• qr_payload is the exact value to encode as a QR code.
• The API returns the payload, not a PNG, SVG, or Base64 image.
• The six-digit code and the QR payload refer to the same session and share the same expiry time.
• A session can be completed only once.

Expiry

After expiry, the QR payload and code must no longer be used. A new payment attempt must use a new externalId.

Duplicate externalId

Supported statuses

Callbacks

When callbackUrl is provided, Whish reports the outcome of every payment attempt on the session to it.

• Whish calls it after every attempt: once with status: "success" when the session is paid, and once with status: "failed" for each attempt that fails.
• You get one callback per attempt, so a session paid on the second try produces a failed callback followed by a success callback.
• The callback uses HTTP POST with Content-Type: application/json.
• The request body carries the payment result; both shapes are identical apart from status.
• Query parameters already included in the merchant URL are preserved.
• Respond with HTTP 200 to acknowledge receipt.

https://merchant.example/api/whish/payment-result?orderId=ORDER-2026-0001

{
  "status": "success",
  "amount": 10000,
  "currency": "LBP",
  "timestamp": 1787299542710,
  "external_id": "17872994498120050",
  "session_id": 25257080
}

{
  "status": "failed",
  "amount": 10000,
  "currency": "LBP",
  "timestamp": 1787299530415,
  "external_id": "17872994498120050",
  "session_id": 25257080
}

Callback body

Error codes

{
  "status": false,
  "code": "amount.invalid",
  "dialog": {
    "title": "Error",
    "message": "Amount must be greater than zero"
  },
  "actions": null,
  "extra": null,
  "data": null
}

Core codes

Additional error codes

Version history

Notable changes to this API and its reference, newest first. The current version is the one shown at the top of this page.

Postman & tools

Import the ready-made Postman collection for this API, set your credentials as collection variables (or attach a sandbox / production environment), and call every endpoint without writing code. The OpenAPI 3.1 specification is also available to generate client SDKs or validate requests.

Download collectionOpenAPI specAll downloads & environments