Operations and reconciliation

Use operation resources to understand workflow and immutable wallet movements to understand money. Reconcile each tenant account independently; never combine balances or references from separate tenant logins.

Source-of-truth order

The current resource returned by its GET endpoint is authoritative for workflow state.
Wallet movements are authoritative for recorded balance changes.
Webhooks tell you when to fetch those resources; they are not an ordered ledger.
Console activity is a human-readable view over the same records.

References to store

Reference	Who creates it	Use
`externalReference`	Client or Wayex	Stable business lookup and reconciliation; generated when supported and omitted.
Wayex resource ID	Wayex	Fetch one beneficiary, payout, conversion, withdrawal, deposit, or pay-in.
`Idempotency-Key`	Transfer	Make one logical write safe to retry. Do not use it as a display reference.
`eventId`	Wayex	Deduplicate webhook deliveries.
Provider/bank/transaction reference	Downstream rail	Reconcile the external settlement leg when exposed.

Generate the idempotency key before the first submission and persist it with your command. A new network attempt is not a new business action.

Search operations

Use the consolidated operation search for payout, conversion, and withdrawal queues. It can also recover an operation by the stable externalReference after a create response is lost.

curl --get https://api.sandbox.wayex.com/v1/treasury/operations \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY" \
  --data-urlencode "externalReference=payout-9172" \
  --data-urlencode "limit=25"

You can filter by kind, status, externalReference, from, and to. Date filters are ISO 8601 timestamps with an offset. When hasMore is true, pass nextCursor unchanged as cursor while keeping the other filters identical. Cursors are opaque and must not be decoded, edited, or reused with a different filter set.

Common operation states

State	What happened to funds	Next action
`accepted`	Source debit is durably reserved.	Wait for execution; do not duplicate.
`held`	Funds remain reserved or incoming money remains unavailable.	Read the reason and next action.
`submitted`	The external instruction was sent; settlement is not final.	Continue monitoring.
`settled`	The external outcome and wallet capture/credit completed.	Reconcile references and movements.
`failed`	The operation did not complete.	Verify whether the reservation was released before retrying.
`returned`	A previously submitted or settled payout came back.	Reconcile the return and recovery treatment.
Unknown/reconciling detail	The external outcome is not yet proven.	Keep the original operation; contact support when directed.

Every UI and integration message should answer three questions: what happened, whether the funds are spendable, and who acts next. Unknown must never be rendered as zero or failed.

Search and export transactions

The transaction search starts from immutable wallet movements, then adds the linked operation kind, status, and external reference where available. It excludes beneficiary bank details and saved wallet addresses.

curl --get https://api.sandbox.wayex.com/v1/treasury/transactions \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY" \
  --data-urlencode "from=2026-07-01T00:00:00+10:00" \
  --data-urlencode "to=2026-08-01T00:00:00+10:00" \
  --data-urlencode "limit=100"

Page with nextCursor in the same way as operation search. For a finance export, use the same filters without a cursor:

curl --get https://api.sandbox.wayex.com/v1/treasury/transactions/export \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY" \
  --data-urlencode "from=2026-07-01T00:00:00+10:00" \
  --data-urlencode "to=2026-08-01T00:00:00+10:00" \
  --data-urlencode "limit=5000" \
  --output treasury-transactions.csv

An export is bounded to 5,000 rows. If Wayex returns transaction_export_too_large, narrow the date range or other filters and retry. The CSV is a point-in-time record of wallet effects; a linked operation in accepted, held, or submitted is still not externally settled.

Consume webhooks safely

Treasury emits resource updates including:

treasury.wallet.updated
treasury.payin.updated
treasury.deposit.updated
treasury.payout.updated
treasury.withdrawal.updated
treasury.conversion.updated

Subscribe from the Developers area or POST /v1/webhooks.

Verify the signature

Calculate HMAC-SHA256 over the exact raw body using the signing secret and compare it to X-Wayex-Signature in constant time.

Deduplicate

Store eventId. If it has already been processed, acknowledge the delivery without applying it again.

Acknowledge quickly

Return a 2xx, then process the event asynchronously in your own system.

Fetch current state

Use the resource type and ID to call the relevant GET. Do not assume delivery order.

See Developers for signature code and delivery logs.

Daily account reconciliation

For each tenant account and asset:

opening balance
+ credited funding
+ conversion destination credits
+ returned payout credits
- payout, withdrawal, and conversion captures
- fees and approved adjustments
= closing balance

The result must match the wallet balance and its immutable movements. Reconcile accepted work still in reserved, incoming funds still in pending, and external settlement references separately.

Do not force a difference to zero with a client-side adjustment. Preserve the difference, resource IDs, timestamps, and request IDs, then contact Wayex support. Include no API keys, Sumsub tokens, or unnecessary personal data.

Lost-response example

If a payout request times out after submission:

Do not generate another idempotency key.
Retry the identical request with the original key.
If the response remains unknown, search operations by the original external reference.
Read its reservation and status.
Create a new payout only after the first operation is conclusively absent or terminal and safe to retry.

Go-live checks

Run fund, pay, convert, withdraw, return, and failure cases against the correct tenant account.
Prove a credential from one account cannot read or spend another.
Reconcile gross, fee, net credit, source debit, reservation, and closing balance.
Exercise duplicate and out-of-order webhook delivery.
Retry each value-changing request after a simulated lost response.
Confirm your operators understand accepted versus external settlement.

Use the API reference for request and response fields and Errors for machine-readable failure handling.

​Source-of-truth order

​References to store

​Search operations

​Common operation states

​Search and export transactions

​Consume webhooks safely

​Daily account reconciliation

​Lost-response example

​Go-live checks

Source-of-truth order

References to store

Search operations

Common operation states

Search and export transactions

Consume webhooks safely

Daily account reconciliation

Lost-response example

Go-live checks