Guides

Reliability & idempotency

How to build integrations that stay correct through timeouts and network hiccups: use idempotency keys, retry safely, and confirm the real outcome before acting on it.

Idempotency keys

Every money-moving request carries a client-generated identifier that makes it safe to retry. Send a unique value per operation, and reuse the same value if you need to retry that same operation.

API	Idempotency key	Where it goes
International Money Transfer	`Request-id`	Request header (also usable as `requestId` in the status body)
Whish Pay	`externalId`	Request body
Direct Credit	`externalId`	Request body
Bills	`externalId`	Pay Bill request body
Variable Topup	`externalId`	Request body
Vouchers	`externalId`	Request body

🔑

Generate the key on your side (for example a UUID or your own order reference) and store it with the order before you send the request, so you can reproduce it exactly on retry.

Safe retries on timeouts & network issues

If you do not receive a response (timeout, dropped connection, or any communication issue), resend the same request with the same idempotency key. This never creates a duplicate:

If the original request never reached Whish, the operation is initiated now.
If the original request was already processed, Whish returns the original response for that key, so no duplicate is created.

ℹ️

How the "already processed" response looks differs by platform:

International Money Transfer (resend POST /api/woo/send/money with the same Request-id) returns the original response exactly as it was first returned. It does not add a retrieved flag.

The other Whish APIs (resend with the same externalId) return the response with retrieved: true to indicate it was already processed.

Confirm the outcome before acting

Do not assume an outcome from a missing response. Confirm it first, in this order:

Retry the original request with the same idempotency key (above). This is what registers the transaction and returns its authoritative response.
Then read the status. Only query a status endpoint after you know the original request was received. Querying a transfer that was never registered returns sending.transfer.invalid.info, which means it does not exist yet, not that it failed.
Prefer callbacks where available. Whish Pay and Cash Collection transfers notify your callbackUrl when the outcome is ready; treat that as your primary signal and use status polling as a fallback.

Interpreting the result

All APIs return HTTP 200 with a status field. Branch on the body, not the HTTP code.

Condition	Treat as
`status: true`	Success
`status: false` and `code` is not `500`	Failed (resolve automatically by error code)
`status: false` and `code: 500`	Pending (follow up with Whish Money)

See the International Money Transfer handling guide for the full status interpretation, receipt rules, and the list of error codes to treat as final failures.

✅

Checklist: unique key per operation · store it before sending · retry with the same key on no-response · confirm receipt before polling status · prefer callbacks · branch on status and code.