POSTv2/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 v2.2.0 for Banks. At the bottom of the page, also information about the error scenario’s are described.

Document History

Version	Date	Description
1.0	15 Jan 2025	Original Digital Version. Aligned with PDF V2.3

Endpoints

Environment	Endpoint URL
Sandbox	Provided via MSafe after being request to service@surepay.nl
Production	Provided via MSafe after being request to service@surepay.nl

Version 2 Version 2.2.0 (NEW)

Headers

Name
X-Correlation-Id
Type
string
Tag(s)
Mandatory
Description
A unique correlation ID should be sent for every request. -Format: max.length 70 ^[a-zA-Z0-9-]70
Name
X-Request-Id
Type
application/json
Tag(s)
Mandatory
Description
A RFC4122 UUID used as a correlation id.
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)
Optional
Description
This field is used to identify the endpoint user, customer, department or system. It has to be defined by the user.
- 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
X-Request-Id	123e4567-e89b-12d3-a456-42661417400
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)
  Mandatory
  Description
  The identifier of the account to be checked. The max allowed length depends on the type.
  
  IBAN - [A-Z]2[0-9]2[a-zA-Z0-9]30 (For IBAN, just capital letters are accepted, without white spaces).
- Name
  type
  Type
  Enum
  Tag(s)
  Mandatory
  Description
  The possible values are:
  
  IBAN - IBAN is mandatory for VOP.
  
  EMAIL
  
  PHONE
  
  SHORTENED_ACCOUNT
  
  ACCOUNT_NUMBER
  
  SORT_CODE_ACCOUNT_NUMBER
Name
name
Type
String
Tag(s)
Conditional
Description
Name of the account holder. Mandatory when the account type is “IBAN”, “PHONE” or “EMAIL”.
Name
unstructuredRemittanceInformation
Type
String
Tag(s)
Description
Additional information about the account number sent by the Requester.
- Example: ‘Customer reference: CUST123456’
Name
partyAgent
Type
Object
Tag(s)
Mandatory
Description
Identification of the Responding PSP.
- Name
  financialInstitutionId
  Type
  Object
  Tag(s)
  Mandatory
  Description
  Financial Institution object.
  Name
  bicfi
  Type
  String
  Tag(s)
  Mandatory
  Description
  Identification of the Responding PSP (Swift BIC). BIC of the Agent.
  
  Format: [A-Z]{4}[A-Z]{2}[1-9][A-Z]{2}[1-9][A-Z]{3}
  
  Example:
  
  8 characters: ‘DEUTDEFF’
  
  11 characters: ‘DEUTDEFF500’
Name
requestingAgent
Type
Object
Tag(s)
Mandatory
Description
Identification of the Requesting PSP.
- Name
  financialInstitutionId
  Type
  Object
  Tag(s)
  Mandatory
  Description
  Financial Institution object.
  Name
  bicfi
  Type
  String
  Tag(s)
  Mandatory
  Description
  Identification of the Responding PSP (Swift BIC). BIC of the Agent.
  
  Format: [A-Z]{4}[A-Z]{2}[1-9][A-Z]{2}[1-9][A-Z]{3}
  
  Example:
  
  8 characters: ‘DEUTDEFF’
  
  11 characters: ‘DEUTDEFF500’

Request

POST

v2/account/check/banks

{
    "accountId": {
        "value": "NL91SRPY1234565432",
        "type": "IBAN"
    },
    "name": "H Groenen"
    },
        "partyAgent": {
        "financialInstitutionId": {
            "bicfi": "ABCDBEBBXXX "
        }
        },
        "requestingAgent": {
        "financialInstitutionId": {
            "bicfi": "ABCDBEB0XXX"
        }
        }
    }
    }

Response

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

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)

Headers

Name
X-Request-Id
Type
String
Tag(s)
Mandatory
Description
The Requesting PSP’s reference number of the VOP Request. Value sent in the request, mapped directly to the response (not generated again).
Name
X-Correlation-Id
Type
string
Tag(s)
Mandatory
Description
A unique correlation ID should be sent for every request. Value sent in the request, mapped directly to the response (not generated again).

Example of Request headers

Header name	Example
X-Request-Id	123e4567-e89b-12d3-a456-42661417400
X-Correlation-Id	123-456-789-xxy

Name
result
Type
Object
Tag(s)
Description
- Name
  resultType
  Type
  Enum
  Tag(s)
  Mandatory
  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. For instance when the responding bank does not live within the VOP scheme. Equivalent to the NOAP response in the EPC API specifications.
  
  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)
  Mandatory
  Description
  Contains the corrected name of the Payer if one of the following two scenarios is true:
  
  resultType is a “MISTYPE” and accounHholdertype is “ORG” or “NP”
  
  resultType is a “NOT_MATCHING” and accounHoldertype is “ORG”,
  Then, the source can choose to disclose the actual account holder name for the payer to verify or update its input. Depending on the platform that SurePay is connected with and its regional regulations, it is possible that the nameSuggestion is not disclosed.
- Name
  account
  Type
  object
  Tag(s)
  Conditional
  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)
  Conditional
  Description
  The status of the account.
  
  ACTIVE: a valid account and supported for checks.
  
  INACTIVE: a valid account marked by the account holding PSP as inactive.
  
  UNKNOWN: for an account that its status has been not known/provided by the PSP.
  
  NOT_FOUND: the account number was not found in the responding PSP’s records/books.
  
  Name
  iban
  Type
  string
  Tag(s)
  Conditional
  Description
  Contains the IBAN of the requested account. Only relevant when the request accountId.type is “Phone”, “Email” or “ShortenedAccount”. Contact SurePay for more information on these scenarios.
  Name
  accountHolderType
  Type
  enum
  Tag(s)
  Conditional
  Description
  Describes the type of the account holder. The possible values are:
  
  NP - The PSP account holder is a Natural Person.
  
  ORG - The PSP account holder is an organisation.
  
  UNKNOWN - The PSP account holder is an unknown to us. Only returned when resultType is a “MATCH”, “MISTYPE”or “NOT_MATCHING”.
  
  Name
  municipality
  Type
  string
  Tag(s)
  Conditional
  Description
  The residence municipality of the account holder. Only returned when resultType is “NOT_MATCHING” and 'accounHolderType' is “ORG”, and only by PSPs that choose to disclose this data.
Name
fraudRiskIndicator
Type
String
Tag(s)
Premium feature
Description
This is an add-on feature, available upon request.
Name
switchingInformation
Type
String
Tag(s)
Premium feature
Description
This is an add-on feature, available upon request.

Request

POST

v2/account/check/banks

{
    "accountId": {
        "value": "NL91SRPY1234565432",
        "type": "IBAN"
    },
    "name": "H Groenen"
    },
        "partyAgent": {
        "financialInstitutionId": {
            "bicfi": "ABCDBEBBXXX "
        }
        },
        "requestingAgent": {
        "financialInstitutionId": {
            "bicfi": "ABCDBEB0XXX"
        }
        }
    }
    }

Response

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

Status and error codes

The IBAN-Name Check v2.2.0 API for 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 table.

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
405 - Method not Allowed	The Requester tried to access the resource with a method that is not supported
406 - Not Accepted	The request contained an accept header that requested a content-type other than application/JSON and a character set other than UTF-8
429 - Too many requests	Too many requests towards the endpoint within a given amount of time. In this case the response contains a Retry-After header indicating how long the consumer must wait before retrying the operation
500 - Internal server error	Something went wrong on the API or service. In this case the body might contain extra details
503 - Service Unavailable	The service is down for maintenance. The response should include a Retry-After header indicating how long the Requester must wait before retrying the operation
504 - Timeout	There was no timely response from an upstream server that was needed to complete the request

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_NAME	The Name provided exceeds the maximum length (140 characters) 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_REQUEST_ID	A Request ID is invalid if it does not match the regular expression
INVALID_ID_TYPE	The provided ‘accountId.type’ is different than those supported by SurePay: IBAN, EMAIL, PHONE, SHORTENED_ACCOUNT, SORT_CODE_ACCOUNT_NUMBER
IBAN_AND_NAME_NOT_PROVIDED	Either IBAN or Name were not provided in the request
IBAN_AND_SHORTENED_ACCOUNT_NUMBER_NOT_PROVIDED	Either IBAN or Shortened account number were not provided in the request
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_PHONE	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",
    }
]