Bank Account Validation Reference

This document provides a comprehensive reference for all bank account field validations in the Mural API, organized by currency and payment method type.

About This Document

This validation reference is designed to help you integrate with the Mural API's payout capabilities. The validations documented here apply when:

• Creating Payout Requests: Use the Payouts API to send funds to recipients via bank transfers or blockchain wallets
• Creating Payment Methods: Use the Payment Methods API to store bank account details for counterparties

Bank Name Validation

Many currencies require the bank name to match a specific list of supported banks. To retrieve these lists programmatically, use the Bank Details API. This endpoint returns the list of valid bank names for each currency and rail combination, which you can use to validate user input before submitting payout requests.

Table of Contents

1. Overview
2. USD - United States Dollar (Domestic)
3. USD - Peru
4. USD - Panama
5. USD - China
6. ARS - Argentine Peso
7. BRL - Brazilian Real
8. COP - Colombian Peso
9. EUR - Euro (SEPA)
10. MXN - Mexican Peso
11. CLP - Chilean Peso
12. PEN - Peruvian Sol
13. BOB - Bolivian Boliviano
14. CRC - Costa Rican Colón
15. ZAR - South African Rand
16. Validation Algorithms

---

Overview

The Mural API enforces strict validations on bank account information to ensure successful payouts across different currencies and payment methods. All validations are applied when creating or updating payout methods.

Validation Levels

Validations are enforced at multiple levels:

• Format Validation: Regex patterns, character sets, and length requirements
• Checksum Validation: Mathematical algorithms to verify account numbers and identification documents
• Business Rule Validation: Geographic restrictions, supported bank lists, and field dependencies

---

USD - United States Dollar (Domestic)

Type Discriminator: type: "usdDomestic"

Required Fields

Field Validations

bankAccountNumber

• Format: Numeric only
• Length: 6-17 digits
• Pattern: Must contain only digits (0-9)

bankRoutingNumber

• Format: Numeric only
• Length: Exactly 9 digits
• Checksum: MOD 10 algorithm (see US Routing Number Checksum)
• The routing number must pass checksum validation to ensure it's valid

accountType

• Allowed values: CHECKING, SAVINGS

transferType

• Allowed values: ACH, WIRE

bankName

• Length: 2-255 characters
• Format: Free text

---

USD - Peru

Type Discriminator: type: "usdPeru"

Required Fields

Field Validations

bankAccountNumber

• Format: Numeric only
• Length: Exactly 20 digits
• Must contain only digits

documentNumber

• Validation depends on documentType
• See document type validations for Peru

documentType

• Allowed values: NATIONAL_ID, RUC_NIT, PASSPORT, RESIDENT_ID

bankName

• Must match one of the supported banks for Peru
• See Bank Name Validation for how to retrieve the list of supported banks
• Length: 2-255 characters

accountType

• Allowed values: CHECKING, SAVINGS

---

USD - Panama

Type Discriminator: type: "usdPanama"

Required Fields

Field Validations

bankAccountNumber

• Format: Numeric only
• Length: 1-45 digits
• Panama allows longer account numbers than most countries

documentNumber

• Validation depends on documentType:

documentType

• Allowed values: NATIONAL_ID, RUC_NIT, PASSPORT, RESIDENT_ID
• TAX_ID is not supported for Panama

bankName

• Must match one of the supported banks for Panama
• See Bank Name Validation for how to retrieve the list of supported banks
• Length: 2-255 characters

accountType

• Allowed values: CHECKING, SAVINGS

---

USD - China

Type Discriminator: type: "usdChina"

Required Fields

Field Validations

bankAccountNumber

• Format: Numeric only
• Length: 15-25 digits

phoneNumber

• Format: Valid international phone number
• E.164 format recommended

address

• Format: Free text string
• Required field

swiftBic

• Format: Valid SWIFT/BIC code (8 or 11 characters)
• Validated using the ibantools library

documentNumber

• Validation depends on documentType:

documentType

• Allowed values: PASSPORT, TAX_ID, RESIDENT_ID

Document Type Details:

PASSPORT:

• Must match: G######## (G followed by 8 digits) OR E[A-HJ-NP-Z]####### (E, letter except I/O, then 7 digits)

TAX_ID (Business Tax ID):

• Legacy format (15 digits): Exactly 15 numeric digits with MOD 11 checksum
• USCC format (18 alphanumeric): 18 uppercase characters using restricted alphabet (excludes I, O, S, V, Z)
  • Positions 3-8 must be digits
  • Uses ISO 7064 MOD 31-2 checksum
  • See Chinese USCC Validation

RESIDENT_ID (Individual ID):

• Format: 17 digits + 1 check character (0-9 or X)
• Positions 7-14 contain birthdate (YYYYMMDD) which must be a valid date
• Birthdate must be between 1900 and current year
• Check character calculated using MOD 11-2 algorithm
• See Chinese Resident ID Validation

bankName

• Must match one of the supported banks for China
• See Bank Name Validation for how to retrieve the list of supported banks
• Length: 2-255 characters

accountType

• Allowed values: CHECKING, SAVINGS

---

ARS - Argentine Peso

ARS supports two variants based on how the account is identified.

ARS Alias

Type Discriminator: type: "arsAlias"

Required Fields

Field Validations

alias

• Format: Free text string
• This is the bank account alias registered with the Argentine banking system

documentNumber

• Format: CUIT/CUIL (Código Único de Identificación Tributaria)
• Pattern: XX-XXXXXXXX-X (hyphens optional)
• Length: 11 digits (excluding hyphens)
• Example: 20-12345678-9

bankName

• Format: Free text
• Length: 2-255 characters

---

ARS Account Number (CBU/CVU)

Type Discriminator: type: "arsAccountNumber"

Required Fields

Field Validations

bankAccountNumber

• Format: Numeric only (for CBU/CVU)
• Length: 6-22 digits
• Validation applies to CBU and CVU types only

bankAccountNumberType

• Allowed values: CVU, CBU, ALIAS
• CVU (Clave Virtual Uniforme): Virtual account number
• CBU (Clave Bancaria Uniforme): Standard bank account number
• ALIAS: Human-readable alias

documentNumber

• Same format as ARS Alias (CUIT/CUIL)
• Pattern: XX-XXXXXXXX-X

bankName

• Format: Free text
• Length: 2-255 characters

---

BRL - Brazilian Real

BRL supports five variants: four PIX variants (different key types) and one traditional wire transfer.

BRL PIX Phone

Type Discriminator: type: "pixPhone"

Required Fields

Field Validations

phoneNumber

• Format: Valid international phone number
• E.164 format recommended (e.g., +5511987654321)
• This is the PIX key registered with the phone number

documentNumber

• Format: CPF (individual, 11 digits) or CNPJ (business, 14 digits)

bankName

• Must match one of the supported banks for Brazil
• See Bank Name Validation for how to retrieve the list of supported banks
• Length: 2-255 characters

---

BRL PIX Email

Type Discriminator: type: "pixEmail"

Required Fields

Field Validations

email

• Format: Valid email address
• This is the PIX key registered with the email address

documentNumber

• Format: CPF (individual) or CNPJ (business)

bankName

• Must match one of the supported banks for Brazil
• See Bank Name Validation for how to retrieve the list of supported banks
• Length: 2-255 characters

---

BRL PIX Document

Type Discriminator: type: "pixDocument"

Required Fields

Field Validations

documentNumber

• Format: CPF (11 digits) or CNPJ (14 digits)
• This field serves dual purpose: it is both the identity document AND the PIX key

bankName

• Must match one of the supported banks for Brazil
• See Bank Name Validation for how to retrieve the list of supported banks
• Length: 2-255 characters

---

BRL PIX Bank Account

Type Discriminator: type: "pixBankAccount"

Required Fields

Field Validations

bankAccountNumber

• Format: EVP (Endereço Virtual de Pagamento) key - UUID format
• Must be a valid UUID (e.g., 123e4567-e89b-12d3-a456-426614174000)

documentNumber

• Format: CPF (individual) or CNPJ (business)

bankName

• Must match one of the supported banks for Brazil
• See Bank Name Validation for how to retrieve the list of supported banks
• Length: 2-255 characters

---

BRL Wire Transfer

Type Discriminator: type: "wire"

Required Fields

Field Validations

bankBranch

• Format: Branch code (agência)
• Free text string

accountType

• Allowed values: CHECKING, SAVINGS

accountNumber

• Format: Bank account number
• Free text string

documentNumber

• Format: CPF (individual) or CNPJ (business)

bankName

• Must match one of the supported banks for Brazil
• See Bank Name Validation for how to retrieve the list of supported banks
• Length: 2-255 characters

---

COP - Colombian Peso

Type Discriminator: type: "copDomestic"

Required Fields

Field Validations

phoneNumber

• Format: Valid international phone number

accountType

• Allowed values: CHECKING, SAVINGS

bankAccountNumber

• Format: Numeric only
• Length: 6-18 digits

documentNumber

• Validation depends on documentType:

documentType

• Allowed values: NATIONAL_ID, RUC_NIT, PASSPORT, RESIDENT_ID
• TAX_ID is not supported for Colombia

NIT Validation:

• Colombian NIT requires checksum validation using MOD 11 algorithm
• Format: 8-10 digits + 1 check digit
• See Colombian NIT Validation for algorithm details

bankName

• Must match one of the supported banks for Colombia
• See Bank Name Validation for how to retrieve the list of supported banks
• Length: 2-255 characters

---

EUR - Euro (SEPA)

Type Discriminator: type: "eurSepa"

Required Fields

Field Validations

iban

• Format: Valid IBAN with proper country code and checksum
• Must be a properly formatted IBAN
• Validated using the ibantools library

swiftBic

• Format: Valid SWIFT/BIC code (8 or 11 characters)
• Validated using the ibantools library

country

• Format: ISO 3166-1 alpha-2 country code (e.g., "DE", "FR", "ES")
• Important: Country must be a valid SEPA country

bankName

• Format: Free text
• Length: 2-255 characters

---

MXN - Mexican Peso

Type Discriminator: type: "mxnDomestic"

Required Fields

Field Validations

bankAccountNumber (CLABE)

• Format: Exactly 18 numeric digits
• Checksum: Weighted checksum algorithm
• Must pass CLABE checksum validation
• See CLABE Validation Algorithm

CLABE Structure:

• Digits 1-3: Bank code
• Digits 4-6: Branch code
• Digits 7-17: Account number (11 digits)
• Digit 18: Check digit

bankName

• Format: Free text
• Length: 2-255 characters

---

CLP - Chilean Peso

Type Discriminator: type: "clpDomestic"

Required Fields

Field Validations

accountType

• Allowed values: CHECKING, SAVINGS

bankAccountNumber

• Format: Numeric only
• Length: 6-25 digits

documentType

• Allowed values: NATIONAL_ID, PASSPORT, RESIDENT_ID, RUC_NIT, TAX_ID
• Note: RUT (Rol Único Tributario) is the standard document type for Chile

documentNumber (Chilean RUT)

• Format: 7-8 digits + 1 check digit (0-9 or K)
• Can include formatting: dots and hyphens (e.g., "12.345.678-5")
• Checksum: MOD 11 algorithm
• Examples: "12.345.678-5", "11111111-1", "7775777-K"
• See Chilean RUT Validation Algorithm

bankName

• Must match one of the supported banks for Chile
• See Bank Name Validation for how to retrieve the list of supported banks
• Length: 2-255 characters

---

PEN - Peruvian Sol

Type Discriminator: type: "penDomestic"

Required Fields

Field Validations

bankAccountNumber

• Format: Exactly 20 numeric digits
• Important: First 3 digits must match the bank code for the specified bankName
• Each bank has a specific 3-digit code that must appear at the start of the account number

accountType

• Allowed values: CHECKING, SAVINGS

documentNumber

• Validation depends on documentType

documentType

• Allowed values: NATIONAL_ID, RUC_NIT, PASSPORT, RESIDENT_ID, TAX_ID

bankName

• Must match one of the supported banks for Peru
• See Bank Name Validation for how to retrieve the list of supported banks
• First 3 digits of account number must match the bank's code
• Length: 2-255 characters

Bank Code Validation Example

If you select "Banco de Crédito del Perú" (bank code: 002):

• ✅ Valid account: 00212345678901234567 (starts with "002")
• ❌ Invalid account: 00112345678901234567 (starts with "001", wrong bank)

---

BOB - Bolivian Boliviano

Type Discriminator: type: "bobDomestic"

Required Fields

Field Validations

bankAccountNumber

• Format: Numeric only
• Length: 10-15 digits

documentNumber

• Validation depends on documentType:

documentType

• Allowed values: NATIONAL_ID, RUC_NIT, RESIDENT_ID
• PASSPORT and TAX_ID are not supported for Bolivia

bankName

• Must match one of the supported banks for Bolivia
• See Bank Name Validation for how to retrieve the list of supported banks
• Length: 2-255 characters

---

CRC - Costa Rican Colón

Type Discriminator: type: "crcDomestic"

Required Fields

Field Validations

iban

• Format: Valid IBAN with proper country code and checksum
• Validated using the ibantools library

documentNumber

• Format: Depends on documentType

documentType

• Allowed values: NATIONAL_ID, RUC_NIT, PASSPORT, RESIDENT_ID, TAX_ID

bankName

• Format: Free text
• Length: 2-255 characters

---

ZAR - South African Rand

Type Discriminator: type: "zarDomestic"

Required Fields

Field Validations

accountType

• Allowed values: CHECKING, SAVINGS

bankAccountNumber

• Format: Numeric string
• Length: 6-25 digits

bankName

• Must match one of the supported banks for South Africa
• See Bank Name Validation for how to retrieve the list of supported banks
• Length: 2-255 characters

---

Validation Algorithms

This section provides detailed explanations of the checksum and validation algorithms used across different currencies.

US Routing Number Checksum

The US routing number uses a MOD 10 checksum algorithm to validate the 9-digit routing number.

Algorithm:

Given routing number: d1 d2 d3 d4 d5 d6 d7 d8 d9

checksum = 3 × (d1 + d4 + d7) + 7 × (d2 + d5 + d8) + (d3 + d6 + d9)

Valid if: checksum % 10 === 0

Example:

• Routing number: 026009593
• Calculation:
  • 3 × (0 + 0 + 9) = 27
  • 7 × (2 + 0 + 5) = 49
  • (6 + 9 + 3) = 18
  • Sum = 27 + 49 + 18 = 94
  • 94 % 10 = 4 (would fail validation)

---

Mexican CLABE Validation

The CLABE (Clave Bancaria Estandarizada) is Mexico's standardized 18-digit bank account number with a checksum.

Structure:

• Positions 1-3: Bank code
• Positions 4-6: Branch code
• Positions 7-17: Account number (11 digits)
• Position 18: Check digit

Checksum Algorithm:

Weights: [3, 7, 1] (repeating pattern)

For each digit i from 0 to 16:
  weighted_sum += digit[i] × weight[i % 3]

check_digit = (10 - (weighted_sum % 10)) % 10

Valid if: digit[17] === check_digit

Example:

• CLABE: 032180000118359719
• First 17 digits: 03218000011835971
• Apply weights cyclically to calculate check digit
• Final digit must match calculated value

---

Chilean RUT Validation

The Chilean RUT (Rol Único Tributario) uses a MOD 11 algorithm with a special check digit that can be 'K'.

Format: 7-8 digits + check digit (0-9 or K)

Algorithm:

Multipliers: [2, 3, 4, 5, 6, 7] (repeating)

sum = 0
for each digit (right to left):
  multiplier = multipliers[position % 6]
  sum += digit × multiplier

remainder = sum % 11

check_digit =
  if remainder === 0: '0'
  else if remainder === 1: 'K'
  else: (11 - remainder)

Example:

• RUT: 12.345.678-5
• Clean format: 123456785
• Extract body: 12345678
• Calculate check digit using MOD 11
• Compare with provided check digit

---

Colombian NIT Validation

The Colombian NIT uses the MOD 11 algorithm with specific multipliers.

Format: 8-10 digits + check digit (total 10-11 digits)

Multipliers: [41, 37, 29, 23, 19, 17, 13, 7, 3]

Algorithm:

1. Extract body (first 9 digits, pad with zeros if needed)
2. Extract check digit (last digit)

sum = 0
for i from 0 to 8:
  sum += digit[i] × multipliers[i]

remainder = sum % 11

check_digit =
  if remainder < 2: remainder
  else: 11 - remainder

Valid if: extracted check digit === calculated check digit

Example:

• NIT: 860007738-7
• Clean format: 8600077387
• Apply multipliers to first 9 digits
• Calculate and verify check digit

---

Chinese USCC Validation

The Chinese Unified Social Credit Code (USCC) uses the ISO 7064 MOD 31-2 algorithm.

Format: 18 alphanumeric characters

Restricted Character Set: 0123456789ABCDEFGHJKLMNPQRTUWXY (excludes I, O, S, V, Z)

Structure:

• Positions 1-2: Organization type
• Positions 3-8: Date/region code (must be digits)
• Positions 9-17: Organization code
• Position 18: Check character

Algorithm:

Weights: [1, 3, 9, 27, 19, 26, 16, 17, 20, 29, 25, 13, 8, 24, 10, 30, 28]

1. Convert each character to numeric value (0-30) based on position in character set
2. Calculate weighted sum using the weights above
3. Calculate check value using MOD 31-2 algorithm
4. Convert back to character and verify

---

Chinese Resident ID Validation

The Chinese Resident ID uses a MOD 11-2 algorithm with birthdate validation.

Format: 17 digits + check character (0-9 or X)

Structure:

• Positions 1-6: Region code
• Positions 7-14: Birthdate (YYYYMMDD) - must be valid date
• Positions 15-17: Sequence code
• Position 18: Check character

Weights: [7, 9, 10, 5, 8, 4, 2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2]

Check Character Map: ['1', '0', 'X', '9', '8', '7', '6', '5', '4', '3', '2']

Algorithm:

1. Validate format: 17 digits + [0-9 or X]
2. Extract and validate birthdate (must be real calendar date, year 1900-current)
3. Calculate weighted sum
4. Check character = CHECK_MAP[sum % 11]
5. Verify against provided character

---

Support

For questions about bank account validations or to report issues with this documentation, please contact the Mural API support team.