> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rails.wayex.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Operations and reconciliation
> Track Treasury operations, consume webhooks safely, and reconcile each isolated account to wallet movements.
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
1. The current resource returned by its `GET` endpoint is authoritative for workflow state.
2. Wallet movements are authoritative for recorded balance changes.
3. Webhooks tell you when to fetch those resources; they are not an ordered ledger.
4. 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.
```bash theme={null}
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.
```bash theme={null}
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:
```bash theme={null}
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`.
Calculate HMAC-SHA256 over the exact raw body using the signing secret and compare it to
`X-Wayex-Signature` in constant time.
Store `eventId`. If it has already been processed, acknowledge the delivery without applying it
again.
Return a `2xx`, then process the event asynchronously in your own system.
Use the resource type and ID to call the relevant `GET`. Do not assume delivery order.
See [Developers](/console/developers) for signature code and delivery logs.
## Daily account reconciliation
For each tenant account and asset:
```text theme={null}
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:
1. Do not generate another idempotency key.
2. Retry the identical request with the original key.
3. If the response remains unknown, search operations by the original external reference.
4. Read its reservation and status.
5. 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](/api-reference/overview) for request and response fields and
[Errors](/errors) for machine-readable failure handling.