Recipients

Before You Start

Read the following guides before proceeding:

Guide	Why
Getting Started	Platform overview and setup
Api Basics	Required headers and request configuration
Authentication	How to obtain the corporation token
Corridor Transfers	Corridor payouts name a recipient by id

A recipient is a stored payee: one identity — a person or a business — with one or more sets of payment
details, each covering a rail. A single recipient can hold a SEPA IBAN, a US routing and account number,
a PIX key and a crypto address at once, and a payout names the identity and the details it wants.

Recipients belong to the corporation. Every employee holding a corporation token can read them; creating
and changing them requires TransactionManage or TransactionSu.

Create with POST /api/v2/recipients, which writes the identity and its first payment details in one
call and performs a name check against the account. The v1 pair — create identity, then add details —
remains available for adding a second rail to an existing recipient.

A name_check result of name_matched: false does not block creation. The recipient is created and
payable, and the mismatch is what a rail rejects later, after the debit.

Recipient Lifecycle (Simplified)

Detailed documentation available in Creating a Recipient and
Managing Recipients.

sequenceDiagram
    participant App as Your App
    participant Corp as Wirex Corporate API

    App->>Corp: 1. POST /api/v2/recipients
    Corp-->>App: recipient id, payment_details[].id, name_check
    Corp->>App: POST /v2/webhooks/recipients

    App->>Corp: 2. POST /api/v1/recipients/{recipientId}/payment_details
    Corp-->>App: second payment details id

    App->>Corp: 3. POST /api/v3/bank/estimate/{corridor}
    Corp-->>App: estimation id
    App->>Corp: 4. POST /api/v3/bank/initiate/{corridor}
    Corp-->>App: transfer id

Step	Action	Description
1	`POST /api/v2/recipients`	Create the payee with its first rail, and read the name check
2	`POST /api/v1/recipients/{recipientId}/payment_details`	Add another rail to the same payee
3	`POST /api/v3/bank/estimate/{corridor}`	Quote a payout naming `recipient_id` and `recipient_payment_details_id`
4	`POST /api/v3/bank/initiate/{corridor}`	Execute the payout

Supported Details Types

Crypto · Sepa · Swift · FasterPayment · Ach · Spei · Card · Pix · FpsHk · Imps ·
Instapay · BiFast · Nip · Ipp · Pse

Guides

Guide	Description
Creating a Recipient	Creating a payee with details, per-rail fields and their formats
Managing Recipients	Listing, filtering, updating, deleting, and adding rails