Validate payment

Validate IBAN

IBANs follow a specific algorithm to ensure that the chance of an error is minimized. You can query it individually or with other inputs POST /payments/validations

Valid IBAN
Invalid IBAN (and BIC)
Invalid IBAN (put as account number)

Request

{
  "creditorAccount": {
    "id": {
      "value": "LT601010012345678901",
      "type": "IBAN"
    }
  }
}

Response

{
  "status": "OK",
  "alerts": []
}

Request

{
  "creditorAgent": {
    "bic": "BARCGB00XXX"
  },
  "creditorAccount": {
    "id": {
      "value": "GB33BARC2000625555555",
      "type": "IBAN"
    }
  }
}

Response

{
  "status": "ALERT",
  "alerts": [
    {
      "code": "CREDITOR_IBAN_INVALID_BBAN_STRUCTURE"
    },
    {
      "code": "CREDITOR_BIC_DOES_NOT_EXIST"
    }
  ]
}

Request

{
  "creditorAccount": {
    "id": {
      "value": "BE57967950097279",
      "type": "ACCOUNT_NUMBER"
    }
  }
}

Response

{
  "status": "ALERT",
  "alerts": [
    {
      "code": "CREDITOR_IBAN_INCORRECT_CHECK_DIGITS"
    }
  ]
}

Validate IBAN and BIC

You might want to check that the IBAN (beneficiary’s account) is from the right BIC (bank). It’s helpful when you ask for both fields in the UI.

Note on IBAN-BIC consistency checks we perform

Two or more BICs can be associated with a single IBAN (for example, REVOGB21 and REVOGB2L for GB85REVO04007549976222), and their use varies based on the currency and payment scheme. For EUR payments within the SEPA region, the optimal scheme is typically SEPA or SEPA Instant, and the correct BIC for this is REVOGB21. Using REVOGB2L will lead to payment failure or unintended routing through Target2 with intermediary fees.By default, we assume you prefer SEPA/SEPA Instant for eligible EUR transfers. Therefore, if you indicate that a transfer is in EUR, we will alert you if the BIC provided does not support SEPA/SEPA Instant. This alert won’t be triggered if the currency is not specified.Outside of the SEPA context, we opt for softer consistency checks in order to compensate for potential issues in how banks share the account details with their customers. For example, if your user enters an AE IBAN and a BIC that corresponds to that bank’s branch (like ABINAEAADXB) instead of the head entity (like ABINAEAAXXX), we won’t return an alert.

POST /payments/validations

Inconsistent IBAN and BIC
Non-SEPA BIC
Non-SEPA BIC for SEPA
Unsupported currency

Request

{
  "creditorAgent": {
    "bic": "BARCGB22"
  },
  "creditorAccount": {
    "id": {
      "value": "GB45CITI18502612467878",
      "type": "IBAN"
    }
  }
}

Response

{
  "status": "ALERT",
  "alerts": [
    {
      "code": "CREDITOR_BIC_IBAN_INCONSISTENCY"
    }
  ]
}

Request

{
  "creditorAgent": {
    "bic": "REVOGB2L"
  },
  "creditorAccount": {
    "id": {
      "value": "GB85REVO04007549976222",
      "type": "IBAN"
    }
  }
}

Response

{
  "status": "OK",
  "alerts": []
}

Request

{
  "creditorAgent": {
    "bic": "REVOGB2L"
  },
  "creditorAccount": {
    "id": {
      "value": "GB85REVO04007549976222",
      "type": "IBAN"
    }
  },
  "currency": "EUR"
}

Response

{
  "status": "ALERT",
  "alerts": [
    {
      "code": "CREDITOR_BIC_SCHEME_UNSUPPORTED"
    }
  ]
}

Request

{
  "creditorAgent": {
    "bic": "LOYDGB2L"
  },
  "currency": "KRW"
}

Response

{
  "status": "ALERT",
  "alerts": [
    {
      "code": "CREDITOR_BIC_NO_SSI_FOR_CURRENCY"
    }
  ]
}

Validate bank identifier

When sending local transfers, you might want to ensure that the customer input for the bank identifier (BIC, sort code, ABA routing number,
clearingnummer…) is correct. You need to clarify the country of that local bank identifier, so we know what you’re dealing with. POST /payments/validations

Valid UK sort code
Invalid CA transit number
Valid HU identifier of a BE bank

Request

{
  "country": "GB",
  "creditorAgent": {
    "clearingSystemMemberId": {
      "memberId": "040075"
    }
  }
}

Response

{
  "status": "OK",
  "alerts": []
}

Request

{
  "country": "CA",
  "creditorAgent": {
    "clearingSystemMemberId": {
      "memberId": "001"
    },
    "branchId": "12345"
  }
}

Response

{
  "status": "ALERT",
  "alerts": [
    {
      "code": "CREDITOR_BRANCH_IDENTIFIER_DOES_NOT_EXIST"
    }
  ]
}

Request

{
  "country": "HU",
  "creditorAgent": {
    "clearingSystemMemberId": {
      "memberId": "12600016"
    }
  }
}

Response

{
  "status": "OK",
  "alerts": []
}

Validate account number

Some account numbers can be validated through specific algorithms. POST /payments/validations

Inconsistent UK sort code and account number
Invalid AR account number
Valid MA RIB
Valid SE kontonummer

Request

{
  "country": "GB",
  "creditorAgent": {
    "clearingSystemMemberId": {
      "memberId": "040075"
    }
  },
  "creditorAccount": {
    "id": {
      "value": "49976223",
      "type": "ACCOUNT_NUMBER"
    }
  }
}

Response

{
  "status": "ALERT",
  "alerts": [
    {
      "code": "CREDITOR_BANK_IDENTIFIER_ACCOUNT_NUMBER_INCONSISTENCY"
    }
  ]
}

Request

{
  "country": "AR",
  "creditorAccount": {
    "id": {
      "value": "0270056510000438550019",
      "type": "ACCOUNT_NUMBER"
    }
  }
}

Response

{
  "status": "ALERT",
  "alerts": [
    {
      "code": "CREDITOR_ACCOUNT_NUMBER_INCORRECT_CHECKSUM"
    }
  ]
}

Request

{
  "country": "MA",
  "creditorAccount": {
    "id": {
      "value": "350810000000000547371076",
      "type": "ACCOUNT_NUMBER"
    }
  }
}

Response

{
  "status": "OK",
  "alerts": []
}

Request

{
  "country": "SE",
  "creditorAccount": {
    "id": {
      "value": "8937028383339",
      "type": "ACCOUNT_NUMBER"
    }
  }
}

Response

{
  "status": "OK",
  "alerts": []
}

Differences in corridor requirements

When working with different providers in various corridors, there can be discrepancies in how they handle inputs. The most common variation occurs when there are two identifiers for the bank - such as a bank code and a branch code. Some providers expect separate fields for each identifier, while others require the two to be combined into a single string. Our API is designed to accommodate these differences and aims to support the well-known formatting patterns used by different providers.

Country	Possible UI fields	Supported patterns
Brazil	Bank code (`AAA`), branch code (`BBBB`)	- Concatenated: `clearingSystemMemberId: AAABBBB` - Separated: `clearingSystemMemberId: AAA`, `branchId: BBBB`
Canada	Institution number (`AAA`), transit number (`BBBBB`)	- Concatenated: `clearingSystemMemberId: AAABBBBB` - Separated: `clearingSystemMemberId: AAA`, `branchId: BBBBB`
Japan	Bank code (`AAAA`), branch code (`BBB`)	- Concatenated: `clearingSystemMemberId: AAAABBB` - Separated: `clearingSystemMemberId: AAAA`, `branchId: BBB`

Validate chain of intermediaries

When processing payments that involve an intermediary bank, you might want to ensure that the customer input for the intermediary BICs is correct and appropriate for the creditor agent and currency. By validating this information, we help confirm that the intermediary bank is suitable for the transaction, preventing potential routing errors. POST /payments/validations

Valid single intermediary
Invalid single intermediary
Two intermediaries

Request

{
  "intermediaryAgent1": {
    "bic": "CHASGB2LXXX"
  },
  "creditorAgent": {
    "bic": "REVOGB2LXXX"
  },
  "currency": "USD"
}

Response

{
  "status": "OK",
  "alerts": []
}

Request

{
  "intermediaryAgent1": {
    "bic": "CITIGB22XXX"
  },
  "creditorAgent": {
    "bic": "REVOGB2LXXX"
  },
  "currency": "USD"
}

Response

{
  "status": "ALERT",
  "alerts": [
    {
      "code": "INTERMEDIARY_1_NO_SSI"
    }
  ]
}

Request

{
  "intermediaryAgent1": {
    "bic": "IRVTUS3NXXX"
  },
  "intermediaryAgent2": {
    "bic": "DEUTDEFFXXX"
  },
  "creditorAgent": {
    "bic": "RVBKUZ22XXX"
  },
  "currency": "USD"
}

Response

{
  "status": "ALERT",
  "alerts": [
    {
      "code": "INTERMEDIARY_2_NO_SSI"
    }
  ]
}

Validate settlement system

You can validate that a bank identifier supports the specified settlement system. Different banks may support different settlement systems, and validating this compatibility helps prevent payment failures caused by routing through unsupported settlement methods. POST /payments/validations

US ABA routing number

Request

{
  "country": "US",
  "creditorAgent": {
    "clearingSystemMemberId": {
      "memberId": "011001726"
    }
  },
  "settlementInformation": {
    "settlementSystem": "US_FEDWIRE"
  }
}

Response

{
  "status": "ALERT",
  "alerts": [
    {
      "code": "CREDITOR_BANK_IDENTIFIER_SCHEME_UNSUPPORTED"
    }
  ]
}

Validate document identifiers

In some corridors, the settlement scheme or your payment provider may require you to specify the creditor’s personal identifier - such as a tax ID or passport number. You can validate these identifiers before submitting a payment. We validate format and, where applicable, checksum for well-known document types. Some corridors have well-known formatting patterns using special symbols (e.g. Brazilian CPF - 231.002.999-00). We respect those formatting patterns and validate both 231.002.999-00 and 23100299900 in the same way. POST /payments/validations

Valid BR CPF
Invalid CO NIT format
Incorrect AR CUIT checksum

Request

{
  "country": "BR",
  "creditor": {
    "documents": [
      {
        "type": "CPF",
        "value": "60735047480"
      }
    ]
  }
}

Response

{
  "status": "OK",
  "alerts": []
}

Request

{
  "country": "CO",
  "creditor": {
    "documents": [
      {
        "type": "NIT",
        "value": "700522594"
      }
    ]
  }
}

Response

{
  "status": "ALERT",
  "alerts": [
    {
      "code": "CREDITOR_DOCUMENT_1_INVALID_FORMAT"
    }
  ]
}

Request

{
  "country": "AR",
  "creditor": {
    "documents": [
      {
        "type": "CUIT",
        "value": "27316952429"
      }
    ]
  }
}

Response

{
  "status": "ALERT",
  "alerts": [
    {
      "code": "CREDITOR_DOCUMENT_1_INCORRECT_CHECKSUM"
    }
  ]
}

Supported document types by corridor

Country	Document types
Argentina	CUIT - Clave Única de Identificación Tributaria CUIL - Código Único de Identificación Laboral
Brazil	CPF - Cadastro de Pessoas Físicas CNPJ - Cadastro Nacional da Pessoa Jurídica
Chile	RUT - Rol Único Tributario
China	CUI - Resident Identity Card PASS - Passport TAXID - Tax ID
Colombia	CC - Cédula de Ciudadanía NIT - Número de Identificación Tributaria CE - Carnet de Extranjería PASS - Pasaporte PEP - Permiso Especial de Permanencia
Costa Rica	CI - Cédula de Identidad CJ - Cédula Jurídica CR - Cédula de Residencia
Ecuador	CI - Cédula de Identidad RUC - Registro Único de Contribuyentes PASS - Pasaporte
Panama	CI - Cédula de Identidad RUC - Registro Único de Contribuyentes PASS - Pasaporte
Paraguay	CI - Cédula de Identidad RUC - Registro Único de Contribuyentes
Peru	DNI - Documento Nacional de Identidad RUC - Registro Único de Contribuyentes CE - Carnet de Extranjería PASS - Pasaporte
Uruguay	CI - Cédula de Identidad RUT - Registro Único Tributario DE - Documento Extranjero PASS - Pasaporte

Bulk validation

If you need to validate multiple payments at once, use the bulk validation endpoint. Each item in the array follows the exact same schema as POST /payments/validations and produces the same alert codes. The response returns validation results in the same order as the input. The maximum number of items per request is 20. POST /payments/bulk-validations

Mixed results

Request

{
  "items": [
    {
      "creditorAccount": {
        "id": {
          "value": "LT601010012345678901",
          "type": "IBAN"
        }
      }
    },
    {
      "creditorAgent": {
        "bic": "BARCGB00XXX"
      },
      "creditorAccount": {
        "id": {
          "value": "GB33BARC2000625555555",
          "type": "IBAN"
        }
      }
    },
    {
      "country": "BR",
      "creditor": {
        "documents": [
          {
            "type": "CPF",
            "value": "60735047480"
          }
        ]
      }
    }
  ]
}

Response

{
  "items": [
    {
      "status": "OK",
      "alerts": []
    },
    {
      "status": "ALERT",
      "alerts": [
        {
          "code": "CREDITOR_IBAN_INVALID_BBAN_STRUCTURE"
        },
        {
          "code": "CREDITOR_BIC_DOES_NOT_EXIST"
        }
      ]
    },
    {
      "status": "OK",
      "alerts": []
    }
  ]
}

Alert codes

Here’s the list of the alerts with explanations, which you can use in UI localization. In some cases, there can be more than one alert code in our response.

Code	Explanation	Example
CREDITOR_IBAN_INVALID_FORMAT	The IBAN doesn’t follow the correct format or structure.	`GT01`
CREDITOR_IBAN_INVALID_COUNTRY_CODE	The IBAN country code is not a valid ISO 3166-1 alpha-2 code.	`XY02`
CREDITOR_IBAN_COUNTRY_NOT_SUPPORTED	The entered country does not support IBAN standards.	`US03`
CREDITOR_IBAN_INVALID_BBAN_STRUCTURE	The IBAN’s BBAN has an incorrect length or contains invalid characters.	`GB01DEEL999LETSGO`
CREDITOR_IBAN_INCORRECT_CHECK_DIGITS	The IBAN is incorrect due to check digits.	`LT043250045821439861`
CREDITOR_IBAN_COUNTRY_INCONSISTENCY	The IBAN does not match the selected bank country.	`GB85REVO04007549976222` for US
CREDITOR_IBAN_NO_SSI_FOR_CURRENCY	The IBAN does not support selected currency.	`BRL` to `LT583250045821439861`
CREDITOR_BIC_INVALID_FORMAT	The BIC does not match the correct format.	`BOFAUS`
CREDITOR_BIC_INVALID_COUNTRY_CODE	The BIC’s country code is not a valid ISO 3166-1 alpha-2 code.	`BOFAXX33`
CREDITOR_BIC_DOES_NOT_EXIST	The BIC cannot be found in official bank listings - it might be outdated or incorrect.	`DEELUS99`
CREDITOR_BIC_IBAN_INCONSISTENCY	The IBAN and BIC entered are not consistent. Another BIC must be used.	`BARCGB2L` for `GB85REVO04007549976222`
CREDITOR_BIC_SCHEME_UNSUPPORTED	The BIC does not support the required payment scheme for the transfer.	`REVOGB2L` for `GB85REVO04007549976222` (should be `REVOGB21`, as SEPA is preferred to any other payment scheme)
CREDITOR_BIC_NO_SSI_FOR_CURRENCY	The BIC does not support selected currency.	`KRW` to `LOYDGB2L`
CREDITOR_BIC_COUNTRY_INCONSISTENCY	The BIC does not match the selected country.	`NDEASESSXXX` for CH
CREDITOR_BIC_COMPLIANCE_HIT	The BIC is restricted for compliance reasons.	`HAVIGB2LXXX`
CREDITOR_BANK_IDENTIFIER_INVALID_FORMAT	The bank identifier doesn’t follow the correct format for this country.	`0400755` for GB
CREDITOR_BANK_IDENTIFIER_DOES_NOT_EXIST	The local bank identifier entered does not seem to be present in published bank lists. It could be wrong, deprecated, or has yet to appear.	`040123` for GB
CREDITOR_BRANCH_IDENTIFIER_INVALID_FORMAT	The branch identifier doesn’t follow the correct format for this country.	`1234` for JP
CREDITOR_BRANCH_IDENTIFIER_DOES_NOT_EXIST	The branch identifier entered does not seem to be present in published lists for the bank. It could be wrong, deprecated, or has yet to appear.	`999` for Mizuho Bank (JP)
CREDITOR_ACCOUNT_NUMBER_INVALID_FORMAT	The account number does not match the valid format for this country.	`123456789` for GB
CREDITOR_ACCOUNT_NUMBER_TOO_SHORT	The account number you entered is too short. It may be truncated, have missing zeroes, or missing the bank identifier.	`947093420` for SE
CREDITOR_ACCOUNT_NUMBER_TOO_LONG	The account number you entered is too long. It may contain extra digits.	`135000144454` for SE
CREDITOR_ACCOUNT_NUMBER_INCORRECT_CHECKSUM	The account number fails the checksum validation.	`0270056410000438550018` for AR
CREDITOR_ACCOUNT_NUMBER_INVALID_BANK_IDENTIFIER	The account number contains an invalid bank identifier.	`0280056110000438550019` for AR (as 028 is not valid bank identifier) or `10011234567` for SE (1001 is not a valid clearingnummer)
CREDITOR_ACCOUNT_NUMBER_POSSIBLE_CARD_NUMBER	The account number appears to be a valid bank card number (passes the Luhn check).	`4111111111111111` for KE
CREDITOR_ACCOUNT_ID_EMAIL_INVALID_FORMAT	The provided email address doesn’t follow the correct format.	`user@domain` or `user.domain.tld`
CREDITOR_ACCOUNT_ID_MSISDN_INVALID_FORMAT	The provided mobile number doesn’t follow the correct format	`+12345` or `0011111111`
CREDITOR_BANK_IDENTIFIER_ACCOUNT_NUMBER_INCONSISTENCY	The account number and bank identifier combination is incorrect.	`040075` and `49976223` for GB
CREDITOR_BANK_IDENTIFIER_ACCOUNT_NUMBER_SWAP	The account number is an actual bank identifier	For US, `021000021` as account number
CREDITOR_BANK_IDENTIFIER_ACCOUNT_NUMBER_DUPLICATION	The bank identifier and account number are duplicated	For US, `021000021` as both account number and routing number
CREDITOR_BANK_IDENTIFIER_SCHEME_UNSUPPORTED	The bank identifier is not compatible with the specified settlement scheme	`011001726` as routing number and `US_FEDWIRE` as settlement system
CREDITOR_DOCUMENT_1_INVALID_FORMAT	The creditor document doesn’t follow the correct format for this country and document type.	`700522594` as NIT for CO (expected 10 digits)
CREDITOR_DOCUMENT_1_INCORRECT_CHECKSUM	The creditor document fails checksum validation.	`27316952429` as CUIT for AR
INTERMEDIARY_1_INVALID_FORMAT	The intermediary BIC you entered is of invalid format	`BOFAUS`
INTERMEDIARY_1_DOES_NOT_EXIST	The intermediary BIC you entered does not exist.	`CHASUSMMXXX`
INTERMEDIARY_1_NO_SSI	The intermediary BIC does not have standing settlement instructions for this currency with the next agent in the chain.	`USD` to `REVOGB2LXXX` through `CITIGB22XXX`
INTERMEDIARY_1_COMPLIANCE_HIT	The intermediary BIC is restricted for compliance reasons.	`HAVIGB2LXXX`
INTERMEDIARY_2_INVALID_FORMAT	The intermediary BIC you entered is of invalid format	`BOFAUS`
INTERMEDIARY_2_DOES_NOT_EXIST	The intermediary BIC you entered does not exist.	`CHASUSMMXXX`
INTERMEDIARY_2_NO_SSI	The intermediary BIC does not have standing settlement instructions for this currency with the next agent in the chain.	`USD` to `RVBKUZ22XXX` through `IRVTUS3NXXX` and `SCPEUZ22XXX`
INTERMEDIARY_2_COMPLIANCE_HIT	The intermediary BIC is restricted for compliance reasons.	`HAVIGB2LXXX`
INTERMEDIARY_3_INVALID_FORMAT	The intermediary BIC you entered is of invalid format	`BOFAUS`
INTERMEDIARY_3_DOES_NOT_EXIST	The intermediary BIC you entered does not exist.	`CHASUSMMXXX`
INTERMEDIARY_3_NO_SSI	The intermediary BIC does not have standing settlement instructions for this currency with the next agent in the chain.	`USD` to `REVOGB21XXX` through `CHASUS33XXX`, `CHASGB2LXXX` and `REVOLT21XXX`
INTERMEDIARY_3_COMPLIANCE_HIT	The intermediary BIC is restricted for compliance reasons.	`HAVIGB2LXXX`

Get Started

Payment Preparation

Beneficiary Hub

Gamgem

Webhooks

Validate IBAN

Validate IBAN and BIC

Validate bank identifier

Validate account number

Differences in corridor requirements

Validate chain of intermediaries

Validate settlement system

Validate document identifiers

Bulk validation

Alert codes

Get Started

Payment Preparation

Beneficiary Hub

Gamgem

Webhooks

Documentation Index

​Validate IBAN

​Validate IBAN and BIC

​Validate bank identifier

​Validate account number

​Differences in corridor requirements

​Validate chain of intermediaries

​Validate settlement system

​Validate document identifiers

​Bulk validation

​Alert codes

Validate IBAN

Validate IBAN and BIC

Validate bank identifier

Validate account number

Differences in corridor requirements

Validate chain of intermediaries

Validate settlement system

Validate document identifiers

Bulk validation

Alert codes