Exchange and authorise

Exchange information and authorise execution

An assessment result of Allow is not permission to move funds. Keep your payment job on hold until its current requirements and the separate execution check pass. The execution path covers outgoing and incoming institutional transfers. Self-hosted wallets use a separate signed-wallet path. Below-threshold authorisation requires an explicit qualified policy, not just a low amount.

1. Complete the information review and the independent country reviews for the exact active policy version. Review all source, destination and organisation countries.
2. Create or refresh clearance with POST /transactions/{id}/travel-rule/transfer.
3. Prepare the message with POST /transactions/{id}/travel-rule/exchanges, using the current expectedRevision and the receiving institution's travelAddress. Myaza selects the matching existing approved route automatically. connectionId remains supported and is required if multiple scoped routes match that origin. An ordinary wallet address cannot select a route. Use a UUID v4 Idempotency-Key.
4. Send once with POST /transactions/{id}/travel-rule/exchanges/{messageId}/send. Wait for an authenticated acceptance. An uncertain or conflicting reply stays held.
5. From your backend, request and consume an execution authorisation as shown below.

Your original transaction must identify exactly one recipient crypto-wallet instrument, with its real identifier and network. An opaque wallet reference, masked address or customer-supplied verified flag is not sufficient. The assessed address and institution-approved address must both match recipientAddress exactly. The amount, asset and network come from the immutable assessed transaction.

Request a short-lived authorisation

POST /api/v1/transactions/{id}/travel-rule/execution/authorisations
Authorization: Bearer <secret-api-key>
Idempotency-Key: <uuid>
Content-Type: application/json

{
  "expectedRevision": 2,
  "recipientAddress": "<exact-assessed-wallet-address>"
}

The response contains authorisation.id, authorisation.token and authorisation.expiresAt. The signed token expires within 60 seconds. Keep it on your backend and out of logs, analytics, URLs and browser storage. Do not treat a valid signature or successful issuance as permission to send funds.

Consume once, immediately before execution

Your organisation's wallet executes the transfer; Myaza supplies the compliance authorisation. Integrate this gate into your backend before the wallet sends funds. You do not need to give Myaza custody of your funds. Your system owns submission, duplicate prevention, transaction confirmation and reconciliation. A webhook or an assessment's Allow is not a payment instruction: check current authorisation.

Persist a unique UUID externalExecutionId in your own durable payment job before this request. Use the same secret API key that requested the authorisation.

POST /api/v1/transactions/{id}/travel-rule/execution/consume
Authorization: Bearer <secret-api-key>
Content-Type: application/json

{
  "expectedRevision": 2,
  "recipientAddress": "<exact-assessed-wallet-address>",
  "token": "<authorisation.token>",
  "externalExecutionId": "<durable-payment-job-uuid>"
}

Myaza checks the current policy, country reviews, fraud decision, recipient, exchange evidence, connection, network catalogue and retention approval again. A changed or expired prerequisite holds the transfer even when the token has not expired.

• action: "execute_once": execute that exact durable job once. Your payment or custody integration must enforce the same job identifier against duplicate sends.
• action: "reconcile_execution": this is a replay, not another permission. Look up the existing job and reconcile it; never create a new payment.
• Any error, missing response or ambiguous result: keep the job held. Read GET /transactions/{id}/travel-rule/execution to reconcile the recorded receipt. This read remains available after token expiry; it does not grant new permission.

A transfer can have only one consumption receipt, across every token and revision. The receipt's settlementStatus: "UNKNOWN" is intentional: authorisation is not evidence of a broadcast or settlement. Myaza does not move funds. If the execution result is lost or uncertain, resolve it with your wallet system before taking any further action. Do not automatically retry a funds-moving operation with a new ID.