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

Headers

Name
X-Correlation-Id
Type
string
Tag(s)
Mandatory
Description
A unique correlation ID should be sent for every request.
- Format: Max. 70 characters
- ^[a-zA-Z0-9\-]{1,70}
Name
Content-Type
Type
application/json
Tag(s)
Mandatory
Description
Content type and encoding of the request.
Name
Authorization
Type
Bearer
Tag(s)
Mandatory
Description
Oauth 2.0 bearer token
Name
X-End-User
Type
string
Tag(s)
Description
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

Name
accountId
Type
object
Tag(s)
Mandatory
Description
Object used to send the account information in the request.
- Name
  value
  Type
  string
  Tag(s)
  Description
  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}
  
  (For IBAN, just capital letters are accepted, without white spaces).
- Name
  type
  Type
  enum
  Tag(s)
  Description
  Describes the type of the account that needs to be found. For now it can be IBAN, SHORTENED_ACCOUNT, EMAIL or PHONE. Only checks with IBAN, Shortened account, Phone and Email are functionally available for the EU market. More information on Shortened account, Phone and Email can be found in the scenarios of the PayID section.
Name
name
Type
string
Tag(s)
Description
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)

Name
result
Type
object
Tag(s)
Always returned
Description
- Name
  resultType
  Type
  enum
  Tag(s)
  Always returned
  Description
  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.
- Name
  nameSuggestion
  Type
  string
  Tag(s)
  Description
  The source can disclose the actual account holder name for the sender to verify or update its records. The nameSuggestion is returned when:
  
  accountType is NP, ORG or UNKNOWN and the resultType is a MISTYPE
  
  accountType 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.
- Name
  account
  Type
  object
  Tag(s)
  Always returned
  Description
  Object holding the following bank account details.
  
  Only returned if the resultType is a MATCH, MISTYPE or NOT_MATCHING.
  
  Name
  status
  Type
  enum
  Tag(s)
  Description
  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.
  
  Name
  iban
  Type
  string
  Tag(s)
  Description
  Contains the IBAN of the requested account. Only passed back when using PayID.
  Name
  accountType
  Type
  enum
  Tag(s)
  Description
  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.
  
  If the accountType is provided in the request then the response doesn’t disclose the accountType. It only returns the accountTypeMatchResult.
  Name
  municipality
  Type
  string
  Tag(s)
  Description
  The residence municipality of the account holder. Only returned when resultType is NOT_MATCHING and accounHholdertype 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

Name
Type
Array of objects
Tag(s)
Description
Name
errorCode
Type
String
Tag(s)
Description
The error code that represents the functional error. All the functional errors are described in the Functional Errors' section.

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
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
429 - Too many requests	IResponse status code indicates the user has sent too many requests in a given amount of time
404 - Not Found	We were unable to find the requested resource in any of our available data sources

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:

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
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"
    }
]

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:

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	IBAN_IGNORED_FOR_MATCHING

HTTP 404 - Not found

[
    {
        "errorCode": "PAYID_UNKNOWN"
    }
]