Migrate to Payouts v.2

Moving from /payment/v1/payouts to /payment/v2/payouts brings a new schema, improved compliance support, and Verification of Payee (VoP) for SEPA payouts. This guide highlights the main changes and shows how to adapt your integration.

Why migrate

Implemented a new flow for fiat payouts that aligns with regulatory requirements.
Added VoP support (EUR SEPA only): confirm the beneficiary if account-name matching is inconclusive.
Cleaner request and response schema with standardised fields.

👉 See full documentation at Initiate Payouts (v2) and previous flow.

What changed

Area	v1	v2
Endpoint	`POST /payment/v1/payouts`	`POST /payment/v2/payouts`
VoP flow	Not supported	`202` with `CONFIRM_BENEFICIARY` → confirm via `/payouts/{id}/actions`
Beneficiary	Flat name string	Structured `entity` (INDIVIDUAL/COMPANY) + `bankAccount`
Bank details	Simple account fields	Requires `accountNumberFormat`, `accountType`, `bank.identificationCode`
Extras	Limited	Supports `fees.customerFee`, `metadata`, `requestDetails.originator.ipAddress`
Response	Mixed	Standardized: `type`, `direction`, `originator`, `beneficiary`, `fees`

Minimal v2 request

{
  "walletId": "a:24092324785677:o6rhCEZ:1",
  "amount": 1000.5,
  "currency": "EUR",
  "beneficiary": {
    "remittanceInformation": "Payment for services",
    "entity": {
      "type": "INDIVIDUAL",
      "firstName": "John",
      "lastName": "Dove",
      "relationshipType": "SELF_OWNED"
    },
    "bankAccount": {
      "accountNumber": "DE89 3704 0044 0532 0130 00",
      "accountNumberFormat": "IBAN",
      "bank": { "identificationCode": "CHASUS33" }
    }
  }
}

Field	Changes in v2
Beneficiary	Use `beneficiary.entity` INDIVIDUAL: `firstName`, `lastName`, optional `dateOfBirth` COMPANY: `legalName` Add `relationshipType`, for example, `SELF_OWNED`
Bank account	`bankAccount.accountNumber` + `bankAccount.accountNumberFormat` (`IBAN`, `SORT_CODE`, `ABA`)` `bankAccount.accountType` (`CHECKING`, `SAVINGS`). `bankAccount.bank.identificationCode` required; `bankAccount.bank.nid` optional for US SWIFT. Bank address may be required for SWIFT.
Method	Must match bank details, for example, `SEPA_CT`, `SEPA_INST`
Extras	Optional: `fees.customerFee`, `metadata` For EPC-originated payments: `requestDetails.originator.ipAddress` is now required.

The response now always includes the following:

id, status (PROCESSING, COMPLETED, etc.)
type: "payment:payout:fiat"

New VoP confirmation flow

For EUR SEPA payouts:

If payee verification is needed, you’ll receive 202 Accepted:

{
  "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "requiredAction": "CONFIRM_BENEFICIARY",
  "status": "PAYEE_VERIFICATION_REQUIRED",
  "verificationResults": {
    "matchStatus": "PARTIAL_MATCH",
    "actualName": "George D. Collins",
    "providedName": "George Colins"
  }
}

Confirm the name by sending the POST /payment/v2/payouts/{id}/actions request within five minutes:
```
{
  "type": "CONFIRM_BENEFICIARY"
}
```
If the window expires or the Id is invalid, start a new payout.

🔗 For the details, refer to Initiate Payouts (v2).