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

🏢Vendor Payments

Pay suppliers and vendors for goods and services

👔Contractor Payouts

Send payments to freelancers and contractors

↩️Refunds

Return payments to customers

🤝Marketplace Settlements

Pay sellers on your marketplace platform

How It Works

High-Level Flow

Check your virtual balance

Ensure you have sufficient funds

Create provider contact

Store provider information and bank account

Create PAYOUT order

Specify amount and destination bank account

Funds are debited

Money is immediately reserved from your virtual account

Bank transfer initiated

Koywe initiates transfer to provider’s bank

Provider receives funds

Settlement time varies by country (instant to 24 hours)

You receive confirmation

Webhook notification when transfer completes

Detailed Flow Diagram

Prerequisites

Before making payouts:

Required:

✅ Sufficient funds in virtual account
✅ Provider contact created
✅ Provider bank account linked
✅ Bank account details verified

Critical: Always check your virtual account balance before creating a PAYOUT order. Orders will fail if you have insufficient funds.

Supported Countries

Colombia 🇨🇴

Method: Direct bank transfer
Currency: COP
Settlement: 1-2 hours (business hours)
Banks: All Colombian banks

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: Bank transfer
Currency: CLP
Settlement: 1-2 business days
Banks: All Chilean banks

Argentina 🇦🇷

Method: Bank transfer
Currency: ARS
Settlement: 1-2 business days
Banks: All Argentine banks

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, {
  fullName: 'Servicios ABC SAS',
  email: 'provider@example.com',
  country: 'CO',
  documentType: 'NIT',
  documentNumber: '900123456-1',
  businessType: 'COMPANY'
});
 
// 3. Add bank account
const bankAccount = await addBankAccount(token, orgId, merchantId, provider.id, {
  country: 'CO',
  currency: 'COP',
  bankCode: 'BANCOLOMBIA',
  accountNumber: '1234567890',
  accountType: 'checking',
  holderName: 'Servicios ABC SAS'
});
 
// 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

Feature	PAYIN	PAYOUT
Direction	Customer → Your account	Your account → Provider
Balance	Credits your account	Debits your account
Payment URL	Yes (for customer)	No
Bank Account	Optional	Required
Contact	Optional	Recommended
Balance Check	Not needed	Critical

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:

Country	Method	Typical Settlement
Colombia	Bank Transfer	1-2 hours (business hours)
Brazil	PIX	Instant (24/7)
Mexico	SPEI	Instant ⚡
Chile	Bank Transfer	1-2 business days
Argentina	Bank Transfer	1-2 business days

Business Hours: For countries with business-hour restrictions, transfers initiated after hours or on weekends may be processed the next business day.

Next Steps

💻Integration Guide

Step-by-step implementation with code examples

✅Payout Scenarios

Common payout use cases and examples

👛Virtual Accounts

Learn about balance management

🧪Testing Guide

Test payouts in sandbox environment