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

EnvironmentEndpoint URL
SandboxProvided via MSafe after being requested
ProductionProvided via MSafe after being requested
Version 2Version 3 (Sept 2024)

Go directly to

Headers

  • Name
    X-Correlation-Id
    Type
    string
    Tag(s)
    Mandatory
    Description
  • Name
    Content-Type
    Type
    application/json
    Tag(s)
    Mandatory
    Description
  • Name
    Authorization
    Type
    Bearer
    Tag(s)
    Mandatory
    Description
  • Name
    X-End-User
    Type
    string
    Tag(s)
    Description

Example of Request headers

Header nameExample
X-Correlation-Id123-456-789-xxy
Content-Typeapplication/json;charset=utf-8
AuthorizationBearer <your bearer token>
X-End-UserExample-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}
    • Name
      type
      Type
      enum
      Tag(s)
      Description

      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.

  • Name
    financialInstitutionId
    Type
    object
    Tag(s)
    Description

    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.

    • Name
      value
      Type
      string
      Tag(s)
      Description

      Financial Institution value.

      • BIC - [A-Z]{4}[A-Z]{2}[A-Z]{2}[A-Z]{3}
    • Name
      type
      Type
      enum
      Tag(s)
      Description

      Financial Institution type. The possible values are:

      • BIC: SWIFT Bank Identification Code.
  • 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:

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

    • 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
        accountHolderType
        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.
      • Name
        municipality
        Type
        string
        Tag(s)
        Description

        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

  • 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 CodeDescription
400 - Bad requestThe 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 - UnauthorisedThe 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 - ForbiddenThe 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 errorThe 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 requestsThe 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 FoundThe 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.

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 errorDescription
INVALID_IBANThe IBAN provided ‘accountId.value’ exceeds the maximum length (140 characters) or contains spaces or any of the following special characters !"#$%&'
INVALID_BANKCODEThe provided bank code in the requested IBAN is not supported anymore or does not follow the expected format
ID_OR_NAME_NOT_PROVIDEDThe provided bank code in the requested IBAN is supported anymore or does not follow the expected format
INVALID_CORRELATION_IDA 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_TYPEThe provided ‘accountId.type’ is different than those supported by SurePay: IBAN, EMAIL, PHONE, SHORTENED_ACCOUNT, SORT_CODE_ACCOUNT_NUMBER
INVALID_EMAILThe 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_ACCOUNTThe 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_CODEThe 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_NUMBERThe 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 errorDescription
PAYID_UNKNOWNThe requested PayID cannot be found
IBAN_UNKNOWNThe requested IBAN cannot be found
SHORTENED_ACCOUNT_NUMBER_NOT_FOUNDThe requested shortened account number cannot be found
IBAN_IGNORED_FOR_MATCHINGIBAN_IGNORED_FOR_MATCHING

HTTP 404 - Not found

[
    {
        "errorCode": "PAYID_UNKNOWN"
    }
]
Previous
Next