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.

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 Body

    { 
        "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 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.

{
    "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.

Error Response

Error Response Body

    {
        "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.

List of Enumeration values

companyId

The following table contains a list of enumeration values: