Bills

Integration flow

1. 1
   Fetch the bill. Call Fetch a bill with the customer account. Some billers require a provider OTP first. You receive the billId and the exact baseAmount due.
2. 2
   Pay the bill. Call Pay a bill with the billId and baseAmount returned by fetch, plus a unique externalId.
3. 3
   Reconcile if needed. On a timeout, resend the same externalId; the original result replays with retrieved: true and never pays twice.

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 transaction has progressed. Where an operation has a lifecycle of its own (created, paid, refunded), the endpoint reports it on a separate field inside data; see that endpoint's response fields.

Get account balance

Returns the real and void balance of the account. The void balance is the value of items you purchased that have since been voided, meaning set aside rather than cancelled: that value stays with your account and is drawn on the next time you buy the same product.

curl 'https://partner.api.sbx.whish.money/itel-service/api/account/balance' \
  -H 'sessionId: YOUR_SESSION_ID' \
  -H 'token: YOUR_TOKEN' \
  -H 'language: en' \
  -H 'User-Agent: AcmeStore/2.1 (https://acme.example; dev@acme.example)'

{
  "status": true,
  "code": null,
  "dialog": null,
  "extra": null,
  "data": {
    "balanceDetails": {
      "balance": -217.718,
      "voidBalance": 0.0
    }
  }
}

Response fields

Fetch a bill

Fetches a bill. For most denominations this is a two-step, OTP-verified flow; selected denominations skip OTP.

curl -X POST 'https://partner.api.sbx.whish.money/itel-service/api/bill/fetch' \
  -H 'sessionId: YOUR_SESSION_ID' \
  -H 'token: YOUR_TOKEN' \
  -H 'language: en' \
  -H 'User-Agent: AcmeStore/2.1 (https://acme.example; dev@acme.example)' \
  -H 'Content-Type: application/json' \
  -d '{ "denominationId": 53001, "target": "971555555555" }'

Request body

Standard flow: OTP first

{
  "denominationId": 53001,
  "target": "971555555555"
}

{
  "status": false,
  "code": "bill.requires_provider_otp",
  "dialog": {
    "title": "Verification required",
    "message": "Please enter the OTP sent by the provider."
  },
  "actions": null,
  "extra": null,
  "data": 6789
}

{
  "denominationId": 53001,
  "target": "971555555555",
  "verificationId": 6789,
  "otp": 1234
}

{
  "status": true,
  "code": null,
  "dialog": null,
  "actions": null,
  "extra": null,
  "data": {
    "billId": 1220,
    "target": "0555555555",
    "baseAmount": 19.0,
    "additionalAmount": 0.0,
    "totalAmount": 19.0,
    "allowPayAll": true,
    "minAmount": 19.0,
    "maxAmount": 19.0,
    "amountIncrement": 0.0
  }
}

Alternative flow: no OTP (selected denominations)

{
  "denominationId": 54001,
  "target": "971555555555"
}

{
  "status": true,
  "code": null,
  "dialog": null,
  "extra": null,
  "data": {
    "billId": 1234,
    "target": "971555555555",
    "baseAmount": 30.40,
    "additionalAmount": 1.60,
    "totalAmount": 32.00,
    "allowPayAll": true,
    "minAmount": null,
    "maxAmount": null,
    "amountIncrement": null
  }
}

Response fields (fetched bill)

Pay a bill

Pays the bill retrieved by Fetch Bill. Always pass the exact billId and baseAmount (as amount) returned by fetch.

curl -X POST 'https://partner.api.sbx.whish.money/itel-service/api/bill/payment' \
  -H 'sessionId: YOUR_SESSION_ID' \
  -H 'token: YOUR_TOKEN' \
  -H 'language: en' \
  -H 'User-Agent: AcmeStore/2.1 (https://acme.example; dev@acme.example)' \
  -H 'Content-Type: application/json' \
  -d '{ "externalId": "9876543210", "billId": 1220, "amount": 19.0 }'

Request body

{
  "externalId": "9876543210",
  "billId": 1220,
  "amount": 19.0
}

{
  "status": true,
  "code": null,
  "dialog": null,
  "extra": null
}

{
  "status": true,
  "code": null,
  "dialog": null,
  "extra": null,
  "retrieved": true
}

{
  "status": false,
  "code": "payment.failed",
  "dialog": {
    "title": "Error",
    "message": "Payment failed"
  },
  "extra": null
}

Sandbox scenarios

Best practices

• Always include sessionId, token, language headers.
• Treat bill.requires_provider_otp as a two-step flow, not an error; persist verificationId.
• Use the exact billId and baseAmount from fetch when paying.
• Use one externalId per payment (client-side idempotency). To retry the same payment after a timeout, resend the same externalId so it is not charged twice; only mint a new one for a genuinely new payment.
• Normalize amounts to two decimals for display; preserve full precision internally.
• On a timeout, treat the outcome as unknown: reconcile before you retry, and never assume a non-response means failure.

Error codes

Every code below is returned with status: false. Match the string exactly and branch on it, never on the dialog message text, which is written for display and can change.

Re-sending an already-used externalId never re-executes the transaction: the recorded result is replayed verbatim, including the original error code (safe retry, no double charge).

Bill fetch codes

Other provider-specific texts may surface under provider error codes, for example bill.payment.contact_touch, bill.payment.pay_at_touch_agent, bill.payment.pay_at_alfa_agent, bill.ajman.voucher.expired, bill.payment.wrong.amount.currency.usd, bill.payment.not_allowed_postpaid, bill.payment.not_available, and bill.skiptick_invalid_payment_status.

Bill payment codes

Common codes (all payment & billing endpoints)

Authentication, session, and request validation:

Account, balance, and limits (any debiting endpoint):

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