POST/account/matchingdata

Online Data Provisioning API specifications

Welcome to the Online Data Provisioning API specification. This document provides implementation guidelines for Responding Payment Service Providers (PSPs) to build and configure an API endpoint that enables secure account data sharing for Verification of Payee (VoP) checks. The purpose of this API is to facilitate compliance with EPC VoP requirements by delivering accurate and relevant account information when requested. SurePay will call this endpoint to perform real-time verification, enhancing payment security and reducing fraud risks.

This specification outlines the API structure, data models, and response handling to ensure a seamless and standardized integration. By following this guide, PSPs can confidently implement a robust VoP solution that meets industry standards.

Document History

Version	Date	Description
1.0.0	15 Jan 2025	Original Digital Version. Aligned with PDF V1.3
1.1.0	03 Feb 2025	Validation added to accountId.type.iban, updated mandatory, condition & optional values for startDate, bankAccountType, surname, birthName, language. Added 'nomatchSuggestionAllowed' field in the 'organisationAccountHolder' object. Changed validation format of the fields 'iban' and 'lei'
1.1.1	19 Feb 2025	Changed 'legalNames' to 'legalName', 'language' format from 'ISO 639' to 'ISO 639-1'
2.0.0	20 Mar 2025	Format changes, refer to the detailed changes here.

Endpoints example

Environment	Method	Endpoint URL suggestion (Defined by customer)
Acceptance	POST	https://api.acc.yourbank.com/account/matchingdata
Production	POST	https://api.yourbank.com/account/matchingdata

Go directly to

Endpoints
Connection Requirements
Request
- Request Headers
- Request Body
Response
- Response Headers
- Response Body
Error Handling
List of Enumeration Values

Which data is mandatory to deliver?

Depending on the accessibility of your data, we highly recommend delivering at least the mandatory fields, as they are essential to ensure the service functions properly for the end user (the payer initiating the transaction). Optional fields are not required for the basic functionality of the VoP check but can improve the algorithm’s matching quality.

In a response, we always expect the mandatory information for the requested bank account.

What items do we need to establish the connection?

The exact endpoints for both production and test environments.
The certificates required to connect to the provided endpoints (SurePay's certificates are signed by DigiCert).
Client credentials, if needed, to access an Access Token API.
The token endpoint to be used with the above client credentials to retrieve the access token.
A Postman collection (including both the Data Provisioning and Token APIs). If a collection is not possible, a text file containing equivalent "curl" requests.

Request

Request Headers

Name
X-Request-Id
Type
String
Tag(s)
Mandatory
Description
An RFC4122 UUID used as a correlation id.
Name
Content-Type
Type
String
Tag(s)
Mandatory
Description
Content type and encoding of the request.
- Example: application/json
Name
Authorization
Type
String
Tag(s)
Mandatory
Description
OAuth 2.0 bearer token. You will also need to create an authentication endpoint where we can fetch and refresh this token.
Name
Accept
Type
String
Tag(s)
Optional
Description
The media type the client can process in the response. This is always set to application/json.
- Example: application/json

Example of Request headers

Header name	Example
X-Request-Id	550e8400-e29b-41d4-a716-446655440000
Content-Type	application/json;charset=utf-8
Authorization	Bearer <a bearer token>
Accept	application/json

Request Body

Name
accountId
Type
Object
Tag(s)
Mandatory
Description
Object used to send the account information in the request.
- Name
  type
  Type
  Enum
  Tag(s)
  Mandatory
  Description
  Describes the type of account that needs to be retrieved.
  
  Possible Values:
  
  IBAN: International Bank Account Number. No spaces are allowed.
- Name
  value
  Type
  String
  Tag(s)
  Mandatory
  Description
  The identifier of the account details to be retrieved.
  
  Format:
  
  IBAN: ^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$
  
  Format: Max. 34 Characters.
Name
unstructuredRemittanceInformation
Type
Array of Strings
Tag(s)
Optional
Description
Additional information about the account number sent by the Requesting PSP.
- Format: Max. 140 Characters.

Request

POST

account/matchingdata

    { 
        "accountId": { 
            "type": "IBAN",
            "value": "NL11SRPY1234567890"
        }   
    }

Response

In case of a successful response, the following headers and parameters are expected to be returned. In case of an unsuccessful response, a meaningful HTTP code and error message is expected, please read Error Handling.

Response Headers

Name
X-Request-Id
Type
String
Tag(s)
Mandatory
Description
Value as sent in the corresponding request header.
Name
Content-Type
Type
String
Tag(s)
Mandatory
Description
Content type and encoding of the request.
- Example: application/json

Example of Response Headers

Header name	Example
X-Request-Id	123e4567-e89b-12d3-a456-42661417400
Content-Type	application/json;charset=utf-8

Response Body

Within the following fields, you will encounter shared attributes applicable to both Natural Persons and Organisations in the ‘Account object’ section. However, each of these entities also possesses distinct attributes, which can be located within the "Person" and "Organisation" objects respectively.

Name
accountName
Type
String
Tag(s)
Conditional
Description
The name under which the account is registered at the PSP. In case the name of the account holder is longer than the permitted characters, this has to be shortened until it reaches the maximum number of allowed characters. The accountName can be created based on the following combinations:
- For Natural Persons, the account name can be a combination of: allFirstNames + surname or initials + surname.
- For Organisations, the account name can be taken from the following field: legalName.
- Format: Max. 140 Characters.
- Usage Rule:
  - If the account is found, then Mandatory.
  - If the account is NOT_FOUND, then this field is not returned.
Name
accountHolderType
Type
Enum
Tag(s)
Optional
Description
This designates if the account is a personal account or an account owned by an organisation.
- Possible Values:
  - NP: Natural Person
  - ORG: Organisation
- Usage Rule:
  - If NP then personalAccountHolders is mandatory.
  - If ORG then organisationAccountHolder is mandatory.
Name
bankAccountType
Type
Enum
Tag(s)
Conditional
Description
The type of bank account.
- Possible Values:
  - PAYMENTS: A payments account, also known as a checking account.
  - SAVINGS: A savings account.
  - MORTGAGE: A mortgage account.
  - TRUST: Also known as Escrow account. Used by notary offices, lawyers and bailiffs.
  - COLLECTION: Also known as beheer rekening. Typically owned by a collection agency or a debt buyer, but can also be used by Collecting Payment Service Providers.
  - INVESTMENT: Also known as brokerage account or pension account. An account used for investing.
  - OTHER: Other products.
  - UNKNOWN: Unknown account type.
- Usage Rule: Mandatory when the customer has enabled the FRI add-on.
Name
status
Type
Enum
Tag(s)
Mandatory
Description
The status of the account.
- Possible Values:
  - ACTIVE: Account is a valid account and supported for checks.
  - INACTIVE: An account has been marked as 'closed' permanently or temporarily unable to receive payments.
  - NOT_FOUND: The account could not be found by the PSP.
Name
startDate
Type
String
Tag(s)
Conditional
Description
The date when the account was opened and registered by the PSP. Reflects the real start date of the account.
- Usage Rule: Mandatory when the customer has enabled the FRI add-on.
- Format: "YYYY-MM-DD".
Name
personalAccountHolders
Type
Array of Objects
Tag(s)
Conditional
Description
Name
organisationAccountHolder
Type
Object
Tag(s)
Conditional
Description

Response

{
    "accountName": "J.R. van der Werff",
    "status": "ACTIVE",
    "personalAccountHolders": [
        {
            "allFirstNames": "John Richard",
            "surname": "van der Werff"
        }
    ]
}

Error Handling

Status and error codes

Errors follow standard HTTP status codes in the 4xx and 5xx ranges. In some cases, it is useful to include a JSON error object in the response body, especially for a 400 Bad Request status. The chosen structure aligns with the error format used in the VoP Gateway API.

HTTP Status Code	Description
400 - Bad request	Request has malformed missing or non-compliant JSON body or URL parameters
401 - Unauthorised	Authorization header missing or invalid token
403 - Forbidden	Token has incorrect scope or a security policy was violated
404 - Not Found	We were unable to find the requested resource in any of our available data sources
429 - Too many requests	Response status code indicates the user has sent too many requests in a given amount of time
500 - Internal server error	Something went wrong on the API gateway or service. In this case the body might contain different details based on the schema that we are connected with

Error Response

Error Response Headers

Name
X-Request-Id
Type
String
Tag(s)
Mandatory
Description
Value as sent in the corresponding request header.
Name
Content-Type
Type
String
Tag(s)
Mandatory
Description
Content type and encoding of the request.
- Example: application/json

Example of Error Response Headers

Header name	Example
X-Request-Id	123e4567-e89b-12d3-a456-42661417400
Content-Type	application/json;charset=utf-8

Error Response Body

Name
errorCode
Type
String
Tag(s)
Mandatory
Description
The error code that represents the functional error. All the functional errors are described in the Functional Errors table.
Name
message
Type
String
Tag(s)
Optional
Description
A description of the error that occurred.

HTTP 400 - Bad Request

    {
        "errorCode": "INVALID_IBAN",
        "message": "Invalid correlation ID in the request headers."
    }

Functional errors

HTTP 400 - Bad Request

If the client's submitted request does not pass the validations, the service will return an Error Response object with the details of the issue. The possible errorCode values are gathered in the following table:
Not all codes are mandatory to implement; these are suggestions.

Functional error	Description	Message
INVALID_IBAN	The IBAN provided does not pass the MOD97 algorithm check.	"The IBAN in the request body is invalid."
INVALID_REQUEST_ID	A correlation ID is invalid if it does not match the regular expression, if its length is shorter than 1 or its length is longer than 70 characters	"Invalid correlation ID in the request headers."
INVALID_UNSTRUCTURED_REMITTANCE_INFORMATION	The secondary identification is invalid.	"The unstructured remittance information in the request body is invalid."
INVALID_REQUEST	The provided request’s JSON format does not comply with the expected structure.	"The request has an invalid JSON format."

List of Enumeration values

companyId

The following table contains a list of enumeration values:

Enumeration value	Description	Format	Example
NL_KVK	Identifying number for a registration in the Netherlands Business Register.	Format: `[0-9]{8}`	Example: '12345678'
NL_KVK_BRANCH	Identifying number of a branch, providing information about the specific branch.	Format: `[0-9]{12}`	Example: '123456789101'
FR_SIREN	The unique French business identification number assigned by INSEE, the French National Institute for Statistics and Economic Studies.	Format: `[0-9]{9}`	Example: '123456789'
FR_SIRET	Number providing information about the business location in France. The registration number contains an extra 5 digits (added to the end of the SIREN number to form the full SIRET number).	Format: `[0-9]{14}`	Example: '12345678900001'
EU_VAT	Number used for sending a VAT number associated with a European company. To accept its value, the user must send the country code (from an EU country) plus the VAT number.	Format: Varies by country; typically `[A-Z]{2}[0-9]{8,12}`	Example: 'FR12345678901'
UK_CRN	The unique identifier in the register of the UK's Companies House.	Format: `(SC\|OC\|SO\|NI\|R\|NC\|RC\|LP\|SL\|NL){1,2}[0-9]{6,7}` or `[0-9]{8}`	Example: 'SC123456' or '12345678'
BE_KBO	The unique business identifier in the Belgium Kruispuntbank van Ondernemingen (KBO).	Format: `[0-9]{10}`	Example: '1234567890'
ES_CIF	The tax ID (CIF - Certificado de Identificación Fiscal) for Spanish companies.	Format: `[A-Z]{1}[0-9]{8}`	Example: 'A12345678'
DE_HRN	The German Handelsregister Number, a unique identifier for limited companies in Germany.	Format: `(HRA)[0-9]{6}` or `(HRB)[0-9]{6}` or `(HRB)[0-9]{6}(B){1}`	Example: 'HRA123456' or 'HRB123456' or 'HRB123456B'
LEI	Legal Entity Identifier, an alternate identification for a party. The LEI is a 20-character, alphanumeric code based on the ISO 17442 standard.	Format: `[A-Z0-9]{18}[0-9]{2}`	Example: 'XYZEFGHIJ0ABCDEF011'
BANK	Bank Party Identification request. A unique and unambiguous assignment made by a specific bank or financial institution to identify a relationship between the bank and its client.	Format: `[CountryCode][BankCode][BranchCode]`	Example: 'US123BANK001'
CBID	Central Bank Identification Number request. A unique identification number assigned by a central bank to identify an organisation.	Format: `(CB)[0-9]{9,12}`	Example: 'CB123456789'
CHID	Clearing Identification Number request. A unique identification number assigned by a clearing house to identify an organisation.	Format: `[A-Z]{2,4}[0-9]{4,6}`	Example: 'CHCLRG1234'
CINC	Certificate of Incorporation Number request. A unique identification number assigned by a designated authority to a certificate of incorporation, used to identify an organisation.	Format: `(INC)[0-9]{7,10}`	Example: 'INC1234567'
COID	Country Identification Code request. An identification code assigned by the country authority to identify an organisation (e.g., corporate registration number).	Format: `[A-Z]{2}[0-9]{8,10}`	Example: 'US123456789'
CUST	Customer Number request. A number assigned by an issuer to identify a customer or by a party to identify a creditor or debtor relationship.	Format: `(CUST)[0-9]{6,8}`	Example: 'CUST789456'
DUNS	Data Universal Numbering System request. A unique identification number provided by Dun & Bradstreet to identify an organisation.	Format: `[0-9]{9}`	Example: '123456789'
EMPL	Employee Identification Number request.	Format: `(EMP)[0-9]{6,8}`	Example: 'EMP123456'
GS1G	GS1 GLN (Global Location Number) Identifier request. A non-significant reference number used to identify legal, functional, or physical entities according to GS1 numbering scheme rules.	Format: `[0-9]{13,14}`	Example: 'GLN1234567890123'
TXID	Tax Identification Number request.	Format: `(TX)[0-9]{8,12}`	Example: 'TX123456789'
BDID	Business Domain Identifier request. An identifier representing the business domain in which the organisation operates.	Format: `(BUSDOM)[0-9]{5,10}`	Example: 'BUSDOM12345'
BOID	Business Other Identification request. Other identification for the organisation.	Format: Not specified	Example: Not Applicable