Field Validation Rules

All Cashela API requests must pass validation before processing. This guide covers the data types, formats, regex patterns, and business rules applied to request fields.

---

Data Types

String

Property	Description
Encoding	UTF-8
Max length	255 characters (unless otherwise specified)
Trimming	Leading/trailing whitespace is trimmed
Null handling	Empty strings are treated as null for optional fields

Number

Property	Description
Integer	Whole numbers only (e.g., 100, 42)
Decimal	Floating point with up to 2 decimal places for amounts (e.g., 100.50)
Precision	Amounts use banker’s rounding
Negative	Not allowed for amounts

Boolean

Property	Description
Values	true or false (lowercase)
Strings	"true" and "false" are not automatically converted

Date/DateTime

Property	Description
Format	ISO-8601 (e.g., 2025-01-15T10:30:00.000Z)
Timezone	UTC preferred; local times are converted to UTC
Date only	YYYY-MM-DD format (e.g., 1990-05-15)

---

Standard Field Formats

Country Codes

Standard	Format	Example
ISO 3166-1 alpha-3	3-letter uppercase	MEX, USA, BRA, COL

Valid countries for PayIn and PayOut are returned by the respective endpoints.

Currency Codes

Standard	Format	Example
ISO 4217	3-letter uppercase	USD, MXN, BRL, COP

Phone Numbers

Standard	Format	Example
E.164	+ followed by country code and number	+521234567890, +5511999999999

{
  "phone": "+521234567890",
  "msisdn": "+5511999999999"
}

Email Addresses

Validation	Description
Format	RFC 5322 compliant
Max length	254 characters
Case	Case-insensitive, stored lowercase

^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$

Amounts

Constraint	Description
Minimum	Varies by payment method (typically 10.00)
Maximum	Varies by payment method and country
Precision	2 decimal places
Format	Numeric, no thousand separators

{
  "amount": 1500.00,
  "currency": "MXN"
}

---

Document Validation

Document numbers are validated based on the document type and country. Each country has specific regex patterns and validation rules.

Mexico (MEX)

Document Type	Format	Example
RFC (Tax ID)	12-13 alphanumeric	XAXX010101000
CURP	18 alphanumeric	XXXX000000XXXXXX00
INE/IFE	13 or 18 digits	1234567890123
Passport	9 alphanumeric	G12345678

Brazil (BRA)

Document Type	Format	Example
CPF	11 digits	12345678901
CNPJ	14 digits	12345678000195
RG	7-14 alphanumeric	123456789

Colombia (COL)

Document Type	Format	Example
CC (Cédula)	6-10 digits	12345678
NIT	9-10 digits	901234567
CE (Foreigner ID)	6-7 digits	1234567

---

Field Validation Structure

Payment methods return mandatory_fields that specify validation rules:

{
  "mandatory_fields": [
    {
      "fieldName": "document_number",
      "fieldRegex": "^[0-9]{10,13}$",
      "type": "text",
      "required": true,
      "description": "National ID number"
    },
    {
      "fieldName": "email",
      "fieldRegex": "^[^@]+@[^@]+\\.[^@]+$",
      "type": "email",
      "required": true,
      "description": "Customer email address"
    },
    {
      "fieldName": "amount",
      "type": "number",
      "required": true,
      "min": 10.00,
      "max": 50000.00,
      "description": "Payment amount in local currency"
    }
  ]
}

Field Schema Properties

Property	Type	Description
fieldName	string	API field name to use in request
fieldRegex	string	Regular expression for validation
type	string	Data type: text, email, number, date, select
required	boolean	Whether the field is mandatory
min	number	Minimum value (for numbers)
max	number	Maximum value (for numbers)
minLength	number	Minimum character length (for strings)
maxLength	number	Maximum character length (for strings)
allowedValues	array	List of valid values (for select fields)
description	string	Human-readable field description

---

Payment Type Values

Code	Description
CARD	Credit or debit card
CREDIT_CARD	Credit card only
DEBIT_CARD	Debit card only
BANK_TRANSFER	Bank transfer (SPEI, PIX, etc.)
CASH	Cash payment at retail location
WALLET	Digital wallet
VOUCHER	Payment voucher

---

Client-Side Validation

Implement client-side validation using the mandatory_fields from the API:

function validateField(value, fieldConfig) {
  const errors = [];

  // Required check
  if (fieldConfig.required && (!value || value.trim() === '')) {
    errors.push(`${fieldConfig.fieldName} is required`);
    return errors;
  }

  // Skip further validation if empty and not required
  if (!value) return errors;

  // Type-specific validation
  switch (fieldConfig.type) {
    case 'email':
      const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
      if (!emailRegex.test(value)) {
        errors.push('Invalid email format');
      }
      break;

    case 'number':
      const num = parseFloat(value);
      if (isNaN(num)) {
        errors.push('Must be a number');
      } else {
        if (fieldConfig.min !== undefined && num < fieldConfig.min) {
          errors.push(`Minimum value is ${fieldConfig.min}`);
        }
        if (fieldConfig.max !== undefined && num > fieldConfig.max) {
          errors.push(`Maximum value is ${fieldConfig.max}`);
        }
      }
      break;

    case 'text':
      if (fieldConfig.minLength && value.length < fieldConfig.minLength) {
        errors.push(`Minimum length is ${fieldConfig.minLength} characters`);
      }
      if (fieldConfig.maxLength && value.length > fieldConfig.maxLength) {
        errors.push(`Maximum length is ${fieldConfig.maxLength} characters`);
      }
      break;
  }

  // Regex validation
  if (fieldConfig.fieldRegex) {
    const regex = new RegExp(fieldConfig.fieldRegex);
    if (!regex.test(value)) {
      errors.push(`Invalid format for ${fieldConfig.fieldName}`);
    }
  }

  // Allowed values check
  if (fieldConfig.allowedValues && !fieldConfig.allowedValues.includes(value)) {
    errors.push(`Invalid value. Allowed: ${fieldConfig.allowedValues.join(', ')}`);
  }

  return errors;
}

// Usage
const fieldConfig = {
  fieldName: 'document_number',
  fieldRegex: '^[0-9]{10,13}$',
  type: 'text',
  required: true
};

const errors = validateField('1234567890', fieldConfig);
if (errors.length > 0) {
  console.error('Validation errors:', errors);
}

---

Validation Error Responses

When validation fails, the API returns detailed error information:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "document_number": "Invalid format. Expected pattern: ^[0-9]{10,13}$",
      "amount": "Amount must be between 10.00 and 50000.00 MXN",
      "email": "Invalid email format"
    }
  },
  "request_id": "req_01HJ3KBCD8E9F0G1H2I3J4K5L6"
}

---

Best Practices

1. Validate Before Submitting

Always validate data client-side before making API calls to improve user experience and reduce failed requests.

2. Use Dynamic Validation Rules

Fetch and cache mandatory_fields from the API to stay current with validation rules:

async function getPaymentMethodValidation(methodCode, countryCode) {
  const cacheKey = `validation_${methodCode}_${countryCode}`;
  const cached = cache.get(cacheKey);

  if (cached && cached.expiresAt > Date.now()) {
    return cached.fields;
  }

  const response = await api.getPaymentMethods({
    country: countryCode,
    payment_method: methodCode
  });

  const fields = response.data.mandatory_fields;
  cache.set(cacheKey, {
    fields,
    expiresAt: Date.now() + 3600000 // 1 hour cache
  });

  return fields;
}

3. Display Clear Error Messages

Map technical validation errors to user-friendly messages:

const fieldLabels = {
  'document_number': 'ID Number',
  'email': 'Email Address',
  'phone': 'Phone Number',
  'amount': 'Payment Amount'
};

function formatValidationError(field, error) {
  const label = fieldLabels[field] || field;
  return `${label}: ${error}`;
}

4. Handle Country-Specific Rules

Different countries have different validation requirements. Always fetch the latest rules:

// Mexico requires RFC for certain payment methods
// Brazil requires CPF
// Colombia requires CC (Cédula de Ciudadanía)

function getDocumentLabel(countryCode) {
  const labels = {
    'MEX': 'RFC / CURP',
    'BRA': 'CPF / CNPJ',
    'COL': 'Cédula de Ciudadanía'
  };
  return labels[countryCode] || 'Document Number';
}

---

Related Documentation

• Error Handling – Understanding validation error responses
• PayIn Create Deposit – Field requirements for deposits
• PayOut Transaction – Field requirements for payouts