POST/v2/account/check/banks

API Specification

This chapter contains information on the header, request and response body required to make a successful request with the IBAN-Name Check API for EU banks. At the bottom of the page, also information about the error scenario’s 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 testcases 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

Version 2 Version VOP Compliant

Headers

X-Correlation-IdstringMandatory
A unique correlation ID should be sent for every request.
- Format: Max. 70 characters
- ^[a-zA-Z0-9-]{1,70}
Content-Typeapplication/jsonMandatory
Content type and encoding of the request.
AuthorizationBearerMandatory
Oauth 2.0 bearer token
X-End-Userstring
This field is used to identify the endpoint user, customer, department or system.
- In case the customer identifies more departments/end users within the same company which will use the API. Every department could be identified with a unique X-End-User.
- In case the customer is reselling the API as a partner. Every new customer of the partner should be identified with a unique X-End-User.
- Format: Max. 50 characters
- ^[a-zA-Z0-9-]{3,50}

Example of Request headers

Header name	Example
X-Correlation-Id	123-456-789-xxy
Content-Type	application/json;charset=utf-8
Authorization	Bearer <your bearer token>
X-End-User	Example-user-1

Request body

accountIdobjectMandatory
Object used to send the account information in the request.
valuestring
The identifier of the account to be checked. The max. allowed length depends on the type.

IBAN - [A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}

typeenum
Describes the type of the account that needs to be found. For now it can be IBAN, ACCOUNT_NUMBER, SHORTENED_ACCOUNT, EMAIL or PHONE. More information on Shortened account, Phone and Email can be found in the scenarios of the PayID section.
financialInstitutionIdobject
Object used to send additional information of responding bank financial institution. Adding the BIC of the responding bank is mandatory in order to make a VOP compliant request or when accountId.type = ACCOUNT_NUMBER.
valuestring
Financial Institution value.

BIC - [A-Z]{4}[A-Z]{2}[A-Z]{2}[A-Z]{3}

typeenum
Financial Institution type. The possible values are:

BIC: SWIFT Bank Identification Code.
namestring
Name of the account holder. Mandatory when the account type is "IBAN", "PHONE" or "EMAIL".
- Format: Max. 70 characters.

Response body

The response has a different structure depending on the API call results.

Successful response (HTTP 200 - described below)
Error response (HTTPXXX - described in Errors)

resultobjectAlways returned
resultTypeenumAlways returned
Describes the result of the account name check:

MATCH - when the provided name matches the value of the account holder name held by the source.

MISTYPE - when the provided name closely resembles the value of the account holder name held by the source.

NOT_MATCHING - when the provided name does not match the value of the account holder name held by the source.

COULD_NOT_MATCH - when the provided name could not be matched against the source data. This could have several reasons:

SurePay does not have the data of this specific bank account in order to successfully do the matching.

There is no name provided in the input, so there is no input name to match against.

NAME_TOO_SHORT- when the provided name is too short to perform a match against the value of the account holder name held by the source. For instance when the SurePay algorithm identifies that only a first name is provided.

NAME_TOO_LONG- When the provided name is too long to perform a match against the value of the account holder name held by the source.

nameSuggestionstring
The source can disclose the actual account holder name for the sender to verify or update its records. The nameSuggestion is returned when:

accountHolderType is NP, ORG or UNKNOWN and the resultType is a MISTYPE

accountHolderType is ORG and the resultType is NOT_MATCHING.

Depending on the platform that SurePay is connected with and its regional regulations, it is possible that the nameSuggestion is not always disclosed in these scenario's.
accountobjectAlways returned
Object holding the following bank account details.

Only returned if the resultType is a MATCH, MISTYPE or NOT_MATCHING.

statusenum
The status of the account.

ACTIVE - Account is a valid account and supported for checks.

INACTIVE - Account is a valid account marked as inactive by the account holding bank, by a third party or by SurePay if SurePay has reason to believe that the account should be marked as inactive.

UNKNOWN - Account status is for an account that is either found as part of DERIVED data or a NOT_VALID account.

ibanstring
Contains the IBAN of the requested account. Only passed back when using PayID.
accountHolderTypeenum
Describes the type of the account holder. The possible values are:

NP - The bank account holder is a Natural Person.

ORG - The bank account holder is an organisation.

UNKNOWN - The bank account holder is an unknown to us.

municipalitystring
The residence municipality of the account holder. Only returned when resultType is NOT_MATCHING and accountholdertype is ORG, and only by banks that choose to disclose this data.

Request

POST

v2/account/check/banks

{
    "accountId": {
        "value": "NL72SRPY0000000001",
        "type": "IBAN"
    },
    "name": "David Alex Miller"
}

Response

{
    "result": {
        "account": {
            "accountHolderType": "NP",
            "status": "ACTIVE"
        },
        "resultType": "MATCHING"
    }
}

Status and error codes

V2 of the IBAN-Name Check API for EU banks, 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
errorCodeString
The error code that represents the functional error. All the functional errors are described in the Functional Errors' section.

Error response

[
    {
        "errorCode": "INVALID_ACCOUNT_ID"
    }
]

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.
429 - Too many requests	The client has sent too many requests in a given time frame, as indicated by the rate-limiting policy. To avoid this error, reduce the frequency of your requests and try again after some time.
404 - Not Found	The server could not find the requested resource. This could be due to an incorrect URL or the resource being unavailable in the current data sources. Double-check the URL and ensure the resource exists.

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:

HTTP 400 - Bad Request

[
    {
        "errorCode": "INVALID_IBAN"
    }
]

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 supported anymore or does not follow the expected format
ID_OR_NAME_NOT_PROVIDED	The provided bank code in the requested IBAN is supported anymore or does not follow the expected format
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_ID_TYPE	The provided ‘accountId.type’ is different than those supported by SurePay: IBAN, EMAIL, PHONE, SHORTENED_ACCOUNT, SORT_CODE_ACCOUNT_NUMBER
INVALID_EMAIL	The value provided for any of the ‘accountId.type’ fields exceeds the maximum length (140 characters) or contains spaces or any unallowed special characters
INVALID_SHORTENED_ACCOUNT	The value provided for any of the ‘accountId.type’ fields exceeds the maximum length (140 characters) or contains spaces or any unallowed special characters
INVALID_SORT_CODE	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 404 - Not found

If the client's submitted request cannot be found, the service will return an Error Response object with the details of the issue. The possible ‘errorCodes’ are gathered in the following table:

HTTP 404 - Not found

[
    {
        "errorCode": "PAYID_UNKNOWN"
    }
]

Functional error	Description
PAYID_UNKNOWN	The requested PayID cannot be found
IBAN_UNKNOWN	The requested IBAN cannot be found
SHORTENED_ACCOUNT_NUMBER_NOT_FOUND	The requested shortened account number cannot be found
IBAN_IGNORED_FOR_MATCHING	The requested IBAN was not considered for matching because it was identified in SurePay’s derived dataset.