Field Validation

Proper field validation is essential for successful API integration. This guide documents field validation rules that apply to the Pave Bank API (apiv1), helping you avoid common integration errors.

SWIFT Character Set X (Char Set X)

Some fields use SWIFT Char Set X, a standardized set of characters permitted for international payment processing.

Allowed Characters

The following characters are permitted in Char Set X fields:

• Letters: a-z, A-Z
• Numbers: 0-9
• Special characters: /, -, ?, :, (, ), ., ,, ', +, and spaces

Pattern: ^[a-zA-Z0-9/\-?:()\.,'\+\s]*$

Examples

Valid Beneficiary Name:

John Smith-Jones

Invalid Beneficiary Name:

John Smith@Jones (contains @ symbol)
John Smith & Co. (contains & symbol)

Valid API Request:

{
    "beneficiary_name": "ACME Corp - Branch 3",
    "account_number": "123456789",
    "address_line_1": "123 Main Street",
    "postal_code": "12345",
    "remittance_info": "Invoice 12345 / Payment"
}

ISO Country Codes

All country-related fields use ISO 3166-1 alpha-2 format—a standardized two-letter country code.

Format

Country codes are exactly 2 uppercase letters, for example:

• US - United States
• GB - United Kingdom
• SG - Singapore
• DE - Germany
• JP - Japan

Common Pitfall: Using 3-Letter Codes

A frequent error is using ISO 3166-1 alpha-3 (3-letter) codes instead of alpha-2. These will be rejected:

Examples

Valid Country Code in Address:

{
    "country": "US",
    "town_name": "New York",
    "post_code": "10001"
}

Invalid Country Code:

{
    "country": "USA" // Error: Must be 2-letter ISO code
}

Error Response:

{
    "code": "invalid_argument",
    "message": "country_code: must be a valid two-letter country code",
    "details": null
}

ISO Currency Codes

Currency amounts in the Pave Bank API use ISO 4217 three-letter codes. For detailed information about currency representations and minor units, see the Currencies guide.

Format

Currency codes are exactly 3 uppercase letters, for example:

• USD - US Dollar
• EUR - Euro
• GBP - British Pound
• JPY - Japanese Yen
• HUF - Hungarian Forint

Examples

Valid Currency Transfer:

{
    "currency": "USD",
    "amount": "10000",
    "description": "Payment"
}

BIC/SWIFT Code Validation

BIC (Business Identifier Code), also known as SWIFT code, is required for international transfers. It must follow a specific format.

Format Requirements

BIC codes are either 8 or 11 characters long with the following structure:

Complete Structure

8-character BIC (no branch):

PBNKUS33
├─ Institution: PBNK
├─ Country: US
├─ Location: 33
└─ Branch: (omitted, defaults to XXX)

11-character BIC (with branch):

PBNKUSNYCLX
├─ Institution: PBNK
├─ Country: US
├─ Location: NY
└─ Branch: CLX

Examples

Valid 8-Character BIC:

{
    "bic": "DEUTDEFF" // Deutsche Bank in Frankfurt
}

Valid 11-Character BIC:

{
    "bic": "DEUTDEFFHAM" // Deutsche Bank in Hamburg
}

Invalid BIC Format:

{
    "bic": "PBNK" // Error: Too short (must be 8 or 11 characters)
}

Other Common Validation Rules

Account Names

Account names must contain only letters, numbers, spaces, and hyphens.

• Pattern: ^[a-zA-Z0-9\s\-]+$
• Length: 1-250 characters

Valid:

John Smith
ABC Company - Branch 3
Account-123

Invalid:

John@Smith (contains @)
ABC Company & Co. (contains &)

Email Addresses

When email notifications are enabled, a valid email address is required.

Valid:

[email protected]
[email protected]

Invalid:

user@invalid
[email protected]
invalid.email

Structured Address Fields (Nominal Accounts)

Addresses follow a specific structure with required and optional fields:

Valid Complete Address:

{
    "country": "US",
    "post_code": "10001",
    "town_name": "New York",
    "country_subdivision": "NY",
    "street_name": "Broadway",
    "building_number": "123",
    "building_name": "Empire State",
    "floor": "10"
}