Wise Rail

Overview

The Wise rail executes international bank transfers using the Wise API. It auto-detects the recipient format and routes through the appropriate Wise payment type:

• IBAN (EU/international) — GB29NWBK60161331926819
• UK sort code + account — 60-00-01 12345678
• US ABA routing + account — 021000021/000123456789
• SWIFT/BIC — fallback for other formats

Wise supports 80+ currencies. The rail creates a quote, registers the recipient account, creates a transfer, and funds it from your Wise balance — all in one executeAgentPayment() call.

Setup

WISE_API_KEY=...           # From Wise Dashboard → Settings → API tokens
WISE_ENV=sandbox           # 'sandbox' (default) or 'live'
WISE_PROFILE_ID=12345      # Optional — skip GET /v1/profiles on first call

Caution

For production use (WISE_ENV=live), Wise requires a verified business profile with KYB completed. Complete verification in the Wise Business Dashboard before enabling live mode.

Usage

Pay via IBAN

const result = await executeAgentPayment(signed, {
  recipient: 'GB29NWBK60161331926819',  // IBAN
  amount: 1000,
  rail: 'wise',
  memo: 'Contractor invoice INV-2026-042',
})

console.log(result.success)                    // true
console.log(result.txId)                       // '12345678' (Wise transfer ID)
console.log(result.meta?.wiseStatus)           // 'processing'
console.log(result.meta?.wiseTransferId)       // 12345678

Pay via UK sort code

const result = await executeAgentPayment(signed, {
  recipient: '60-00-01 12345678',  // sort code + account number
  amount: 250,
  rail: 'wise',
  memo: 'Invoice payment',
})

Pay via US ABA routing

const result = await executeAgentPayment(signed, {
  recipient: '021000021/000123456789',  // routing/account
  amount: 500,
  rail: 'wise',
  memo: 'US vendor payment',
})

Wise API flow

The rail executes these Wise API calls in sequence:

1. GET /v1/profiles → fetch business profile ID (cached per process)
2. POST /v3/quotes → create FX quote for the transfer amount
3. POST /v1/accounts → register recipient bank account
4. POST /v3/profiles/{profileId}/transfers → create the transfer
5. POST /v3/profiles/{profileId}/transfers/{id}/payments → fund from Wise balance

Mock mode (development)

Set PQSAFE_MOCK_MODE=1 to skip all Wise API calls. Returns a simulated wise_sbx_... transaction ID. Safe for integration testing without a Wise account.

Environment variables

Variable	Required	Description
WISE_API_KEY	Yes	API token from Wise Dashboard
WISE_ENV	No	live or sandbox (default: sandbox)
WISE_PROFILE_ID	No	Pre-set profile ID to skip the profiles lookup
PQSAFE_MOCK_MODE	No	Set to 1 to skip real API calls

Error codes

Code	Cause	Fix
INSUFFICIENT_FUNDS	Wise balance below transfer amount	Top up via Wise Dashboard
INVALID_RECIPIENT	Bank details rejected by Wise	Verify IBAN/sort code format
COMPLIANCE_BLOCK	Transaction flagged for compliance review	Contact Wise support

Related

→ Rails concept page — cross-rail comparison
→ Recipe: Pay Cloudflare Invoice — Wise + Stripe dual-rail example