Whish Collect — integration guide

When a customer pays, Whish hands you a hosted payment URL. You redirect the buyer there; they pay from their Whish wallet balance or by card on Whish's page; funds land in your Whish account; your server confirms the result out-of-band. Because the buyer leaves your checkout, the flow is redirect-based — plan your UX around the hand-off. There are two realistic routes to production:

The output of this stage is three credentials — a channel, a secret, and a registered websiteurl. Nothing technical works without them.

1. 1

   Create a Whish account

   Install the app and register at apps.whish.money.
2. 2

   Request merchant / Whish Pay

   In the app, choose the Whish Pay / merchant service and submit your business details.
3. 3

   Whish contacts you

   Their team follows up and sends a PDF onboarding form with next steps.
4. 4

   Submit the form + KYC

   Return the completed form with a valid ID and proof of residency/registration for verification.
5. 5

   Receive credentials

   Once verified, you're issued your Whish channel and secret.

Four operations cover everything you need to take a payment and reconcile it.

Every response shares a consistent envelope:

// present on every Collect response
{
  "status": true,            // true = success, false = failure
  "code":   null,            // operation-specific failure code when status=false
  "dialog": { "title": "…", "message": "…" }, // safe to show the user
  "data":   { /* operation payload */ }
}

No OAuth dance. Every request carries the same three header values from onboarding.

Five stops. The discipline that matters most is the last one — you decide an order is paid on your server, after asking Whish, not when the browser comes back.

1. 1

   Create the collect — your server → Whish

   POST amount, currency (LBP or USD), your own orderId, and success/failure callback URLs. Optionally call Get Rate first to show the net of fees.
2. 2

   Receive the collect URL — Whish → your server

   The response carries a hosted payment URL. Persist the Whish reference against your order so you can reconcile later.
3. 3

   Redirect & pay — customer ↔ Whish

   Send the buyer to the collect URL. They pay from their Whish balance or with a card on Whish's page. You don't see card data — that's the point.
4. 4

   Return to your callback — Whish → customer → you

   The buyer is redirected back to your success/failure URL. Treat this purely as a signal to go verify — not proof of payment.
5. 5

   Verify with Collect Status — your server → Whish

   Call Collect Status server-side with your stored reference. Only on success do you fulfil, mark paid, and run idempotency so a refresh can't double-fulfil.

A thin client plus two routes. Field names are placeholders to align with your spec PDF; the structure and the safety model carry over unchanged.

1 — A small Whish client. One place that owns the headers, base URL, and response envelope.

import axios from "axios";

const api = axios.create({
  baseURL: process.env.WHISH_BASE_URL,   // sandbox vs prod, from the spec
  headers: {
    channel:    process.env.WHISH_CHANNEL,
    secret:     process.env.WHISH_SECRET,
    websiteurl: process.env.WHISH_WEBSITE_URL,
    "Content-Type": "application/json",
  },
  timeout: 15000,
});

// Unwrap Whish's { status, code, dialog, data } envelope
async function call(path, body) {
  const { data: res } = await api.post(path, body ?? {});
  if (!res.status) {
    const err = new Error(res?.dialog?.message ?? "Whish request failed");
    err.code = res.code;
    throw err;
  }
  return res.data;
}

export const whish = {
  getRate: (amount, currency) => call("/payment/whish/rate", { amount, currency }),

  collect: (p) => call("/payment/whish/collect", {
    amount: p.amount,
    currency: p.currency,                 // "LBP" | "USD"
    invoice: p.invoice,                   // description shown to payer
    externalId: p.orderId,                // YOUR id, for reconciliation
    successCallbackUrl: p.successUrl,
    failureCallbackUrl: p.failureUrl,
  }),

  status: (orderId) => call("/payment/whish/collect/status", { externalId: orderId }),
};

2 — Start a payment. Create the collect, store the reference, redirect.

router.post("/pay", async (req, res) => {
  const order = await Orders.create({ amount: 25, currency: "USD", state: "pending" });

  const data = await whish.collect({
    amount: order.amount,
    currency: order.currency,
    invoice: `Order #${order.id}`,
    orderId: order.id,
    successUrl: `${BASE}/checkout/return?order=${order.id}`,
    failureUrl: `${BASE}/checkout/return?order=${order.id}&failed=1`,
  });

  await order.update({ whishRef: data.collectId });   // confirm field name
  res.redirect(data.collectUrl);                       // hosted Whish page
});

3 — Verify on return. The redirect only triggers a check; the order is paid only if Whish says so.

router.get("/return", async (req, res) => {
  const order = await Orders.find(req.query.order);

  // Idempotent: never fulfil the same order twice
  if (order.state === "paid") return res.redirect("/thank-you");

  const result = await whish.status(order.id);   // ask the source of truth

  if (result.collectStatus === "success") {       // confirm enum in spec
    await order.update({ state: "paid" });
    await fulfil(order);
    return res.redirect("/thank-you");
  }
  res.redirect("/checkout?status=unpaid");
});

• Sandbox first. Test the full lifecycle in sandbox and only flip the base URL to production once it passes. Sandbox and prod credentials are separate.
• Two currencies, real consequences. LBP and USD are both supported, but amounts, balances, and fees differ per currency. Be explicit about currency on every call and store it on the order.
• Fees come out of the invoice. Get Rate tells you what Whish deducts. If you need to net a specific amount, gross it up before calling Collect.
• Redirect ≠ receipt. Anyone can hit your success URL. Fulfilment must hang off a server-side Collect Status check, never the query string.
• Idempotency. A refresh on the return page must not charge or fulfil twice. Guard on order state.
• Field names vary. Exact request/response keys and status enums live in your spec PDF. Wire them against the document, not this guide's placeholders.
• UX for the hand-off. Customers leave your site to pay. Set expectations on checkout and design the return clearly so the redirect doesn't read as an error.