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

1. 1

   Check your virtual balance

   Ensure you have sufficient funds

2. 2

   Create provider contact

   Store provider information and bank account

3. 3

   Create PAYOUT order

   Specify amount and destination bank account

4. 4

   Funds are debited

   Money is immediately reserved from your virtual account

5. 5

   Bank transfer initiated

   Koywe initiates transfer to provider’s bank

6. 6

   Provider receives funds

   Settlement time varies by country and destination bank (instant to the next business day)

7. 7

   You receive confirmation

   Webhook notification when transfer completes

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 ⚡, 24/7
• Limits: No limit
• Banks: All Mexican banks

Chile 🇨🇱

• Method: Bulk payment file
• Currency: CLP
• Settlement: 24/7, within 5 minutes
• Limits: No per-transaction limit. Large amounts are paid out in batches of transfers of CLP 7,000,000 each
• Banks: All Chilean banks

Argentina 🇦🇷

• Method: Transfer to a named CVU
• Currency: ARS
• Settlement: Instant ⚡, 24/7 including weekends and holidays. No cut-off time
• Limits: Minimum ARS 1, no per-transaction maximum
• Banks: All Argentine banks. Named accounts only — the beneficiary’s identity has to match

Peru 🇵🇪

• Method: Wire transfer
• Currency: PEN, USD
• Banks: All Peruvian banks
• Limits: Minimum PEN 1. Maximum PEN 420,000 / USD 75,000 per transfer to Interbank and other banks. No maximum to BCP (for USD, BCP to BCP)
• Settlement: The same times apply to PEN and USD, and depend on the destination bank:

Other banks — the credit time depends on when the payout is sent (Peru time):

Bolivia 🇧🇴

• Method: Bank transfer
• Currency: BOB
• Settlement: Up to 20 minutes, 24/7, except during the ACH system cut-off window between 23:50 and 00:10. Payouts received in that window are processed as soon as the system is back
• Limits: Minimum equivalent to USD 1, no per-transaction maximum
• Compliance review: Payouts up to USD 1,000 are sent automatically. Above that, the payout goes through a compliance review before it is executed
• 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: '9001234561',
  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 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