Whish Pay Split

Integration flow

1. 1
   Create the split payment. Call Create a split payment with the amount, currency, your externalId, the breakdown, 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.

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 reported on data.collectStatus by Get payment status.

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
  }
}

Response fields

Create a split payment

Creates a payment and records how the collected amount should be split across destination accounts. Returns the hosted URL where the payer completes the payment from their Whish balance.

curl -X POST 'https://partner.api.sbx.whish.money/itel-service/api/payment/whish/split' \
  -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": 100,
  "currency": "USD",
  "externalId": "your-unique-id-001",
  "invoice": "Order #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",
  "breakdownType": "amount",
  "breakdown": {
    "destination-1": 60,
    "destination-2": 40
  }
}'

Request body

{
  "amount": 100,
  "currency": "USD",
  "externalId": "your-unique-id-001",
  "invoice": "Order #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",
  "breakdownType": "amount",
  "breakdown": {
    "destination-1": 60,
    "destination-2": 40
  }
}

{
  "status": true,
  "code": null,
  "data": {
    "collectUrl": "https://pay.whish.money/invoice/pay/?q=abc123"
  }
}

Response fields

Get payment status

Returns the status of a payment. Call it with the externalId you sent when creating the payment. 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": "your-unique-id-001" }'

Request body

{
  "currency": "USD",
  "externalId": "your-unique-id-001"
}

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

Response fields

The breakdown object

breakdown is an object of identifier: value pairs. The identifier is any string you choose to label a destination: a name, a phone number, or an account id. Several identifiers may point at the same underlying destination. How the value is read depends on breakdownType.

Amount mode (default)

Use this when you already know the exact figure each destination should receive. Omitting breakdownType selects it.

"breakdownType": "amount",
"breakdown": {
  "destination-1": 60,
  "destination-2": 40
}

Percentage mode

Use this when you do not know each destination's exact figure up front, for example because a fee is deducted on the merchant's side and you would rather split whatever actually lands than split what you predicted. Set breakdownType to percentage and send the values as percentages instead of amounts.

"breakdownType": "percentage",
"breakdown": {
  "destination-1": 60,
  "destination-2": 40
}

Callbacks

Callbacks tell you the outcome of a payment attempt. Provide successCallbackUrl and failureCallbackUrl when you create the split 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=your-unique-id-001&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.
• The callback carries no breakdown information: it reports the outcome of the collect from the payer.

https://merchant.example/api/payment/success?externalId=your-unique-id-001&order=A-1234

IP whitelisting

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 payment: the recorded result is replayed verbatim, including the original error code (safe retry, no double charge).

{
  "status": false,
  "code": "400",
  "dialog": {
    "title": "Error",
    "message": "Invalid request"
  },
  "actions": null,
  "extra": null,
  "data": null
}

Payment codes

Common codes (all payment & billing endpoints)

Authentication, session, and request validation:

Account, balance, and limits:

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