> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paysway.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/api-reference/payment-preparation/validate-payment-details)
```json Request theme={null}
{
"creditorAccount": {
"id": {
"value": "LT601010012345678901",
"type": "IBAN"
}
}
}
```
```json Response theme={null}
{
"status": "OK",
"alerts": []
}
```
```json Request theme={null}
{
"creditorAgent": {
"bic": "BARCGB00XXX"
},
"creditorAccount": {
"id": {
"value": "GB33BARC2000625555555",
"type": "IBAN"
}
}
}
```
```json Response theme={null}
{
"status": "ALERT",
"alerts": [
{
"code": "CREDITOR_IBAN_INVALID_BBAN_STRUCTURE"
},
{
"code": "CREDITOR_BIC_DOES_NOT_EXIST"
}
]
}
```
```json Request theme={null}
{
"creditorAccount": {
"id": {
"value": "BE57967950097279",
"type": "ACCOUNT_NUMBER"
}
}
}
```
```json Response theme={null}
{
"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.
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](/api-reference/payment-preparation/validate-payment-details)
```json Request theme={null}
{
"creditorAgent": {
"bic": "BARCGB22"
},
"creditorAccount": {
"id": {
"value": "GB45CITI18502612467878",
"type": "IBAN"
}
}
}
```
```json Response theme={null}
{
"status": "ALERT",
"alerts": [
{
"code": "CREDITOR_BIC_IBAN_INCONSISTENCY"
}
]
}
```
```json Request theme={null}
{
"creditorAgent": {
"bic": "REVOGB2L"
},
"creditorAccount": {
"id": {
"value": "GB85REVO04007549976222",
"type": "IBAN"
}
}
}
```
```json Response theme={null}
{
"status": "OK",
"alerts": []
}
```
```json Request theme={null}
{
"creditorAgent": {
"bic": "REVOGB2L"
},
"creditorAccount": {
"id": {
"value": "GB85REVO04007549976222",
"type": "IBAN"
}
},
"currency": "EUR"
}
```
```json Response theme={null}
{
"status": "ALERT",
"alerts": [
{
"code": "CREDITOR_BIC_SCHEME_UNSUPPORTED"
}
]
}
```
```json Request theme={null}
{
"creditorAgent": {
"bic": "LOYDGB2L"
},
"currency": "KRW"
}
```
```json Response theme={null}
{
"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](/api-reference/payment-preparation/validate-payment-details)
```json Request theme={null}
{
"country": "GB",
"creditorAgent": {
"clearingSystemMemberId": {
"memberId": "040075"
}
}
}
```
```json Response theme={null}
{
"status": "OK",
"alerts": []
}
```
```json Request theme={null}
{
"country": "CA",
"creditorAgent": {
"clearingSystemMemberId": {
"memberId": "001"
},
"branchId": "12345"
}
}
```
```json Response theme={null}
{
"status": "ALERT",
"alerts": [
{
"code": "CREDITOR_BRANCH_IDENTIFIER_DOES_NOT_EXIST"
}
]
}
```
```json Request theme={null}
{
"country": "HU",
"creditorAgent": {
"clearingSystemMemberId": {
"memberId": "12600016"
}
}
}
```
```json Response theme={null}
{
"status": "OK",
"alerts": []
}
```
## Validate account number
Some account numbers can be validated through specific algorithms.
[**POST** /payments/validations](/api-reference/payment-preparation/validate-payment-details)
```json Request theme={null}
{
"country": "GB",
"creditorAgent": {
"clearingSystemMemberId": {
"memberId": "040075"
}
},
"creditorAccount": {
"id": {
"value": "49976223",
"type": "ACCOUNT_NUMBER"
}
}
}
```
```json Response theme={null}
{
"status": "ALERT",
"alerts": [
{
"code": "CREDITOR_BANK_IDENTIFIER_ACCOUNT_NUMBER_INCONSISTENCY"
}
]
}
```
```json Request theme={null}
{
"country": "AR",
"creditorAccount": {
"id": {
"value": "0270056510000438550019",
"type": "ACCOUNT_NUMBER"
}
}
}
```
```json Response theme={null}
{
"status": "ALERT",
"alerts": [
{
"code": "CREDITOR_ACCOUNT_NUMBER_INCORRECT_CHECKSUM"
}
]
}
```
```json Request theme={null}
{
"country": "MA",
"creditorAccount": {
"id": {
"value": "350810000000000547371076",
"type": "ACCOUNT_NUMBER"
}
}
}
```
```json Response theme={null}
{
"status": "OK",
"alerts": []
}
```
```json Request theme={null}
{
"country": "SE",
"creditorAccount": {
"id": {
"value": "8937028383339",
"type": "ACCOUNT_NUMBER"
}
}
}
```
```json Response theme={null}
{
"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](/api-reference/payment-preparation/validate-payment-details)
```json Request theme={null}
{
"intermediaryAgent1": {
"bic": "CHASGB2LXXX"
},
"creditorAgent": {
"bic": "REVOGB2LXXX"
},
"currency": "USD"
}
```
```json Response theme={null}
{
"status": "OK",
"alerts": []
}
```
```json Request theme={null}
{
"intermediaryAgent1": {
"bic": "CITIGB22XXX"
},
"creditorAgent": {
"bic": "REVOGB2LXXX"
},
"currency": "USD"
}
```
```json Response theme={null}
{
"status": "ALERT",
"alerts": [
{
"code": "INTERMEDIARY_1_NO_SSI"
}
]
}
```
```json Request theme={null}
{
"intermediaryAgent1": {
"bic": "IRVTUS3NXXX"
},
"intermediaryAgent2": {
"bic": "DEUTDEFFXXX"
},
"creditorAgent": {
"bic": "RVBKUZ22XXX"
},
"currency": "USD"
}
```
```json Response theme={null}
{
"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](/api-reference/payment-preparation/validate-payment-details)
```json Request theme={null}
{
"country": "US",
"creditorAgent": {
"clearingSystemMemberId": {
"memberId": "011001726"
}
},
"settlementInformation": {
"settlementSystem": "US_FEDWIRE"
}
}
```
```json Response theme={null}
{
"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](/api-reference/payment-preparation/validate-payment-details)
```json Request theme={null}
{
"country": "BR",
"creditor": {
"documents": [
{
"type": "CPF",
"value": "60735047480"
}
]
}
}
```
```json Response theme={null}
{
"status": "OK",
"alerts": []
}
```
```json Request theme={null}
{
"country": "CO",
"creditor": {
"documents": [
{
"type": "NIT",
"value": "700522594"
}
]
}
}
```
```json Response theme={null}
{
"status": "ALERT",
"alerts": [
{
"code": "CREDITOR_DOCUMENT_1_INVALID_FORMAT"
}
]
}
```
```json Request theme={null}
{
"country": "AR",
"creditor": {
"documents": [
{
"type": "CUIT",
"value": "27316952429"
}
]
}
}
```
```json Response theme={null}
{
"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](/api-reference/payment-preparation/validate-payment-details) and produces the same [alert codes](#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](/api-reference/payment-preparation/bulk-validate-payment-details)
```json Request theme={null}
{
"items": [
{
"creditorAccount": {
"id": {
"value": "LT601010012345678901",
"type": "IBAN"
}
}
},
{
"creditorAgent": {
"bic": "BARCGB00XXX"
},
"creditorAccount": {
"id": {
"value": "GB33BARC2000625555555",
"type": "IBAN"
}
}
},
{
"country": "BR",
"creditor": {
"documents": [
{
"type": "CPF",
"value": "60735047480"
}
]
}
}
]
}
```
```json Response theme={null}
{
"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` |