Whish Pay

Integration flow

1. 1
   Create a payment. Call Create a payment with the amount, currency, your externalId, and your callback URLs. You receive a collectUrl.
2. 2
   Redirect the payer. Send the customer to the collectUrl. On that hosted page the payer authorizes the payment from their Whish balance and confirms with a one-time code (OTP) that Whish delivers to them as an in-app notification in the Whish app. This step happens entirely on the hosted page; your integration never sends or verifies the OTP.
3. 3
   Receive the callback. When the payment settles, Whish calls your successCallbackUrl or failureCallbackUrl by GET.
4. 4
   Confirm before fulfilling. Call Get payment status to verify the outcome, then release the order. Poll it as a fallback if no callback arrived.
5. 5
   Refund if needed. Use Refund a payment with the original externalId.

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 balance of the 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

Returns the hosted URL where the client is redirected to pay the merchant through their Whish balance.

curl -X POST 'https://partner.api.sbx.whish.money/itel-service/api/payment/whish' \
  -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": "1",
  "currency": "USD",
  "invoice": "Order #1",
  "externalId": "1",
  "successCallbackUrl": "https://merchant.example/api/payment/success",
  "failureCallbackUrl": "https://merchant.example/api/payment/failure",
  "successRedirectUrl": "https://merchant.example/thank-you",
  "failureRedirectUrl": "https://merchant.example/payment-error"
}'

Request body

{
  "amount": "1",
  "currency": "USD",
  "invoice": "Order #1",
  "externalId": "1",
  "successCallbackUrl": "https://merchant.example/api/payment/success",
  "failureCallbackUrl": "https://merchant.example/api/payment/failure",
  "successRedirectUrl": "https://merchant.example/thank-you",
  "failureRedirectUrl": "https://merchant.example/payment-error"
}

{
  "status": true,
  "code": null,
  "dialog": null,
  "extra": null,
  "data": {
    "collectUrl": "https://whish.money/pay/8nQS2mL"
  }
}

Response fields

Get payment status

Returns the collect status of a Whish Pay transaction. Use it to reconcile when a callback did not arrive, and to tell a settled outcome from an open one: a failure callback leaves the status pending while the link is still payable, so this endpoint is what confirms a payment 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": "1" }'

Request body

{
  "currency": "USD",
  "externalId": "1"
}

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

Response fields

Refund a payment

Initiates a refund for a Whish Pay transaction.

curl -X POST 'https://partner.api.sbx.whish.money/itel-service/api/payment/whish/refund' \
  -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": "1", "refundReason": "Customer canceled order" }'

Request body

{
  "currency": "USD",
  "externalId": "1",
  "refundReason": "Customer canceled order"
}

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

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

{
  "status": false,
  "code": "external_id.not_exists",
  "dialog": null,
  "actions": null,
  "extra": null,
  "data": null
}

Response fields

Callbacks

Callbacks tell you the outcome of a payment attempt. Provide successCallbackUrl and failureCallbackUrl when you create the payment; Whish calls them when an attempt on the payment link succeeds or fails.

• Each callback is an HTTP GET with no request body.
• You get one callback per attempt, so a link paid on the second try produces a failure callback followed by a success callback.
• Whish adds no identifying parameters of its own, so include your own reference in the callback URL (for example ?externalId=1&order=A-1234); Whish preserves and forwards them unchanged.
• Because the callback is an unauthenticated GET, treat it as a signal to verify, not as proof. Confirm the outcome with Get payment status before releasing the order.
• Respond with HTTP 200 to acknowledge receipt.
• A missing callback (for example a transient network failure) should be reconciled by polling Get payment status, not treated as a failure.

https://merchant.example/api/payment/success?externalId=1&order=A-1234

IP whitelisting

IP allowlisting applies to Whish Pay in two directions. Set up whichever your integration uses.

Calling restricted endpoints (you → Whish)

The Refund endpoint only accepts requests from source IPs that Whish has registered for your account. Send Whish the public egress IP address(es) your servers call from, for both Sandbox and Production, and Whish allowlists them on their side. Until then, refund requests from unregistered IPs are rejected.

Receiving callbacks (Whish → you)

Whish calls your successCallbackUrl and failureCallbackUrl from a fixed set of source IPs. If your callback endpoint restricts inbound traffic, allowlist them so callbacks are not blocked. The current list is maintained in one place: Callback source IPs in the Reliability & Idempotency guide.

Sandbox scenarios

Sandbox does not deliver the OTP that the payer would normally receive in the Whish app. Drive the hosted payment page with the fixed values below instead.

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

Whish Pay 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