Get Payers

The Payers endpoint returns available payout providers for a specific country and currency. Each payer has specific requirements for beneficiary information, supported transaction types, and amount limits.

Endpoint

Property	Value
Method	`GET`
URL	`/api/v1/pay-out/payers`
Authentication	Basic Auth (Business Key + Secret)

Query Parameters

Parameter	Type	Required	Description
`country_iso_code`	string	Recommended	ISO-3 country code to filter payers (e.g., `BRA`, `MEX`)
`currency`	string	Recommended	ISO-4217 currency code (e.g., `BRL`, `MXN`)
`service_id`	integer	No	Filter by service type (1=Cash, 2=Bank, 3=Wallet)
`per_page`	integer	No	Results per page (default: 100, max: 500)
`page`	integer	No	Page number for pagination

Request Example

curl -X GET "https://api.cashela.com/api/v1/pay-out/payers?country_iso_code=BRA&currency=BRL" \
  -H "Authorization: Basic $(echo -n 'your_key:your_secret' | base64)" \
  -H "Accept: application/json"

Response Example

{
  "success": true,
  "data": {
    "total": 45,
    "per_page": 100,
    "current_page": 1,
    "last_page": 1,
    "data": [
      {
        "id": 45,
        "name": "BANCO SANTANDER BRASIL S.A",
        "code": "santander_br",
        "currency": "BRL",
        "country_iso_code": "BRA",
        "service": {
          "id": 2,
          "name": "BankAccount"
        },
        "logo_url": "https://assets.cashela.com/payers/santander.png",
        "transaction_types": [
          {
            "transaction_type": "C2C",
            "name": "Customer to Customer",
            "minimum_amount": 10.00,
            "maximum_amount": 50000.00,
            "precision": 2,
            "required_sending_entity_fields": [
              "first_name",
              "last_name",
              "date_of_birth",
              "id_type",
              "id_number",
              "country_iso_code",
              "address"
            ],
            "required_receiving_entity_fields": [
              "first_name",
              "last_name",
              "id_number",
              "email",
              "msisdn"
            ],
            "credit_party_identifiers_accepted": [
              {
                "key": "bank_account_number",
                "description": "Bank account number",
                "regex": "^[0-9]{5,20}$",
                "required": true
              },
              {
                "key": "branch_number",
                "description": "Bank branch code (agência)",
                "regex": "^[0-9]{4}$",
                "required": true
              },
              {
                "key": "bank_account_type",
                "description": "Account type",
                "allowed_values": ["CHECKING", "SAVINGS"],
                "required": true
              }
            ],
            "required_documents": [],
            "purpose_of_remittance_values_accepted": [
              "FAMILY_SUPPORT",
              "EDUCATION",
              "MEDICAL",
              "SAVINGS",
              "TRAVEL",
              "GOODS_SERVICES"
            ]
          }
        ],
        "estimated_delivery": {
          "minimum_hours": 0,
          "maximum_hours": 24,
          "description": "Same day to next business day"
        },
        "cut_off_time": "16:00",
        "cut_off_timezone": "America/Sao_Paulo"
      },
      {
        "id": 78,
        "name": "PIX Instant Transfer",
        "code": "pix_br",
        "currency": "BRL",
        "country_iso_code": "BRA",
        "service": {
          "id": 2,
          "name": "BankAccount"
        },
        "transaction_types": [
          {
            "transaction_type": "C2C",
            "name": "Customer to Customer",
            "minimum_amount": 1.00,
            "maximum_amount": 100000.00,
            "credit_party_identifiers_accepted": [
              {
                "key": "pix_key",
                "description": "PIX key (CPF, email, phone, or random key)",
                "regex": "^.{1,77}$",
                "required": true
              }
            ]
          }
        ],
        "estimated_delivery": {
          "minimum_hours": 0,
          "maximum_hours": 0,
          "description": "Instant (24/7)"
        }
      }
    ]
  },
  "message": "Payers retrieved successfully"
}

Response Fields

Payer Object

Field	Type	Description
`id`	integer	Unique payer identifier. Use this in quotation and transaction requests
`name`	string	Display name of the payer
`code`	string	Internal code identifier
`currency`	string	Currency supported (ISO-4217)
`country_iso_code`	string	Country served (ISO-3)
`service`	object	Service type information
`logo_url`	string	URL to payer logo for display
`transaction_types`	array	Supported transaction types with requirements
`estimated_delivery`	object	Delivery time estimates
`cut_off_time`	string	Daily processing cutoff (local time)
`cut_off_timezone`	string	Timezone for cutoff time

Transaction Type Object

Field	Type	Description
`transaction_type`	string	Type code: `C2C`, `C2B`, `B2C`, `B2B`
`name`	string	Human-readable type name
`minimum_amount`	number	Minimum transaction amount
`maximum_amount`	number	Maximum transaction amount
`precision`	integer	Decimal precision for amounts
`required_sending_entity_fields`	array	Fields required for sender KYC
`required_receiving_entity_fields`	array	Fields required for beneficiary KYC
`credit_party_identifiers_accepted`	array	Bank/wallet account details required
`required_documents`	array	Document uploads required (if any)
`purpose_of_remittance_values_accepted`	array	Valid purpose codes for this payer

Credit Party Identifier Object

Field	Type	Description
`key`	string	Field name to use in transaction request
`description`	string	Human-readable field description
`regex`	string	Validation pattern (if applicable)
`allowed_values`	array	Valid values (if applicable)
`required`	boolean	Whether field is mandatory

Service Types

Service ID	Name	Description
1	Cash	Cash pickup at retail locations
2	BankAccount	Bank account transfer
3	MobileWallet	Mobile money or digital wallet
4	CardDeposit	Debit/credit card deposit

Transaction Types

Code	Description
`C2C`	Customer to Customer - Personal remittance
`C2B`	Customer to Business - Bill payment, merchant payment
`B2C`	Business to Customer - Payroll, disbursements
`B2B`	Business to Business - Supplier payments

Usage Example

Building a Dynamic Beneficiary Form

Use the payer requirements to build your beneficiary data collection form:

async function buildBeneficiaryForm(payerId) {
  // 1. Fetch payer details
  const response = await api.getPayers({ payer_id: payerId });
  const payer = response.data.data[0];

  // 2. Get required fields for C2C transaction
  const txType = payer.transaction_types.find(t => t.transaction_type === 'C2C');

  // 3. Build form fields
  const formFields = [];

  // Add credit party identifiers (bank account details)
  for (const identifier of txType.credit_party_identifiers_accepted) {
    formFields.push({
      name: identifier.key,
      label: identifier.description,
      type: identifier.allowed_values ? 'select' : 'text',
      options: identifier.allowed_values || null,
      validation: identifier.regex,
      required: identifier.required
    });
  }

  // Add beneficiary KYC fields
  for (const field of txType.required_receiving_entity_fields) {
    formFields.push({
      name: `beneficiary.${field}`,
      label: formatFieldLabel(field),
      type: getFieldType(field),
      required: true
    });
  }

  return formFields;
}

function formatFieldLabel(field) {
  const labels = {
    'first_name': 'First Name',
    'last_name': 'Last Name',
    'id_number': 'Document Number',
    'email': 'Email Address',
    'msisdn': 'Phone Number'
  };
  return labels[field] || field.replace(/_/g, ' ');
}

Filtering by Service Type

// Get only bank transfer payers for Mexico
const bankPayers = await api.getPayers({
  country_iso_code: 'MEX',
  currency: 'MXN',
  service_id: 2  // BankAccount
});

// Get only cash pickup locations for Colombia
const cashPayers = await api.getPayers({
  country_iso_code: 'COL',
  currency: 'COP',
  service_id: 1  // Cash
});

Best Practices

Cache payer list – Refresh every few hours rather than on each request
Validate before submitting – Use the regex patterns and allowed values provided
Show delivery estimates – Display estimated delivery time to users
Handle cutoff times – Warn users about processing cutoffs
Support multiple transaction types – Some payers support both C2C and B2C

function shouldWarnAboutCutoff(payer) {
  if (!payer.cut_off_time) return false;

  const now = new Date();
  const [hours, minutes] = payer.cut_off_time.split(':').map(Number);

  // Convert to payer's timezone
  const payerTime = new Date(now.toLocaleString('en-US', {
    timeZone: payer.cut_off_timezone
  }));

  const cutoffMinutes = hours * 60 + minutes;
  const currentMinutes = payerTime.getHours() * 60 + payerTime.getMinutes();

  // Warn if within 30 minutes of cutoff
  return (cutoffMinutes - currentMinutes) <= 30 && (cutoffMinutes - currentMinutes) > 0;
}

Common Errors

HTTP Code	Error Code	Description
400	`INVALID_COUNTRY`	Invalid or unsupported country code
400	`INVALID_CURRENCY`	Invalid or unsupported currency code
401	`UNAUTHORIZED`	Invalid authentication credentials
404	`NO_PAYERS_FOUND`	No payers available for the specified filters

Get Countries – Supported destination countries
Get Services – Available payout services
Create Quotation – Get rates for a specific payer
Create Transaction – Submit a payout using a payer