Paying Providers (PAYOUT)

Learn how to send payments from your virtual balance to external bank accounts.

What is PAYOUT?

PAYOUT is the order type used to send funds from your virtual balance account to external bank accounts (providers, vendors, contractors, etc.).

Use Cases

How It Works

High-Level Flow

Detailed Flow Diagram

Prerequisites

Before making payouts:

Supported Countries

The payout side of every corridor. For payin coverage, currencies and the local rail behind each one, see Supported Corridors & Currencies.

Colombia 🇨🇴

• Method: ACH Colombia, Bre-B
• Currency: COP
• Settlement: ACH runs on cycles; Bre-B settles in seconds
• Banks: All Colombian banks
• Bre-B destinations: declare rail: "BREB" on the destination account and put the key in accountNumber — see Payment Rails

Brazil 🇧🇷

• Method: PIX transfer
• Currency: BRL
• Settlement: Instant
• Banks: All Brazilian banks with PIX

Mexico 🇲🇽

• Method: SPEI transfer
• Currency: MXN
• Settlement: Instant ⚡
• Banks: All Mexican banks

Chile 🇨🇱

• Method: Bulk payment file
• Currency: CLP
• Settlement: Effectively instant. Transactions above CLP 7,000,000 are split into parts
• Banks: All Chilean banks

Argentina 🇦🇷

• Method: Transfer to a named CVU
• Currency: ARS
• Settlement: 1-2 business days
• Banks: All Argentine banks. Named accounts only — the beneficiary’s identity has to match

Peru 🇵🇪

• Method: Wire transfer
• Currency: PEN, USD
• Settlement: 1-2 business days
• Banks: All Peruvian banks

Bolivia 🇧🇴

• Method: Bank transfer
• Currency: BOB
• Settlement: 1-2 business days
• Banks: All Bolivian banks

Venezuela 🇻🇪

• Method: Bank transfer
• Currency: VES
• Settlement: 1-2 business days
• Banks: All Venezuelan banks
• Daily payout limit: $3,500 USD equivalent per day

United States 🇺🇸

• Method: Wire or ACH to a named account
• Currency: USD
• Settlement: 1-2 business days
• Banks: All US banks (routing number required)
• Note: Requires a separate KYB/KYC onboarding

Quick Example

Here’s a simple PAYOUT flow:

// 1. Check balance
const balance = await getBalance(token, orgId, merchantId, 'COP');
console.log('Available:', balance.availableBalance); // e.g., 1,000,000 COP
 
// 2. Create provider contact
const provider = await createContact(token, orgId, merchantId, {
  firstName: 'Servicios ABC SAS',
  countrySymbol: 'CO',
  documentType: 'NIT',
  documentNumber: '900123456-1',
  businessType: 'COMPANY',
  type: 'BUSINESS',
  email: 'provider@example.com'
});
 
// 3. Add bank account
const bankAccount = await addBankAccount(token, orgId, merchantId, provider.id, {
  name: 'Bancolombia COP',
  kind: 'BANK',
  isDefault: true,
  countrySymbol: 'CO',
  currencySymbol: 'COP',
  entity: 'BANCOLOMBIA',
  accountNumber: '1234567890',
  type: 'CHECKING'
});
 
// 4. Create PAYOUT order
const payout = await createPayoutOrder(token, orgId, merchantId, {
  type: 'PAYOUT',
  originCurrencySymbol: 'COP',
  destinationCurrencySymbol: 'COP',
  amountIn: 500000,  // 500,000 COP
  contactId: provider.id,
  destinationAccountId: bankAccount.id,
  description: 'Payment for Invoice #INV-001'
});
 
console.log('Payout created:', payout.id);
console.log('Status:', payout.status); // "PROCESSING"

Key Differences vs PAYIN

Payment Flow Comparison

PAYIN (Receiving)

Customer pays → Funds credited → Webhook → Fulfill order

PAYOUT (Sending)

Check balance → Create order → Funds debited → Bank transfer → Webhook confirmation

Balance Requirements

Checking Balance Before PAYOUT

async function safeCreatePayout(token, orgId, merchantId, payoutData) {
  // 1. Get current balance
  const balances = await getMerchantBalances(token, orgId, merchantId);
  const balance = balances.find(b => b.currencySymbol === payoutData.currency);
  
  // 2. Check available balance
  if (!balance || balance.availableBalance < payoutData.amount) {
    throw new Error(
      `Insufficient balance. Available: ${balance?.availableBalance || 0} ${payoutData.currency}, ` +
      `Required: ${payoutData.amount} ${payoutData.currency}`
    );
  }
  
  console.log(`✓ Sufficient balance: ${balance.availableBalance} ${payoutData.currency}`);
  
  // 3. Create payout
  const payout = await createPayoutOrder(token, orgId, merchantId, payoutData);
  
  return payout;
}

Settlement Times

Understanding when providers receive funds:

For every payout corridor, including Bolivia, Peru, Venezuela, the United States and cross-border settlement, see Supported Corridors & Currencies.

Next Steps

Additional Resources

• Core Concepts - Orders
• Contacts & Bank Accounts
• Error Handling
• API Reference