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

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 Numeral, using Internal accounts.

When a requesting PSP sends a request related to one of your accounts, 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 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 Numeral dashboard

Account holder information requests to your system

Upon receiving a VOP request and after having verified its validity, 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, 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
}
'

Your system should respond with:

• The relevant status code (2xx, 4xx, 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. Numeral will perform checks on incoming requests and send an incoming_vop_request.pending event to your webhook so you can compute and return the result to be forwarded to the requesting PSP.

Below is an example of what a VOP request between 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" //  received request ID
}
'

Your system should respond with:

• The relevant status code (2xx, 4xx, or 5xx)
• 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)

Other authentication methods can be evaluated on demand.

Webhooks sent by Numeral will always originate from the same IPs. We recommend whitelisting these IPs.