Guides
Log inContact us
Start typing to search…

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:

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, 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

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, 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.

Events sent by Mambu Payments to your webhook will always originate from the same IPs. We recommend whitelisting these IPs.

Updated 6 days ago

What's next