Create an outgoing wire transfer

Use this when you need to move funds out of the Weavr platform to an external bank account.

It transfers funds from one of the identity's managed accounts to a destination bank account over SEPA, Faster Payments, SWIFT, or RIX. The rails are chosen from the destination's bank details and reported back as type.

A transfer isn't submitted the moment you create it. Depending on the destination and the amount, it may first need payee confirmation, a transaction confirmation challenge, or both. Always read state in the response to decide what to do next.

Prerequisites

The source managed account must have an IBAN, otherwise the request fails with IBAN_UPGRADE_REQUIRED. See Add an IBAN to an account.

The Outgoing Wire Transfer Profile referenced by profileId, configured in the Multi Portal, must be active and must support the payment type being used. It determines the fees and restrictions applied to the transfer.

Fields

Source

sourceInstrument must be a managed account; cards can't fund a wire transfer. transferAmount is taken from that account and must be in the account's currency, or the request fails with CURRENCY_MISMATCH. Any fee is charged separately and reported as fee on the transfer.

Destination

destinationBeneficiary accepts the destination in one of three ways:

• Bank details: a SEPABeneficiary, FasterPaymentsBeneficiary, SWIFTBeneficiary, or RIXBeneficiary, supplied inline. The rails follow from the details you provide.
• A trusted payee: beneficiaryId, referencing a payee the identity has already added and verified. See Add payees.
• A linked account: an ExternalAccountId of type linked_accounts, referencing an external account the identity has already proven it owns.

Reference and purpose

description is passed to the beneficiary as the payment reference. It is mandatory for SEPA and SWIFT, and the length limit depends on the rails: 35 characters for SEPA and SWIFT, 18 for Faster Payments. purpose is mandatory for SWIFT; omitting it where it's required fails with PURPOSE_OF_PAYMENT_REQUIRED.

Scheduling

Set scheduledTimestamp to an epoch timestamp to execute the transfer at a future time. The transfer is held in SCHEDULED until then and can be canceled with Cancel an outgoing wire transfer.

Payee confirmation

Weavr checks the payee name before executing the transfer. GBP Faster Payments use Confirmation of Payee (CoP), and EUR SEPA transfers use Verification of Payee (VoP).

When confirmation is required, the transfer is created in PENDING_CONFIRMATION. Show the result to the user, then either confirm the transfer or cancel it. Where the name is close but not exact, you can correct it with Update the beneficiary name before confirming.

GBP transfers to linked accounts skip this confirmation, because ownership was already checked when the account was linked. EUR transfers to linked accounts still require confirmation.

Transaction confirmation

The user must complete a transaction confirmation challenge before the transfer is submitted. A transfer waiting on this is in PENDING_CHALLENGE; issue a challenge with one-time password or push notification, then verify it.

States

A newly created transfer is in one of:

State	Meaning
PENDING_CONFIRMATION	Payee confirmation is required. Show the result, then confirm or cancel.
PENDING_CHALLENGE	A transaction confirmation challenge is required before submission.
SCHEDULED	Accepted and waiting for scheduledTimestamp.
SUBMITTED	Sent to the financial institution for processing.
INVALID	Failed initial validation and won't proceed.

Once submitted, the transfer moves on to APPROVED, then COMPLETED, or to REJECTED, FAILED, or RETURNED. Track it with Get an outgoing wire transfer.