Recipient Validation

Tupel provides detailed validation rules for recipient bank accounts across different currencies. These rules help ensure that payment information is correctly formatted before attempting to create a recipient or process a payment.

Validation Rules Endpoint

You can retrieve the current validation rules by currency using the following endpoint:

GET https://tupel.com/api/recipients/rules/

Authentication

This endpoint requires basic authentication with your Organization ID and API Key.

Understanding Validation Rules

For each currency, the rules include:

• required - An array of fields that must be provided for this currency
• For each field:
• min_length - Minimum number of characters
• max_length - Maximum number of characters
• regex - Regular expression pattern to validate the field
• example - A sample valid value
• name - The display name for the field (e.g., "Sort Code" instead of "bank_code")

Three Worked Examples

Below we provide detailed examples for three of our main currencies: USD, EUR, GBP. Using these three examples together with the currency rules provided in the response you will be able to deal with all other currencies supported by tupel as well.

USD (United States Dollar)

USD bank accounts require three pieces of information:
1. Account Type - Either CHECKING or SAVINGS
2. Routing Number (bank_code) - A 9-digit number that identifies the financial institution
3. Account Number - A 4-17 digit number that identifies the specific account

Example:

{
  "type": "CHECKING",
  "bank_code": "022000020",
  "account_number": "12345678"
}

EUR (Euro)

EUR accounts use the IBAN (International Bank Account Number) format:
1. IBAN (account_number)
- Includes country code, check digits, and bank account details
- Format varies by country but follows ISO 13616 standard
- Length varies between 14-42 characters depending on the country

Example:

{
  "account_number": "DE89370400440532013000"
}

GBP (British Pound)

GBP accounts require:
1. Sort Code (bank_code) - A 6-digit number that identifies the bank and branch
2. Account Number - An 8-digit number that identifies the specific account

Example:

{
  "bank_code": "403020",
  "account_number": "12345678"
}

Implementing Validation

When creating recipients, you should:

1. First call the validation rules endpoint to get the latest requirements
2. Validate input against these rules before submission
3. Format input according to the requirements (e.g., removing spaces or special characters if not allowed)
4. Include all required fields for the specific currency

Best Practices

• Cache validation rules but refresh them periodically to stay current with any updates
• Implement client-side validation using the returned regex patterns
• Provide clear field labels to users based on the name value for each field
• Include the example values as placeholder text in your UI
• Pre-format input fields to match the expected format (e.g., add dashes or spaces where appropriate)
• For IBAN validation, consider using a checksum validation library in addition to the regex pattern