1
app.post('/webhooks/koywe', express.raw({type: 'application/json'}), async (req, res) => {
2
  // Convert raw body to string once
3
  const rawBody = req.body.toString();
4
  
5
  // Verify signature with string body
6
  const signature = req.headers['koywe-signature'];
7
  if (!verifySignature(rawBody, signature, process.env.KOYWE_WEBHOOK_SECRET)) {
8
    return res.status(401).send('Invalid signature');
9
  }
10
  
11
  // Parse JSON from string
12
  const event = JSON.parse(rawBody);
13
  
14
  switch (event.type) {
15
    case 'order.processing':
16
      console.log('Payout processing:', event.data.orderId);
17
      // Update internal status
18
      await updatePayoutStatus(event.data.externalId, 'processing');
19
      break;
20
      
21
    case 'order.completed':
22
      console.log('Payout completed:', event.data.orderId);
23
      // Mark as paid in your system
24
      await markInvoiceAsPaid(event.data.externalId);
25
      await notifyProvider(event.data.externalId);
26
      break;
27
      
28
    case 'order.failed':
29
      console.log('Payout failed:', event.data.orderId);
30
      // Handle failure
31
      await handlePayoutFailure(event.data.externalId, event.data.errorMessage);
32
      break;
33
  }
34
  
35
  res.status(200).send('OK');
36
});

1
async function waitForPayoutCompletion(token, orgId, merchantId, orderId, maxAttempts = 20) {
2
  for (let i = 0; i < maxAttempts; i++) {
3
    const order = await axios.get(
4
      `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders/${orderId}`,
5
      { headers: { 'Authorization': `Bearer ${token}` } }
6
    );
7
    
8
    const status = order.data.status;
9
    console.log(`Attempt ${i + 1}: Status = ${status}`);
10
    
11
    if (status === 'COMPLETED') {
12
      console.log('✓ Payout completed successfully');
13
      return order.data;
14
    }
15
    
16
    if (status === 'FAILED') {
17
      throw new Error(`Payout failed: ${order.data.errorMessage}`);
18
    }
19
    
20
    // Wait 5 seconds before checking again
21
    await new Promise(resolve => setTimeout(resolve, 5000));
22
  }
23
  
24
  throw new Error('Timeout waiting for payout completion');
25
}
26
27
// Usage
28
const completed = await waitForPayoutCompletion(token, orgId, merchantId, payout.id);
29
console.log('Payout completed at:', completed.dates.deliveryDate);

1
async function payProvider(providerData, bankData, payoutData) {
2
  try {
3
    // 1. Authenticate
4
    console.log('1. Authenticating...');
5
    const token = await authenticate();
6
    
7
    // 2. Check balance
8
    console.log('\n2. Checking balance...');
9
    const balance = await getBalance(token, orgId, merchantId, payoutData.currency);
10
    console.log(`Available: ${balance.availableBalance} ${payoutData.currency}`);
11
    
12
    if (balance.availableBalance < payoutData.amount) {
13
      throw new Error(`Insufficient balance. Need ${payoutData.amount}, have ${balance.availableBalance}`);
14
    }
15
    
16
    // 3. Create or get provider contact
17
    console.log('\n3. Creating provider contact...');
18
    const provider = await createProviderContact(token, orgId, merchantId, providerData);
19
    console.log('✓ Provider contact:', provider.id);
20
    
21
    // 4. Add bank account
22
    console.log('\n4. Adding bank account...');
23
    const bankAccount = await addProviderBankAccount(token, orgId, merchantId, provider.id, bankData);
24
    console.log('✓ Bank account:', bankAccount.id);
25
    
26
    // 5. Create payout
27
    console.log('\n5. Creating payout order...');
28
    const payout = await createPayoutOrder(token, orgId, merchantId, {
29
      ...payoutData,
30
      contactId: provider.id,
31
      destinationAccountId: bankAccount.id
32
    });
33
    console.log('✓ Payout created:', payout.id);
34
    console.log('✓ Status:', payout.status);
35
    
36
    // 6. Wait for completion (or use webhooks in production)
37
    console.log('\n6. Waiting for completion...');
38
    const completed = await waitForPayoutCompletion(token, orgId, merchantId, payout.id);
39
    console.log('✓ Payout completed');
40
    
41
    // 7. Update internal systems
42
    console.log('\n7. Updating internal records...');
43
    await markInvoiceAsPaid(payoutData.externalId);
44
    
45
    console.log('\n✅ Success! Provider has been paid.');
46
    
47
    return {
48
      success: true,
49
      payoutId: completed.id,
50
      amount: completed.amountIn,
51
      currency: completed.originCurrencySymbol
52
    };
53
    
54
  } catch (error) {
55
    console.error('❌ Error:', error.message);
56
    throw error;
57
  }
58
}
59
60
// Usage
61
await payProvider(
62
  {
63
    email: 'provider@example.com',
64
    fullName: 'Servicios ABC SAS',
65
    country: 'CO',
66
    documentType: 'NIT',
67
    documentNumber: '900123456-1',
68
    businessType: 'COMPANY'
69
  },
70
  {
71
    country: 'CO',
72
    currency: 'COP',
73
    bankCode: 'BANCOLOMBIA',
74
    accountNumber: '1234567890',
75
    accountType: 'checking',
76
    holderName: 'Servicios ABC SAS'
77
  },
78
  {
79
    currency: 'COP',
80
    amount: 500000,
81
    description: 'Payment for Invoice #INV-001',
82
    externalId: 'inv-001'
83
  }
84
);

1
async function safeCreatePayout(token, orgId, merchantId, payoutData) {
2
  const balance = await getBalance(token, orgId, merchantId, payoutData.currency);
3
  
4
  if (balance.availableBalance < payoutData.amount) {
5
    throw new Error('INSUFFICIENT_BALANCE');
6
  }
7
  
8
  return await createPayoutOrder(token, orgId, merchantId, payoutData);
9
}

1
// Use invoice ID or unique reference
2
const externalId = `payout-invoice-${invoiceId}`;
3
4
// Safe to retry - same externalId returns same order
5
const payout = await createPayoutOrder(token, orgId, merchantId, {
6
  ...payoutData,
7
  externalId: externalId
8
});

1
try {
2
  const payout = await createPayoutOrder(token, orgId, merchantId, payoutData);
3
} catch (error) {
4
  if (error.response?.data?.code === 'INSUFFICIENT_BALANCE') {
5
    // Handle insufficient balance
6
    await notifyAdminLowBalance();
7
  } else if (error.response?.data?.code === 'INVALID_BANK_ACCOUNT') {
8
    // Handle invalid bank details
9
    await requestBankAccountUpdate(providerId);
10
  } else {
11
    // Log and retry later
12
    await queuePayoutForRetry(payoutData);
13
  }
14
}