Vouchers

Integration flow

1. 1
   Purchase a voucher. Call Purchase a voucher with the chosen denomination and a unique externalId.
2. 2
   Read the codes. The response returns the sold item synchronously, including the serialNumber and secretCode. Deliver these to your customer.
3. 3
   Retry safely. Resend the same externalId to retry; an already-processed purchase replays the same codes and never charges 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 balance of the account, including the value currently held as voided vouchers.

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,
  "actions": null,
  "extra": null,
  "data": {
    "balanceDetails": {
      "balance": 999790.646,
      "voidBalance": 0.0
    }
  }
}

Response fields (in data.balanceDetails)

Purchase a voucher

Purchases one or more vouchers of the given denomination and returns the item data (serial & secret).

curl -X POST 'https://partner.api.sbx.whish.money/itel-service/api/sale/item' \
  -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": "987654", "denominationId": 17002, "numberOfItems": 1 }'

Request body

{
  "externalId": "987654",
  "denominationId": 17002,
  "numberOfItems": 1
}

{
  "status": true,
  "code": null,
  "dialog": null,
  "actions": null,
  "extra": null,
  "data": {
    "listOfSoldItems": [
      {
        "date": "2026-07-20 14:34:18",
        "transactionId": 20224990,
        "service": "ITUNES USA",
        "denomination": "iTUNES $2 - USA",
        "denominationValue": 2.0,
        "validityPeriod": null,
        "expiryDate": "2027-06-13",
        "itemId": 64399932,
        "sessionCounter": 1,
        "serialNumber": "SBXITN8JBCXGOSUSNSC2PX",
        "secretCode": "SBXSEC4AXLW54V7YO2MSMX2J",
        "help": "",
        "contact": "+961 1 788 999",
        "type": 5,
        "picture": "iconitunes",
        "category": 0,
        "fromVoid": false,
        "printType": 1,
        "viewType": 1
      }
    ]
  }
}

{
  "status": true,
  "code": null,
  "dialog": null,
  "actions": null,
  "extra": null,
  "retrieved": true,
  "data": {
    "listOfSoldItems": [
      {
        "date": "2026-07-20 14:34:18",
        "transactionId": 20224990,
        "service": "ITUNES USA",
        "denomination": "iTUNES $2 - USA",
        "denominationValue": 2.0,
        "validityPeriod": null,
        "expiryDate": "2027-06-13",
        "itemId": 64399932,
        "sessionCounter": 1,
        "serialNumber": "SBXITN8JBCXGOSUSNSC2PX",
        "secretCode": "SBXSEC4AXLW54V7YO2MSMX2J",
        "help": "",
        "contact": "+961 1 788 999",
        "type": 5,
        "picture": "iconitunes",
        "category": 0,
        "fromVoid": false,
        "printType": 1,
        "viewType": 1
      }
    ]
  }
}

Response fields (listOfSoldItems[])

{
  "status": false,
  "code": "sales.requested_quantity_not_available_in_our_stock",
  "dialog": {
    "title": "Error",
    "message": "Sorry, the requested quantity is not available in our stock right now."
  },
  "actions": null,
  "extra": null,
  "data": null
}

Test denominations

Voiding vouchers

Voiding sets a purchased voucher aside for reuse instead of cancelling it. It is not a refund: no money moves, and no credit note is issued. The voucher's value stays with your account as void balance, and the item goes back to the front of the queue for its denomination, so your next purchase of that same denominationId hands you the voided voucher instead of charging you for new stock.

Requesting a void

Voiding is done by Whish, not through this API. Contact the Whish After Sales department with either the transactionId or the serialNumber of the voucher you want voided, both of which are returned in listOfSoldItems[] when you purchase. Store them with your order records so you can identify a voucher later.

What to void

How a voided voucher comes back

Voided items are consumed before new stock, per denomination. A purchase can therefore be filled from both: if you hold 3 voided vouchers of a denomination and request 10, you receive 10 vouchers, of which 3 come from your voided items and 7 are sold as new. You are charged for the 7 only. Each item that came back this way is flagged with fromVoid: true, so you can reconcile the charge against the response.

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).

Vouchers 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