Skip to content

Airwallex "Make Transaction" on the real Payouts→Transfers API

Goal

Build a real outbound-payment flow on Airwallex's CURRENT Transfers API. The existing "Send transfer" drawer posts to the LEGACY /api/v1/payments/create ({source_id, beneficiary_id, amount, currency}) — wrong product. Rebuild on Payouts → Transfers, with beneficiary management we don't have today.

Research (2026-06-13, official docs + repo)

  • Create transfer: POST /api/v1/transfers/create — required: request_id (UUID idempotency), source_currency, transfer_currency, one of transfer_amount/ source_amount, transfer_method (LOCAL|SWIFT), reason (enum), reference, and beneficiary (saved beneficiary_id OR inline beneficiary{}).
  • Beneficiary: POST /api/v1/beneficiaries/create; required fields are DYNAMIC — fetch per destination via POST /api/v1/beneficiary_api_schemas/generate (drive the form off the returned fields[]+regex). We only list/get today.
  • FX (if source≠transfer ccy): POST /api/v1/fx/quotes/create → quote_id.
  • Flow: auth → bene schema → create/lookup bene → (FX quote) → create transfer → fund/approve (auto-debits wallet; may route to PENDING_APPROVAL) → status/webhook (transfer.*). Pin x-api-version (funding/approval changed 2024-01-31).
  • Per-statement join keys: request_id (our correlation id) + reference; show transfer_id/short_reference/status. No free-form metadata{} on Transfers.
  • Sandbox: AIRWALLEX_API_BASE_URL=https://api-demo.airwallex.com (+ demo keys); simulate status via POST /api/v1/simulation/transfers/{id}/transition.
  • SAFETY: the send must be an explicit user confirm step, never automatic.

Plan

New server routes wrapping the above (beneficiaries/schema, beneficiaries/create, fx/quote, transfers/create, transfers/{id}); add createTransfer/createBeneficiary/ createFxQuote to lib/airwallex/client.ts; schema-driven beneficiary form + review-&-confirm screen in the Make-Transaction drawer (T-023 mounts the button). Build + test in sandbox before prod.

Log

  • 2026-06-13 created from the Airwallex API research. Not started; follows T-023.
  • 2026-06-13 APPROACH APPROVED by owner ("nod to T-024"): build on the Transfers API (new beneficiary-schema + create + transfer + status routes), sandbox-first (api-demo.airwallex.com), explicit confirm-before-send. Cleared to build after T-023 pt2 (the visible Make-Transaction button this engine plugs into).