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 Banks (VOP Compliant). 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
1.1	27 Jan 2025	Changed format of the 'bicfi' fields
1.2	05 Feb 2025	Changed naming convention to 'IBAN-Name Check API for Banks (VOP Compliant)' and changed the endpoint to 'v2/account/check/vop'.
1.3	10 Feb 2025	Changed validation format to the request fields: 'accountId.type.iban'
1.4	20 Mar 2025	Changed partyAgent and requestingAgent to be conditional for backwards compatibility. Removed X-Request-Id header. Changed the endpoint back to 'v2/account/check/banks'. Updated examples
1.5	15 Apr 2025	Added HTTP 400 validation errors 'INVALID_REQUESTING_AGENT_BIC' and 'INVALID_PARTY_AGENT_BIC'. Changed layout of the section 'Functional Errors' and description for 'IBAN_IGNORED_FOR_MATCHING'
1.6	16 Jun 2025	Updated `resultType` "MATCH" to "MATCHING".

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 VOP Compliant

Headers

X-Correlation-IdstringMandatory
A unique correlation ID should be sent for every request.
- Format: max.length 70
- Format: ^[a-zA-Z0-9-]{1,70}
Content-Typeapplication/jsonMandatory
Content type and encoding of the request.
AuthorizationBearerMandatory
Oauth 2.0 bearer token.
X-End-UserstringOptional
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
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.
valueStringMandatory
The identifier of the account to be checked. The max allowed length depends on the type.

IBAN - ^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$ (For IBAN, just capital letters are accepted, without white spaces).

typeEnumMandatory
The possible values are:

IBAN - IBAN is mandatory for VOP.

EMAIL

PHONE

SHORTENED_ACCOUNT

ACCOUNT_NUMBER

SORT_CODE_ACCOUNT_NUMBER
nameStringConditional
Name of the account holder. Mandatory when the account type is "IBAN", "PHONE" or "EMAIL".
unstructuredRemittanceInformationArray of Strings
Additional information about the account number sent by the Requester.
- Example: 'Customer reference: CUST123456'
partyAgentObjectConditional
Identification of the Responding PSP.
- Usage Rule: Mandatory when Requesting PSP does not utilise the SurePay BIC Enrichment service or request must be routed through the VOP scheme.
financialInstitutionIdObjectMandatory
Financial Institution object.
bicfiStringMandatory
Identification of the Responding PSP (Swift BIC). BIC of the Agent.

Format: ^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$

Example:

8 characters: 'DEUTDEFF'

11 characters: 'DEUTDEFF500'
requestingAgentObjectConditional
Identification of the Requesting PSP. Not providing the requestingAgent can lead to this request not being VoP routable.
- Usage Rule: Mandatory when request must be routed through the VOP scheme.
financialInstitutionIdObjectMandatory
Financial Institution object.
bicfiStringMandatory
Identification of the Responding PSP (Swift BIC). BIC of the Agent.

Format: ^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{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

X-Correlation-IdstringMandatory
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-Correlation-Id	123-456-789-xxy

resultObject
resultTypeEnumMandatory
Describes the result of the account name check:

MATCHING - 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.

nameSuggestionStringMandatory
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.

accountobjectConditional
Object holding the following bank account details.

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

statusenumConditional
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.

ibanstringConditional
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.
accountHolderTypeenumConditional
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 "MATCHING", "MISTYPE"or "NOT_MATCHING".

municipalitystringConditional
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.
fraudRiskIndicatorStringAdd-on feature
This is an add-on feature, available upon request.
switchingInformationStringAdd-on feature
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 API for Banks (VOP Compliant) 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

0Array of objects
errorCodeString
The error code that represents the functional error. All the functional errors are described in the Functional Errors table.

Error response

[
    {
        "errorCode": "INVALID_ACCOUNT_ID"
    }
]

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

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_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
INVALID_PARTY_AGENT_BIC	The BIC provided in `partyAgent` is invalid if it does not match the regular expression.
INVALID_REQUESTING_AGENT_BIC	The BIC provided in `requestingAgent` is invalid if it does not match the regular expression.

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.