POST/account/check/organisations

API Specification

This API specification contains information on the header, request body and response body required to make a successful request with the IBAN-Name Check API for Organisations. At the bottom, alsyou'll find relevant information about the error scenarios 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 test cases which can be used on the sandbox environment.

Endpoints

EnvironmentEndpoint URL
SandboxProvided via MSafe after being requested
ProductionProvided via MSafe after being requested

Headers

  • Name
    X-Correlation-Id
    Type
    string
    Tag(s)
    required
    Description

    A unique correlation ID should be sent for every request. Example: 'request1', '123455-dd'.

    • Format: Max. 70 characters
      • ^[a-zA-Z0-9\-]{1,70}
  • Name
    Content-Type
    Type
    application/json
    Tag(s)
    Description

    Content type and encoding of the request.

  • Name
    Authorization
    Type
    Bearer
    Tag(s)
    required
    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}
  • Name
    X-Software-Supplier
    Type
    string
    Tag(s)
    Description

    It is used in case there is an external software supplier involved. This header must be provided if you are using a third party software supplier. In case the SurePay customer uses more than one software supplier then all of them can be provided in the header.

    Example: X-Software-Supplier = "supplierA" / "supplierB" / "supplierC"

Example of Request headers

Header nameExample
X-Correlation-Id123-456-789-xxy
Content-Typeapplication/json;charset=utf-8
X-End-UserExample-user-1
AuthorizationBearer <your bearer token>
X-Software-SuppliersoftwareSupplier1

Request body

  • Name
    accountId
    Type
    object
    Tag(s)
    required
    Description
  • Name
    name
    Type
    string
    Tag(s)
    Description

    Name of the account holder. Mandatory In case of an IBAN-Name Check. Optional when one type of company identifier is added in the request.

    • Format: Max. 140 characters. We support special characters and all letters of the extended latin alphabets.
  • Name
    companyIds
    Type
    object
    Tag(s)
    Description

    The companyIds object can contain multiple sets of companyId value & companyId type.

    • Name
      companyIdValue
      Type
      string
      Tag(s)
      Description

      The input validations are:

      • NL_KVK - [0-9]{8}
      • NL_KVK_BRANCH - [0-9]{12}
      • FR_SIREN - [0-9]{9}
      • FR_SIRET - [0-9]{14}
      • UK_CRN - [SC,OC,SO,NI,R,NC,RC,LP, SL, NL]{2,1}[0-9]{6,7} or [0-9]{8}
      • EU_VAT - Multiple formats. Always starting with the country code. A complete list with all the validations is available on request.
    • Name
      companyIdType
      Type
      enum
      Tag(s)
      Description

      Describes the type of Company Identifier to be verified. Possible values are: NL_KVK, NL_KVK_BRANCH, FR_SIREN, EU_VAT, FR_SIRET or UK_CRN.

  • Name
    accountType
    Type
    enum
    Tag(s)
    Description

    This field allows the user to input the account’s type to be checked as part of the request.

    Possible values are:

    • NP
    • ORG
  • Name
    bic
    Type
    string
    Tag(s)
    Description

    Describes the BIC for SWIFT use. This field is mandatory for ACCOUNT_NUMBER accountId.type.

    • Format: [A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}
  • Name
    secondaryReferenceId
    Type
    string
    Tag(s)
    Description

    Secondary Reference Data is information in addition to the SCAN that is entered by the Payer and used by the CoP Responder to enable them to identify the underlying Account Name in their books, within a Collection Account structure. In order to be accepted, the SRD has to be sent in combination with a SORT_CODE_ACCOUNT_NUMBER.

    • Format: {1,140}.
  • Name
    birthDate
    Type
    string
    Tag(s)
    Not supported
    Description

Response body

  • Name
    nameMatchResult
    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.
    • CLOSE_MATCH - when the provided name closely resembles the value of the account holder name held by the source.
    • NO_MATCH - 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.
  • Name
    dataUsedForMatching
    Type
    enum
    Tag(s)
    Description

    Describes the data used to reach the match result:

    • VERIFIED : Verified is the data that exists at the beneficiary bank.
    • DERIVED: Derived is data based on historical transactions.
  • 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 nameMatchResult is a CLOSE_MATCH
    • accountType is ORG and the nameMatchResult is NO_MATCH.

    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
    companyIds
    Type
    object
    Tag(s)
    Description

    Object holding the following bank account details.

    • Name
      type
      Type
      string
      Tag(s)
      Description

      Describes the company Id type provided in the request:

      • NL_KVK
      • NL_KVK_BRANCH
      • FR_SIREN
      • FR_SIRET
      • UK_CRN
      • EU_VAT
    • Name
      matchResult
      Type
      enum
      Tag(s)
      Description

      Describes the result of the company Id check.

      • MATCH - Returned when the provided id value matches the value of the company held by the source.
      • NO_MATCH - Returned when the provided id value does not match the value of the company held by the source.
      • COULD_NOT_MATCH - Returned when the provided id value could not be matched against the source data.
    • Name
      knownAtBankId
      Type
      enum
      Tag(s)
      Description

      A suggestion of the unique identifier associated with an entity that has been formally acknowledged and verified at its source (the bank).

      • Returned in case of type = “NL_KVK” and "matchResult" = “NO_MATCH”.
  • Name
    account
    Type
    object
    Tag(s)
    Always returned
    Description

    Object holding the following bank account details.

    • Name
      accountNumberValidation
      Type
      enum
      Tag(s)
      Description

      The account validity as determined by SurePay. The possible values are:

      • VALID - An account that conforms to the standards, e.g. a valid Mod97 calculation for an IBAN.
      • NOT_VALID - account is an account that does not conform to the standards.
    • Name
      paymentPreValidation
      Type
      enum
      Tag(s)
      Description

      Returns the pre-validation status of the payment. Only applicable for SurePay Scheme.

      • PASS - is returned when the account identification was successfully validated to an account that can receive funds.
      • WILL_FAIL - is returned if the payment will definitely fail.
      • WARNING - is returned in case the account identification was not successfully validated to an account that can receive funds, however, the responding bank is unable to provide a definitive answer.
    • Name
      optedOut
      Type
      boolean
      Tag(s)
      Description

      Informs whether an account has opted out of the CoP service. Only returned when optedOut is true.

    • 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.
      • NOT_SUPPORTED - Account status stands for an account that is valid but is not supported to perform any checks.
      • NOT_FOUND - Account status stands for an account that is valid but could not be found in any of the connected data sources.
      • 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
      accountTypeMatchResult
      Type
      enum
      Tag(s)
      Description

      Describes the result of the account type check.

      • MATCH - when the provided account type matches the value of the account holder name held by the source.
      • NO_MATCH - when the provided account type does not match the value of the account holder account type held by the source.
      • COULD_NOT_MATCH - when the provided account type could not be matched against the source data.

      Only returned:
      WHEN the accountType is provided in the request
      AND the nameMatchResult and/or a companyIds.matchResult equals MATCH, CLOSE_MATCH or NO_MATCH.

    • Name
      city
      Type
      string
      Tag(s)
      Description

      The residence city of the account holder. Only return in case of NO_MATCH and the value for'accountType' is ORG.

    • Name
      jointAccount
      Type
      boolean
      Tag(s)
      Description

      Indicates whether there is more than one account holder associated with the checked account.

      true if there is more than 1 account holder. Otherwise, it’s retrieved as false.

      • Only returned in NL and when nameMatchResult is a MATCH or CLOSE_MATCH
    • Name
      numberOfAccountHolders
      Type
      int
      Tag(s)
      Description

      Contains the number of account holders.

      • Only returned in NL and when nameMatchResult is a MATCH or CLOSE_MATCH
    • Name
      countryCode
      Type
      string
      Tag(s)
      Description

      Two letter country code from the IBAN or derived based on accountId type. In ISO 3166-1 alpha-2 format.

      • This field is only returned if the nameMatchResult and/or a companyIds.matchResult equals MATCH, CLOSE_MATCH or NO_MATCH.
  • Name
    scheme
    Type
    enum
    Tag(s)
    Always returned
    Description

    The supported platforms used for the IBAN-Name Check: SWIFT, COP_UK, SEPAMAIL, SurePay.

  • Name
    schemeData
    Type
    enum
    Tag(s)
    Description

    Contains the response information that SurePay receives based on the used scheme.

Request

POST
/account/check/organisations
{
    "accountId": {
        "value": "NL72SRPY0000000001",
        "type": "IBAN"
    },
    "name": "David Alex Miller"
}

Response

{
    "nameMatchResult": "MATCH",
    "dataUsedForMatching": "VERIFIED",
    "account": {
        "accountNumberValidation": "VALID",
        "paymentPreValidation": "PASS",
        "status": "ACTIVE",
        "accountType": "NP",
        "jointAccount": false,
        "numberOfAccountHolders": 1,
        "countryCode": "NL"
    },
    "scheme": "SurePay"
}

Status and error codes

The IBAN-Name Check API for Organisations, 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.

  • Name
    message
    Type
    String
    Tag(s)
    Description

    The description of the error occurred.

Example - Array of error messages

[
    {
        "errorCode": "INVALID_CORRELATION_ID",
        "message": "Invalid correlation ID in the request headers"
    }
]

Technical Errors

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.
502 - Bad GatewayThe server, while acting as a gateway or proxy, received an invalid response from the upstream server. This can indicate issues with the server the API is trying to communicate with. Please try again later.
503 - Service UnavailableThe server is currently unable to handle the request due to temporary overloading or maintenance of the server. This is usually a temporary state. Please try again after some time.

Error response

[
    {
        "errorCode": "INVALID_ACCOUNT_ID",
        "message": "The provided IBAN contains spaces or special characters"
    }
]

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_ACCOUNT_IDThe value provided ‘accountId.value’ exceeds the maximum length (140 characters) or contains spaces or any of the following special characters !"#$%&'
INVALID_REQUESTThe provided JSON in the request has to follow the expected format. See the format expected in the ‘Request Body’ section.
NAME_NOT_PROVIDEDThe request is missing a value in the ‘name’ request field.
INVALID_CORRELATION_IDA correlation ID is invalid if: it does not match the regular expression, its length is shorter than 1, its length is longer than 70 characters
INVALID_ID_TYPEThe provided ‘accountId.type’ is different than those supported by SurePay: IBAN, SortCodeAccountNumber, NL_KVK, NL_KVK_BRANCH, EU_VAT, FR_SIREN, FR_SIRET and UK_CRN.
INVALID_COMPANY_IDThe value provided for any of the ‘companyId.type’ fields exceeds the maximum length (140 characters) or contains spaces or any of the following special characters !"#$%&'*+,-./:;
INVALID_ACCOUNT_TYPEThe provided input is different from ‘ORG’ or ‘NP’ and cannot be handled by the system.
NAME_TOO_LONGWhen the value in the ‘name’ request field exceeds the maximum length (140 characters).
INVALID_SOFTWARE_SUPPLIERThe provided software supplier does not match the regular expression.

HTTP 400 - Bad Request

[
    {
        "errorCode": "INVALID_ACCOUNT_ID",
        "message": "The provided IBAN contains spaces or special characters"
    }
]

More like this

Quick Setup - IBAN-Name Check API for Organisations
Quick configuration guide to set up IBAN-Name Check API for Organisations quickly.
API Specification - VOP Requester API for Banks in EU
API documentation which defines the content and functionalities of the Account Check for Banks.
Use Cases - IBAN-Name Check API for Organisations
Use cases of the IBAN-Name Check API for Organisations
Previous
Next