As a VOP scheme participant, you receive and respond to Verification of Payee (VOP) requests as the responding PSP. Mambu Payments supports three integration modes for handling incoming requests.

Synchronised accounts

Duplicate your account database in Mambu Payments using internal accounts. When a requesting PSP sends a VOP request for one of your accounts, Mambu Payments handles the entire flow:

1. Validate that the requesting PSP is a VOP scheme participant and that the request complies with the EPC VOP Scheme Rulebook.
2. Find the corresponding account by IBAN.
3. Compute the matching result using the VOP matching algorithm, which complies with the EU Instant Payments Regulation and the EPC matching recommendations.
4. Return the result to the requesting PSP and notify you via webhook.

sequenceDiagram
    participant RPSP as Requesting PSP
    participant MP as Mambu Payments
    participant You as Responding PSP

    You->>MP: Synchronise accounts database
    RPSP->>MP: Send VOP request
    activate MP
    Note over MP: Validate request
    Note over MP: Find account by IBAN
    Note over MP: Compute matching
    MP->>RPSP: Return result
    deactivate MP
    MP-->>You: Notify via webhook

Two methods are available to synchronise your accounts:

API. Create and update internal accounts using the internal accounts API.

File upload. Upload your accounts via SFTP or through the dashboard. Use the account upload template for the expected format.

Account holder information requests

Mambu Payments validates the incoming request and looks up the account holder in your system. You provide the account data; Mambu Payments computes the matching.

1. Mambu Payments receives the VOP request and validates it.
2. Mambu Payments sends the IBAN and identification type to your webhook endpoint.
3. Your system returns the account holder's name (or organisation identifier).
4. Mambu Payments computes the matching result and returns it to the requesting PSP.

sequenceDiagram
    participant RPSP as Requesting PSP
    participant MP as Mambu Payments
    participant You as Responding PSP

    RPSP->>MP: Send VOP request
    activate MP
    Note over MP: Validate request
    MP->>You: Forward IBAN and identification type
    activate You
    Note over You: Look up account
    You->>MP: Return account holder name
    deactivate You
    Note over MP: Compute matching
    MP->>RPSP: Return result
    deactivate MP
    MP-->>You: Notify via webhook

Mambu Payments sends the following payload to your VOP endpoint:

POST YOUR_VOP_ENDPOINT

{
  "payee_account_number": "FR8517569000405475971712Q97",
  "payee_identification_type": "name",
  "id": "4dd0c340-fa39-4616-ae95-0afb5d44aba5",
  "scheme_request_id": "1dfd9cd3-0057-45a2-a2e1-18d0c96bbee4",
  "request_timestamp": "2025-01-26T13:51:10Z"
}

Return the appropriate status code and body from your system.

200 – Account found. Return the account holder information:

{
  "payee_account_number": "FR8517569000405475971712Q97",
  "payee_identification_type": "name",
  "payee_identification": ["Jean Dupont"]
}

404 – Account not found:

{
  "error": "account not found"
}

404 – Identification type not supported:

{
  "error": "identification type not found"
}

5xx – Server error. Mambu Payments treats this as impossible_to_match and returns that result to the requesting PSP.

Pass-through integration

You handle both the account lookup and the matching computation. Mambu Payments validates the request, forwards it to your system, and relays your result to the requesting PSP.

1. Mambu Payments receives the VOP request and validates it.
2. Mambu Payments forwards the full request (including the payee's name or identifier) to your webhook endpoint.
3. Your system looks up the account, computes the matching, and returns the result.
4. Mambu Payments relays the result to the requesting PSP.

sequenceDiagram
    participant RPSP as Requesting PSP
    participant MP as Mambu Payments
    participant You as Responding PSP

    RPSP->>MP: Send VOP request
    activate MP
    Note over MP: Validate request
    MP->>You: Forward full request
    activate You
    Note over You: Look up account
    Note over You: Compute matching
    You->>MP: Return matching result
    deactivate You
    MP->>RPSP: Relay result
    deactivate MP
    MP-->>You: Notify via webhook

Mambu Payments sends the following payload to your VOP endpoint. Note that payee_identification is included – unlike the account holder information mode, your system receives the name to match against.

POST YOUR_VOP_ENDPOINT

{
  "payee_account_number": "FR8517569000405475971712Q97",
  "payee_identification_type": "name",
  "payee_identification": "Jean Dupond",
  "id": "4dd0c340-fa39-4616-ae95-0afb5d44aba5",
  "scheme_request_id": "1dfd9cd3-0057-45a2-a2e1-18d0c96bbee4",
  "request_timestamp": "2025-01-26T13:51:10Z"
}

Return the matching result and optionally a suggested name.

200 – Account found. Return the matching result:

{
  "matching_result": "close_match",
  "payee_suggested_name": "Jean Dupont"
}

Valid values for matching_result: match, no_match, close_match, impossible_to_match.

Include payee_suggested_name when matching_result is close_match. Set it to null otherwise.

404 – Account not found:

{
  "error": "account not found"
}

404 – Identification type not supported:

{
  "error": "identification type not found"
}

Authentication

The account holder information and pass-through integration modes require Mambu Payments to call your system. Two authentication methods are supported:

API key:

curl --request POST \
     --url YOUR_VOP_ENDPOINT \
     --header 'accept: application/json' \
     --header 'x-api-key: YOUR_API_KEY'

Basic auth:

curl --request POST \
     --url YOUR_VOP_ENDPOINT \
     --header 'accept: application/json' \
     --header 'Authorization: Basic YOUR_CREDENTIALS'

YOUR_CREDENTIALS is the Base64 encoding of your username and password separated by a colon.

Contact the Mambu Payments team if you require a different authentication method.

⚠️

Security: Mambu Payments webhook requests always originate from a fixed set of IP addresses. Add these IPs to your allowlist.

Test in sandbox

Simulate incoming VOP requests using either method:

API. Use the simulate incoming payee verification request endpoint.

Dashboard. Go to VOP > Incoming VOP requests > Simulate VOP request.

Related

• Introduction to VOP
• Send VOP requests
• VOP matching algorithm
• VOP failure codes and status details
• Internal account object
• Payee verification request object