Online Data Provisioning API specifications
This page describes the technical specification of realtime account data provisioning to SurePay. Based on this specification, the provider of the data should be able to expose a Restful API over HTTP and allow the SurePay solution to access it with required security and performance levels. We suggest creating a POST instead of a GET endpoint so that we won't have to pass sensitive information (the IBAN) in the URL
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 IBAN Name check, but could improve the matching quality of the algorithm.
- In a response, we always expect the mandatory information of the bank account requested.
- For Natural Person owned accounts, we expect an object per account holder, as some accounts might have multiple account holders.
- For Organisation owned accounts, we expect only one object.
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
X-Correlation-IdStringMandatoryContent-Typeapplication/jsonMandatoryAuthorizationBearerMandatory
Example of Request headers
| Header name | Example |
|---|---|
| X-Correlation-Id | 123-456-789-xxy |
| Content-Type | application/json;charset=utf-8 |
| Authorization | Bearer <a bearer token> |
Request body
accountIdObjectMandatorybicString
Request
{
"accountId": {
"type": "IBAN",
"value": "NL11SRPY1234567890"
}
}
Response body
In case of a successful response, the following parameters are expected to be returned. Most of the data fields are optional, however, the more data you provide, the better our matching algorithm works! In case of an unsuccessful response a meaningful HTTP code and error message is expected, please read the errors chapter.
Suggested response fields
accountNameStringMandatorystatusEnumMandatorystartDateDateOptional (Only used when using FRI)bankAccountTypeEnumOptional (Only used when using FRI)personalAccountHoldersArray of ObjectsorganisationAccountHolderObject
Response
{
"accountName": "J.R. van der Werff",
"status": "ACTIVE",
"personalAccountHolders": [
{
"initials": "J.R.",
"allFirstNames": "John Richard",
"surname": "de Jong - van der Werff",
"birthName": "van der Werff"
}
]
}
Status and error codes
We advise the use of industry standard HTTP response codes to provide feedback on the success or failure of an API request. Responses in the 2xx range are indicative of successful transactions, while responses in the 4xx range signify an error related to the provided data, such as a missing parameter or failed charge. In rare cases, responses in the 5xx range indicate an issue with your servers.
Error response body
0Array of Objects
Example - 400 bad request
[
{
"errorCode": "INVALID_IBAN"
}
]
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_ACCOUNT_ID"
}
]
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 |
|---|---|
| INVALID_IBAN | The IBAN provided ‘accountId.value’ exceeds the maximum length (140 characters) or contains spaces or any of the following special characters !"#$%&' |
| INVALID_BANKCODE | The provided bank code in the requested IBAN is not a bank code you are supporting |
| INVALID_CORRELATION_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_ACCOUNT_NUMBER | The value provided for any of the ‘accountId.type’ fields exceeds the maximum length (140 characters) or contains spaces or any unallowed special characters |
HTTP 400 - Bad Request
[
{
"errorCode": "INVALID_IBAN",
}
]