API Specification
This API specification contains information on the header, request body and response body required to make a successful request with the IBAN-Name Check API for Organisations. At the bottom, alsyou'll find relevant information about the error scenarios are described.
Click one of the buttons below to download the .YAML with the technical description and model of the API, the postman collection or a set of test cases which can be used on the sandbox environment.
Endpoints
| Environment | Endpoint URL |
|---|---|
| Sandbox | Provided via MSafe after being requested |
| Production | Provided via MSafe after being requested |
Headers
X-Correlation-IdstringrequiredContent-Typeapplication/jsonAuthorizationBearerrequiredX-End-UserstringX-Software-Supplierstring
Example of Request headers
| Header name | Example |
|---|---|
| X-Correlation-Id | 123-456-789-xxy |
| Content-Type | application/json;charset=utf-8 |
| X-End-User | Example-user-1 |
| Authorization | Bearer <your bearer token> |
| X-Software-Supplier | softwareSupplier1 |
Request body
accountIdobjectrequirednamestringcompanyIdsobjectaccountTypeenumbicstringsecondaryReferenceIdstringbirthDatestringNot supported
Response body
nameMatchResultenumAlways returneddataUsedForMatchingenumnameSuggestionstringcompanyIdsobjectaccountobjectAlways returnedschemeenumAlways returnedschemeDataenum
Request
{
"accountId": {
"value": "NL72SRPY0000000001",
"type": "IBAN"
},
"name": "David Alex Miller"
}
Response
{
"nameMatchResult": "MATCH",
"dataUsedForMatching": "VERIFIED",
"account": {
"accountNumberValidation": "VALID",
"paymentPreValidation": "PASS",
"status": "ACTIVE",
"accountType": "NP",
"jointAccount": false,
"numberOfAccountHolders": 1,
"countryCode": "NL"
},
"scheme": "SurePay"
}
Status and error codes
The IBAN-Name Check API for Organisations, offered by SurePay, follows the industry standard of using 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 SurePay's servers.
Error response body
errorsArray of objects
Example - Array of error messages
[
{
"errorCode": "INVALID_CORRELATION_ID",
"message": "Invalid correlation ID in the request headers"
}
]
Technical Errors
Technical Errors
| HTTP Status Code | Description |
|---|---|
| 400 - Bad request | The server could not understand the request due to invalid syntax. This may occur if the request contains malformed JSON, missing required parameters, or incorrect URL parameters. Please review your request format and try again. |
| 401 - Unauthorised | The request lacks valid authentication credentials. This may happen if the authorization header is missing or contains an invalid token. Ensure you are providing a valid token in the request header. |
| 403 - Forbidden | The server understood the request but refuses to authorize it. This can occur if the provided token has insufficient permissions or violates a security policy. Verify that your token has the correct scope and necessary permissions. |
| 500 - Internal server error | The server encountered an unexpected condition that prevented it from fulfilling the request. This may be due to an issue with the API gateway or an internal service. The response body might contain additional details based on the connected schema. Please try again later. |
| 502 - Bad Gateway | The server, while acting as a gateway or proxy, received an invalid response from the upstream server. This can indicate issues with the server the API is trying to communicate with. Please try again later. |
| 503 - Service Unavailable | The server is currently unable to handle the request due to temporary overloading or maintenance of the server. This is usually a temporary state. Please try again after some time. |
Error response
[
{
"errorCode": "INVALID_ACCOUNT_ID",
"message": "The provided IBAN contains spaces or special characters"
}
]
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:
| Functional error | Description |
|---|---|
| INVALID_ACCOUNT_ID | The value provided ‘accountId.value’ exceeds the maximum length (140 characters) or contains spaces or any of the following special characters !"#$%&' |
| INVALID_REQUEST | The provided JSON in the request has to follow the expected format. See the format expected in the ‘Request Body’ section. |
| NAME_NOT_PROVIDED | The request is missing a value in the ‘name’ request field. |
| INVALID_CORRELATION_ID | A correlation ID is invalid if: it does not match the regular expression, its length is shorter than 1, its length is longer than 70 characters |
| INVALID_ID_TYPE | The provided ‘accountId.type’ is different than those supported by SurePay: IBAN, SortCodeAccountNumber, NL_KVK, NL_KVK_BRANCH, EU_VAT, FR_SIREN, FR_SIRET and UK_CRN. |
| INVALID_COMPANY_ID | The value provided for any of the ‘companyId.type’ fields exceeds the maximum length (140 characters) or contains spaces or any of the following special characters !"#$%&'*+,-./:; |
| INVALID_ACCOUNT_TYPE | The provided input is different from ‘ORG’ or ‘NP’ and cannot be handled by the system. |
| NAME_TOO_LONG | When the value in the ‘name’ request field exceeds the maximum length (140 characters). |
| INVALID_SOFTWARE_SUPPLIER | The provided software supplier does not match the regular expression. |
HTTP 400 - Bad Request
[
{
"errorCode": "INVALID_ACCOUNT_ID",
"message": "The provided IBAN contains spaces or special characters"
}
]