# Create an API key Source: https://docs.rails.wayex.com/api-reference/api-keys/create-an-api-key /api-reference/openapi.json post /v1/api-keys Creates a tenant-bound API key with the requested type and access restrictions. ## What this endpoint does Creates a tenant-bound API key with the requested type and access restrictions. ## When to use it Create a separate key for each service or integration boundary so it can be rotated independently. ## Before you call Create keys from a console session with API-key administration access and a recent second-factor (MFA) confirmation — a request authenticated only with an API key is refused with `403 step_up_required`. Grant only the access the new integration needs. ## Money and balance effect This changes a resource or configuration but does not directly reserve, debit, credit, or settle wallet money. ## States and completion The full secret is returned once. Store it immediately; later reads return metadata only. ## Safe retries Send a unique `Idempotency-Key` for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read [API keys](/console/developers) for the complete workflow. # List API keys Source: https://docs.rails.wayex.com/api-reference/api-keys/list-api-keys /api-reference/openapi.json get /v1/api-keys Lists API-key metadata for the current tenant account without returning secret values. ## What this endpoint does Lists API-key metadata for the current tenant account without returning secret values. ## When to use it Use it to audit access, locate a key for rotation, or review its role and restrictions. ## Before you call Authenticate with an API key that can read this resource. Results are restricted to the tenant account bound to that key. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Each key’s `status` is `active` or `revoked`. Restrictions are reported separately in the optional `scopes` and `allowedIps` fields — a key without them has full role-implied access from any IP. Secret material is never recoverable from this endpoint. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [API keys](/console/developers) for the complete workflow. # Revoke an API key Source: https://docs.rails.wayex.com/api-reference/api-keys/revoke-an-api-key /api-reference/openapi.json delete /v1/api-keys/{id} Revokes an API key so it can no longer authenticate new requests. ## What this endpoint does Revokes an API key so it can no longer authenticate new requests. ## When to use it Revoke a key when an integration is retired, compromised, or replaced. ## Before you call Manage keys from a console session with a recent second-factor (MFA) confirmation — a request authenticated only with an API key is refused with `403 step_up_required` — and pass a key ID owned by the same tenant account. Ensure another administrator key remains available. ## Money and balance effect This changes a resource or configuration but does not directly reserve, debit, credit, or settle wallet money. ## States and completion Revocation is the terminal key state. It does not cancel money operations already accepted. ## Safe retries DELETE does not use an `Idempotency-Key`. If the response is lost, list the key first. An already revoked or absent key means there is no active credential left to revoke. Read [API keys](/console/developers) for the complete workflow. # Rotate an API key Source: https://docs.rails.wayex.com/api-reference/api-keys/rotate-an-api-key /api-reference/openapi.json post /v1/api-keys/{id}/rotate Issues a replacement API key that inherits the retiring key’s scopes and IP allow-list. The replacement has a new key ID; the retired key becomes status `revoked` with `rotatedToId` pointing at its replacement. ## What this endpoint does Issues a replacement API key that inherits the retiring key’s scopes and IP allow-list. The replacement has a new key ID; the retired key becomes status `revoked` with `rotatedToId` pointing at its replacement. ## When to use it Rotate routinely and immediately after suspected exposure. ## Before you call Manage keys from a console session with a recent second-factor (MFA) confirmation — a request authenticated only with an API key is refused with `403 step_up_required` — and pass a key ID owned by the same tenant account. Prepare to update the consuming service. ## Money and balance effect This changes a resource or configuration but does not directly reserve, debit, credit, or settle wallet money. ## States and completion The new secret is returned once, on this response only. The old secret stops authenticating the moment rotation succeeds — there is no grace period. Update stored key IDs as well as the secret: later update or revoke calls must target the replacement key’s ID. ## Safe retries Send a unique `Idempotency-Key` for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read [API keys](/console/developers) for the complete workflow. # Update API-key restrictions Source: https://docs.rails.wayex.com/api-reference/api-keys/update-key-restrictions /api-reference/openapi.json patch /v1/api-keys/{id} Changes supported restrictions on an existing API key. ## What this endpoint does Changes supported restrictions on an existing API key. ## When to use it Use it to reduce or adjust access without issuing another key. ## Before you call Manage keys from a console session with a recent second-factor (MFA) confirmation — a request authenticated only with an API key is refused with `403 step_up_required` — and pass a key ID owned by the same tenant account. ## Money and balance effect This changes a resource or configuration but does not directly reserve, debit, credit, or settle wallet money. ## States and completion A successful response makes the new restrictions effective for later requests. Existing requests are not replayed. ## Safe retries PATCH does not use an `Idempotency-Key`. After an unknown response, list the key and compare its restrictions before retrying the identical update. Read [API keys](/console/developers) for the complete workflow. # Create a customer Source: https://docs.rails.wayex.com/api-reference/customers/create-a-customer /api-reference/openapi.json post /v1/customers Creates an individual or business customer under the current tenant account. ## What this endpoint does Creates an individual or business customer under the current tenant account. ## When to use it Create the customer before issuing verification or customer-owned payment routes. ## Before you call Use a secret API key with customer write access. The minimum body is the customer’s email — the customer then self-completes verification via a verification link. To supply identity up front, send the typed shape instead (`type` plus `contact`, and `businessDetails` for businesses). `externalCustomerId` is optional on every shape and is echoed back for cross-referencing. The optional free-form `metadata` map reserves one key name, `@@wxtype` (and any `@@wxtype.esc…` variant): a bag containing it is refused with `400 invalid_request` and nothing is written. ## Money and balance effect This changes a resource or configuration but does not directly reserve, debit, credit, or settle wallet money. ## States and completion Creation does not approve the customer. Verification and entitlements progress asynchronously. ## Safe retries Send a unique `Idempotency-Key` for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read [Customers](/console/customers) for the complete workflow. # Create a hosted verification link Source: https://docs.rails.wayex.com/api-reference/customers/create-a-verification-link /api-reference/openapi.json post /v1/customers/{id}/verification-link Issues a hosted link where a customer completes identity or business verification. ## What this endpoint does Issues a hosted link where a customer completes identity or business verification. ## When to use it Create it after onboarding a customer that still needs verification, then redirect or send them to the returned URL. ## Before you call Use a secret API key with customer write access and pass a customer ID owned by this tenant account. ## Money and balance effect This changes a resource or configuration but does not directly reserve, debit, credit, or settle wallet money. ## States and completion The link only starts verification. The final result arrives asynchronously and updates the customer and entitlements. ## Safe retries Send a unique `Idempotency-Key` for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read [Customers](/console/customers) for the complete workflow. # Get a customer Source: https://docs.rails.wayex.com/api-reference/customers/get-a-customer /api-reference/openapi.json get /v1/customers/{id} Returns the current record for one customer. ## What this endpoint does Returns the current record for one customer. ## When to use it Use it for customer detail, support checks, and authoritative state after a webhook. ## Before you call Authenticate with customer read access and pass a customer ID owned by the same tenant account. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion The customer’s `verificationStatus` is `in_progress`, `approved`, `rejected`, or `requires_action`; each `entitlements` entry carries its own `status` from the same set. Both are authoritative at response time — only `approved` entitlements can be used. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Customers](/console/customers) for the complete workflow. # List customers Source: https://docs.rails.wayex.com/api-reference/customers/list-customers /api-reference/openapi.json get /v1/customers Lists end customers onboarded under the current tenant account. ## What this endpoint does Lists end customers onboarded under the current tenant account. ## When to use it Use it to build customer search, onboarding queues, and links into customer detail. ## Before you call Authenticate with an API key that can read this resource. Results are restricted to the tenant account bound to that key. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Customer and verification states are snapshots. Fetch the customer or its entitlements when you need current eligibility. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Customers](/console/customers) for the complete workflow. # List customer entitlements Source: https://docs.rails.wayex.com/api-reference/customers/list-entitlements /api-reference/openapi.json get /v1/customers/{id}/entitlements Returns the capabilities currently granted to one customer. ## What this endpoint does Returns the capabilities currently granted to one customer. ## When to use it Check it before creating a payment route or enabling a customer flow in your product. ## Before you call Authenticate with customer read access and pass a customer ID owned by the same tenant account. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Entitlements can be in progress, approved, rejected, or require action. Only approved capabilities may be used. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Customers](/console/customers) for the complete workflow. # Update a customer Source: https://docs.rails.wayex.com/api-reference/customers/update-a-customer /api-reference/openapi.json patch /v1/customers/{id} Updates supported fields on an existing customer without replacing the whole record. ## What this endpoint does Updates supported fields on an existing customer without replacing the whole record. ## When to use it Use it when customer details change and the schema permits that field to be edited. ## Before you call Use a secret API key with customer write access and pass a customer ID owned by the same tenant account. ## Money and balance effect This changes a resource or configuration but does not directly reserve, debit, credit, or settle wallet money. ## States and completion Updates apply immediately and do not re-trigger verification. The customer’s verification state and entitlements are unchanged by this call. ## Safe retries PATCH does not use an `Idempotency-Key`. After an unknown response, read the customer first; retry the identical field update only if the desired values are not present. Read [Customers](/console/customers) for the complete workflow. # Get the developer fee schedule Source: https://docs.rails.wayex.com/api-reference/fees/get-developer-fees /api-reference/openapi.json get /v1/developer-fees Returns the developer fee schedule applied to eligible future direct-route conversions. ## What this endpoint does Returns the developer fee schedule applied to eligible future direct-route conversions. ## When to use it Use it to display the current flat and basis-point fee configuration. ## Before you call Authenticate with an API key that can read this resource. Results are restricted to the tenant account bound to that key. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion The response is the effective schedule at read time. It does not reprice transfers already in progress. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Developer settings](/console/developers) for the complete workflow. # Set the developer fee schedule Source: https://docs.rails.wayex.com/api-reference/fees/set-developer-fees /api-reference/openapi.json put /v1/developer-fees Replaces the developer fee schedule used for eligible future direct-route conversions. ## What this endpoint does Replaces the developer fee schedule used for eligible future direct-route conversions. ## When to use it Use it when changing the flat amount, basis-point amount, or removing the schedule. ## Before you call Requires a secret API key plus a recent second-factor (MFA) confirmation from the signed-in user — a request authenticated only with an API key is refused with `403 step_up_required`. In practice, change the schedule from a console session and send the complete desired schedule. ## Money and balance effect This does not debit a wallet immediately. The new schedule affects eligible conversions created after the change. ## States and completion A successful response confirms the saved schedule. In-flight transfers keep the pricing captured for them. ## Safe retries Send a unique `Idempotency-Key` for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read [Developer settings](/console/developers) for the complete workflow. # Accept a team invitation Source: https://docs.rails.wayex.com/api-reference/invitations/accept-an-invitation /api-reference/openapi.json post /v1/invite/{token}/complete Uses a valid invitation token to set the first administrator’s permanent console password and activate the account the invitation was issued to. ## What this endpoint does Uses a valid invitation token to set the first administrator’s permanent console password and activate the account the invitation was issued to. ## When to use it Submit it once after the recipient has reviewed the invitation and chosen a password. ## Before you call Pass a valid, unused invitation token and a request that meets the credential requirements. No API key is required. ## Money and balance effect This changes a resource or configuration but does not directly reserve, debit, credit, or settle wallet money. ## States and completion A successful response consumes the token. Expired or previously used tokens must be replaced by a new invitation. ## Safe retries Do not submit concurrently. If the response is lost, validate the token again before retrying; a consumed token means activation already completed. Read [Team and roles](/console/team-roles) for the complete workflow. # Validate a team invitation Source: https://docs.rails.wayex.com/api-reference/invitations/validate-an-invitation /api-reference/openapi.json get /v1/invite/{token} Checks whether a one-time team invitation token is valid and returns the invitation details needed by the activation screen. ## What this endpoint does Checks whether a one-time team invitation token is valid and returns the invitation details needed by the activation screen. ## When to use it Call it after a recipient opens an invitation link and before showing the account-activation form. ## Before you call Pass the invitation token from the link. This endpoint does not require an API key. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion A valid token returns the invitation context. Unknown, expired, and already-used tokens all return the same generic `404` — the response deliberately never reveals which — so build the activation screen around two outcomes: proceed with activation, or request a new invitation. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Team and roles](/console/team-roles) for the complete workflow. # Get an invoice Source: https://docs.rails.wayex.com/api-reference/invoices/get-an-invoice /api-reference/openapi.json get /v1/invoices/{id} Returns line items and status for one invoice. ## What this endpoint does Returns line items and status for one invoice. ## When to use it Use it for invoice detail, accounting export, or support investigation. ## Before you call Authenticate with an API key that can read fees — a scoped key must include `fees:read` (`fees:write` implies it); this family also covers revenue and invoices — and pass an invoice ID owned by the same tenant account. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Use the invoice status and amounts as returned; a listed invoice is not necessarily settled. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Revenue and invoices](/console/activity) for the complete workflow. # List invoices Source: https://docs.rails.wayex.com/api-reference/invoices/list-invoices /api-reference/openapi.json get /v1/invoices Lists invoices issued to the current tenant account. ## What this endpoint does Lists invoices issued to the current tenant account. ## When to use it Use it to reconcile billing periods, platform fees, developer-fee credits, and payment status. ## Before you call Authenticate with an API key that can read fees — a scoped key must include `fees:read` (`fees:write` implies it); this family also covers revenue and invoices. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Only `issued` and `settled` invoices appear here — `issued` means awaiting settlement; `settled` is final. The schema’s `draft` and `void` values are internal states that are never returned on this endpoint. Open the invoice for its line-item detail. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Revenue and invoices](/console/activity) for the complete workflow. # API reference Source: https://docs.rails.wayex.com/api-reference/overview Base URL, authentication, conventions, and endpoint explainers for the Wayex REST API. The Wayex API is resource-oriented, returns JSON, and uses standard HTTP verbs and status codes. The OpenAPI document is generated from the application and enriched with client-facing workflow context. ## Base URLs | Environment | Base URL | | -------------- | ------------------------------------- | | **Sandbox** | `https://api.sandbox.rails.wayex.com` | | **Production** | `https://api.rails.wayex.com` | Current endpoints are versioned under `/v1`. Sandbox runs on fully simulated provider rails and never moves real funds; production moves real value. API keys are issued per environment. ## Authentication and account isolation Send a tenant-bound API key as `Authorization: Bearer ` or `X-Api-Key: `. Secret keys can perform permitted writes; publishable keys are read-only. The key determines the tenant account. A request cannot choose another tenant in its body. Separate tenant accounts have separate keys, wallets, configuration, webhooks, and reporting. See [Authentication](/authentication). ## Two integration models ### Direct payment routes Create a route under an onboarded customer and share its reusable funding instructions. A funding event automatically creates a transfer, prices at the live rate, converts, and delivers funds. The Rates API is indicative and never binds this workflow. Read [Payment routes](/console/payment-routes) for the full flow. ### Treasury Prefund an isolated tenant wallet in AUD or supported stablecoin. Then create beneficiaries and AUD payouts, request and accept exact conversion quotes, and withdraw stablecoin to saved destinations. `accepted` means Wayex approved the request and reserved the full amount, including fees, from your wallet — it moves from `available` to `reserved`. It does not mean money has moved anywhere yet: the bank payout, on-chain transfer, or conversion settles asynchronously afterwards. Watch webhooks or poll the operation until it reaches a final status — `settled`, `failed`, or `returned`. A conversion credits the destination balance only after settlement completes. Read the [Treasury overview](/treasury/overview) before integrating. ## Find the endpoint you need The API reference is organized by workflow. Expand **Core workflows** for the endpoints needed to fund a wallet, pay AUD, convert balances, withdraw stablecoin, or create a direct payment route. Expand **Advanced API** when you need list and detail lookups, lifecycle actions, reconciliation, webhook diagnostics, credentials, or reporting. These endpoints remain fully documented without crowding the launch path. ## Conventions * **Idempotency** — every authenticated `POST`/`PUT` requires an `Idempotency-Key` header; requests without one are rejected. Retry a timeout or unknown outcome with the same key and the API replays the original response instead of acting twice; reusing a key with different parameters is rejected. `PATCH`/`DELETE` retry rules appear on their endpoint pages. See [Idempotency](/idempotency). * **Money** — amounts are exact decimal strings with an explicit asset; never parse them as floating point. * **Networks** — treat asset and network as one pair. Never infer a network from an address. Supported pairs are enforced fail-closed. **USDC:** `ethereum`, `base`, `arbitrum`, `optimism`, `polygon`, `bsc`, `solana`. **USDT:** `ethereum`, `arbitrum`, `optimism`, `avalanche`, `solana`, `tron`. Any other pair is rejected `400` with code `unsupported_asset_network`. Treasury availability is additionally gated by your account's effective settings (`GET /v1/treasury/configurations/effective`) and surfaces as `422` with code `asset_network_unavailable`. * **References** — store the Wayex resource ID from every create response. Some writes require an `externalReference` from your own system (for example, Treasury payouts); on others (for example, beneficiaries) it is optional and Wayex generates one when omitted. Each endpoint page's request schema marks which applies. * **Lists** — use server filters and cursors when exposed. Do not fetch a short window and treat it as a complete ledger. * **Webhooks** — deliveries are at-least-once and unordered. Deduplicate, then fetch current state. * **Errors** — branch on stable `code` and log `requestId`; never parse human-readable messages. ## What every endpoint page explains Each generated endpoint page includes: 1. what the endpoint does; 2. when to use it; 3. prerequisites and required access; 4. money and wallet effect; 5. important states and what completion means; 6. retry and idempotency behavior; 7. a link to the relevant end-to-end guide. This content is enforced by the public-spec generator. An endpoint cannot be published without a complete explainer entry. ## Resources | Resource | Description | | -------------------- | ---------------------------------------------------------------------------- | | **Customers** | Onboard and verify end users for direct payment routes. | | **Payment routes** | Issue reusable customer funding instructions for automatic on-ramp/off-ramp. | | **Transfers** | Read conversions created by direct-route funding events. | | **Rates** | Read current indicative conversion rates. | | **Treasury** | Fund, pay, convert, withdraw, and reconcile one isolated tenant wallet. | | **Webhooks** | Subscribe to signed asynchronous updates and inspect deliveries. | | **API keys** | Create, restrict, rotate, and revoke tenant-bound credentials. | | **Fees and revenue** | Manage developer fees and report earned revenue. | | **Invoices** | Reconcile issued billing records and line items. | | **Invitations** | Activate staff access to a tenant account. | Choose a workflow in the navigation or download the complete OpenAPI specification from the page menu. Production instructions move real value. Test in sandbox first, then confirm the agreed asset/network and limits with Wayex before funding a production instruction. # Create a payment route for a customer Source: https://docs.rails.wayex.com/api-reference/payment-routes/create-a-customer-payment-route /api-reference/openapi.json post /v1/customers/{customerId}/payment-routes Creates a standing payment route under the customer identified in the URL. ## What this endpoint does Creates a standing payment route under the customer identified in the URL. ## When to use it Use this customer-scoped form when your integration already works from a customer record. ## Before you call Use a secret API key with route write access. The customer must belong to this tenant account and have the required approved entitlement. ## Money and balance effect Creating the route does not move money. Funding the issued instructions later starts a transfer. ## States and completion Creation confirms route provisioning, not funding or settlement. Track each later funding through its transfer. ## Safe retries Send a unique `Idempotency-Key` for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read [Payment routes](/console/payment-routes) for the complete workflow. # Create a payment route Source: https://docs.rails.wayex.com/api-reference/payment-routes/create-a-payment-route /api-reference/openapi.json post /v1/payment-routes Creates a standing on-ramp or off-ramp route and provisions its reusable funding instructions. ## What this endpoint does Creates a standing on-ramp or off-ramp route and provisions its reusable funding instructions. ## When to use it Use it after the customer has the required approved entitlement and you know the delivery destination and route limits. ## Before you call Use a secret API key with route write access. The customer must belong to this tenant account and be eligible for the requested route. ## Money and balance effect Creating the route does not move money. A later funding event starts a transfer and may convert and deliver funds. ## States and completion Creation returns the route, not a completed transfer. Monitor transfers created when the route receives funding. ## Safe retries Send a unique `Idempotency-Key` for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read [Payment routes](/console/payment-routes) for the complete workflow. # Get a payment route Source: https://docs.rails.wayex.com/api-reference/payment-routes/get-a-payment-route /api-reference/openapi.json get /v1/payment-routes/{id} Returns configuration and current status for one standing payment route. ## What this endpoint does Returns configuration and current status for one standing payment route. ## When to use it Use it to display route detail, validate its state, or follow a route reference from a transfer. ## Before you call Authenticate with route read access and pass a route ID owned by the same tenant account. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion The route status does not describe an individual funding. Read the linked transfer for conversion and settlement state. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Payment routes](/console/payment-routes) for the complete workflow. # Get payment route funding instructions Source: https://docs.rails.wayex.com/api-reference/payment-routes/get-funding-instructions /api-reference/openapi.json get /v1/payment-routes/{id}/instructions Returns the reusable bank or blockchain instructions a payer uses to fund one route. ## What this endpoint does Returns the reusable bank or blockchain instructions a payer uses to fund one route. ## When to use it Fetch it immediately before displaying or sharing instructions so you show the current values exactly as issued. ## Before you call Authenticate with route read access and pass a route ID owned by the same tenant account. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Instructions do not prove a payment was received. A funding event creates a transfer that must be tracked separately. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Payment routes](/console/payment-routes) for the complete workflow. # List a customer’s payment routes Source: https://docs.rails.wayex.com/api-reference/payment-routes/list-customer-payment-routes /api-reference/openapi.json get /v1/customers/{customerId}/payment-routes Lists standing payment routes owned by one customer. ## What this endpoint does Lists standing payment routes owned by one customer. ## When to use it Use it on customer detail pages or before deciding whether another route is needed. ## Before you call Authenticate with route read access and pass a customer ID owned by the same tenant account. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Route states indicate availability; individual funding and settlement states belong to transfers. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Payment routes](/console/payment-routes) for the complete workflow. # List payment routes Source: https://docs.rails.wayex.com/api-reference/payment-routes/list-payment-routes /api-reference/openapi.json get /v1/payment-routes Lists standing customer payment routes for the current tenant account. ## What this endpoint does Lists standing customer payment routes for the current tenant account. ## When to use it Use it for route search, monitoring, or locating the route linked to a direct-route transfer. ## Before you call Authenticate with an API key that can read this resource. Results are restricted to the tenant account bound to that key. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion A route’s `status` is `active` or `inactive`; only share an `active` route’s instructions with payers. Funding events and their conversion states appear as transfers, not on the route. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Payment routes](/console/payment-routes) for the complete workflow. # Get an indicative exchange rate Source: https://docs.rails.wayex.com/api-reference/rates/get-an-indicative-rate /api-reference/openapi.json get /v1/rates Returns the current indicative all-in rate for an AUD and stablecoin pair. It is useful for estimates and display only. ## What this endpoint does Returns the current indicative all-in rate for an AUD and stablecoin pair. It is useful for estimates and display only. ## When to use it Call it before showing an estimate. Do not treat the response as a locked quote: direct payment routes price when funds arrive, while Treasury conversions use a conversion quote. ## Before you call Authenticate with an API key that can read this resource. Results are restricted to the tenant account bound to that key. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion A successful response is a point-in-time indication. It does not create an operation and has no settlement status. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Quickstart](/quickstart) for the complete workflow. # Get developer-fee revenue Source: https://docs.rails.wayex.com/api-reference/revenue/get-revenue /api-reference/openapi.json get /v1/revenue Returns developer-fee revenue earned by the current tenant account. ## What this endpoint does Returns developer-fee revenue earned by the current tenant account. ## When to use it Use it to build fee-revenue reporting: group by `period` (`day`, `week`, or `month`; default `day`), and optionally bound the window with `from`/`to` or filter by `asset`. Amounts are decimal strings with an explicit asset code. Pair it with `GET /v1/invoices` to reconcile the developer-fee credits netted off each invoice. ## Before you call Authenticate with an API key that can read fees — a scoped key must include `fees:read` (`fees:write` implies it); this family also covers revenue and invoices. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Revenue appears according to completed conversion and billing records; unsettled transfers may not yet contribute. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Revenue and invoices](/console/activity) for the complete workflow. # Get developer-fee revenue (alias) Source: https://docs.rails.wayex.com/api-reference/revenue/get-revenue-alias /api-reference/openapi.json get /v1/reports/revenue Returns the same developer-fee revenue report through the reports namespace. ## What this endpoint does Returns the same developer-fee revenue report through the reports namespace. ## When to use it Use it only when your integration groups reporting endpoints under `/reports`; new integrations can use `/v1/revenue`. ## Before you call Authenticate with an API key that can read fees — a scoped key must include `fees:read` (`fees:write` implies it); this family also covers revenue and invoices. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Revenue appears according to completed conversion and billing records; unsettled transfers may not yet contribute. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Revenue and invoices](/console/activity) for the complete workflow. # Get a direct-route transfer Source: https://docs.rails.wayex.com/api-reference/transfers/get-a-transfer /api-reference/openapi.json get /v1/transfers/{id} Returns the authoritative lifecycle and linked references for one direct-route transfer. ## What this endpoint does Returns the authoritative lifecycle and linked references for one direct-route transfer. ## When to use it Use it after a webhook, when investigating a transfer, or when you need its current settlement state. ## Before you call Authenticate with transfer read access and pass a transfer ID owned by the same tenant account. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Read `status` together with the `timeline` array: entries record each state with its timestamp and, when present, a plain-language `description` explaining holds. `on_hold`, `payout_held`, `frozen`, `failed`, and `returned` are not settlement — only `completed` is. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Activity and history](/console/activity) for the complete workflow. # List recent account activity Source: https://docs.rails.wayex.com/api-reference/transfers/list-recent-activity /api-reference/openapi.json get /v1/activity Returns a reverse-chronological, cursor-paginated feed of direct-route transfer activity across all of your customers — a compact projection of the same set `GET /v1/transfers` returns. Treasury operations and customer events never appear here. ## What this endpoint does Returns a reverse-chronological, cursor-paginated feed of direct-route transfer activity across all of your customers — a compact projection of the same set `GET /v1/transfers` returns. Treasury operations and customer events never appear here. ## When to use it Use it for a dashboard feed of direct-route transfers. Treasury operations never appear here — read those from `GET /v1/treasury/operations` and `GET /v1/treasury/transactions`. Use resource-specific list and detail endpoints for full reconciliation. ## Before you call Authenticate with an API key that can read this resource. Results are restricted to the tenant account bound to that key. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Entries are compact transfer summaries; each entry’s `id` is the transfer ID. Fetch the transfer for its authoritative status and timeline. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Activity and history](/console/activity) for the complete workflow. # List direct-route transfers Source: https://docs.rails.wayex.com/api-reference/transfers/list-transfers /api-reference/openapi.json get /v1/transfers Lists conversions automatically created when customers fund direct payment routes. ## What this endpoint does Lists conversions automatically created when customers fund direct payment routes. ## When to use it Use it for transfer search, reconciliation, and monitoring across customers and routes. ## Before you call Authenticate with an API key that can read this resource. Results are restricted to the tenant account bound to that key. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion The `status` field carries the enum values shown in the schema, not display copy. Broadly: `awaiting_payin`, `awaiting_deposit`, and the `deposit_*` states are waiting on funds; states such as `screening`, `fx_executed`, `sweeping`, `pooled`, `payout_instructed`, and `sending` are in flight; `on_hold`, `payout_held`, and `frozen` are holds; `completed`, `failed`, `cancelled`, `returned`, `expired`, and `reversed` are terminal. Treat only `completed` as settled — never infer settlement from creation alone. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Activity and history](/console/activity) for the complete workflow. # Accept a Treasury conversion quote Source: https://docs.rails.wayex.com/api-reference/treasury/accept-a-conversion-quote /api-reference/openapi.json post /v1/treasury/conversions Accepts an unexpired quote, creates the wallet conversion, and durably reserves its source debit. ## What this endpoint does Accepts an unexpired quote, creates the wallet conversion, and durably reserves its source debit. ## When to use it Submit the quote ID returned by quote creation only after the user reviews and confirms the exact terms. Console users never type or copy that ID. ## Before you call Use a secret API key with `treasury:write`. The quote must belong to this tenant account, remain unexpired, and still pass balance, limit, and provider-capacity checks. ## Money and balance effect Acceptance reserves the quoted source debit. Wayex credits the destination wallet only after the trade and physical post-trade fund movements complete. ## States and completion Both `accepted` and `held` conversions have durably reserved the source debit. `accepted` means execution work is also durable; follow trade and settlement progress — an unknown leg remains reserved and reconciling until its real outcome is known. ## Safe retries Send a unique `Idempotency-Key` for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read [Conversions and withdrawals](/treasury/conversions-and-withdrawals) for the complete workflow. # Create a Treasury beneficiary Source: https://docs.rails.wayex.com/api-reference/treasury/create-a-beneficiary /api-reference/openapi.json post /v1/treasury/beneficiaries Creates a reusable individual or business recipient whose AUD payout destination is either a bank account (BSB and account number) or a PayID (email, phone, or ABN) — each carries an account name — and can validate optional Sumsub evidence in the same request. ## What this endpoint does Creates a reusable individual or business recipient whose AUD payout destination is either a bank account (BSB and account number) or a PayID (email, phone, or ABN) — each carries an account name — and can validate optional Sumsub evidence in the same request. ## When to use it Create the beneficiary before the first payout. Choose the `destination.type` your recipient uses (`bank_account` or `payid`). Supply `externalReference` only when your system already has a stable recipient identifier; otherwise Wayex generates one. ## Before you call Use a secret API key with `treasury:write`. Supply the required recipient and destination data. If a fresh end-client Sumsub share token is available or required by policy, send it in the input-only, single-use `sumsub.shareToken` field on this request. The free-form maps on this request — `partyContext`, `businessIdentity`, and `glMapping` — reserve one key name, `@@wxtype` (and any `@@wxtype.esc…` variant): a map containing it is refused with `400 invalid_request` and nothing is written. ## Money and balance effect This changes a resource or configuration but does not directly reserve, debit, credit, or settle wallet money. ## States and completion Creation does not guarantee a payout will pass current policy. Evidence, screening, limits, and balance are checked when the payout is submitted. ## Safe retries Send a unique `Idempotency-Key` for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read [Beneficiaries and payouts](/treasury/beneficiaries-and-payouts) for the complete workflow. # Create a Treasury conversion quote Source: https://docs.rails.wayex.com/api-reference/treasury/create-a-conversion-quote /api-reference/openapi.json post /v1/treasury/conversion-quotes Creates an exact, short-lived quote to convert between AUD and an enabled stablecoin in this tenant account. ## What this endpoint does Creates an exact, short-lived quote to convert between AUD and an enabled stablecoin in this tenant account. ## When to use it Create it after the user chooses a direction and source amount, then display its all-in rate, fee, source debit, destination amount, and expiry for review alongside the available source balance from the balances endpoint. The quote always returns the settlement network it was struck on; the console stores the returned quote ID internally. ## Before you call Use a secret API key with `treasury:write`. The pair must be enabled and the source amount must meet current limits. Converting **AUD to a stablecoin** requires `settlementNetwork` — the chain the purchased stablecoin is settled onto, and therefore the chain you will hold and withdraw it on. There is no default: omitting it fails with `settlement_network_required`, a chain Wayex cannot receive on fails with `unsupported_asset_network`, and a chain that differs from a route Wayex has pinned for that asset fails with `conversion_route_conflict`. Converting a stablecoin to AUD does not need the field — that direction routes by the balance you already hold, and a supplied value is only an override. ## Money and balance effect Creating a quote does not reserve or move money. The source wallet is checked and reserved only when the quote is accepted. ## States and completion A quote is usable until its expiry. If it expires or no longer passes acceptance checks, create a fresh quote rather than altering it. ## Safe retries Send a unique `Idempotency-Key` for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read [Conversions and withdrawals](/treasury/conversions-and-withdrawals) for the complete workflow. # Create Treasury funding instructions Source: https://docs.rails.wayex.com/api-reference/treasury/create-a-funding-instrument /api-reference/openapi.json post /v1/treasury/funding-instruments Provisions reusable AUD funding instructions or a stablecoin deposit address for this tenant account. An AUD instrument returns a BSB and account number and, by default, an email `payId` to pay into as well — set `includePayId` to false to skip the PayID. ## What this endpoint does Provisions reusable AUD funding instructions or a stablecoin deposit address for this tenant account. An AUD instrument returns a BSB and account number and, by default, an email `payId` to pay into as well — set `includePayId` to false to skip the PayID. ## When to use it Create one when the account does not already have suitable instructions for the required asset, rail, or network. ## Before you call Use a secret API key with `treasury:write`. The requested rail, asset, and network must be enabled for this tenant account. `includePayId` applies to AUD instruments only and defaults to true. ## Money and balance effect Provisioning instructions does not credit the wallet. The balance changes only after Wayex detects, validates, and credits incoming funds. ## States and completion Creation confirms the instrument was issued. A newly issued AUD account or PayID can take a few minutes to become active for NPP; when the response carries an `activationMessage`, show it and wait for activation before relying on the PayID. Track incoming funds separately and wait for the wallet credit before spending them. ## Safe retries Send a unique `Idempotency-Key` for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read [Funding and balances](/treasury/funding-and-balances) for the complete workflow. # Create an AUD payout Source: https://docs.rails.wayex.com/api-reference/treasury/create-a-payout /api-reference/openapi.json post /v1/treasury/payouts Creates an AUD payout to a saved beneficiary and durably reserves its source debit from this tenant account’s AUD wallet. ## What this endpoint does Creates an AUD payout to a saved beneficiary and durably reserves its source debit from this tenant account’s AUD wallet. ## When to use it Submit it after choosing the beneficiary, confirming the amount and purpose, and reviewing the effective fee and available balance. ## Before you call Use a secret API key with `treasury:write`. The beneficiary, its accepted evidence when required, limits, BSB/account rail, and wallet balance must all be eligible. Sumsub share tokens are submitted with beneficiary creation, not here. ## Money and balance effect On acceptance, the payout source debit is reserved so it cannot be spent twice. Settlement captures the reservation; a proven pre-settlement failure releases it, while returns follow the configured return policy. ## States and completion Both `accepted` and `held` payouts have durably reserved the source debit — the response’s `reservation` object shows `reserved`. `accepted` means policy passed; `held` needs review before submission. `submitted` reached the bank rail; `settled`, `failed`, and `returned` describe later outcomes. ## Safe retries Send a unique `Idempotency-Key` for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read [Beneficiaries and payouts](/treasury/beneficiaries-and-payouts) for the complete workflow. # Create a stablecoin destination Source: https://docs.rails.wayex.com/api-reference/treasury/create-a-stablecoin-destination /api-reference/openapi.json post /v1/treasury/destinations Saves and validates an asset/network/address destination for later stablecoin withdrawals from this tenant account. ## What this endpoint does Saves and validates an asset/network/address destination for later stablecoin withdrawals from this tenant account. ## When to use it Create it after verifying the owner, exact network, address, and required tag or memo out of band. ## Before you call Use a secret API key with `treasury:write`. The asset/network must be enabled and the address must pass format validation and screening. ## Money and balance effect Creating a destination does not reserve or move wallet money. ## States and completion A successful response returns an active validated destination. A failed or held screening result cannot be used for withdrawal. ## Safe retries Send a unique `Idempotency-Key` for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read [Conversions and withdrawals](/treasury/conversions-and-withdrawals) for the complete workflow. # Create a stablecoin withdrawal Source: https://docs.rails.wayex.com/api-reference/treasury/create-a-withdrawal /api-reference/openapi.json post /v1/treasury/withdrawals Creates a stablecoin withdrawal and durably reserves its source debit from this tenant account’s matching asset/network wallet. ## What this endpoint does Creates a stablecoin withdrawal and durably reserves its source debit from this tenant account’s matching asset/network wallet. ## When to use it Submit it after reviewing the approved destination, exact network, fee, source debit, and available balance. ## Before you call Use a secret API key with `treasury:write`. The destination, asset/network, limits, screening, and available balance must all be eligible. ## Money and balance effect On acceptance, the source debit is reserved. It is captured after confirmed execution or released only when non-execution is proven. ## States and completion Both `accepted` and `held` withdrawals have durably reserved the source debit; `accepted` means reserved, not sent, and `held` needs review before submission. A withdrawal on a network this account has no credited deposit or settled conversion for is accepted as `held` with `statusReason` `withdrawal_network_not_held` and stays parked until Wayex releases it — withdraw on a chain you have funded, or convert onto it first. The status moves to `settled` only after on-chain finality is reached — confirmation counts are not exposed on this resource. Follow status, reason, and next action through submission, failure, and hold; an unresolved outcome remains reconciling. ## Safe retries Send a unique `Idempotency-Key` for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read [Conversions and withdrawals](/treasury/conversions-and-withdrawals) for the complete workflow. # Deactivate a Treasury beneficiary Source: https://docs.rails.wayex.com/api-reference/treasury/deactivate-a-beneficiary /api-reference/openapi.json post /v1/treasury/beneficiaries/{id}/deactivate Deactivates a beneficiary for new payouts without deleting its identity or payout history. ## What this endpoint does Deactivates a beneficiary for new payouts without deleting its identity or payout history. ## When to use it Use it when a recipient should no longer be selectable, such as after destination details change. ## Before you call Use a secret API key with `treasury:write` and pass an active beneficiary ID owned by this tenant account. ## Money and balance effect This changes a resource or configuration but does not directly reserve, debit, credit, or settle wallet money. ## States and completion Deactivation blocks new payout use. Existing accepted or historical payouts keep their original beneficiary snapshot and continue through their real lifecycle. ## Safe retries Send a unique `Idempotency-Key` for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read [Beneficiaries and payouts](/treasury/beneficiaries-and-payouts) for the complete workflow. # Deactivate Treasury funding instructions Source: https://docs.rails.wayex.com/api-reference/treasury/deactivate-a-funding-instrument /api-reference/openapi.json post /v1/treasury/funding-instruments/{id}/deactivate Deactivates a reusable funding instrument without deleting its historical funding links. ## What this endpoint does Deactivates a reusable funding instrument without deleting its historical funding links. ## When to use it Use it when instructions must no longer be shown or used for new funding. ## Before you call Use a secret API key with `treasury:write` and pass an active funding-instrument ID owned by this tenant account. ## Money and balance effect This changes a resource or configuration but does not directly reserve, debit, credit, or settle wallet money. ## States and completion Deactivation prevents normal new use but does not erase incoming funding or wallet movements already linked to the instrument. ## Safe retries Send a unique `Idempotency-Key` for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read [Funding and balances](/treasury/funding-and-balances) for the complete workflow. # Deactivate a stablecoin destination Source: https://docs.rails.wayex.com/api-reference/treasury/deactivate-a-stablecoin-destination /api-reference/openapi.json post /v1/treasury/destinations/{id}/deactivate Deactivates a saved stablecoin destination for new withdrawals without rewriting withdrawal history. ## What this endpoint does Deactivates a saved stablecoin destination for new withdrawals without rewriting withdrawal history. ## When to use it Use it when an address should no longer receive funds or when replacing its details with a newly validated destination. ## Before you call Use a secret API key with `treasury:write` and pass an active destination ID owned by this tenant account. ## Money and balance effect This changes a resource or configuration but does not directly reserve, debit, credit, or settle wallet money. ## States and completion Deactivation blocks new use. Existing accepted or historical withdrawals retain the exact destination snapshot used at submission. ## Safe retries Send a unique `Idempotency-Key` for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read [Conversions and withdrawals](/treasury/conversions-and-withdrawals) for the complete workflow. # Export Treasury transactions Source: https://docs.rails.wayex.com/api-reference/treasury/export-transactions /api-reference/openapi.json get /v1/treasury/transactions/export Exports the same tenant-scoped, non-PII transaction view as a CSV file for reconciliation and finance workflows. ## What this endpoint does Exports the same tenant-scoped, non-PII transaction view as a CSV file for reconciliation and finance workflows. ## When to use it Use it for a bounded accounting export after selecting an external reference, movement kind, operation status, or date range. ## Before you call Authenticate with `treasury:read`. The export supports up to 5,000 rows; if the selected result is larger, narrow the filters and request another export. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion The file is a point-in-time transaction snapshot. A linked operation may still be accepted, held, or submitted, so CSV presence is not proof of external settlement. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Operations and reconciliation](/treasury/operations-and-reconciliation) for the complete workflow. # Get a Treasury beneficiary Source: https://docs.rails.wayex.com/api-reference/treasury/get-a-beneficiary /api-reference/openapi.json get /v1/treasury/beneficiaries/{id} Returns one saved AUD beneficiary and its current eligibility details for this tenant account. ## What this endpoint does Returns one saved AUD beneficiary and its current eligibility details for this tenant account. ## When to use it Use it before payout review, after an evidence change, or when investigating a beneficiary reference. ## Before you call Authenticate with `treasury:read` and pass a beneficiary ID owned by the same tenant account. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Only an active eligible beneficiary can receive a new payout. Inactive records remain readable for historical operations. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Beneficiaries and payouts](/treasury/beneficiaries-and-payouts) for the complete workflow. # Get a Treasury wallet conversion Source: https://docs.rails.wayex.com/api-reference/treasury/get-a-conversion /api-reference/openapi.json get /v1/treasury/conversions/{id} Returns the quote, source reservation, fee, trade, physical settlement legs, destination credit, and current state for one conversion. ## What this endpoint does Returns the quote, source reservation, fee, trade, physical settlement legs, destination credit, and current state for one conversion. ## When to use it Use it after a webhook, timeout, recovery event, or support question to determine which leg has completed and whether funds are spendable. ## Before you call Authenticate with `treasury:read` and pass a conversion ID owned by the same tenant account. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Destination funds are spendable only after the conversion settles and the destination wallet credit exists. Held or unknown legs require reconciliation, not a duplicate conversion. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Conversions and withdrawals](/treasury/conversions-and-withdrawals) for the complete workflow. # Get Treasury funding instructions Source: https://docs.rails.wayex.com/api-reference/treasury/get-a-funding-instrument /api-reference/openapi.json get /v1/treasury/funding-instruments/{id} Returns one reusable AUD or stablecoin funding instrument owned by this tenant account. An AUD instrument shows its BSB and account number and any issued `payId`. ## What this endpoint does Returns one reusable AUD or stablecoin funding instrument owned by this tenant account. An AUD instrument shows its BSB and account number and any issued `payId`. ## When to use it Use it to display the exact current instructions or inspect an instrument followed from an incoming pay-in or deposit. ## Before you call Authenticate with `treasury:read` and pass a funding-instrument ID owned by the same tenant account. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion An active instrument can receive funds. A newly issued AUD account or PayID can take a few minutes to activate for NPP; honour any `activationMessage` before relying on the PayID. An inactive instrument remains readable for history but must not be shared for new funding. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Funding and balances](/treasury/funding-and-balances) for the complete workflow. # Get an AUD payout Source: https://docs.rails.wayex.com/api-reference/treasury/get-a-payout /api-reference/openapi.json get /v1/treasury/payouts/{id} Returns the authoritative amount, fee, reservation, beneficiary, references, and lifecycle for one AUD payout. ## What this endpoint does Returns the authoritative amount, fee, reservation, beneficiary, references, and lifecycle for one AUD payout. ## When to use it Use it after a webhook, timeout, hold, return, or support question to determine the current payout outcome. ## Before you call Authenticate with `treasury:read` and pass a payout ID owned by the same tenant account. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Read the status, reason, reservation state, and next action together. Never infer settlement from `accepted` or `submitted`. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Beneficiaries and payouts](/treasury/beneficiaries-and-payouts) for the complete workflow. # Get an incoming stablecoin deposit Source: https://docs.rails.wayex.com/api-reference/treasury/get-a-stablecoin-deposit /api-reference/openapi.json get /v1/treasury/deposits/{id} Returns one provider-created stablecoin deposit with asset/network, transaction reference, finality, amounts, status, next action, and linked wallet movement. ## What this endpoint does Returns one provider-created stablecoin deposit with asset/network, transaction reference, finality, amounts, status, next action, and linked wallet movement. ## When to use it Use it after a deposit webhook, during blockchain reconciliation, or when a detected transaction has not become available. ## Before you call Authenticate with `treasury:read` and pass a deposit ID owned by the same tenant account. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Follow detected, confirming, credited, held, and returned. A transaction hash is not enough: only a credited deposit with finality can increase spendable balance. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Funding and balances](/treasury/funding-and-balances) for the complete workflow. # Get a stablecoin destination Source: https://docs.rails.wayex.com/api-reference/treasury/get-a-stablecoin-destination /api-reference/openapi.json get /v1/treasury/destinations/{id} Returns one saved stablecoin destination with its asset, network, address, version, validation, and activity status. ## What this endpoint does Returns one saved stablecoin destination with its asset, network, address, version, validation, and activity status. ## When to use it Use it for withdrawal review, audit, or to resolve the destination referenced by a historical withdrawal. ## Before you call Authenticate with `treasury:read` and pass a destination ID owned by the same tenant account. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Active validated destinations may be used when they match the withdrawal. Inactive versions are historical only. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Conversions and withdrawals](/treasury/conversions-and-withdrawals) for the complete workflow. # Get a stablecoin withdrawal Source: https://docs.rails.wayex.com/api-reference/treasury/get-a-withdrawal /api-reference/openapi.json get /v1/treasury/withdrawals/{id} Returns the authoritative amount, fee, reservation, destination, transaction reference, and lifecycle for one withdrawal. ## What this endpoint does Returns the authoritative amount, fee, reservation, destination, transaction reference, and lifecycle for one withdrawal. ## When to use it Use it after a webhook, timeout, hold, or support question to determine the current on-chain outcome. ## Before you call Authenticate with `treasury:read` and pass a withdrawal ID owned by the same tenant account. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Read status, reservation state, reason, and next action together. Confirmation counts are not exposed; the status moves to `settled` only after on-chain finality is reached. Unknown is not failed and must be reconciled. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Conversions and withdrawals](/treasury/conversions-and-withdrawals) for the complete workflow. # Get an incoming AUD pay-in Source: https://docs.rails.wayex.com/api-reference/treasury/get-an-aud-payin /api-reference/openapi.json get /v1/treasury/payins/{id} Returns one provider-created AUD pay-in with amounts, source references, status, reason, next action, and linked wallet movement. ## What this endpoint does Returns one provider-created AUD pay-in with amounts, source references, status, reason, next action, and linked wallet movement. ## When to use it Use it after a pay-in webhook, during reconciliation, or when a detected payment has not become available. ## Before you call Authenticate with `treasury:read` and pass a pay-in ID owned by the same tenant account. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Follow detected, confirming, credited, held, and returned. Only credited net funds represented in the available balance can be spent. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Funding and balances](/treasury/funding-and-balances) for the complete workflow. # Get effective Treasury settings Source: https://docs.rails.wayex.com/api-reference/treasury/get-effective-settings /api-reference/openapi.json get /v1/treasury/configurations/effective Returns the client-safe fees, limits, rails, networks, and evidence policy currently effective for this tenant account. ## What this endpoint does Returns the client-safe fees, limits, rails, networks, and evidence policy currently effective for this tenant account. ## When to use it Use it to explain availability, validate user input, and display the settings Wayex will enforce server-side. ## Before you call Authenticate with `treasury:read`. The current tenant account is inferred from the API key; clients do not send an account selector. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion The response is effective at read time. Every accepted operation records the configuration version used for its decision. Internal pricing-margin settings are never returned to client credentials. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Treasury overview](/treasury/overview) for the complete workflow. # Get tenant treasury settings Source: https://docs.rails.wayex.com/api-reference/treasury/get-tenant-settings /api-reference/openapi.json get /v1/treasury/settings Returns this tenant account’s writable payout preferences — currently the payout remitter default that controls whose name appears on AUD payouts. ## What this endpoint does Returns this tenant account’s writable payout preferences — currently the payout remitter default that controls whose name appears on AUD payouts. ## When to use it Read it before showing a payout settings screen, or to confirm the current default before submitting payouts that rely on it. ## Before you call Authenticate with `treasury:read`. The setting is bound to the tenant account inferred from the API key. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion The response is the current default. Individual payouts may still override the remitter per request, so a payout’s recorded remitter can differ from this default. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Beneficiaries and payouts](/treasury/beneficiaries-and-payouts) for the complete workflow. # Get the Treasury overview Source: https://docs.rails.wayex.com/api-reference/treasury/get-the-overview /api-reference/openapi.json get /v1/treasury Returns the tenant account’s Treasury summary, including wallet balances, funding setup, and effective capabilities. ## What this endpoint does Returns the tenant account’s Treasury summary, including wallet balances, funding setup, and effective capabilities. ## When to use it Use it to initialise a Treasury dashboard or confirm the account is ready before beginning a workflow. ## Before you call Authenticate with `treasury:read`. The API key is bound to one tenant account and cannot select or read another account. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Treat balance timestamps and capability flags as point-in-time values. Read the specific resource before acting on changing state. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Treasury overview](/treasury/overview) for the complete workflow. # List incoming AUD pay-ins Source: https://docs.rails.wayex.com/api-reference/treasury/list-aud-payins /api-reference/openapi.json get /v1/treasury/payins Lists provider-created incoming AUD payments observed on this tenant account’s funding instructions. ## What this endpoint does Lists provider-created incoming AUD payments observed on this tenant account’s funding instructions. ## When to use it Use it to monitor incoming AUD activity and reconcile each pay-in to its funding instrument, source references, and wallet movement. ## Before you call Authenticate with an API key that can read this resource. Results are restricted to the tenant account bound to that key. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Detected and confirming funds are not spendable. A credited record links gross amount, inbound fee, net credit, and the wallet movement; held and returned remain explicit. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Funding and balances](/treasury/funding-and-balances) for the complete workflow. # List Treasury wallet balances Source: https://docs.rails.wayex.com/api-reference/treasury/list-balances /api-reference/openapi.json get /v1/treasury/balances Lists the isolated AUD and stablecoin wallet balances owned by this tenant account. ## What this endpoint does Lists the isolated AUD and stablecoin wallet balances owned by this tenant account. ## When to use it Use it before previews and to display available, reserved, pending, and posted amounts with their `asOf` time (`posted` is available plus reserved; pending is excluded). ## Before you call Authenticate with `treasury:read`. A different tenant login or API key reads a different wallet and cannot net or spend this balance. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Only `available` is spendable. `reserved` backs accepted operations; `pending` is detected but not yet usable. Stale or unavailable balance data must not be treated as zero. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Funding and balances](/treasury/funding-and-balances) for the complete workflow. # List Treasury beneficiaries Source: https://docs.rails.wayex.com/api-reference/treasury/list-beneficiaries /api-reference/openapi.json get /v1/treasury/beneficiaries Lists reusable individual and business recipients that this tenant account can pay in AUD. ## What this endpoint does Lists reusable individual and business recipients that this tenant account can pay in AUD. ## When to use it Use it to select a recipient for a payout and confirm its BSB/account details and status. ## Before you call Authenticate with an API key that can read this resource. Results are restricted to the tenant account bound to that key. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Only an eligible active beneficiary can be used. Identity or screening state may require evidence or review before payout submission. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Beneficiaries and payouts](/treasury/beneficiaries-and-payouts) for the complete workflow. # List Treasury wallet conversions Source: https://docs.rails.wayex.com/api-reference/treasury/list-conversions /api-reference/openapi.json get /v1/treasury/conversions Lists accepted AUD-to-stablecoin and stablecoin-to-AUD wallet conversions for this tenant account. ## What this endpoint does Lists accepted AUD-to-stablecoin and stablecoin-to-AUD wallet conversions for this tenant account. ## When to use it Use it for conversion operations and to reconcile each quote, trade, physical settlement leg, and wallet credit. ## Before you call Authenticate with an API key that can read this resource. Results are restricted to the tenant account bound to that key. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion A conversion is not complete until every required funding, trade, and destination-settlement leg succeeds. Accepted or submitted is not destination credit. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Conversions and withdrawals](/treasury/conversions-and-withdrawals) for the complete workflow. # List Treasury funding instructions Source: https://docs.rails.wayex.com/api-reference/treasury/list-funding-instruments /api-reference/openapi.json get /v1/treasury/funding-instruments Lists reusable AUD funding instructions — a BSB and account number, plus any issued `payId` — and stablecoin deposit addresses issued to this tenant account. ## What this endpoint does Lists reusable AUD funding instructions — a BSB and account number, plus any issued `payId` — and stablecoin deposit addresses issued to this tenant account. ## When to use it Use it when displaying where to send funds, or when verifying the asset and network before a deposit. ## Before you call Authenticate with an API key that can read this resource. Results are restricted to the tenant account bound to that key. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion An active instrument can receive funds. A newly issued AUD account or PayID can take a few minutes to activate for NPP; honour any `activationMessage` before relying on the PayID. The instrument is not a deposit record and does not prove funds arrived or became available. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Funding and balances](/treasury/funding-and-balances) for the complete workflow. # List AUD payouts Source: https://docs.rails.wayex.com/api-reference/treasury/list-payouts /api-reference/openapi.json get /v1/treasury/payouts Lists AUD payouts submitted by this tenant account. ## What this endpoint does Lists AUD payouts submitted by this tenant account. ## When to use it Use it for payout operations, customer support, and reconciliation by Wayex or external reference. ## Before you call Authenticate with an API key that can read this resource. Results are restricted to the tenant account bound to that key. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Accepted, held, and submitted do not mean bank settlement. Treat settled, returned, and failed outcomes distinctly; an operation whose provider outcome is still unknown stays in a non-terminal status with its reservation intact until reconciled. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Beneficiaries and payouts](/treasury/beneficiaries-and-payouts) for the complete workflow. # List incoming stablecoin deposits Source: https://docs.rails.wayex.com/api-reference/treasury/list-stablecoin-deposits /api-reference/openapi.json get /v1/treasury/deposits Lists provider-created stablecoin deposits observed on this tenant account’s issued addresses. ## What this endpoint does Lists provider-created stablecoin deposits observed on this tenant account’s issued addresses. ## When to use it Use it to monitor incoming stablecoin activity and reconcile each deposit to its address, transaction reference, finality, and wallet movement. ## Before you call Authenticate with an API key that can read this resource. Results are restricted to the tenant account bound to that key. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Detected and confirming deposits are not spendable. Wayex credits the net amount only after required finality and screening; held and returned remain explicit. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Funding and balances](/treasury/funding-and-balances) for the complete workflow. # List stablecoin destinations Source: https://docs.rails.wayex.com/api-reference/treasury/list-stablecoin-destinations /api-reference/openapi.json get /v1/treasury/destinations Lists saved, validated stablecoin withdrawal destinations owned by this tenant account. ## What this endpoint does Lists saved, validated stablecoin withdrawal destinations owned by this tenant account. ## When to use it Use it to select an eligible destination before previewing or submitting a stablecoin withdrawal. ## Before you call Authenticate with an API key that can read this resource. Results are restricted to the tenant account bound to that key. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Only an active destination matching the withdrawal asset and network can be used. Inactive versions remain readable for historical withdrawals. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Conversions and withdrawals](/treasury/conversions-and-withdrawals) for the complete workflow. # List Treasury wallet movements Source: https://docs.rails.wayex.com/api-reference/treasury/list-wallet-movements /api-reference/openapi.json get /v1/treasury/movements Lists immutable wallet credits, debits, reservations, releases, returns, and adjustments for this tenant account. Fees never appear as separate movements: each operation’s reserved debit already includes its fee, and a pay-in is credited net of its inbound fee. ## What this endpoint does Lists immutable wallet credits, debits, reservations, releases, returns, and adjustments for this tenant account. Fees never appear as separate movements: each operation’s reserved debit already includes its fee, and a pay-in is credited net of its inbound fee. ## When to use it Use it to reconcile balance changes and follow a payout, conversion, withdrawal, or funding reference into the wallet ledger. ## Before you call Authenticate with an API key that can read this resource. Results are restricted to the tenant account bound to that key. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Movements are financial facts, while operations have workflows. A movement does not by itself prove an external bank or blockchain leg settled. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Operations and reconciliation](/treasury/operations-and-reconciliation) for the complete workflow. # List stablecoin withdrawals Source: https://docs.rails.wayex.com/api-reference/treasury/list-withdrawals /api-reference/openapi.json get /v1/treasury/withdrawals Lists stablecoin withdrawals from this tenant account’s wallet. ## What this endpoint does Lists stablecoin withdrawals from this tenant account’s wallet. ## When to use it Use it for withdrawal operations, blockchain reconciliation, and customer support. ## Before you call Authenticate with an API key that can read this resource. Results are restricted to the tenant account bound to that key. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Accepted and submitted withdrawals remain unsettled. Track status, reason, and next action explicitly; `settled` is reached only after on-chain finality. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Conversions and withdrawals](/treasury/conversions-and-withdrawals) for the complete workflow. # Preview an AUD payout Source: https://docs.rails.wayex.com/api-reference/treasury/preview-a-payout /api-reference/openapi.json post /v1/treasury/payouts/preview Calculates the effective payout fee, total AUD source debit, current eligibility, and any hold reason without creating an operation. ## What this endpoint does Calculates the effective payout fee, total AUD source debit, current eligibility, and any hold reason without creating an operation. ## When to use it Call it after the user enters the payout and before showing the final review screen. Submit the same intent to the create endpoint only after confirmation. ## Before you call Use a secret API key with `treasury:write`. The saved beneficiary must be active. You may select an existing `evidenceId`; otherwise Wayex uses the beneficiary’s newest accepted, unexpired evidence when policy requires it. ## Money and balance effect Previewing does not reserve, debit, or send AUD. The returned source debit and `canProceed` value are advisory until the create request atomically rechecks policy and reserves funds. ## States and completion `canProceed` reports current static eligibility. A `holdReason` explains a current block or review path; the final create response remains authoritative under concurrent balance and provider changes. ## Safe retries Send a unique `Idempotency-Key` for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read [Beneficiaries and payouts](/treasury/beneficiaries-and-payouts) for the complete workflow. # Preview a stablecoin withdrawal Source: https://docs.rails.wayex.com/api-reference/treasury/preview-a-withdrawal /api-reference/openapi.json post /v1/treasury/withdrawals/preview Calculates the effective withdrawal fee, total source debit, current eligibility, and any hold reason for a saved destination without creating an operation. ## What this endpoint does Calculates the effective withdrawal fee, total source debit, current eligibility, and any hold reason for a saved destination without creating an operation. ## When to use it Call it after the user chooses the active destination and amount, then show the returned terms on the final review screen before confirmation. ## Before you call Use a secret API key with `treasury:write`. The saved destination must belong to this tenant account and match an enabled asset and network. ## Money and balance effect Previewing does not reserve, debit, or send stablecoin. The create request rechecks the balance, destination, screening, limits, and provider capacity before reserving funds. ## States and completion `canProceed` reports current static eligibility. A `holdReason` identifies a current block or review path; any later create response — `accepted` or `held` — records a durable reservation. The preview does not test whether this account holds the requested network: a withdrawal on a chain with no credited deposit or settled conversion previews cleanly and is then held on create with `withdrawal_network_not_held`. ## Safe retries Send a unique `Idempotency-Key` for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read [Conversions and withdrawals](/treasury/conversions-and-withdrawals) for the complete workflow. # Search Treasury operations Source: https://docs.rails.wayex.com/api-reference/treasury/search-operations /api-reference/openapi.json get /v1/treasury/operations Returns a cursor-paginated view across this tenant account’s payouts, conversions, and stablecoin withdrawals. ## What this endpoint does Returns a cursor-paginated view across this tenant account’s payouts, conversions, and stablecoin withdrawals. ## When to use it Use it to operate a queue, filter lifecycle states, or recover an operation by `externalReference` after a create response was lost. ## Before you call Authenticate with `treasury:read`. Filter by operation kind, status, external reference, or an ISO 8601 date range; cursors belong to the exact filtered result set. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Each row reports the current operation state and next action. `accepted`, `held`, and `submitted` do not prove external settlement; open the resource detail before acting. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Operations and reconciliation](/treasury/operations-and-reconciliation) for the complete workflow. # Search Treasury transactions Source: https://docs.rails.wayex.com/api-reference/treasury/search-transactions /api-reference/openapi.json get /v1/treasury/transactions Returns cursor-paginated wallet movements enriched with their operation kind, operation state, and external reference when available. ## What this endpoint does Returns cursor-paginated wallet movements enriched with their operation kind, operation state, and external reference when available. ## When to use it Use it for transaction history, balance reconciliation, and investigation without exposing beneficiary bank details or saved wallet addresses. ## Before you call Authenticate with `treasury:read`. Filter by movement kind, operation status, external reference, or an ISO 8601 date range; pass `nextCursor` unchanged to read the next page. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion A transaction is an immutable wallet effect, while its linked operation can still be in progress. Reconcile the movement and operation state together. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Operations and reconciliation](/treasury/operations-and-reconciliation) for the complete workflow. # Submit optional reusable identity evidence Source: https://docs.rails.wayex.com/api-reference/treasury/submit-identity-evidence /api-reference/openapi.json post /v1/treasury/sumsub-evidence Validates a single-use Sumsub share token and binds the reusable accepted evidence result to one beneficiary. ## What this endpoint does Validates a single-use Sumsub share token and binds the reusable accepted evidence result to one beneficiary. ## When to use it Use it only to add evidence to an existing beneficiary. The normal flow submits the token in `sumsub.shareToken` while creating the beneficiary, never on a payout. ## Before you call Use a secret API key with `treasury:write`. The beneficiary must belong to this tenant account and the fresh single-use token must match that beneficiary. ## Money and balance effect Evidence validation does not reserve or move wallet money. ## States and completion Accepted evidence can later satisfy payout policy until it expires. Invalid, mismatched, rejected, or unavailable evidence is never silently ignored. ## Safe retries The share token is single-use. Send one `Idempotency-Key`, then retry the exact request with the same key after a lost response so Wayex replays the result rather than validating the token again. Read [Beneficiaries and payouts](/treasury/beneficiaries-and-payouts) for the complete workflow. # Update tenant treasury settings Source: https://docs.rails.wayex.com/api-reference/treasury/update-tenant-settings /api-reference/openapi.json put /v1/treasury/settings Sets the tenant-wide payout remitter default: `wayex` shows “Wayex” as the remitter on AUD payouts, while `tenant` shows your onboarded company name. The choice is constrained to those two values — it is never free text. ## What this endpoint does Sets the tenant-wide payout remitter default: `wayex` shows “Wayex” as the remitter on AUD payouts, while `tenant` shows your onboarded company name. The choice is constrained to those two values — it is never free text. ## When to use it Set it during onboarding, or whenever you want subsequent payouts to default to a different remitter. Each payout request can still override the default per payout. ## Before you call Use a secret API key with `treasury:write`. The onboarded company name used by the `tenant` option comes from your account profile and cannot be edited through this endpoint. ## Money and balance effect This changes a resource or configuration but does not directly reserve, debit, credit, or settle wallet money. ## States and completion The new default applies to payouts created after it is set; it does not change the remitter recorded on payouts already submitted. ## Safe retries Send a unique `Idempotency-Key` for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read [Beneficiaries and payouts](/treasury/beneficiaries-and-payouts) for the complete workflow. # Create a webhook subscription Source: https://docs.rails.wayex.com/api-reference/webhooks/create-a-subscription /api-reference/openapi.json post /v1/webhooks Registers an HTTPS endpoint to receive signed Wayex events for this tenant account. ## What this endpoint does Registers an HTTPS endpoint to receive signed Wayex events for this tenant account. ## When to use it Create one when your integration needs asynchronous transfer, Treasury, verification, or route updates. ## Before you call Use a secret API key with webhook write access. You choose and supply the HMAC signing `secret` (minimum 8 characters) in this request; it is stored encrypted and never returned in any response, so save your copy first. The destination `url` must be a public HTTPS endpoint — private, loopback, link-local, and metadata addresses are refused — and your handler must preserve the raw request body to verify signatures. ## Money and balance effect This changes a resource or configuration but does not directly reserve, debit, credit, or settle wallet money. ## States and completion Creation confirms the subscription exists; it does not prove your endpoint acknowledged a delivery. Inspect delivery records and verify every signature. ## Safe retries Send a unique `Idempotency-Key` for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read [Webhooks](/console/developers) for the complete workflow. # List webhook deliveries Source: https://docs.rails.wayex.com/api-reference/webhooks/list-deliveries /api-reference/openapi.json get /v1/webhooks/{id}/deliveries Returns recent delivery attempts for one webhook subscription, including their outcome. ## What this endpoint does Returns recent delivery attempts for one webhook subscription, including their outcome. ## When to use it Use it to diagnose missing events, non-2xx responses, or repeated delivery attempts. ## Before you call Authenticate with an API key that can read webhooks, and pass a subscription ID owned by the same tenant account. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion Delivery success means your endpoint returned an accepted response. Events remain at-least-once and unordered, so deduplicate by event ID. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Webhooks](/console/developers) for the complete workflow. # List webhook subscriptions Source: https://docs.rails.wayex.com/api-reference/webhooks/list-subscriptions /api-reference/openapi.json get /v1/webhooks Lists the webhook endpoints registered for the current tenant account. ## What this endpoint does Lists the webhook endpoints registered for the current tenant account. ## When to use it Use it to audit integrations, check which URL receives events, or locate a subscription before reviewing deliveries. ## Before you call Authenticate with an API key that can read this resource. Results are restricted to the tenant account bound to that key. ## Money and balance effect This is a read-only request. It does not reserve, debit, credit, or settle money. ## States and completion A subscription’s `status` is `active` or `disabled`; only `active` subscriptions receive deliveries. An `active` status does not prove your endpoint is accepting events — check its deliveries, where each event is `pending`, `failed`, `delivered`, or `dead`. ## Safe retries GET requests are read-only and may be retried with normal exponential backoff. Do not send an `Idempotency-Key`. Read [Webhooks](/console/developers) for the complete workflow. # Authentication Source: https://docs.rails.wayex.com/authentication Authenticate with a tenant-bound API key and grant direct-route or Treasury access. The Wayex API authenticates with an **API key**. Send it on every request in either header: ```bash theme={null} # Preferred Authorization: Bearer YOUR_API_KEY # Or X-Api-Key: YOUR_API_KEY ``` ## Key types | Prefix | Type | Use | | ------ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `sk_…` | **Secret key** | Server-side only. Works on every endpoint; required for value-affecting writes. Never expose it in a browser, mobile app, or public repo. | | `pk_…` | **Publishable key** | Read-only, and accepted only on a small set of read endpoints (listed below). | Publishable keys work on live rates (`GET /v1/rates`), the activity feed (`GET /v1/activity`), your fee schedule (`GET /v1/developer-fees`), and revenue reports (`GET /v1/revenue`, `GET /v1/reports/revenue`). Every other endpoint — including all other reads — requires a secret key and returns `403 secret_key_required` when called with a publishable key. Treat your secret key like a password. If a key is exposed, rotate it immediately from the console (**Developers → API keys**). Wayex will never ask you for your secret key. ## Tenant binding Every API key belongs to one tenant account. Its requests can read and change only that account's customers, wallet, configuration, webhooks, and reporting. Create and store credentials separately for every tenant account. Choose the credential before making a request; the key determines the account for every Treasury call. Never reuse an idempotency key across separate credential stores. ## Roles Each key is bound to a **role** that scopes what it can do. Reads are available to your role's scope. **Value-affecting** writes — creating a customer, a payment route, or a webhook subscription, or submitting a Treasury wallet operation — require a secret key with write access. API key creation, rotation, restriction, and revocation additionally require a recent second-factor (MFA) confirmation, so manage keys from the console (**Developers → API keys**). A key-management request authenticated only with an API key returns `403 step_up_required`. ## Scopes and key restrictions Scopes are optional, per-key restrictions granted per resource family. The families are `customers`, `routes`, `transfers`, `treasury`, `webhooks`, `fees`, `keys`, `team`, and `settings`, each with `:read` and `:write`, plus `rates:read`. Within a family, `:write` implies `:read`. `team:write` (inviting a teammate) is a **credential-issuing** action, like API key management above — it always requires a signed-in console admin with a fresh second factor, so a bare API key can hold the scope but can never satisfy the request on its own. A key created without a scope list keeps its full role-implied access. A scoped key can call only endpoints in the families it holds, so include every family your integration uses — for example `rates:read` if you fetch live rates, as in the example below. A request outside a scoped key's grants returns `403 insufficient_scope`, and the error message names the scope the route requires. ### Treasury scopes | Scope | Access | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `treasury:read` | Treasury overview, effective account settings, balances, funding, beneficiaries, payouts, withdrawals, conversions, and transaction history. | | `treasury:write` | Funding-instrument and beneficiary creation, Sumsub evidence handoff, AUD payouts, stablecoin withdrawals, conversion quotes and conversion acceptance. Write access implies Treasury read access. | ### Network binding A key may optionally carry an `allowedIps` list of IP addresses or CIDR blocks (IPv4 or IPv6; a bare address means a single host). Set it at key creation or rotation, or via `PATCH /v1/api-keys/{id}` — passing `null` clears the restriction, and a rotated key inherits the retiring key's scopes and allowed IPs unless you override them. Requests presented from outside those networks return `403 ip_not_allowed`; a request whose source network cannot be determined is also refused. Keys without `allowedIps` are callable from anywhere. Direct-route transfers are recorded automatically when a customer funds a payment route. Treasury is different: you create payouts, withdrawals and quoted wallet conversions against a prefunded wallet owned only by the authenticated tenant account. See the [Treasury overview](/treasury/overview) and [API reference](/api-reference/overview). ## Example request ```bash theme={null} curl "https://api.sandbox.rails.wayex.com/v1/rates?source=aud&destination=usdc" \ -H "Authorization: Bearer YOUR_API_KEY" ``` An unauthenticated or invalid request returns `401`. See [Errors](/errors) for the full error shape. # Changelog Source: https://docs.rails.wayex.com/changelog Dated API changes, with the migration step for anything that breaks an existing integration. Changes that affect what you send us or what we send back. Entries are newest first. A **Breaking** entry needs a code change before you take the release; everything else is additive. Breaking changes are announced here and applied to both environments. Exercise them in the [sandbox](https://api.sandbox.rails.wayex.com) — it runs fully simulated provider rails — before updating your production integration. ## 2026-07-25 ### Breaking · you name the settlement network when buying stablecoin `POST /v1/treasury/conversion-quotes` now **requires `settlementNetwork` when `sourceAsset` is `"AUD"`**. Wayex no longer selects a chain for that direction. The network you name is the chain the purchased stablecoin is delivered onto, so it is the chain your account then holds the balance on and the chain you can withdraw it on. That is your decision, not ours, and there is no default and no fallback behind it. ```json theme={null} { "sourceAsset": "AUD", "destinationAsset": "USDC", "settlementNetwork": "base", "sourceAmount": "1000.00", "externalReference": "quote-10027" } ``` **Migration.** Add `settlementNetwork` to every AUD-to-stablecoin quote request. Choose from the `runtimeCapabilities` entries on `GET /v1/treasury`, and choose a chain your account can actually withdraw on. Omitting it now fails with `400` `settlement_network_required` on the `settlementNetwork` parameter. Two refusals you should treat as "pick a different chain", not as transient errors: * `400` `unsupported_asset_network` — the asset does not settle on that chain, or Wayex cannot receive it there. This is now checked before your account's enabled pairs, so an unwired chain fails here rather than with `422` `asset_network_unavailable`. A pair that is wired but not enabled for your account still returns the `422`. * `409` `conversion_route_conflict` — Wayex has a settlement route pinned for that asset and you named a different chain. This check is unchanged, but it is now reachable on every AUD-to-stablecoin quote, because previously nobody sent the field. If a route is pinned for your account, name exactly that chain. **Not affected: stablecoin to AUD.** That direction is unchanged. `settlementNetwork` stays optional there, Wayex still routes from the chains your account holds the balance on, and a supplied value is still only an override. Do not make the field mandatory across both directions in your client. See [Choosing the settlement network](/treasury/conversions-and-withdrawals#choosing-the-settlement-network). ### Breaking · free-form maps reject a reserved key `metadata` on customers and counterparties, and `partyContext`, `businessIdentity`, and `glMapping` on Treasury requests, now refuse the reserved key `@@wxtype` and any `@@wxtype.esc…` variant, with `400` `invalid_request`. Nothing is written, including on a `PATCH` that would otherwise merge. These keys were previously accepted. **Migration.** Only integrations that happen to use that exact key name are affected. Near misses such as `wxtype`, `@@wxtypes`, and `my@@wxtype` remain ordinary keys. See [Reserved metadata key](/errors#reserved-metadata-key). ### New hold reason · `withdrawal_network_not_held` A stablecoin withdrawal on a network your account has no credited deposit and no settled conversion for is now accepted as `held` with `statusReason` `withdrawal_network_not_held`, instead of proceeding. The source debit is reserved and nothing is sent until Wayex releases it. Retrying will not clear it: withdraw on a network you have funded, or convert onto that network first. The withdrawal preview does not test this restriction, so an unheld network previews cleanly with `canProceed` true and is held on create — treat the create response as authoritative. See [Withdrawals on a network you do not hold](/treasury/conversions-and-withdrawals#withdrawals-on-a-network-you-do-not-hold). # Activity and history Source: https://docs.rails.wayex.com/console/activity Follow direct-route transfers and reconcile Treasury wallet activity inside one tenant account. The console gives you a running view of everything that is moving: a live **activity feed**, a per-transfer **detail view** with its full lifecycle timeline, and a **Your revenue** report. ## Activity feed A live activity feed runs down the left side of the console. It shows recent transfers across **all** of your customers in reverse-chronological order — corridor (on-ramp or off-ramp), customer, the amount in and out, and the current status — so you always have a running history of what is moving without leaving the page you are on. * **Status is shown explicitly** — held, failed, and returned transfers carry their own tone and are never collapsed into a generic "success". * The feed refreshes on its own, and each item links straight to that transfer's detail view. ## Transfer detail & timeline Select any item in the activity feed — or open a conversion from a [payment route](/console/payment-routes) — to see the complete picture of a single transfer: The corridor, customer, the amount you send and the amount the customer receives, and the destination (AUD bank account or crypto address). While a transfer is still awaiting the customer's deposit or pay-in, the funding instructions are shown here to share with them. A progress checklist plus a timeline of every state change — what happened and when. Held and failed states appear as an explicit banner with their reason. Linked references for reconciliation — including the route the funding arrived on, the executed FX trade, the on-chain transaction, and the AUD rail reference — appear as the transfer progresses. While a transfer is still in progress, the detail view refreshes automatically so you see the current state without reloading. You can also refresh on demand. ## Your revenue The **Your revenue** screen reports **your developer fees** — the markup you configure and charge your end customers on each conversion. It is scoped to your organisation only. * **Headline totals** per asset, with the number of completed transfers. * A **by-asset breakdown** of your fees. * A **time series** you can view at daily, weekly, or monthly granularity. All amounts are shown with their currency exactly as reported. Your fees appear here once transfers complete, so the view fills in as you move money. ## Treasury transactions Treasury has its own **Transactions** page because its wallet movements are different from direct-route customer transfers. Use it to search credits, reservations, captures, releases, fees, returns, conversions, payouts, and withdrawals for the signed-in tenant account. Open an operation to see its source debit, fee, reservation, settlement step, external references, reason, and next action. `accepted` and `submitted` do not mean external settlement. Exported CSV data uses the same account boundary and must not be combined with another account as if their balances net. See [Console Treasury](/console/treasury) and [Operations and reconciliation](/treasury/operations-and-reconciliation). The exchange rate you and your customers see is the **all-in rate Wayex quotes** — Wayex's margin is inside the rate and is not your revenue, so it never appears in this report. Your revenue is your **developer fee**: a markup you configure (see [Developer fees](/console/developers#developer-fees)) that is withheld from each conversion's payout and credited against your monthly Wayex invoice. ## Billing & invoices Wayex bills platform fees on a monthly invoice, and your accrued developer fees are credited against it: * **Platform fees due** — the per-event fees on your Wayex plan (for example verification or transfer fees) for the period. * **Developer-fee credit** — the developer fees withheld from your conversions during the period, owed to you. * **Net due = platform fees due (plus any tax) − developer-fee credit.** A negative net due means Wayex owes you for the period. Retrieve your invoices through the API: `GET /v1/invoices` lists your issued and settled invoices, and `GET /v1/invoices/{id}` returns one with its line items, the developer-fee credit, and an informational memo of what was already collected in-flow. All amounts are exact decimal strings with an explicit currency. # Onboarding customers Source: https://docs.rails.wayex.com/console/customers Add end customers by email, track verification, and unlock entitlements on approval. A **customer** is an end user you onboard and act for. Before a customer can transact, they complete identity verification. When verification is approved, the customer is granted **entitlements** — the specific things they are allowed to do. ## Add a customer by email Onboarding is **email-only**. You enter just the customer's email address; the customer completes their own identity verification, so you do not need to collect their personal or business details up front. Go to **Customers** in the navigation and select **Add customer**. Enter the email address where the verification link should go. You can optionally add a **name** as a label for your own records — it is not required. Select **Add & get verification link**. The customer is created and you are taken to their detail page, where you can generate the link to send them. You can also create a customer and request a verification link programmatically. See the **API Reference** for the customers and verification-link endpoints. ## Verification On the customer's detail page, the **Verification** card asks how you want to verify the customer. With **Start a fresh identity verification** selected (the default), select **Start verification** to produce a hosted verification link — it appears in the card as **Open hosted verification**, ready to send to the customer. The customer opens it and completes the identity checks themselves. ### What the verification states mean Each customer shows a verification status. It moves through these states: | Status | What it means | | ------------------- | -------------------------------------------------------------------------------- | | **In progress** | Verification has started and is being assessed. No entitlements yet. | | **Requires action** | The customer needs to provide or correct something before assessment can finish. | | **Approved** | Identity checks passed. Entitlements are granted and the customer can transact. | | **Rejected** | Verification did not pass. The customer cannot transact. | The console reflects the current status as the API reports it. Customers awaiting verification, or whose verification needs action or was rejected, surface in **Needs your attention** on the Home dashboard. In the sandbox, identity verification is simulated — there is no external vendor page to complete. Start a verification as normal; the issued link is simulated, and a **Simulate approval** control appears so you can drive an approved outcome and see entitlements granted. This control never appears in production. ## Entitlements Entitlements are listed on the customer's detail page. They are granted **only on an approved verification** — nothing is unlocked before then. The entitlements you will see include: | Entitlement | Unlocks | | --------------- | --------------------------------------------------------------------- | | `payment_route` | Creating [payment routes](/console/payment-routes) for this customer. | | `aud_onramp` | On-ramp transfers — AUD in, stablecoin out. | | `aud_offramp` | Off-ramp transfers — stablecoin in, AUD out. | Until a customer is approved and holds the relevant entitlement, the matching actions are blocked. For example, you cannot create a payment route for an unverified customer — the console disables the action and tells you verification is required first. # Developers Source: https://docs.rails.wayex.com/console/developers Manage API keys and your developer fee in the console, and wire up webhook subscriptions through the API. The console is a UI over the same API you can call directly. The **Developers** area is where you manage your **API keys** and your **developer fee**; **webhook endpoints** are managed through the API and are documented below. This page covers the developer surface at a product level. For request and response shapes and the full endpoint list, see the [API reference](/api-reference/overview). ## API keys Every API request authenticates with an **API key**. There are two kinds: | Key | Prefix | Use it for | | ------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------- | | **Publishable key** | `pk_…` | Documented non-sensitive read-only calls. Do not use it to expose Treasury or beneficiary data in an untrusted browser. | | **Secret key** | `sk_…` | Server-side only. Required for state-changing writes. Never expose it in a browser, mobile app, or public repository. | Send your key on every request as a bearer token: ```bash theme={null} Authorization: Bearer YOUR_API_KEY ``` Or, equivalently, in the `X-Api-Key` header: ```bash theme={null} X-Api-Key: YOUR_API_KEY ``` ### Managing keys From **Developers → API keys** you can: * **Create** a key. * **Rotate** a key — issue a replacement and retire the old one. * **Revoke** a key — disable it immediately. A key is bound to one tenant account. Reads and writes cannot select another tenant in a request. Keep each tenant account's key in a separate secret. A key's **scope** follows its configured access. Treasury reads require `treasury:read`; funding, beneficiary, payout, quote, conversion, destination, and withdrawal writes require `treasury:write`. A request made with an out-of-scope key is rejected. Treat your secret key like a password. The full secret value is shown **once**, at creation — copy it then and store it securely. If a key is ever exposed, rotate it immediately. Wayex will never ask you for your secret key. ## Developer fees Your **developer fee** is your revenue: a markup you charge your end customers on each conversion, on top of the rate. Configure it from **Developers → Fees** (or programmatically via `GET` / `PUT` `/v1/developer-fees`) as a **flat AUD amount**, a **percentage in basis points**, or both, applied per transfer. The exchange rate you and your customers see is the **all-in rate Wayex quotes** — Wayex's margin is inside that rate and is not your revenue. Your developer fee is the only fee surface you configure, and it works like this: * **Withheld from each conversion.** When a funded route converts, your fee is deducted from the conversion — the end customer receives the net **minus your fee**. The withheld amount is held owed to you. * **Credited against your monthly invoice.** Each billing period, your accrued developer fees appear as a credit on your Wayex invoice, netted against the platform fees you owe — see [Billing and invoices](/console/activity). * **Applies going forward.** A saved schedule applies to conversions struck **after** the change; it never reprices a conversion already in flight. * **Capped.** A schedule above the per-transfer caps — **500 basis points** or **A\$100.00 flat** — is rejected outright (HTTP `422`), never silently reduced. * **Never eats a transfer.** If a configured fee would consume an entire conversion, the fee for that transfer is reduced to zero and the conversion proceeds normally; the skip is recorded. A fee misconfiguration can never strand a customer's funds. Setting an empty schedule means you charge no developer fee. Updating the schedule is value-affecting: it requires a secret key (or a console role with write access), and every change is audited. This developer fee applies to direct customer-route conversions. Treasury pricing and operation fees come from the effective settings for the authenticated tenant account. ## Webhooks Webhooks are how your systems learn about things that happen asynchronously — a customer's verification outcome, a payment route being created, and every conversion a funded route spawns. Webhooks are the signal that state changed: subscribe an endpoint, verify the event, then fetch the current resource as the authoritative state. ### Subscribe your endpoint Register an HTTPS URL on your server with `POST /v1/webhooks`. The request must include the `url`, the `eventTypes` you want, and a `secret` you choose (minimum 8 characters — use a long random value). That secret is what Wayex uses to sign every delivery to the endpoint, so generate it yourself and keep your own copy securely: Wayex stores it encrypted and never returns it in any response. Wayex sends each event to your URL as an HTTP `POST` with a JSON body. ### Event shape Every event carries a stable **`eventId`**, a **`type`**, a **`createdAt`** timestamp, and a typed **`data`** payload. The event types you can receive are: | Event | Fires when | | ----------------------------- | ------------------------------------------------------------------------------- | | `counterparty.created` | A counterparty is created. | | `counterparty.invited` | A counterparty is invited to the console. | | `counterparty.activated` | A counterparty completes activation. | | `customer.created` | A customer is created. | | `kyc.updated` | A customer's verification status changes (and entitlements update on approval). | | `payment_route.created` | A payment route is created. | | `transfer.created` | A funded route spawns a conversion. | | `transfer.updated` | A transfer changes state. | | `transfer.completed` | A transfer completes. | | `treasury.wallet.updated` | A Treasury wallet balance or reservation changes. | | `treasury.payin.updated` | An incoming AUD pay-in changes state. | | `treasury.deposit.updated` | An incoming stablecoin deposit changes state. | | `treasury.payout.updated` | An AUD payout changes state. | | `treasury.withdrawal.updated` | A stablecoin withdrawal changes state. | | `treasury.conversion.updated` | A Treasury conversion or physical settlement leg changes state. | Transfers are created automatically when a route is funded — Wayex converts at the live rate the instant funds land. You never create a transfer yourself, so there is no quote to accept and no price to lock; the binding price is struck fresh at funding. The Rates API and the console Rates screen are live indicative only and never bind. ### Verify the signature Each delivery is **signed** so you can confirm it genuinely came from Wayex and was not tampered with. Wayex sends the signature in the **`X-Wayex-Signature`** header, formatted as `sha256=`, where `` is the **HMAC-SHA256** of the **raw request body**, keyed by the signing secret **you supplied** in the `secret` field when you created the subscription. Wayex stores that secret encrypted and never returns it in any response, so verification uses the copy you kept. Capture the exact raw request bytes before any JSON parsing — the signature is computed over the raw body, so re-serializing it will change the result. `HMAC-SHA256(rawBody, yourSigningSecret)`, hex-encoded. Strip the `sha256=` prefix from the header and compare against your computed hex using a constant-time comparison. If they do not match, reject the request with a non-2xx. ```js theme={null} import { createHmac, timingSafeEqual } from 'node:crypto'; function verifyWayexSignature(rawBody, header, signingSecret) { const expected = createHmac('sha256', signingSecret).update(rawBody).digest('hex'); const received = (header ?? '').replace(/^sha256=/, ''); const a = Buffer.from(expected); const b = Buffer.from(received); return a.length === b.length && timingSafeEqual(a, b); } ``` ### Handle deliveries safely Delivery is **at-least-once** and **unordered**, so build your consumer to tolerate that: * **Deduplicate** by `eventId` — you may receive the same event more than once. * **Do not assume ordering** — events can arrive out of sequence. When you need the authoritative state of a resource, fetch it from the API rather than inferring it from event order. * **Respond quickly** with a `2xx` to acknowledge receipt, then do heavier work asynchronously. ### Delivery and retries Your endpoint must return a `2xx` within **10 seconds** — do heavier work asynchronously. A non-`2xx` response, a timeout, or **any redirect** counts as a failed attempt: redirects are never followed, so serve the webhook URL directly over HTTPS at a publicly resolvable address (the URL is re-validated on every attempt). A failed delivery is retried with exponential backoff: **up to 8 attempts in total**, spaced roughly 10 seconds, 20 seconds, 40 seconds, 80 seconds, 2.7 minutes, 5.3 minutes, 10.7 minutes, and 21.3 minutes apart (with jitter), so the full schedule spans about **40 minutes**. After the final attempt the delivery is marked `dead` and is never retried — reconcile missed events with `GET /v1/webhooks/{id}/deliveries` and by fetching current resource state. Alongside `X-Wayex-Signature`, each delivery carries `x-wayex-event-id`, `x-wayex-event-type`, `x-wayex-delivery-id`, `x-wayex-delivery-attempt`, and `x-wayex-timestamp` headers you can use for logging and dedupe. ### Delivery logs Retrieve recent **deliveries** for a subscription with `GET /v1/webhooks/{id}/deliveries` — each delivery reports the event sent, the attempts made, the HTTP status your endpoint returned, and whether it is `pending`, `failed` (awaiting a retry), `delivered`, or `dead`. Use it to debug an integration and confirm events are being received. Sandbox is fully simulated — no real funds ever move. Production moves real funds. Treat your webhook handling as production code in every environment. # Console overview Source: https://docs.rails.wayex.com/console/overview What the Wayex console is, who signs in, and a tour of every section. The **Wayex console** is the institutional UI for your team. It is a presentation layer over the same API you can call directly. Use it to onboard direct-route customers or operate a prefunded Treasury account without writing code. The sandbox console (`sandbox.rails.wayex.com`) is fully simulated — no real funds ever move, and any funding instructions it displays are test fixtures. The production console (`rails.wayex.com`) moves real funds. Confirm which environment you are signed in to before sharing instructions. ## Who signs in The console is for **your staff** — the people at your organisation who onboard end customers and set up payment routes or operate Treasury. Each person signs in with their own user, and what they can see and do is governed by their [role](/console/team-roles). Your end customers never sign in to the console. The login belongs to one tenant account. Staff use the login for the account they intend to operate. Every account's wallets, settings, webhooks, and history remain isolated. ## Signing in Sign in with your **email and password**. Each person on your team has their own account — there is no shared login and no separate identity provider to visit. You enter your credentials on the console's sign-in screen and are taken straight in. Navigate to your console URL. If you are not signed in, you land on the sign-in screen. Type the email and password for your account and select **Sign in**. Your role and capabilities load automatically and are reflected in the navigation and the actions available to you. ### First-time setup The first administrator at a new organisation receives an **invitation link** by email. Opening it lets them set a password and activate the organisation. Invitation links expire and can be used only once — if yours no longer works, ask your Wayex contact to send a fresh one. The first time you sign in from an invitation — or after an administrator resets your account — the console asks you to set a permanent password before you continue. On every sign-in after that, your email and password take you straight in. To sign out, open the account menu in the top-right and select **Sign out**. ## A tour of the console A compact navigation sits at the top-left, with a live **activity feed** below it that shows recent transfers across all of your customers in reverse-chronological order. Your dashboard for the products enabled on this tenant account, including work that needs attention. Fund an isolated wallet, manage beneficiaries, make AUD payouts, convert, withdraw stablecoin, and reconcile transaction history. Onboard end customers by email, track their verification status, and manage what each is entitled to do. **Payment routes live inside each customer** — they are where money moves. Where money moves. Routes have no navigation item of their own — you open them from a customer's detail page. Create a standing route — off-ramp (stablecoin to AUD) or on-ramp (AUD to stablecoin) — and the customer funds it any time. Wayex converts automatically at the live rate the moment funds land. A live feed of every transfer across your customers, each opening a detail view with the full lifecycle timeline and linked references. The **live indicative rate right now** — what a customer would get if they converted this instant. It is the all-in rate Wayex quotes, indicative only, and never binds; the binding price is struck fresh when a route's funds land. Your developer-fee revenue over time — headline totals per asset, a by-asset breakdown, and a time series of the fees you charge your customers on each conversion. Your invoices — Wayex platform fees due for each billing period, with your withheld developer fees credited against them. Create and manage API keys, and set the developer fee you charge on each conversion. Notification preferences and your own sign-in security, including your second factor. Read-only roles see the same screens but with create and edit actions hidden or disabled. Wherever an action is unavailable to your role, the console explains why. ## Reading money and status * **Money** is always shown with its currency (and network, for crypto) exactly as the API returns it — values are never rounded or recomputed in the browser. * **Status** is always shown explicitly. A held, failed, or returned transfer is never hidden or collapsed into "success"; it is surfaced with its reason so you know what to do next. * **Availability** is explicit. Pending and reserved money is not spendable, `accepted` is not external settlement, and stale or unknown data never appears as zero. # Payment routes Source: https://docs.rails.wayex.com/console/payment-routes The product. Create a standing route for a verified customer; they fund it any time, and Wayex auto-converts at the live rate the moment funds land. A **payment route** is how money moves on Wayex. You create one or more standing routes under a customer (for example, an on-ramp route and an off-ramp route), share each route's deposit instructions, and the customer funds it — **any amount, any time**. When their funds land (and clear finality + screening), Wayex **automatically converts at the live rate at that instant** and pays out or sends on. There is no operator-created transfer, no quote to accept, and no locked price: the route is the product, and a funding event is the trigger. This page covers direct customer routes. For an organisation-prefunded wallet with explicit AUD payouts to saved beneficiaries, quoted conversions, and stablecoin withdrawals, use [Treasury](/treasury/overview). Routes run in either direction: * **Off-ramp** — stablecoin in, delivered as AUD to a bank account you whitelist. The route gives the customer a crypto **deposit address**. * **On-ramp** — AUD in, delivered as stablecoin to a crypto destination you whitelist. The route gives the customer an AUD **virtual account / PayID** to pay. ## How a route moves money Set up a standing route for a verified customer (below). The route provisions and persists its deposit surface — the crypto deposit address (off-ramp) or the AUD virtual account / PayID (on-ramp). Give the customer the route's deposit instructions. The same instructions are reused for every funding — a route has **one** standing deposit destination. The customer sends stablecoin (off-ramp) or pays AUD (on-ramp), in whatever amount they choose, whenever they choose. Each funding is an independent event. When the funds land and pass finality + screening, Wayex strikes a **fresh price at the live rate at that moment**, converts the exact amount that arrived at the all-in rate, withholds your developer fee if you have one configured, and pays out (off-ramp → AUD bank) or sends (on-ramp → crypto destination). Each funding shows up as its own conversion in the route's history and in the [activity feed](/console/activity). There is no "accept a quote" step and nothing to time. The price is whatever the live rate is **when the customer's funds land** — never a price locked earlier. The [Rates](/console/overview) screen shows that live rate so you can see what a conversion would fetch right now, but it is indicative and never binds. ## Routes live under a customer Payment routes belong to a specific customer — there is no global "create route" screen. You always pick the customer first, then create the route on that customer's detail page. The route inherits the customer it was created under. A route can only be created for a **verified (approved)** customer who holds the `payment_route` entitlement. If the customer is not yet approved, the console disables the create action and explains that verification is required first. ## Create a route Go to **Customers**, open the customer, and scroll to the **Payment routes** section. Select **New route**. Pick **On-ramp — AUD to stablecoin** or **Off-ramp — stablecoin to AUD**. Optionally set **limits** that govern what happens each time the route is funded (explained below). For an **on-ramp** route, enter the crypto destination: network, stablecoin, and destination address. For an **off-ramp** route, choose the deposit asset and network — or pick **EVM — any EVM chain** to get one deposit address that accepts the asset on any supported EVM chain. The console lists the accepted chains when you pick it, and the created route's deposit instructions carry the authoritative accepted-network list — always share that list with the payer, because funds sent on a chain outside it are not accepted. Then set the AUD payout target — a bank account (account holder name, BSB, account number) or a PayID. Select **Create payment route**. The route is created and its deposit instructions are shown right away. ## How a funding is handled Every funding on a route is converted **automatically**. The moment funds land — and clear finality and compliance screening — Wayex strikes the live rate, converts, and pays out (off-ramp) or sends the stablecoin on (on-ramp). There is no per-route mode to choose and no operator step in the normal flow. An off-ramp route pays out to the AUD target you set at creation — a bank account (BSB and account number) or a PayID. You can point that AUD target at **your own Treasury account**. Set the off-ramp payout to your Treasury funding instrument's BSB/account (or its PayID) and every funding auto-converts and lands in your Treasury AUD wallet — see [Auto-convert deposits into your AUD balance](/treasury/conversions-and-withdrawals#auto-convert-deposits-into-your-aud-balance). ## Limits You can set **per-funding** and **rolling** limits on a route: * **Minimum** and **maximum** per funding — an amount below the minimum or above the maximum does not auto-convert. * A **daily** cap across all fundings on the route. Limits are **fail-closed**. If a funding falls outside a configured limit, Wayex does not convert it: the funding is recorded and **parked on a hold** with the reason shown, and a case is opened for an operator to review. Funds are never moved past a breached limit on their own — releasing a held funding is a deliberate operator action. ## Deposit instructions Each route has **deposit instructions** — the details a payer uses to fund it — visible on the route's detail page at any time, alongside the route's direction, limits, destination, and status. * **Off-ramp** routes show the crypto deposit address to send stablecoin to. * **On-ramp** routes show the AUD pay-in details (the account to pay and a reference) to give to whoever is funding the route. The console renders instruction values exactly as returned by the API. Always share the instructions straight from the route rather than copying them by hand. The same instructions are reused for every funding. ## Conversions on a route Each time the route is funded, that funding becomes its own **conversion** — a transfer spawned from the route — and appears in the route's conversion history. Pricing uses the live all-in rate Wayex quotes (Wayex's margin is inside the rate, not a separate charge). If you have configured a [developer fee](/console/developers#developer-fees), it is withheld from the conversion — the customer receives the net minus your fee, and the withheld amount is credited to you against your monthly Wayex invoice. Every conversion is tracked end-to-end: * It progresses through the same lifecycle states as any transfer — detecting the funding, confirming it, compliance screening, executing the conversion at the live rate, and paying out or sending on. * **Every outcome is shown explicitly.** A funding that is held (a limit breach or a compliance checkpoint) or that fails is surfaced with its reason and never collapsed into "success". Open any conversion to see its full lifecycle timeline and linked references — see [Activity & history](/console/activity). In the sandbox, write-capable users get a **Fund this route** control on the route detail page that synthesises the customer's deposit or pay-in and drives the resulting conversion through the full lifecycle — the sandbox stand-in for a real funding. Everything in the sandbox is simulated: no real funds ever move. This control is never available in production. # Team & roles Source: https://docs.rails.wayex.com/console/team-roles How team membership works and how roles govern what each person can see and do in the console. The console is operated by your own staff. Each person has their own account and a **role** that governs what they can see and do. ## Team members Your team is made up of the people at your organisation who use the console. The first administrator is activated from an invitation link Wayex sends by email; opening it lets them set a password and activate the organisation. To add team members or change a member's role, contact Wayex — membership and roles are provisioned by Wayex, not managed from the console. Newly provisioned members still set their own permanent password the first time they sign in. Everyone signs in with their own [email and password](/console/overview#signing-in). Membership belongs to one tenant account. If the same staff member operates multiple accounts, access is granted and audited independently in each account. ## Roles Each member has one role. Roles are hierarchical — a higher role includes everything a lower one can do. | Role | Can do | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | **Viewer** | Read-only. View direct-route resources and enabled Treasury balances, funding, settings, and transactions. | | **Operator** | Viewer access plus customer/route actions, API key management, and enabled Treasury beneficiary, payout, conversion, and withdrawal actions. | | **Admin** | Operator access plus Treasury funding instruments and stablecoin destinations. | There is no separate approval step in the console — a member whose role permits an action performs it directly. That includes your pricing and fees, which operators and admins update from the console's Fees page. Money actions and sensitive destination/key changes require a fresh MFA step-up in the console. This confirms the acting user; it does not replace server-side tenant, role, policy, limit, or balance checks. The console adapts to your role automatically. Where an action is not available to you, the button is hidden or disabled and the screen explains why — for example, a viewer sees a "read-only access" notice in place of create actions. ## Audit Sensitive actions are recorded for audit. When recording a note on an action, keep it short and never include secrets or personal information. # Treasury Source: https://docs.rails.wayex.com/console/treasury Use the client console to fund, pay, convert, withdraw, track, and configure one isolated Treasury account. The **Treasury** area is the client-facing PSP workspace for one tenant account. It shows the same wallet and operations available through the Treasury API. ## Account isolation Your login opens one account with its own balances, fees, limits, users, API keys, webhooks, and history. Staff use the login for the account they intend to operate. The login determines the account for every money form. Confirm the account identity in the console header before funding or submitting an operation. Funds cannot be spent or netted across the two accounts. ## Pages | Page | What you do there | | ----------------- | --------------------------------------------------------------------------------------------------------------------- | | **Overview** | Read available, reserved, pending, and total balances; check freshness, recent activity, and action-required notices. | | **Funding** | Copy AUD or stablecoin instructions and follow incoming funding until it becomes available. | | **Beneficiaries** | Create and review individual or business BSB/account recipients and identity-evidence state. | | **Payouts** | Preview fees and source debit, confirm an AUD payout, and follow settlement or return state. | | **Convert** | Review and accept an expiring AUD/stablecoin quote, then follow physical settlement progress. | | **Withdraw** | Manage destinations, preview fees and source debit, then confirm and track a withdrawal. | | **Transactions** | Filter cursor-paginated wallet and operation history, inspect references, and export a bounded CSV. | | **Settings** | Read the effective fees, limits, rails, networks, and evidence requirements for this account. | ## Money actions Payout, conversion, and withdrawal forms follow the same pattern: Select a saved beneficiary or destination and enter the amount. Payout and withdrawal forms require an external reference, and payouts also require a purpose. The console uses the reference to recover a lost response, so reuse your own system's reference where you have one. Conversion generates its reference automatically. The console calls the payout or withdrawal preview endpoint and shows its principal, fee, source debit, eligibility, and any hold reason. For conversion, the exact expiring quote is the preview and also shows the all-in rate, destination amount, available source balance, and network. The console keeps the generated quote ID internal. No preview reserves money. Operators and administrators complete a fresh MFA step-up before the console submits the action. The console keeps the same action identity across MFA and safe retries, then shows reservation, external settlement, reason, and next action. `accepted` means the source debit was durably reserved; it is not a bank or blockchain receipt. Keep the operation open until its detail shows the terminal outcome. The create request repeats policy, balance, screening, and provider checks after confirmation. If conditions changed after preview, the console shows the authoritative create error or hold instead of assuming the earlier preview still applies. ## Funding safely Copy instructions from **Funding** immediately before use. For a stablecoin deposit, check the asset and network together. Incoming money appears as pending while it is detected, confirmed, and screened, then becomes available only after the wallet credit. If a funding record is held, the page shows whether you should wait or contact support. Stale or unavailable provider data appears as unavailable—not as a zero balance. ## Transactions and exports Transactions are loaded from the server in cursor pages. Filters for reference, type, status, and date range remain fixed while the console passes each opaque `nextCursor` unchanged. The CSV action uses the same filters and downloads at most 5,000 non-PII rows. If the selection is larger, narrow the date range or filters and export again. ## Roles | Role | Treasury access | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | **Viewer** | Read balances, funding, activity, statements/exports, and effective settings. | | **Operator** | Viewer access plus beneficiary, payout, conversion, and withdrawal actions. | | **Admin** | Operator access plus funding instruments, stablecoin destinations, API keys, webhooks, team, and account settings allowed by policy. | The API enforces tenant and role access even if a button is hidden in the browser. See [Team and roles](/console/team-roles). ## When something is unclear Open the operation and read its status reason, reservation state, settlement step, references, and next action. Never submit a replacement simply because the first result is slow or unknown. Use the request ID when contacting support, but never include an API key, signing secret, Sumsub token, or unnecessary beneficiary data. For integration behavior, start with the [Treasury overview](/treasury/overview) and then browse the [API reference](/api-reference/overview). # Errors Source: https://docs.rails.wayex.com/errors The standard error envelope and what each status code means. Wayex uses conventional HTTP status codes and returns a consistent JSON error envelope on every failure. ```json theme={null} { "type": "authentication_error", "code": "missing_api_key", "message": "A human-readable explanation of what went wrong", "requestId": "req_e43037e6-8149-4297-9a94-9bcf11a59dbb" } ``` | Field | Description | | ----------- | --------------------------------------------------------------------------------- | | `type` | The error category (e.g. `validation_error`, `authorization_error`, `not_found`). | | `code` | A stable, machine-readable code you can branch on. | | `message` | A human-readable explanation. Do not parse this — use `code`. | | `requestId` | The unique id for this request. **Include it when contacting support.** | ## Status codes | Status | Meaning | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `200` / `201` | Success. | | `400` | Malformed request. | | `401` | Missing or invalid API key. | | `403` | Authenticated, but not allowed to perform this action. | | `404` | The resource does not exist (or is out of your scope). | | `409` | Conflict — e.g. an illegal state transition, or an `Idempotency-Key` reused with different parameters (`idempotency_key_conflict`). | | `422` | Validation failed (a semantically invalid value, e.g. a developer fee above the cap). | | `429` | Rate limited — honor the `Retry-After` header, then retry with backoff. See [Rate limits](#rate-limits). | | `5xx` | A Wayex-side error. Safe to retry idempotent requests with backoff. | ## Rate limits Each API key is a **token bucket**, not a fixed window: it refills continuously at a **sustained rate of 25 requests/second** and can hold up to **50 requests** of burst capacity (defaults — your account may be configured differently). A request spends one token; an empty bucket returns `429` until the bucket refills. Responses include three headers you can use to pace your integration: | Header | Meaning | | ----------------------- | ------------------------------------------------------------------------------------------ | | `X-RateLimit-Limit` | The bucket's burst capacity (the largest instantaneous burst it admits). | | `X-RateLimit-Remaining` | How many tokens remain in the bucket right now. | | `X-RateLimit-Reset` | Seconds until the bucket refills to full capacity at the sustained rate — not a timestamp. | Exceeding the limit returns `429` with code `rate_limited` and a `Retry-After` header (in seconds). Wait at least that long, then retry with backoff. ## Common API codes | Code | Status | Meaning | | ----------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `idempotency_key_required` | `400` | The write is missing its `Idempotency-Key` header. See [Idempotency](/idempotency). | | `unsupported_asset_network` | `400` | The asset does not settle on the requested network, or Wayex cannot send or receive it there. Choose another network — this is not transient. | | `invalid_request` | `400` | The body failed schema validation. One case worth coding for: free-form maps reject the reserved key `@@wxtype` (and any `@@wxtype.esc…` variant). See [Reserved metadata key](#reserved-metadata-key). | | `secret_key_required` | `403` | A publishable key was used on an endpoint that requires a secret key. | | `insufficient_scope` | `403` | The API key's scope list does not include the scope this endpoint needs. The message names the scope. | | `ip_not_allowed` | `403` | The request came from outside the key's `allowedIps` networks. | | `step_up_required` | `403` | The action needs a recent second-factor (MFA) confirmation from a console session. Re-confirm and retry. | | `idempotency_key_conflict` | `409` | The `Idempotency-Key` was reused with different parameters. Use a fresh key for a different request. | | `idempotency_key_in_progress` | `409` | The original request with this key is still executing. Honor `Retry-After`, then retry with the *same* key. | | `rate_limited` | `429` | Too many requests this second. Honor `Retry-After`, then retry with backoff. | ## Common Treasury codes | Code | Status | Meaning | | --------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------- | | `treasury_configuration_required` | `409` | This tenant account has no effective Treasury configuration. Contact Wayex before retrying. | | `sumsub_evidence_required` | `403` | The payout does not have current accepted KYC evidence. | | `sumsub_token_invalid` | `422` | Sumsub could not accept the single-use share token. Request a fresh token for this beneficiary. | | `insufficient_balance` | `422` | This account's wallet has insufficient available funds after existing reservations. | | `asset_network_unavailable` | `422` | The asset/network is not enabled for this account and available at runtime. | | `settlement_network_required` | `400` | A conversion quote from AUD to a stablecoin omitted `settlementNetwork`. Name the chain the stablecoin settles onto. | | `conversion_route_conflict` | `409` | The named `settlementNetwork` differs from the settlement route Wayex has pinned for that asset. Use the pinned chain. | | `quote_expired` | `409` | The Treasury conversion quote expired before acceptance. Create a new quote. | | `sumsub_provider_unavailable` | `502` | Reusable-KYC validation is temporarily unavailable. Retry the same idempotent request with backoff. | | `destination_screening_required` | `403` | The stablecoin destination is not yet eligible for withdrawal. Use an active validated destination. | ## Treasury operation statuses | Status | Meaning | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `accepted` | KYC and policy checks passed and the source amount was durably reserved. Provider submission may still be pending or have an unknown outcome. | | `held` | The effective manual-review or threshold policy requires operator approval before the operation can continue. | | `submitted` | Funds remain reserved and the bank or blockchain instruction was submitted. This is not settlement. | | `settled` | The downstream bank or blockchain leg completed and the reservation was captured. | | `failed` | The operation did not complete. Inspect wallet movements to confirm the reservation release or any recovery action. | | `returned` | A previously submitted or settled payout was returned. The effective return-loss policy determines the client credit and any recovery exposure. | Some responses also include more specific settlement detail or a `nextAction`. An unknown or reconciling external outcome is not a failure: keep the original operation and reservation intact until its real outcome is established. See [Operations and reconciliation](/treasury/operations-and-reconciliation). ## Treasury hold reasons A `held` operation carries a `statusReason` naming why it is parked. Show it, and use it to decide whether waiting will help. Most reasons describe a review or capacity condition that Wayex clears; this one describes your request and will not clear on its own: | `statusReason` | Meaning | What to do | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `withdrawal_network_not_held` | The stablecoin withdrawal names a network this account has no credited deposit and no settled conversion for. The source debit is reserved; nothing was sent. | Withdraw on a network you have funded, or convert onto that network first. Wayex releases genuine cases. | Treat `statusReason` as an informational string, not a closed set — new reasons can appear. Branch on `status` and `nextAction`, and surface the reason to your operators verbatim. ## Reserved metadata key Free-form maps you send us — `metadata` on customers and counterparties, and `partyContext`, `businessIdentity`, and `glMapping` on Treasury requests — reserve one key name: `@@wxtype`, and any `@@wxtype.esc…` variant of it. Wayex uses it internally to encode stored values. A map containing that key is refused with `400` `invalid_request` and nothing is written — including on a `PATCH` that would otherwise merge. Near misses such as `wxtype`, `@@wxtypes`, or `my@@wxtype` are ordinary keys and are accepted. Nothing else about these maps changed. Always log the `requestId` from failed responses. It is the fastest way for support to trace exactly what happened. # Idempotency Source: https://docs.rails.wayex.com/idempotency Safely retry value-affecting requests without creating duplicates. Value-creating or replacing `POST`/`PUT` requests accept — and generally require — an `Idempotency-Key` header. This includes creating customers, payment routes, webhook subscriptions, API keys, Treasury beneficiaries, payouts, withdrawals, quotes, and conversions. It lets you retry after a network error without creating a duplicate. Direct-route transfers are created automatically when a route is funded. Treasury is an explicit wallet API, so its payouts, stablecoin withdrawals, conversion quotes and quote acceptance are all idempotent writes. ```bash theme={null} curl -X POST https://api.sandbox.rails.wayex.com/v1/customers \ -H "Authorization: Bearer YOUR_SECRET_KEY" \ -H "Idempotency-Key: a-unique-key-per-operation" \ -H "Content-Type: application/json" \ -d '{"email":"customer@example.com"}' ``` ## How it works * Use a **unique key per logical operation** (a UUID is ideal). Reuse the *same* key when retrying that same operation. * Persist the key before the first network attempt. A browser refresh, MFA step-up, worker restart, or client timeout must not generate a replacement key for the same action. * **Same key + same parameters** → you get back the original, cached response (with an `Idempotency-Replayed: true` header). The action runs once. * **Same key + same parameters while the original request is still running** → the API waits briefly (up to about five seconds) for the original to finish and, if it does, returns its cached response. Otherwise you get `409` (`idempotency_key_in_progress`) with a `Retry-After` header — wait at least that long, then retry the identical request. Never switch to a new key: the original action may still complete. * **Same key + different parameters** → the request is rejected with `409` (`idempotency_key_conflict`), protecting you from accidentally reusing a key for a different operation. * Keys are isolated per tenant account — all credentials belonging to the same tenant account share one idempotency namespace, so use a unique key per logical operation regardless of which API key sends it. Never reuse a key across separate tenant accounts. * Keys are retained for **7 days**. After that, the same key is treated as brand new and the request would execute again — beyond the window, recover a lost outcome by fetching the resource by its Wayex ID or your `externalReference` instead of retrying. Idempotency keys are scoped to supported `POST`/`PUT` writes, which require a secret key (`sk_`). Read requests (`GET`) are naturally idempotent and do not need a key. The current `PATCH` and `DELETE` resources do not use this header: read current state before retrying an unknown response, as explained on each endpoint page. ## Unknown money outcomes If a payout, conversion, or withdrawal response is lost, retry the identical request with the same key. Do not create a replacement operation while the original is `accepted`, `submitted`, held, or unknown. Fetch the original by its Wayex ID or your `externalReference` and inspect its reservation state first. See [Operations and reconciliation](/treasury/operations-and-reconciliation). ## Webhooks and ordering Wayex is event-driven: webhooks are the source of truth for asynchronous state. **Do not assume webhook ordering** — dedupe by the reference on each event and, when in doubt, fetch the current resource state with a `GET`. See [Developers](/console/developers) for subscription setup and signature verification. # Wayex API Source: https://docs.rails.wayex.com/introduction AUD and stablecoin orchestration through direct customer routes or an isolated, prefunded Treasury account. Wayex moves value between **Australian dollars** and supported stablecoins. You can integrate through direct customer payment routes, an institutional Treasury account, or both: * **Off-ramp** — stablecoin in, AUD out. * **On-ramp** — AUD in, stablecoin out. Direct routes convert when customer funds arrive. Treasury lets your business prefund a wallet, then explicitly fund, pay, convert, withdraw, track, and reconcile through familiar PSP workflows. ## Two product modes Create reusable funding instructions under a verified customer. Each funding event prices at the live rate and automatically creates a transfer. Prefund an isolated tenant account, make AUD payouts, convert AUD/stablecoin, and withdraw stable balances with explicit fees and statuses. ## Two surfaces, one API Build server-to-server workflows with tenant-bound keys, idempotent writes, and signed webhooks. Operate the same resources through an institutional interface without writing code. ## Core concepts * **Tenant account** — the isolation boundary for users, API keys, webhooks, configuration, money, and reporting. If you operate more than one tenant account, treat each as a fully separate integration: separate logins and API keys, and money never moves between accounts. * **Customer** — an end user onboarded for direct payment routes. Verification unlocks the customer's entitlements. * **Payment route** — reusable customer funding instructions. Funding the route automatically creates a direct-route transfer. * **Transfer** — one conversion created from a route funding event, with its own lifecycle and linked settlement references. * **Treasury wallet** — the AUD and stablecoin balances owned by one tenant account. It exposes available, reserved, and pending money. * **Beneficiary** — a saved individual or business recipient for AUD payouts. * **Conversion quote** — an exact, short-lived price for a Treasury conversion. Requesting a quote reserves nothing; accepting it immediately sets aside the amount you are selling, and the amount you are buying becomes available once the trade settles. * **Stablecoin destination** — a saved, validated asset/network/address combination used by Treasury withdrawals. ## Environments | Environment | API base URL | Console | | -------------- | ------------------------------------- | ---------------------------------------------------------- | | **Sandbox** | `https://api.sandbox.rails.wayex.com` | [sandbox.rails.wayex.com](https://sandbox.rails.wayex.com) | | **Production** | `https://api.rails.wayex.com` | [rails.wayex.com](https://rails.wayex.com) | Sandbox runs on fully simulated provider rails: no real bank transfer or on-chain movement ever occurs, so you can exercise every workflow end to end before going live. Production moves real funds. API keys are issued per environment and never work across environments. Production instructions move real value. Before your first production funding or payout, confirm the agreed asset, network, and limits with Wayex. ## Next steps Authenticate and make your first direct-route or Treasury request. Understand balances and complete each prefunded PSP workflow. Choose key types and isolate credentials per tenant account. Read the purpose, money effect, statuses, and retry rules for every endpoint. # Postman collection Source: https://docs.rails.wayex.com/postman Run the tenant-bound Wayex API surface with chained direct-route and Treasury examples. The Wayex Postman collection follows the public API reference. It includes direct customer payment routes and the isolated, prefunded Treasury workflow. Client API requests, tests, and chained resource variables. Base URL and local credential placeholders. ## Set it up Import the collection and environment, then select **Wayex — Sandbox (client)**. Paste the intended account's secret key (`sk_…`) into the local `apiKey` environment value. The collection sends it as `Authorization: Bearer {{ apiKey }}`. Confirm authentication and base URL before running a workflow folder. Customer and route requests chain their IDs. Treasury requests capture beneficiaries, quotes, and operations for the same tenant account. Keep a separate Postman environment for every tenant account. Do not paste two keys into one run or reuse captured resource IDs across accounts. A key, wallet, configuration, webhook set, and resource ID all belong to one tenant account. ## Folders | Folder | What it covers | | ------------------------------- | ------------------------------------------------------------------------------------------------------- | | **Start here** | Authentication and a read-only connectivity check. | | **Rates** | Indicative AUD/stablecoin rates. | | **Customers and verification** | Customer onboarding, hosted verification, and entitlements. | | **Payment routes** | Direct on-ramp/off-ramp route creation and reusable funding instructions. | | **Transfers and activity** | Direct-route conversion lifecycle and search. | | **Fees, invoices, and revenue** | Developer pricing and billing reports. | | **Webhooks** | Subscription creation and delivery inspection. | | **API keys** | Key lifecycle and restrictions. | | **Errors and idempotency** | Error envelope, conflict handling, and safe replay. | | **Treasury** | Funding, optional evidence, review-and-confirm money actions, cursor reporting, and bounded CSV export. | ## Run Treasury safely Before running a Treasury write: * confirm the key has `treasury:write` and belongs to the intended tenant account; * read the effective settings and current balances; * provision and fund the account, then wait for the net credit to become `available`; * keep every generated `Idempotency-Key` stable if you manually retry the same request; * treat `accepted` as durable reservation, not external settlement; * poll the resource or consume its webhook until the final outcome. Payout and withdrawal folders call a non-money-moving preview before create. The two requests use different idempotency keys because keys are tenant-global. Conversion quotes serve as the conversion preview and must be accepted before expiry. Operation and transaction searches return opaque cursors. Pass `nextCursor` unchanged with the same filters. The CSV request returns `text/csv`, is bounded to 5,000 rows, neutralises spreadsheet-formula text, and excludes beneficiary, bank-account, and saved destination-address PII. The optional Sumsub share token is submitted with beneficiary creation. It is input-only, single-use, and must remain a local secret. Do not save it in a shared Postman workspace. The collection is a runnable companion to the [Treasury guide](/treasury/overview). Each generated endpoint page explains its purpose, prerequisites, balance effect, statuses, and retry behavior. ## Existing resources To run against a resource you already created, set its ID as a local environment value. Only use IDs created under the same account as `apiKey`; cross-tenant resources return not found or forbidden. ## Environment safety The provided environment targets the sandbox (`https://api.sandbox.rails.wayex.com`), which runs on fully simulated provider rails — no real funds move. To run against production, duplicate the environment, set `baseUrl` to `https://api.rails.wayex.com`, and use a production key. Every money-moving folder then moves real value: confirm the agreed limits and asset/network with Wayex before running one. # Quickstart Source: https://docs.rails.wayex.com/quickstart Authenticate, confirm your account, and run a direct-route or Treasury workflow. Start with an authenticated read, then choose direct customer payment routes or the prefunded Treasury workflow. **Sandbox:** `https://api.sandbox.rails.wayex.com` · **Production:** `https://api.rails.wayex.com` — all current endpoints are versioned under `/v1`. Examples use the sandbox base URL; swap in the production URL and a production key when you go live. ## Connect Sign in to the intended tenant account and open **Developers → API keys**. Use a secret key (`sk_…`) on your server. Store each tenant account's key separately; a key never switches accounts. Confirm authentication with a read-only request: ```bash theme={null} curl "https://api.sandbox.rails.wayex.com/v1/rates?source=aud&destination=usdc" \ -H "Authorization: Bearer $WAYEX_SECRET_KEY" ``` This rate is indicative — it locks nothing, and the executed rate can differ. For direct routes, the binding rate is struck the moment your customer's funds arrive. For Treasury, lock an exact price by requesting and accepting a short-lived conversion quote. Continue with a direct customer route when every funding belongs to an onboarded customer. Use Treasury when your organisation prefunds its own isolated wallet and explicitly pays, converts, or withdraws. ## Treasury: fund and pay Wayex enables Treasury for your tenant account and sets its policy — fees, limits, and which capabilities (funding, payouts, conversions, withdrawals) are switched on. Requests against a capability that is not enabled are refused. Reads need the `treasury:read` scope; writes need `treasury:write`. ```bash theme={null} curl https://api.sandbox.rails.wayex.com/v1/treasury \ -H "Authorization: Bearer $WAYEX_SECRET_KEY" ``` Confirm the tenant account, enabled rails/networks, and the wallet's `available`, `reserved`, and `pending` amounts. The API key determines the account. Fetch or create an AUD BSB/account funding instrument or stablecoin address. Send only to the exact instructions for this account, then wait until the net credit appears in `available`. See [Funding and balances](/treasury/funding-and-balances). This example creates an individual BSB/account recipient. The external reference is optional; Wayex generates one when you omit it. ```bash theme={null} curl -X POST https://api.sandbox.rails.wayex.com/v1/treasury/beneficiaries \ -H "Authorization: Bearer $WAYEX_SECRET_KEY" \ -H "Idempotency-Key: beneficiary-transfer-aud-001" \ -H "Content-Type: application/json" \ -d '{ "type": "individual", "destination": { "type": "bank_account", "bsb": "062000", "accountNumber": "12345678", "accountName": "Ava Williams" }, "firstName": "Ava", "lastName": "Williams", "dateOfBirth": "1991-05-14", "address": "100 Market Street, Sydney NSW 2000" }' ``` If your account is configured to require reusable identity evidence, add a `sumsub` object with a single-use share token to this request: `"sumsub": { "shareToken": "…" }`. Without it, beneficiary creation fails with `sumsub_evidence_required`. The evidence attaches to the beneficiary — payout requests never carry the token. Reuse the beneficiary ID and give the payout a new external reference and idempotency key: ```bash theme={null} curl -X POST https://api.sandbox.rails.wayex.com/v1/treasury/payouts \ -H "Authorization: Bearer $WAYEX_SECRET_KEY" \ -H "Idempotency-Key: payout-submit-transfer-aud-001" \ -H "Content-Type: application/json" \ -d '{ "beneficiaryId": "ben_123", "amount": "250.00", "currency": "AUD", "externalReference": "payout-9172", "purpose": "Customer withdrawal" }' ``` `accepted` means the full source debit was durably reserved; it is not bank settlement. Subscribe to `treasury.payout.updated` and fetch `GET /v1/treasury/payouts/{id}` until the payout settles, fails, or returns. ## Direct route: onboard and fund Create a customer with `POST /v1/customers`, issue a hosted verification link, and wait until the required entitlement is `approved`. Create an on-ramp or off-ramp route under the customer. The response provides reusable AUD or stablecoin funding instructions. When the customer funds those instructions, Wayex prices at the live rate, creates a transfer, converts, and delivers the destination funds. You do not create or accept a direct-route quote. Subscribe to transfer webhooks and fetch the transfer for its authoritative lifecycle. See [Payment routes](/console/payment-routes). ## Before sending funds Sandbox never moves real funds — its provider rails are fully simulated. Production does. Before your first production funding, confirm the limits and exact asset/network with Wayex in writing. Fund, pay, convert, withdraw, track, and reconcile. Every endpoint explains prerequisites, balance effect, states, and safe retries. Run the client API collection with tenant-bound environment variables. Handle stable error codes and unknown outcomes safely. # Beneficiaries and payouts Source: https://docs.rails.wayex.com/treasury/beneficiaries-and-payouts Save an AUD BSB/account recipient, supply optional identity evidence, and submit a prefunded payout. An AUD payout debits the current tenant account's prefunded AUD wallet and pays one saved beneficiary through their BSB/account details. The beneficiary, fees, limits, and evidence policy all belong to that same isolated account. ## Before you create a beneficiary Collect the recipient information required for the party type: * First and last name - Date of birth - Residential address - The payout destination: a bank account (BSB, account number, and account name) **or** a PayID (email, phone, or ABN, with an account name) - Downstream merchant or wallet-provider references when available - Optional Sumsub share token when available or required by policy * Legal business name - Business identifiers you hold for the recipient (ABN, registration number, and similar), supplied in the optional `businessIdentity` map - The payout destination: a bank account (BSB, account number, and account name) **or** a PayID (email, phone, or ABN, with an account name) - Downstream merchant or wallet-provider references when available - Optional Sumsub share token when available or required by policy `externalReference` is optional. Supply a stable identifier only when you already use one to match the recipient in your system; otherwise Wayex generates and returns one. Do not put secrets or unnecessary personal information in reference, purpose, or metadata fields. The free-form maps on these requests — `partyContext`, `businessIdentity`, and `glMapping` — accept your own key names with one exception: `@@wxtype` (and any `@@wxtype.esc…` variant) is reserved by Wayex, and a map containing it is refused with `400` `invalid_request`. See [Reserved metadata key](/errors#reserved-metadata-key). ## Create a beneficiary This individual example uses BSB/account details. The API key binds the request to the correct tenant account and its settings, so no business-line selector is needed. ```bash theme={null} curl -X POST https://api.sandbox.rails.wayex.com/v1/treasury/beneficiaries \ -H "Authorization: Bearer $WAYEX_SECRET_KEY" \ -H "Idempotency-Key: beneficiary-aud-001" \ -H "Content-Type: application/json" \ -d '{ "type": "individual", "destination": { "type": "bank_account", "bsb": "062000", "accountNumber": "12345678", "accountName": "Ava Williams" }, "firstName": "Ava", "lastName": "Williams", "dateOfBirth": "1991-05-14", "address": "100 Market Street, Sydney NSW 2000", "sumsub": { "shareToken": "" }, "partyContext": { "downstreamMerchantReference": "merchant-7842" } }' ``` Omit `sumsub` when no token is available and the account policy does not require it. You may also supply an optional `externalReference` or `sumsub.externalReference` when your system already has a stable reconciliation identifier; Wayex generates the missing references. Use `GET /v1/treasury/beneficiaries/{id}` before payout review when you need the current status. Deactivate a beneficiary with `POST /v1/treasury/beneficiaries/{id}/deactivate` when it should no longer receive new payouts. Historical payouts keep the beneficiary snapshot they used. ## Pay a PayID instead of a bank account A beneficiary's AUD payout destination can be a **PayID** rather than a bank account. Set `destination.type` to `payid` and supply the `payId`, its `payIdType` (`email`, `phone`, or `abn`), and an `accountName`. Everything else — party details, optional evidence, references — is unchanged. ```bash theme={null} curl -X POST https://api.sandbox.rails.wayex.com/v1/treasury/beneficiaries \ -H "Authorization: Bearer $WAYEX_SECRET_KEY" \ -H "Idempotency-Key: beneficiary-payid-001" \ -H "Content-Type: application/json" \ -d '{ "type": "individual", "destination": { "type": "payid", "payId": "ava.williams@example.com", "payIdType": "email", "accountName": "Ava Williams" }, "firstName": "Ava", "lastName": "Williams", "dateOfBirth": "1991-05-14", "address": "100 Market Street, Sydney NSW 2000" }' ``` Choose one destination type per beneficiary. To move an existing recipient from a bank account to a PayID (or the reverse), create a new beneficiary with the new destination and deactivate the old one; destinations are not edited in place. ## Optional Sumsub evidence The single-use Sumsub share token is optional unless the tenant account's effective policy requires it. Submit the token when creating the beneficiary. Wayex validates it, stores only the reusable evidence result, and associates that result with the saved beneficiary. Payouts use the beneficiary's newest accepted, unexpired evidence automatically, or an explicit `evidenceId` when you need to select a prior result. Evidence expires. To refresh it for an existing beneficiary — for example after the previous result expires — submit a new single-use token with `POST /v1/treasury/sumsub-evidence`, passing the `beneficiaryId`, the `shareToken`, and an `externalReference`. The newest accepted, unexpired result is then selected automatically for payouts. You do not need to recreate the beneficiary. A Sumsub share token is input-only and single-use. Wayex sends it once for validation and never stores, returns, or logs it. Keep it out of your database, analytics, webhook payloads, and support notes. If you provide a token, Wayex validates it and matches it to the beneficiary. Invalid, expired, mismatched, rejected, or temporarily unverifiable evidence is never silently ignored. If you omit it when policy allows omission, normal screening still applies. ## Preview, review, and submit a payout Preview the exact payout intent before asking the user to confirm it: ```bash theme={null} curl -X POST https://api.sandbox.rails.wayex.com/v1/treasury/payouts/preview \ -H "Authorization: Bearer $WAYEX_SECRET_KEY" \ -H "Idempotency-Key: payout-review-aud-001" \ -H "Content-Type: application/json" \ -d '{ "beneficiaryId": "ben_123", "amount": "250.00", "currency": "AUD", "externalReference": "payout-9172", "purpose": "Customer withdrawal", "walletProviderReference": "wallet-au-01", "downstreamMerchantReference": "merchant-7842" }' ``` Show the returned `principal`, `fee`, `sourceDebit`, `canProceed`, and `holdReason` on the review screen. Previewing does not reserve or send money. It can check an existing `evidenceId`, but it does not accept a Sumsub share token. Tokens are submitted at beneficiary creation or to the evidence endpoint — never on the payout request. After confirmation, submit the logical payout with a different stable idempotency key: ```bash theme={null} curl -X POST https://api.sandbox.rails.wayex.com/v1/treasury/payouts \ -H "Authorization: Bearer $WAYEX_SECRET_KEY" \ -H "Idempotency-Key: payout-submit-aud-001" \ -H "Content-Type: application/json" \ -d '{ "beneficiaryId": "ben_123", "amount": "250.00", "currency": "AUD", "externalReference": "payout-9172", "purpose": "Customer withdrawal", "walletProviderReference": "wallet-au-01", "downstreamMerchantReference": "merchant-7842" }' ``` The create request repeats all policy, balance, screening, and provider checks before it reserves money. A successful preview does not guarantee that a later create will still be accepted. Money you send is a bare decimal string (for example `"250.00"`). In payout and preview responses, each money field is an object carrying a decimal-string `amount` and an explicit `currency` — for example `"fee": {"amount": "2.50", "currency": "AUD"}`. The accepted operation response records the authoritative: * requested payout `amount`; * `fee`; * total `sourceDebit` reserved from the AUD wallet. ## Payout remitter Every AUD payout carries a **remitter** — the name the beneficiary sees as the payer on their bank statement. Your tenant account has a default, and each payout may override it. Read and set the account-wide default through the settings resource: ```bash theme={null} # Read the current default curl https://api.sandbox.rails.wayex.com/v1/treasury/settings \ -H "Authorization: Bearer $WAYEX_SECRET_KEY" # Set the default (requires treasury:write) curl -X PUT https://api.sandbox.rails.wayex.com/v1/treasury/settings \ -H "Authorization: Bearer $WAYEX_SECRET_KEY" \ -H "Idempotency-Key: treasury-settings-001" \ -H "Content-Type: application/json" \ -d '{ "payoutRemitter": "wayex" }' ``` `payoutRemitter` accepts exactly two values — never free text: | Value | Remitter shown on the payout | | -------- | ------------------------------------------------------------------------------- | | `wayex` | `Wayex` (the default). | | `tenant` | Your onboarded company name (returned as `tenantRemitterName` on the settings). | `GET /v1/treasury/settings` returns the current `payoutRemitter`, the `tenantRemitterName` the `tenant` option resolves to, and `updatedAt`. The onboarded company name itself comes from your account profile and cannot be changed through this endpoint. To override the default for a single payout, send an optional `remitter` (`wayex` or `tenant`) on the create request. A new default applies only to payouts created after it is set — a payout's recorded remitter never changes retroactively, so the value stored on a payout can differ from the current default. ## What happens to the balance ```text theme={null} available AUD --accept--> reserved AUD --settle--> captured \--proven non-execution--> released ``` Wayex returns `accepted` only after the full source debit is durably reserved. It can no longer back another payout, conversion, or withdrawal. A later bank return follows the tenant account's configured return-loss and recovery policy and creates explicit wallet movements. ## Payout states | State | Meaning | Your next action | | ----------- | ------------------------------------------- | ------------------------------------------------------------- | | `accepted` | Checks passed and source debit is reserved. | Wait for submission; do not pay again. | | `held` | Policy or screening requires review. | Read the reason and next action. | | `submitted` | The instruction reached the AUD rail. | Wait for authoritative settlement. | | `settled` | The downstream payout completed. | Reconcile the capture and references. | | `failed` | The payout did not complete. | Confirm reservation disposition before retrying a new payout. | | `returned` | A submitted or settled payout came back. | Reconcile the return credit/loss and recovery record. | ## Webhooks and safe retries Subscribe to `treasury.payout.updated`. On each event, deduplicate by `eventId` and fetch the payout by ID. Events can arrive more than once or out of order. If the create response is lost, retry the identical body with the same `Idempotency-Key`. Do not use a new key, change the external reference, or send another payout while the result is unknown. Fetch the payout by its Wayex ID or stable external reference before taking another action. Browse every beneficiary, evidence, and payout operation in the [API reference](/api-reference/overview). # Conversions and withdrawals Source: https://docs.rails.wayex.com/treasury/conversions-and-withdrawals Convert between AUD and stablecoin with physical rebalancing, then withdraw to a saved destination. Treasury conversions exchange an available wallet balance between AUD and a supported stablecoin. Stablecoin can remain in the wallet for another operation or be withdrawn to a saved, validated destination on its exact network. ## Auto-convert deposits into your AUD balance The conversion endpoints on this page act on balance you already hold. If instead you want incoming stablecoin to arrive in your Treasury account **already converted to AUD** — with no manual quote or accept step — point a direct off-ramp payment route at your own Treasury account: Provision an AUD [funding instrument](/treasury/funding-and-balances) and note its BSB and account number (or its PayID). Create an ordinary **off-ramp (stablecoin → AUD) [payment route](/console/payment-routes)** whose AUD payout destination is that Treasury BSB/account (or PayID). Send stablecoin to the route. Wayex converts at the live rate the instant the funds land (route-funded pricing), pays the AUD to your Treasury account, and credits your Treasury AUD wallet as an ordinary pay-in. This is a normal off-ramp route pointed at your own account's details — there is no separate "treasury" route type and nothing extra to configure. Each funding appears as a route conversion, and the resulting AUD lands as a Treasury pay-in you reconcile from [Funding and balances](/treasury/funding-and-balances). ## Before you convert * Confirm the source balance is available in this tenant account. * Read the effective pair, limits, fees, and quote lifetime. * API integrations generate one `externalReference` for the quote and a separate one for acceptance. Console users do not enter either reference. * Display the exact rate, fee, source debit, destination amount, and expiry returned by Wayex. * **Converting AUD to a stablecoin, you name the settlement network.** See [Choosing the settlement network](#choosing-the-settlement-network) below. Converting a stablecoin to AUD, you do not: that direction routes from the balance you already hold. * Every quote returns the `settlementNetwork` it was struck on. Store it for reconciliation. ## Quote and accept Creating a quote does not reserve money: ```bash theme={null} curl -X POST https://api.sandbox.rails.wayex.com/v1/treasury/conversion-quotes \ -H "Authorization: Bearer $WAYEX_SECRET_KEY" \ -H "Idempotency-Key: conversion-quote-aud-usdc-001" \ -H "Content-Type: application/json" \ -d '{ "sourceAsset": "AUD", "destinationAsset": "USDC", "settlementNetwork": "base", "sourceAmount": "1000.00", "externalReference": "quote-10027" }' ``` Wayex returns the quote ID and the settlement network the quote was struck on. The console retains the quote ID and submits it when the user confirms; console users never type or copy a quote ID. API integrations pass the returned `id` as `quoteId` on the acceptance request and generate the two external references for their own reconciliation. The reverse direction omits the field — Wayex settles the stablecoin you already hold: ```bash theme={null} curl -X POST https://api.sandbox.rails.wayex.com/v1/treasury/conversion-quotes \ -H "Authorization: Bearer $WAYEX_SECRET_KEY" \ -H "Idempotency-Key: conversion-quote-usdc-aud-001" \ -H "Content-Type: application/json" \ -d '{ "sourceAsset": "USDC", "destinationAsset": "AUD", "sourceAmount": "500.00", "externalReference": "quote-10028" }' ``` After the user reviews the unexpired quote, accept it: ```bash theme={null} curl -X POST https://api.sandbox.rails.wayex.com/v1/treasury/conversions \ -H "Authorization: Bearer $WAYEX_SECRET_KEY" \ -H "Idempotency-Key: conversion-accept-aud-usdc-001" \ -H "Content-Type: application/json" \ -d '{ "quoteId": "qte_123", "externalReference": "conversion-10027" }' ``` An expired quote cannot be altered or revived. Create a fresh quote and ask the user to review the new outcome. ## Choosing the settlement network Converting **AUD to a stablecoin** buys coin that has to be delivered onto one specific chain. That chain is the chain your account then holds the balance on, and the chain you can withdraw it on — so you choose it, and `settlementNetwork` is required on the quote request. There is no default and no fallback. The chains available to your account are the `runtimeCapabilities` entries on [`GET /v1/treasury`](/api-reference/treasury/get-the-overview). Pick one your account can actually withdraw on. | Response | Meaning | What to do | | ----------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | `400` `settlement_network_required` | The request converts AUD to a stablecoin and omitted `settlementNetwork`. | Name the chain. Do not retry the same body. | | `400` `unsupported_asset_network` | That asset does not settle on that chain, or Wayex cannot receive it there. | Choose a different chain. This is not transient. | | `409` `conversion_route_conflict` | Wayex has a settlement route pinned for that asset and you named a different one. | Use the pinned chain. Contact Wayex if you need the route changed. | | `422` `asset_network_unavailable` | The pair is supported and wired but not currently enabled for your account. | Contact Wayex to have the pair enabled. | Converting a **stablecoin to AUD** is unchanged and needs no network: Wayex settles from the chains your account actually holds that stablecoin on. Supplying `settlementNetwork` in that direction is an optional override and is still checked against any pinned route. Convert onto a chain you can leave on. A balance settled onto a chain you never fund again can still be converted back to AUD, but a stablecoin withdrawal on a chain your account has no credited deposit or settled conversion for is held for review — see [Withdrawals on a network you do not hold](#withdrawals-on-a-network-you-do-not-hold). ## Physical post-trade rebalancing Wayex does not credit an IOU and rebalance later. The source reservation remains in place while the trade and actual provider fund movements complete. ```mermaid theme={null} sequenceDiagram participant T as Your account participant W as Wayex wallet participant X as FX and settlement T->>W: Accept exact quote W->>W: Reserve full source debit W->>X: Execute trade W->>X: Settle source funds X->>W: Settle destination funds W->>W: Capture source and credit destination W-->>T: Conversion settled ``` The destination wallet is credited only after all required physical legs succeed. A timeout or ambiguous provider result remains held or reconciling; it is not treated as failed and automatically repeated. ## Conversion states | State or step | Wallet effect | | ---------------------------- | --------------------------------------------------------------- | | Quote created | No reservation or movement. | | `accepted` / trading | Source debit is reserved. | | Source settling | Source remains reserved; destination is not available. | | Destination settling | Source remains reserved; destination is not available. | | `settled` | Source is captured and backed destination amount is credited. | | Held or unknown | Funds remain protected while Wayex reconciles the real outcome. | | Proven pre-execution failure | Reservation is released with an immutable movement. | ## Save a withdrawal destination A stablecoin withdrawal uses a saved destination owned by this tenant account. The destination fixes the asset, network, address, and tag or memo where applicable. Destination changes create a new version instead of rewriting withdrawal history. Validate the beneficiary, asset, network, address, and tag or memo out of band before saving a destination. A valid address on the wrong network is still the wrong destination. Client administrators create destinations with MFA step-up in the console; deactivating a destination requires an authenticated administrator session. API integrations should use the saved destination ID returned by the destination resource; arbitrary inline addresses are not part of the normal workflow. ```bash theme={null} curl -X POST https://api.sandbox.rails.wayex.com/v1/treasury/destinations \ -H "Authorization: Bearer $WAYEX_SECRET_KEY" \ -H "Idempotency-Key: destination-usdc-base-001" \ -H "Content-Type: application/json" \ -d '{ "name": "Operating wallet", "asset": "USDC", "network": "base", "address": "0x1111111111111111111111111111111111111111", "externalReference": "wallet-base-01" }' ``` List or get a destination before use. To replace details, create a new validated destination and deactivate the old one with `POST /v1/treasury/destinations/{id}/deactivate`; do not overwrite history. ## Preview, review, and submit a withdrawal Preview the exact saved-destination withdrawal before asking the user to confirm it: ```bash theme={null} curl -X POST https://api.sandbox.rails.wayex.com/v1/treasury/withdrawals/preview \ -H "Authorization: Bearer $WAYEX_SECRET_KEY" \ -H "Idempotency-Key: withdrawal-review-usdc-001" \ -H "Content-Type: application/json" \ -d '{ "asset": "USDC", "network": "base", "amount": "100.00", "destinationId": "tdst_123", "externalReference": "withdrawal-7781" }' ``` Show the returned `principal`, `fee`, `sourceDebit`, `asset`, `network`, `canProceed`, and any `holdReason`. Previewing does not reserve or send stablecoin. A later create rechecks the balance, destination, limits, screening, and provider capacity. After confirmation, submit the same intent with a different stable idempotency key. The accepted operation response records the authoritative fee and total source debit, which Wayex reserves. Submission to the blockchain is still asynchronous. ```bash theme={null} curl -X POST https://api.sandbox.rails.wayex.com/v1/treasury/withdrawals \ -H "Authorization: Bearer $WAYEX_SECRET_KEY" \ -H "Idempotency-Key: withdrawal-submit-usdc-001" \ -H "Content-Type: application/json" \ -d '{ "asset": "USDC", "network": "base", "amount": "100.00", "destinationId": "tdst_123", "externalReference": "withdrawal-7781" }' ``` Follow `accepted`, `held`, `submitted`, confirmations/finality, `settled`, and `failed` without collapsing them. A blockchain transaction hash is evidence of submission, not finality. ### Withdrawals on a network you do not hold A wallet balance is held per asset, but the coin itself sits on a specific chain. Wayex only sends a stablecoin withdrawal out on a network your account demonstrably holds that asset on — a credited deposit on that network, or a settled conversion that delivered onto it. A withdrawal naming any other network is still accepted and its source debit is still reserved, but it is recorded as `held` with `statusReason` `withdrawal_network_not_held` and is never submitted until Wayex releases it. Read it as "this account has no balance evidence on that chain", not as an outage — retrying the same request will not clear it. Either withdraw on a network you have funded, or [convert onto that network](#choosing-the-settlement-network) first. The withdrawal preview does not test this restriction: a withdrawal on an unheld network previews cleanly with `canProceed` true and is held on create. Treat the create response as authoritative. ## Webhooks and safe retries Subscribe to `treasury.conversion.updated`, `treasury.withdrawal.updated`, and `treasury.wallet.updated`. Deduplicate by `eventId`, then fetch the current resource. For quote creation, acceptance, destination creation, and withdrawal submission, keep one `Idempotency-Key` per logical action and reuse it with an identical payload after a lost response. If the provider outcome is unknown, do not create a replacement operation. Read and reconcile the original first. Browse the generated schemas in the [API reference](/api-reference/overview), then implement [Operations and reconciliation](/treasury/operations-and-reconciliation). # Funding and balances Source: https://docs.rails.wayex.com/treasury/funding-and-balances Fund an isolated Treasury account in AUD or stablecoin and understand when money becomes available. Funding adds backed money to the tenant account that owns the issued instructions. It does not add money to another account held by the same legal entity. ## Three records, three purposes | Resource | What it represents | | ---------------------- | ----------------------------------------------------------------------------------------------------------------- | | **Funding instrument** | Reusable instructions: an AUD BSB/account (and, by default, a PayID to pay into) or a stablecoin deposit address. | | **Pay-in or deposit** | One observed incoming payment with its gross amount, fee, net credit, status, and source references. | | **Wallet movement** | The immutable financial entry created when the incoming payment affects the wallet. | Do not treat a funding instrument as proof that funds arrived, or a detected deposit as spendable. Only the wallet's `available` amount can fund a new operation. ## Before you fund * Confirm you are using the login or API key for the intended tenant account. * Read the effective rails, assets, and networks. * Fetch the current instructions instead of storing a screenshot or retyping them. * For stablecoin, match the asset exactly, and use a network the instrument was issued for — its single `network`, or one of the `acceptedNetworks` listed on an EVM-scope instrument. For stablecoin, sending the wrong token or using a network the instrument was not issued for can make funds unrecoverable or require manual investigation. For AUD, pay only the exact issued BSB and account number. Never infer compatibility from the address format. ## Fund with AUD or stablecoin List the account's funding instruments. Provision an AUD instrument only when a suitable one does not already exist. It returns the BSB, account number, and account name, plus — unless you opt out — a `payId` that resolves to the same account. Incoming payments are matched by the unique BSB and account number — no payment reference is required. A newly issued account or PayID can take a few minutes to become active for NPP; honour any `activationMessage` before sharing the PayID for a real payment. Pay the exact issued instructions from the approved source. Preserve your own payment reference so your operations team can match it later. Wayex detects and matches the pay-in, applies any configured inbound fee, then credits the net amount when it is usable. Until then it remains pending or held. Use a funding instrument issued for the exact stablecoin, on a network the instrument accepts. For a single-network instrument (one with a `network` field), an address issued for one network is not permission to use it on another. An EVM-scope instrument (`networkScope: "evm"`) has one address that accepts the asset on any network listed in its returned `acceptedNetworks` — never a network outside that list. Send the supported token and retain the source wallet reference and transaction hash. Wayex detects the deposit, waits for the required network finality and screening, and credits the net amount. A detected or confirming deposit is not available. ## Provision funding instructions Creating instructions does not move money. Use one idempotency key for the logical provisioning request and keep it stable across retries. The request `type` selects what to provision, and each type has its own options: * **`aud_account`** — reusable AUD instructions. `accountName` is required. `includePayId` is an optional boolean that defaults to **true**: the instrument is issued with an email PayID to pay into alongside the BSB and account number. Set it to `false` to issue the account only. * **`stable_address`** — a stablecoin deposit address. `asset` is required. Provide a single `network` to pin the address to one chain, or `networkScope: "evm"` to accept the asset at one address on any supported EVM chain (see the EVM example below). ```bash theme={null} curl -X POST https://api.sandbox.rails.wayex.com/v1/treasury/funding-instruments \ -H "Authorization: Bearer $WAYEX_SECRET_KEY" \ -H "Idempotency-Key: aud-account-example" \ -H "Content-Type: application/json" \ -d '{ "type": "aud_account", "accountName": "Your Company Treasury", "includePayId": true }' ``` An AUD instrument returns its BSB, account number, and account name and — unless you set `includePayId` to `false` — a `payId` to pay into. A newly issued account or PayID can take a few minutes to become active for NPP. When the response carries an `activationMessage`, show it to your user and wait for activation before sharing the PayID for a real payment; the BSB and account number can be used as soon as they are issued. For stablecoin, choose a pair returned by the account's effective settings: ```bash theme={null} curl -X POST https://api.sandbox.rails.wayex.com/v1/treasury/funding-instruments \ -H "Authorization: Bearer $WAYEX_SECRET_KEY" \ -H "Idempotency-Key: funding-instrument-usdc-base-001" \ -H "Content-Type: application/json" \ -d '{ "type": "stable_address", "asset": "USDC", "network": "base" }' ``` To accept the asset at one address on any supported EVM network, request an EVM-scope instrument instead of naming a single network: ```bash theme={null} curl -X POST https://api.sandbox.rails.wayex.com/v1/treasury/funding-instruments \ -H "Authorization: Bearer $WAYEX_SECRET_KEY" \ -H "Idempotency-Key: funding-instrument-usdc-evm-001" \ -H "Content-Type: application/json" \ -d '{ "type": "stable_address", "asset": "USDC", "networkScope": "evm" }' ``` The response returns one deposit address plus `acceptedNetworks`, filled by Wayex with the networks that address accepts. A deposit on any listed network is processed on the chain it lands on. Always share the returned list with the payer; funds sent on a network outside it are not accepted. ## Gross, fee, and net credit Incoming-funding records separate the amount received from the amount credited: ```text theme={null} gross amount - inbound fee = net wallet credit ``` For example, a gross A$10,000.00 pay-in with a A$5.00 inbound fee credits A\$9,995.00. Do not derive the fee from a balance difference; read the amounts recorded on the funding resource and linked wallet movement. ## Funding states | State | Spendable? | What to do | | ------------ | ------------------- | -------------------------------------------------------------- | | `detected` | No | Wait while Wayex identifies and matches the payment. | | `confirming` | No | Wait for bank usability or blockchain finality and screening. | | `held` | No | Read the reason and next action; contact support if requested. | | `credited` | Yes, in `available` | Reconcile the net credit and linked wallet movement. | | `returned` | No | Reconcile the return and its reason. | Pending money must remain visible as pending. If provider data is stale or unavailable, do not render it as zero and do not submit work based on a guessed balance. ## Read the balance safely ```bash theme={null} curl https://api.sandbox.rails.wayex.com/v1/treasury/balances \ -H "Authorization: Bearer $WAYEX_SECRET_KEY" ``` Check the `asset`, `available`, `reserved`, `pending`, `posted`, and `asOf`. Balance entries never carry a network — balances are per asset, with stablecoin balances aggregated across networks. Networks appear on network-specific resources such as funding instruments, deposits, and withdrawals. A later write can still be rejected if another accepted operation reserves funds first. ## Read incoming funding Wayex creates pay-in and deposit records from provider activity. Clients never `POST` a pretend incoming payment. ```bash theme={null} # AUD received on issued BSB/account instructions curl https://api.sandbox.rails.wayex.com/v1/treasury/payins \ -H "Authorization: Bearer $WAYEX_SECRET_KEY" # Stablecoin detected on issued addresses curl https://api.sandbox.rails.wayex.com/v1/treasury/deposits \ -H "Authorization: Bearer $WAYEX_SECRET_KEY" ``` Open `GET /v1/treasury/payins/{id}` or `GET /v1/treasury/deposits/{id}` for the current reason, next action, source references, gross/fee/net amounts, and linked movement. A stable deposit also shows the transaction reference and whether required finality was reached. Funding instruments have matching list, get, create, and deactivate operations. Deactivation stops normal new use but preserves historical pay-ins, deposits, and wallet movements. ## Webhooks and retries Use `treasury.payin.updated` and `treasury.deposit.updated` to trigger a fresh funding-resource read, and use `treasury.wallet.updated` to refresh balances. Webhooks are at-least-once and unordered: deduplicate by `eventId`, then fetch the current record rather than applying events as an ordered ledger. GET requests can be retried with backoff. For funding-instrument creation or deactivation, retry the same payload with the same `Idempotency-Key`. Never create a second instrument merely because the response was lost. Read [Operations and reconciliation](/treasury/operations-and-reconciliation) before moving from test funding to live-value operations. # Operations and reconciliation Source: https://docs.rails.wayex.com/treasury/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` | Client | 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.rails.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.rails.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.rails.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. The header value is formatted `sha256=` — compute your HMAC over the exact raw request bytes (before any JSON parsing) and compare the full prefixed string in constant time. Drop-in endpoint examples: **Node (Express):** ```js theme={null} import { createHmac, timingSafeEqual } from 'node:crypto'; import express from 'express'; const app = express(); // Verify against the exact raw bytes — don't JSON-parse first. app.post('/webhooks/wayex', express.raw({ type: '*/*' }), (req, res) => { const secret = process.env.WAYEX_WEBHOOK_SECRET; const header = req.get('x-wayex-signature') ?? ''; // "sha256=" const expected = Buffer.from( 'sha256=' + createHmac('sha256', secret).update(req.body).digest('hex'), ); const received = Buffer.from(header); const valid = expected.length === received.length && timingSafeEqual(expected, received); if (!valid) return res.status(401).send('invalid signature'); const event = JSON.parse(req.body.toString('utf8')); // Dedupe by event.eventId, queue heavier work, then acknowledge fast: res.status(200).json({ received: true }); }); ``` **Python (Flask):** ```python theme={null} import hashlib, hmac, os from flask import Flask, request, abort app = Flask(__name__) @app.post("/webhooks/wayex") def wayex_webhook(): secret = os.environ["WAYEX_WEBHOOK_SECRET"].encode() header = request.headers.get("X-Wayex-Signature", "") # "sha256=" expected = "sha256=" + hmac.new(secret, request.get_data(), hashlib.sha256).hexdigest() if not hmac.compare_digest(expected, header): abort(401) event = request.get_json() # Dedupe by event["eventId"], queue heavier work, then acknowledge fast. return {"received": True}, 200 ``` See [Developers](/console/developers) for the signature format in detail 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. # Treasury overview Source: https://docs.rails.wayex.com/treasury/overview How an isolated Wayex Treasury account funds, pays, converts, withdraws, and reconciles AUD and stablecoins. Treasury is a prefunded PSP wallet for moving money on behalf of your business. You fund the account, then use its balance to make AUD payouts, convert between AUD and supported stablecoins, or withdraw stablecoin. ## One account, one boundary Every login and API key belongs to one **tenant account**. That account has its own: * AUD and stablecoin balances; * funding instructions; * fees, limits, rails, and networks; * beneficiaries and stablecoin destinations; * API keys, webhook subscriptions, users, and reporting. If you operate accounts with different commercial terms, Wayex provisions them separately. Sign in and prefund each one independently. Their money and records never net, spend, or report across accounts. The login or API key determines the account, so money forms need no account selector. An API key for one tenant account cannot read or spend another account's wallet. Keep each account's credentials in a separate secret and choose the credential before starting a workflow. ## What you can do Receive AUD through issued BSB/account instructions or deposit a supported stablecoin on the exact network shown. Save a BSB/account beneficiary, then create and track an AUD payout. Review a short-lived quote and convert AUD to stablecoin or stablecoin to AUD. Send an available stablecoin balance to a saved, validated destination on its matching network. Follow statuses, immutable wallet movements, webhooks, and external references. Run the same workflows from the institutional console without building an integration. ## Before you start Your Wayex contact must activate Treasury for the tenant account and configure its commercial terms, limits, rails, networks, and evidence policy. For an API integration, create a secret key with `treasury:read` and `treasury:write`. A reporting integration only needs `treasury:read`. Read the effective settings before exposing an action. Wayex enforces the same settings again when you submit it; client-side checks improve the experience but never replace server-side policy. ## The wallet model | Amount | Meaning | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `available` | Backed funds that can be used for a new operation. | | `reserved` | Funds committed to accepted work but not yet captured or released. | | `pending` | Incoming funds detected but not yet spendable. | | `posted` | The wallet-ledger posted amount: `available` plus `reserved`. Pending inbound receipts are excluded. Every balance also reports the `asOf` time of the reading. | An operation can only spend `available`. When Wayex accepts a payout, conversion, or withdrawal, it moves the full source debit into `reserved` in the same durable decision. This prevents the same funds from backing two operations. `accepted` means validation passed, the balance was durably reserved, and execution can continue. It does not mean a bank payment, blockchain transaction, trade, or post-trade settlement completed. ## First API check Fetch the overview after authenticating. It confirms the account, balances, funding setup, and enabled capabilities in one response. ```bash theme={null} curl https://api.sandbox.rails.wayex.com/v1/treasury \ -H "Authorization: Bearer $WAYEX_SECRET_KEY" ``` Then fetch the tenant-level effective settings before building forms or sending money: ```bash theme={null} curl https://api.sandbox.rails.wayex.com/v1/treasury/configurations/effective \ -H "Authorization: Bearer $WAYEX_SECRET_KEY" ``` Both calls are read-only and need no idempotency key. Browse their request and response schemas in the [API reference](/api-reference/overview). ## Environment safety The sandbox (`https://api.sandbox.rails.wayex.com`) is fully simulated: no real funds ever move, and its funding instructions are test fixtures. Production (`https://api.rails.wayex.com`) moves real funds — confirm the asset and network, and start with small amounts before your first production funding. ## Choose a workflow * Start with [Funding and balances](/treasury/funding-and-balances) to make money available. * Continue with [Beneficiaries and payouts](/treasury/beneficiaries-and-payouts) for AUD delivery. * Use [Conversions and withdrawals](/treasury/conversions-and-withdrawals) for FX and stablecoin delivery. * Implement [Operations and reconciliation](/treasury/operations-and-reconciliation) before going live.