External account verification

Learn how to use Numeral's account verification feature

External account verification enables companies to verify external accounts prior to sending or collecting payments.

Account verification object

AttributeDescription
result
string
Account verification result. It can be:
  • pending_verification: verification is pending
  • valid: results are available and all verifications are valid
  • invalid: results are available but at least one verification is invalid
  • valid_account_number
    object
    Account number verification result, including a result string and a details object.
    matching_account_number
    _and_bank_code

    object
    Bank code verification result, including a result string and a details object.
    matching_account_holder
    object
    Account holder verification result.
  • For counterparty_account of type legal_entity, it includes the company_registration_numberverification result.
  • For counterparty_account of type individual, it includes the account_holder_name verification.
  • It always includes a result string and a details object.
    active_account
    object
    Account activity verification result, including a result string and a details object.
    created_at
    object
    The UTC timestamp of the account verification.

    Below is an example of an account_verification object for a counterparty account with all verifications valid:

    {
      "account_verification": {
        "result":"valid",
        "valid_account_number": {
          "result": "valid",
          "details":{
            "reason":"",
            "message":"",
          },
        },
        "matching_account_number_and_bank_code": {
          "result": "valid",
          "details":{
            "reason":"",
            "message":"",
            "expected_value":""
          },
        },
        "matching_account_holder": {
          "result": "valid",
          "details":{
            "reason":"",
            "message":"",
            "expected_value":""
          },
        },
        "active_account": {
          "result": "valid",
          "details":{
            "reason":"",
            "message":"",
          },
        },
        "created_at": "2022-01-03T11:53:19.734182Z",
      }
    }
    

    Verification object

    Every verification has its own object, with a result string and a details object as follows:

    AttributeDescription
    result
    string
    The result of the sub-item verification. It can be valid, invalid, impossible_to_verify or not_verified.
    details
    object
    The details of the sub-item result, in case it is not valid.
    details.reason
    string
    The reason why the the sub-item is not valid, represented by a reason code. Please find below the list of possible reason codes per sub-item.
    details.message
    string
    A comprehensive message describing the reason.
    details.expected_value
    string
    For matching_account_number_and_bank_code, the bank code matching the account number, if a not-matching bank code has been provided.
    For matching_account_holder, the holder's name found as matching the holder's name provided.

    Verification reasons

    active_account

    ReasonMessage
    inactiveThe account is inactive.
    unknownImpossible to get the account’s activity status.

    valid_account_number

    ReasonMessage
    unauthorized_charactersThe account number has unauthorised characters.
    incorrect_account_check_digitThe account number checksum is incorrect.
    incorrect_iban_check_digitThe IBAN checksum is incorrect.
    incorrect_structureThe account number has an invalid structure.
    incorrect_lengthThe account number has an incorrect number of characters.
    country_doesnt_support_ibanThe country does not support IBAN.
    unsupported_account_number_kindAccount number type is not supported

    matching_account_number_and_bank_code

    ReasonMessageExpected value
    bic_not_matchingBank code and account number do not match. Account number belongs to {{suggested bank code}}.Valid bank code
    could_not_verifyImpossible to retrieve the bank code associated to this account number.

    matching_account_holder

    ReasonMessage
    close_matchThe holder entered is a close match to the registered holder.
    no_matchThe holder entered does not match the registered holder.
    could_not_matchImpossible to match the registered holder.

    Test cases

    📘

    Test cases

    Use our pre-made test cases to test and validate your integration.