Online Data Provisioning API specifications
This page serves as an implementation guide for PSPs, enabling them to securely create and configure a Data Provisioning API to provide account data to SurePay for Verification of Payee purposes.
Document History
| Version | Date | Description |
|---|---|---|
| 1.0 | 15 Jan 2025 | Original Digital Version. Aligned with PDF V1.3 |
Which data is mandatory to deliver?
Depending on the accessibility of your data we highly advise to deliver at least the Mandatory fields, as they are required to ensure the service works in a desirable way for the end user (the payer who initiates a transaction). Optional fields are not required for the basic functionality of the VOP check, but could improve the matching quality of the algorithm.
- In a response, we always expect the mandatory information of the bank account requested.
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 |
What items do we need to establish the connection?
- The exact endpoints for both production and test environment.
- Certificates needed to connect to provided endpoints (SurePay's certificate are signed by DigiCert).
- Client credentials, if needed in order for us to access an Access Token API
- Token endpoint to be used with the above client credentials, to retrieve the access token.
- Postman collection (with both APIs, Data Provisioning and Token APIs). If not possible, a text file containing equivalent “curl” requests.
Headers
- Name
X-Request-Id- Type
- String
- Tag(s)
- Mandatory
- Description
A RFC4122 UUID used as a correlation id.
- Name
Content-Type- Type
- application/json
- Tag(s)
- Mandatory
- Description
Content type and encoding of the request.
- application/json
- Name
Authorization- Type
- Bearer
- 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
- 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.
- 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-zA-Z0-9]{30} [18-34]
- IBAN -
- Name
unstructuredRemittanceInformation- Type
- String
- Tag(s)
- Description
Unstructured remittance information is information in addition to the IBAN.
- Format: 140 characters.
Request
{
"accountId": {
"type": "IBAN",
"value": "NL11SRPY1234567890"
}
}
Response body
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 the errors chapter.
Headers
- Name
X-Request-Id- Type
- String
- Tag(s)
- Mandatory
- Description
Value as sent in the corresponding request header.
- Name
Content-Type- Type
- application/json
- Tag(s)
- Mandatory
- Description
Content type and encoding of the request.
- application/json
Suggested response fields
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)
- Mandatory
- Description
The name under which the account is registered at the bank. The name under which the account is registered at the bank. 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", "initials" + "surname".
- For Organisations, the account name can be taken from the following field: "legalName".
- Format: Max. 140 characters
- Name
status- Type
- Enum
- Tag(s)
- Mandatory
- Description
- 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
- Date
- Tag(s)
- Description
The date when the account was opened and registered by the bank. Reflects the real start date of the account. Required when using Fraud Risk Indicator.
- Format: "YYYY-MM-DD".
- Name
bankAccountType- Type
- Enum
- Tag(s)
- Description
The type of bank account. The possible values are:
- 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 - An account used for investing (Also known as brokerage account or pension account).
- OTHER - Other products.
- UNKNOWN - Unknown account type.
- 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",
"initials": "J.R.",
"surname": "van der Werff"
}]
}
Status and error codes
Errors respect standard HTTP status codes in the 4xx and 5xx range. In some situations, it is desirable to include an error json object in the body, most notably when the status code is 400 Bad Request. The chosen structure is consistent with the error structure in the VOP Gateway API.
Error response body
- Name
- Type
- Array of Objects
- Tag(s)
- Description
- 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)
- Description
A description of the error that occurred.
Example - 400 bad request
[
{
"errorCode": "INVALID_ACCOUNT_NUMBER",
"message": " The ACCOUNT_NUMBER in the request body is invalid."
}
]
Technical Errors
| 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 | IResponse 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
[
{
"errorCode": "INVALID_REQUEST_ID",
"message": "The provided value for this header is invalid"
}
]
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 ‘errorCodes’ are gathered in the following table: Not all codes are mandatory to implement, these are a suggestion.
| Functional error | Description | Message |
|---|---|---|
| INVALID_IBAN | The IBAN provided does not pass the MOD97 algorithm check. | "Invalid correlation ID in the request headers." |
| 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 | "The IBAN in the request body is invalid." |
| 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 requests has an invalid JSON format." |
HTTP 400 - Bad Request
[
{
"errorCode": "INVALID_IBAN",
"message": "Invalid correlation ID in the request headers."
}
]
List of Enumeration values
CompanyId
The following table contain 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. It gives the information about the specific branch. | Format: [0-9]{12} | Example: '123456789101' |
| FR_SIREN | The unique French business identification number. | Format: [0-9]{9} | Example: '123456789' |
| FR_SIRET | The number that provides information about the location of the business in France. The registration number contains extra 5 digits (added onto the end of the SIREN number makes the full SIRET number). | Format: [0-9]{14} | Example: '12345678910111' |
| EU_VAT | Number that allows sending a VAT number associated with an European company. In order to accept its value, the user has to send the country code (belonging to an EU country) plus the VAT number. | Format: Multiple Validations depending on country | - |
| UK_CRN | The unique identifier on the register of the UK's Companies House. | Format: [SC,OC,SO,NI,R,NC,RC,LP,SL,NL] {2,1}[0-9]{6,7} or [0-9]{8} | Example: '12345678' |
| BE_KBO | The unique business identifier on the Belgium Kruispuntbank van Ondernemingen (KBO) | Format: [0-9]{10} | Example: '1234567890' |
| ES_CIF | This is the tax ID (CIF - Certificado de Identificacion Fiscal/Fiscal Identification Certificate) for all Spanish companies. | Format: [A-Z]{1}[0-9]{8} | Example: 'A12345678' |
| DE_HRN | The german HandelsRegister Number is a unique identifier used in Germany to identify limited companies. | Format: [HRA]{6}[0-9] or [HRB]{6}[0-9]{1}[B] | Example: 'HRA123456' |
| LEI | Legal entity identification as an alternate identification for a party. LEI is a code allocated to a party as described in ISO 17442 "Financial Services - Legal Entity Identifier (LEI)". | Format: [0-9]{4}00[A-Z0-9]{12}[[A-Z]0-9]{2} | Example: 'XYZEFGHIJ0ABCDEF011' |
| CBID | RequestCentralBankIdentificationNumber. Central bank identification number is requested. This is a unique identification number assigned by a central bank to identify an organisation. | Format: (CB)(0-9)[9-12 digits] | Example: 'CB123456789' |
| CHID | RequestClearingIdentificationNumber. Clearing identification number is requested. This is a unique identification number assigned by a clearing house to identify an organisation | Format: (A-Z)(2-4 letters)(0-9)(4-6 digits) | Example: 'CHCLRG1234' |
| CINC | RequestCertificateOfIncorporationNumber. Certificate of incorporation number is requested. This is a unique identification number assigned by a designated authority to a certificate of incorporation and used to identify an organisation. | Format: (INC)(0-9)(7-10 digits) | Example: 'INC1234567' |
| COID | RequestCountryIdentificationCode. Country identification code is requested. This is a country authority given organisation identification (e.g., corporate registration number). | Format: (A-Z)(2 digits)(0-9)(8-10 digits) | Example: 'US123456789' |
| CUST | RequestCustomerNumber. Customer number is requested. This is a number assigned by an issuer to identify a customer or a number assigned by a party to identify a creditor or debtor relationship. | Format: (CUST)(0-9)(6-8 digits) | Example: 'CUST789456' |
| DUNS | RequestDataUniversalNumberingSystem. Data universal number is requested. This is a unique identification number provided by Dun & Bradstreet to identify an organisation. | Format: (0-9)(9 digits) | Example: '123456789' |
| EMPL | RequestEmployeeIdentificationNumber. Employee Identification Number is requested. | Format: (EMP)(0-9)[6-8 digits] | Example: 'EMP123456' |
| GS1G | RequestGS1GLNIdentifier. GS1GLN (Global location number) identifier is requested. This is a non-significant reference number used to identify legal entities, functional entities, or physical entities according to GS1 numbering scheme rules. The number is used to retrieve detailed information that is linked to it. | Format: (0-9)(13-14 digits) | Example: 'GLN1234567890123' |
| TXID | RequestTaxIdentificationNumber. Tax Identification Number is requested. | Format: (TX)(0-9)(8-12 digits) | Example: 'TX123456789' |
| BDID | RequestBusinessDomainIdentifier. Identifier of the business domain in which the organisation is active is requested. | Format: (BUSDOM)(0-9)(5-10 digits) | Example: 'BUSDOM12345' |
| BOID | RequestBusinessOtherIdentification. Other identification of the organisation is requested. | - | - |