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.
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. |
| 2.1.0 | 15 May 2025 | Corrected the X-Request-Id example with valid RFC4122 value. Removed usage rule for accountHolderType. Updated usage rules for personalAccountHolders. Updated usage rules for organisationAccountHolder. |
| 2.1.1 | 20 May 2025 | Added reference to RFC6749 for connection (token). |
| 2.1.2 | 16 Jun 2025 | Updated description of EMPL from "employee" to "employer" under schemeNameCode. |
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 |
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. This should be implemented according to the RFC6749 standard, you can find the specification here.
- 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
X-Request-IdStringMandatoryContent-TypeStringMandatoryAuthorizationStringMandatoryAcceptStringOptional
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
accountIdObjectMandatoryunstructuredRemittanceInformationArray of StringsOptional
Request
{
"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
X-Request-IdStringMandatoryContent-TypeStringMandatory
Example of Response Headers
| Header name | Example |
|---|---|
| X-Request-Id | 123e4567-e89b-12d3-a456-426614174000 |
| 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.
accountNameStringConditionalaccountHolderTypeEnumOptionalbankAccountTypeEnumConditionalstatusEnumMandatorystartDateStringConditionalpersonalAccountHoldersArray of ObjectsConditionalorganisationAccountHolderObjectConditional
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
X-Request-IdStringMandatoryContent-TypeStringMandatory
Example of Error Response Headers
| Header name | Example |
|---|---|
| X-Request-Id | 123e4567-e89b-12d3-a456-426614174000 |
| Content-Type | application/json;charset=utf-8 |
Error Response Body
errorCodeStringMandatorymessageStringOptional
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 | Employer Identification Number request. Number assigned by a registration authority to an employer. | 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 |