Guides
Start typing to search…

Verification of Payee (VoP) for SEPA EUR Payments

To comply with new regulations and improve payment safety, we’re adding a Verification of Payee (VoP) step.

When a payee’s details aren’t an exact match, your user must explicitly confirm the details before the payment can proceed.

Scope

This feature is initially available only for SEPA EUR payments. We plan to extend this to other payment schemes later.

Please note that payments made via the EAGLE_NET scheme are not subject to the Verification of Payee (VoP) requirement.

New Verification Flow

Step 1 — Start verification

Create the Payee as you normally would. Then start the verification:

Endpoint: POST /payees/{payeeId}/verification

{
    "id": "pvn_vblpd5j1ak47meya4r",
    "payeeId": "pye_82rl497gpx3k7g5ykv",
    "assignedToId": null,
    "status": "PENDING_CUSTOMER_REVIEW",
    "type": "VERIFICATION_OF_PAYEE",
    "matchResult": {
        "matchLevel": "NO_MATCH",
        "description": null,
        "accountHolder": null
    }
}

Step 2 — Handle the verification result

The verification returns one of:

  • MATCH - Exact match. Proceed to payment using the returned id as payeeVerificationId.
  • CLOSE_MATCH or NO_MATCH - Action required. The user must explicitly confirm they want to proceed despite the mismatch.
    • Via UI: A confirmation modal describes the mismatch and asks the user to proceed or cancel.
    • Via API: Review the verification using the verificationId from Step 1:
    • Endpoint: POST /payees/verifications/{verificationId}/review
{ 
  "accepted": true 
}
{ 
  "accepted": false 
}
❗️

Note

You can only use the payeeVerificationId after a CLOSE_MATCH/NO_MATCH is accepted.

Request Errors

If the verification request itself fails (e.g., validation error), the API returns an error and no verification object is created. Retry once the underlying issue is resolved.

{
  "errorCode":"INVALID_REQUEST_DATA",	
  "message":"Payee couldn't be verified. Please confirm bank details and try again."
}

Step 3 — Send the payment

Attach the payeeVerificationId to your payout request:

{
  "fromId": "fac_4dbv611zb251v3orMg",
  "toId": "pye_eaxp4n74j5127l58vm",
  "payeeVerificationId": "pvn_vkoep8y1d57rmnba1g",
  "reference": "test payout SCT",
  "amount": "6",
  "paymentScheme": "SCT"
}

Lifecycle & constraints

  • Single use. A payeeVerificationId authorizes one payment. After successful use, its status becomes ASSIGNED and it cannot be reused.
  • Required status for assignment. The payment assignment only accepts verifications in ACCEPTED and EXEMPT statuses. If you attempt to use any other status (e.g., ASSIGNED, EXPIRED, PENDING_CUSTOMER_REVIEW), you’ll receive an error similar to: “Couldn't assign payee verification, should be in ACCEPTED status, but was [status].”
  • Expiry. Any verification in PENDING_CUSTOMER_REVIEW or ACCEPTED that is older than 10 minutes automatically transitions to EXPIRED. Start a new verification if it expires.

Interpreting VoP Verification Responses

When you make a call to the Payee Verification endpoint, it's crucial to understand the difference between a successful verification (which returns a match status) and an error (which means the verification could not be performed).

✅ Successful Verification: NO_MATCH A NO_MATCH response is not an error. It is a successful, definitive result from the recipient's bank.

This confirms that the verification was completed and the recipient's bank has definitively stated that the payeeName you provided does not match the account holder's name on their records for the specified IBAN.

Action: You should inform your user of the mismatch and advise them to confirm the payee's details before proceeding.

⚠️ Error: Payee couldn't be verified This is an error message indicating that the verification process itself could not be completed.

The system was unable to get a clear "Match" or "No Match" status from the recipient's bank.

This error can occur in several scenarios:

  • Bank Not on Network: The recipient's bank (the VoP responder) is not yet a participant in the VoP network.
  • Account Not Found/Ready: The recipient's bank is on the network, but the specific account is not yet available for verification. This often happens with newly created accounts that haven't been synchronized with the bank's VoP directory.
  • Account Type Not Supported: The recipient's bank does not support VoP checks for that specific type of account (e.g., certain savings accounts, non-payment accounts, or older accounts).

Action: You should inform your user that the payee's details "could not be verified at this time" and advise them to proceed with caution or check the details again.


Updated 3 months ago