As a participant to the VOP scheme, you will receive and respond to VOP request as the responding PSP.

Mambu Payments (formerly Numeral) 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 (formerly Numeral), using Internal accounts.

When a requesting PSP sends a request related to one of your accounts, Mambu Payments (formerly Numeral) 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

To synchronise accounts in Mambu Payments (formerly Numeral), 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 (formerly Numeral) will request account holder information from your system using the IBAN received to compute and return the result to the requesting PSP.

In this configuration, Mambu Payments (formerly Numeral) 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, or 5xx)
• 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

If you want to keep business logics in your systems, you can choose the pass-through integration mode. Mambu Payments (formerly Numeral) 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 (formerly Numeral) 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, or 500)
• 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) (planned)

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 colon

Other authentication methods can be evaluated on demand.

Webhooks sent by Mambu Payments (formerly Numeral) will always originate from the same IPs. We recommend whitelisting these IPs.