Whish Pay
Collect payments from your customers through their Whish balance. Generate a hosted payment page, track status, and issue refunds.
REST over HTTPS with JSON requests and responses. Intended for authorized distributors.
Flow: call Post Payment to get a collectUrl, then redirect the payer there. To confirm the outcome, rely on your successCallbackUrl and failureCallbackUrl as the primary signal. Whish calls these URLs when the payment settles. Use Get Status only as a fallback, for example if a callback did not arrive.
Authentication & headers
Every request must include the HTTP headers below, plus Content-Type: application/json on requests that send a body.
| Header | Description |
|---|---|
channel | Value provided by Whish. |
secret | Value provided by Whish. |
websiteUrl | URL / name of the integrating site or application. |
User-Agent | Identifies your application to Whish. Send your own app name, version, website, and support contact, not Whish's details. Format: AppName/version (website; contact-email). Example: AcmeStore/2.1 (https://acme.example; dev@acme.example). |
Environments
| Environment | Base URL | Purpose |
|---|---|---|
| Sandbox | https://api.sandbox.whish.money/itel-service/api | Testing, QA, integration verification. |
| Production | https://api.whish.money/itel-service/api | Live environment for real transactions. |
Response format
All endpoints return HTTP 200 with Content-Type: application/json and a shared envelope. Always branch on the status field in the body, not the HTTP status code.
| Field | Type | Description |
|---|---|---|
status | Boolean | true = success · false = failure. |
code | String | Operation-specific failure code; null on success. |
dialog | Object | Optional title / message to display to the user. |
data | Object | Response payload for the operation; shape varies per endpoint. |
actions / extra | Object | Reserved; typically null. |
Get balance
Returns the real balance of the account. Specify the currency via the query string.
| Parameter | Type | Required | Description |
|---|---|---|---|
currency | String | Required | Currency: LBP or USD. |
{
"status": true,
"code": null,
"dialog": null,
"actions": null,
"extra": null,
"data": {
"balance": 10439.0
}
}Post payment
Returns the hosted URL where the client is redirected to pay the merchant through their Whish balance.
Request body
| Field | Type | Description |
|---|---|---|
amount | Double | Amount to be paid by the client. |
currency | String | Currency: LBP or USD. |
invoice | String | Description/details of the payment. |
externalId | Long | Numeric, unique per request; the transaction reference. |
successCallbackUrl | String | GET callback URL for a successful transaction. |
failureCallbackUrl | String | GET callback URL for a failed transaction. |
successRedirectUrl | String | Redirect URL after a successful payment. |
failureRedirectUrl | String | Redirect URL after a failed payment. |
{
"amount": "1",
"currency": "USD",
"invoice": "Order #1",
"externalId": 1,
"successCallbackUrl": "https://example.com/api/payment/success",
"failureCallbackUrl": "https://example.com/api/payment/failure",
"successRedirectUrl": "https://example.com/thank-you",
"failureRedirectUrl": "https://example.com/payment-error"
}{
"status": true,
"code": null,
"dialog": null,
"extra": null,
"data": {
"collectUrl": "https://whish.money/pay/8nQS2mL"
}
}The callback URLs are your primary confirmation. Whish calls them via GET when the payment settles, so treat them as the source of truth and update the order from them. The redirect URLs only send the client's browser onward. You may append custom query params (order reference, timestamp), and Whish forwards them unchanged. No OTP is delivered in sandbox.
Sandbox test: on the payment page use phone 96170902894 with OTP 111111 for success; any other OTP fails.
Get status
Returns the collect status of a Whish Pay transaction. Use this endpoint as a fallback to reconcile when a callback did not arrive; the callback URLs remain the primary confirmation.
Request body
| Field | Type | Description |
|---|---|---|
currency | String | Currency: LBP or USD. |
externalId | Long | ID provided by the third party. |
{
"currency": "USD",
"externalId": 1
}{
"status": true,
"code": null,
"dialog": null,
"extra": null,
"data": {
"collectStatus": "success",
"payerPhoneNumber": "96170902894"
}
}Response fields
| Field | Type | Description |
|---|---|---|
collectStatus | String | success, failed, or pending. |
payerPhoneNumber | Long | Phone number that performed the payment. |
Post refund
Initiates a refund for a Whish Pay transaction.
Requires IP whitelisting. The Refund endpoint only accepts requests from source IPs that Whish has registered for your account. Send Whish the public egress IP(s) your servers call from (Sandbox and Production) to be allowlisted; otherwise refund requests are rejected. See IP whitelisting.
Request body
| Field | Type | Description |
|---|---|---|
currency | String | Currency: LBP or USD. |
externalId | Long | ID of the original transaction to refund. |
refundReason | String | Reason for the refund. |
{
"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
| Field | Type | Description |
|---|---|---|
retrieved | Boolean | true if this refund was already processed before (duplicate). |
Error codes
| Code | Description |
|---|---|
external_id.not_exists | The provided externalId does not exist. |
IP whitelisting
Two kinds of IP allowlisting apply to Whish Pay. They work in opposite directions, so set up whichever your integration needs.
1. Inbound: your IP, allowlisted by Whish (required for Refund)
The Refund endpoint only accepts requests from source IPs that Whish has registered for your account. Provide Whish with the public egress IP address(es) your servers call from, for both Sandbox and Production, and Whish will allowlist them. Until then, refund requests from unregistered IPs are rejected.
2. Outbound: Whish's IPs, allowlisted by you (for callbacks)
Whish calls your successCallbackUrl and failureCallbackUrl from the fixed outbound IP addresses below. If your infrastructure has IP restrictions, allow all of these so callbacks are not blocked.
| Environment | Outbound callback IPs |
|---|---|
| Production | 18.213.222.4552.21.189.5152.21.55.64 |
| Sandbox | 52.4.4.47 |
Allowlist every address for the environment you use. Whish notifies partners in advance of any change to this list.
IP allowlisting is a network-level control. For stronger assurance, also verify the callback request itself (for example a shared secret or signature) rather than relying on source IP alone. See callbacks guidance for how Whish notifies you of outcomes.
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.
⤓ Download collectionAll downloads & environments
In Postman: Import → select the file → choose the Sandbox or Production environment → fill in your credentials. Requests use {{baseUrl}} and the credential variables provided.