Respond to VOP requests
Learn how to respond to VOP requests using Mambu Payments (formerly Numeral)
As a participant to the VOP scheme, you will receive and respond to VOP request as the responding PSP.
Mambu Payments supports three integration modes to fit your needs:
- Synchronised accounts
- Account holder information requests to your system
- Pass-through integration with your system
Learn more about each of these integration modes below.
Synchronised accounts
To respond to incoming VOP requests, you can duplicate your account database in Mambu Payments, using Internal accounts.
When a requesting PSP sends a request related to one of your accounts, Mambu Payments will:
- Check the request coherence making sure the requesting PSP is a participant to the VOP scheme and that the request complies with the VOP scheme rulebook
- Find the corresponding account using the IBAN
- Computes matching using an algorithm that complies with the EU's Instant Payments Regulation and the EPC's VOP scheme rulebook and recommendations
sequenceDiagram
participant Requesting PSP as Requesting PSP
participant Numeral as Mambu Payments
participant Responding PSP as Responding PSP
Responding PSP->>Numeral: Duplicate and update accounts database
Requesting PSP->>Numeral: Send request
activate Numeral
Note over Numeral: Check request coherence
Note over Numeral: Find corresponding account
Note over Numeral: Compute matching
Numeral->>Requesting PSP: Respond
deactivate Numeral
Numeral->>Responding PSP: Notify
To synchronise accounts in Mambu Payments, you can either:
- Use the internal accounts API to create and update internal accounts
- Upload your accounts on Numeral's SFTP server, on your own SFTP server, or in the Mambu Payments (formerly Numeral) dashboard
Account holder information requests to your system
Upon receiving a VOP request and after having verified its validity, Mambu Payments will request account holder information from your system using the IBAN received to compute and return the result to the requesting PSP.
sequenceDiagram
participant Requesting PSP as Requesting PSP
participant Numeral as Mambu Payments
participant Responding PSP as Responding PSP
Requesting PSP->>Numeral: Send request
activate Numeral
Note over Numeral: Check request coherence
Numeral->>Responding PSP: Forward IBAN
activate Responding PSP
Note over Responding PSP: Find corresponding account
Responding PSP->>Numeral: Send name / identification
deactivate Responding PSP
Note over Numeral: Compute matching
Numeral->>Requesting PSP: Respond
deactivate Numeral
Numeral->>Responding PSP: Notify
In this configuration, Mambu Payments will send an API payload containing the account number and identification type to your webhook.
curl --request POST \
--url https://responding-psp.com/payee_identification_webhook \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"payee_account_number": "FR8517569000405475971712Q97",
"payee_identification_type": "name",
"id": "4dd0c340-fa39-4616-ae95-0afb5d44aba5", // The ID of the payee verification requests
"scheme_request_id": "1dfd9cd3-0057-45a2-a2e1-18d0c96bbee4", // received request ID,
"request_timestamp": "2025-01-26T13:51:10Z" // Time at which the request was initiated by the requesting PSP
}
'Your system should respond with:
- The relevant status code (
200,404, or5xx) - The corresponding account holder information found in your database, if any
{
"payee_account_number": "FR8517569000405475971712Q97",
"payee_identification_type": "name",
"payee_identification": ["Jean Dupont"]
}{
"error": "account not found"
}{
"error": "identification type not found"
}Pass-through integration with your system
sequenceDiagram
participant Requesting PSP as Requesting PSP
participant Numeral as Mambu Payments
participant Responding PSP as Responding PSP
Requesting PSP->>Numeral: Send request
Note over Numeral: Check request coherence
Numeral->>Responding PSP: Forward request
Note over Responding PSP: Find corresponding account
Note over Responding PSP: Compute matching
Responding PSP->>Numeral: Send result
Numeral->>Requesting PSP: Respond
Numeral->>Responding PSP: Notify
If you want to keep business logics in your systems, you can choose the pass-through integration mode. Mambu Payments will request your systems to retrieve the matching result, and optionally the suggested name.
Below is an example of what a VOP request between Mambu Payments and your systems:
curl --request POST \
--url https://responding-psp.com/payee_identification_webhook \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"payee_account_number": "FR8517569000405475971712Q97",
"payee_identification_type": "name",
"payee_identification": "Jean Dupond",
"id": "4dd0c340-fa39-4616-ae95-0afb5d44aba5", // The ID of the payee verification requests
"scheme_request_id": "1dfd9cd3-0057-45a2-a2e1-18d0c96bbee4", // The ID of the request received
"request_timestamp": "2025-01-26T13:51:10Z" // Time at which the request was initiated by the requesting PSP
}
'Your system should respond with:
- The relevant status code (
200,404, or500) - The corresponding matching result
{
"matching_result": "close_match",
"payee_suggested_name": "Jean Dupont",
}{
"error": "account not found"
}{
"error": "identification type not found"
}Authentication
For account holder information requests to your system and pass-through integration with your system, supported authentication methods are:
- API key
- Basic auth (username and password)
curl --request POST \
--url 'YOUR_VOP_ENDPOINT' \
--header 'accept: application/json' \
--header 'x-api-key: YOUR_API_KEY'curl --request POST \
--url 'YOUR_VOP_ENDPOINT' \
--header 'accept: application/json' \
--header 'Authorization: Basic YOUR_CREDENTIALS'
// Where YOUR_CREDENTIALS is the Base64 encoding of username and password separated by a single colonOther authentication methods can be evaluated on demand.
Events sent by Mambu Payments to your webhook will always originate from the same IPs. We recommend whitelisting these IPs.
Simulate incoming VOP requests
Incoming VOP requests can be simulated:
- Using the Simulate incoming payee verification request API endpoint
- In the dashboard, VOP > Incoming VOP requests > Simulate VOP request
Updated 7 days ago
