Whish Pay API

Authentication is by channel + secret + websiteUrl, issued by Whish. Payments settle in USD · LBP. This is API v1.4.3; breaking changes are released under a new version.

Every request must include the headers below, plus Content-Type: application/json on requests that send a body.

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.

Interpret the outcome from status and code:

The happy path from a checkout to a confirmed order. Each step links to its endpoint below.

1. 1

   Create a payment

   Call Create a payment with the amount, currency, your numeric externalId, and your callback URLs. You receive a collectUrl.

2. 2

   Redirect the payer

   Send the customer to the collectUrl. They pay from their Whish balance and authorize the charge by entering the OTP delivered to their Whish app. This happens entirely on the hosted page; your integration is not involved in it.

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.

Returns the real balance of the account. Pass currency as a query-string parameter on the request URL to choose which balance to return.

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

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

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

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.

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

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

Initiates a full refund for a Whish Pay transaction (partial refunds are not supported). Requires IP whitelisting: it only accepts requests from source IPs that Whish has registered for your account. Send Whish the public egress IP(s) your servers call from, for both Sandbox and Production; otherwise refund requests are rejected. See IP whitelisting below.

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

When a payment settles, Whish sends an HTTP GET request to the successCallbackUrl or failureCallbackUrl you supplied in Create a payment, with your query parameters and nothing added by Whish. Which URL is called tells you the result. The callback is your primary confirmation; the browser redirect is not.

Handle callbacks like this:

• •Whish sends the callback once and does not retry. If your endpoint is unavailable when it fires, you will not receive it again, so reconcile with Get payment status using the externalId.
• •Before you fulfil the order, confirm the outcome with Get payment status. Requests are idempotent by externalId, so re-checking is always safe.
• •Callback URLs must use HTTPS and be publicly reachable. localhost and private addresses will not receive callbacks.

On failure, read code from the response body. Match on the exact literal value, including any unusual spelling. The documented code is below; code: 500 is a pending result, not a failure (see Response format).

Two kinds of IP allowlisting apply, in opposite directions. Set up whichever your integration needs.

Import the collection and one of the environment files, fill in your credentials, and call every endpoint without writing code. The {{baseUrl}} defaults to Sandbox so you cannot accidentally hit Production; switch to the Production environment for live traffic. Each request ships with an example response.

For credentials, Production access, or clarification, contact the Whish Pay team at whishpay@whish.money.