Wise

The Wise connector polls a Wise Business profile and surfaces multi-currency balances, recipients, and transactions. It initiates transfers between your balances and payouts to recipients across the Wise rail network, and ingests Wise webhooks.

Prerequisites#

You need a Wise Business profile and an API token with read access to balances, recipients, and transfers, plus write access for the outbound rails you initiate. The connector creates a webhook subscription at install and verifies deliveries against the webhookPublicKey you supply — mis-signed events are rejected.

Installation#

curl -X POST $FORMANCE_API_URL/api/payments/v3/connectors/install/wise \
  -H "Content-Type: application/json" \
  -d @config.json

Configuration fields#

Capabilities#

• FETCH_ACCOUNTS — multi-currency balances per profile via GET /v4/profiles/{profileId}/balances.
• FETCH_BALANCES — derived from the Accounts payload.
• FETCH_EXTERNAL_ACCOUNTS — recipients via GET /v1/accounts.
• FETCH_PAYMENTS — transfers with full lifecycle.
• FETCH_OTHERS — quotes and requirements, surfaced under wise-* on v3ListPaymentsOther.
• CREATE_TRANSFER — POST /v1/transfers between your own balances (after a quote).
• CREATE_PAYOUT — POST /v1/transfers to a registered recipient (after a quote).
• CREATE_WEBHOOKS + TRANSLATE_WEBHOOKS — subscribes to transfers#state-change and related events.

CREATE_BANK_ACCOUNT is not implemented; manage recipients via the Wise dashboard or POST /v1/accounts.

Account model#

Every Connectivity internal account is one Wise balance (single-currency, scoped to a profile). The reference is the balance ID; name is the balance name; defaultAsset is the balance currency at ISO 4217 precision. Accounts are emitted per profile. EXTERNAL accounts come from /v1/accounts (Wise recipients). See Accounts for the cross-connector model.

Asset model#

Multi-currency, formatted to UMN at ISO 4217 precision (USD/2, EUR/2, JPY/0, …). Amounts arrive as decimal strings; the connector applies major-to-minor scaling.

Status mapping#

outgoing_payment_sent is non-terminal — the connector keeps the transfer in PENDING until destination-side receipt is confirmed.

Metadata keys#

Under com.wise.spec/:

• Account: balance_id, profile_id, type (STANDARD / SAVINGS), currency.
• External account / recipient: account_holder_name, currency, country, bank_name, iban, swift_code, legal_entity_type.
• Payment: transfer_id, source_currency, target_currency, quote_id, source_amount, target_amount, rate, fee, reference.

Workflow tree#

FetchAccounts (periodic) — per profile
  ├── FetchBalances (FromPayload — no extra API call)
  └── FetchPayments (periodic) — per profile
FetchExternalAccounts (periodic) — per profile
FetchOthers (periodic) — quotes, requirements
CreateTransfer / CreatePayout (event-driven)
  ├── Create quote (POST /v3/quotes)
  ├── Create transfer (POST /v1/transfers)
  ├── Fund transfer (POST /v3/transfers/{id}/payments)
  └── PollTransferStatus / PollPayoutStatus until terminal
CreateWebhooks (one-shot at install)

Pagination and recovery#

offset + limit (max 100). Watermarks persist per profile / per stream in platform-managed State. Webhook deliveries dedupe at the engine level by PSPPayment.Reference.

Known gaps#

• Quote regeneration is handled inside CreateTransfer, but if the rate moves enough between quote and funding the transfer can fail with quote_expired — the PaymentInitiation lands in FAILED; retry to issue a fresh quote.
• Profile multi-tenant: one connector install covers every profile attached to the token (personal + business). Filter on metadata.profile_id to slice.