Migrate to Payouts v.2
This is a short temporary guide on how to move from /payment/v1/payouts
to /payment/v2/payouts
, including VoP flow and request/response changes.
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 |
|
Bank account |
|
Method | Must match bank details, for example, |
Extras |
|
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).
Updated 19 days ago