Skip to main content

Settlement Mechanism

How Pelago aggregates and settles payments to merchant wallets.

Settlement Overview​

Pelago uses batch settlement to optimize costs and efficiency:

Settlement Modes​

Instant Settlement​

For high-priority payments:

  • Immediate on-chain transfer
  • Higher fee (0.5% vs 0.1%)
  • Suitable for large transactions
const payment = await pelago.payments.create({
  amount: 10000.00,
  settlementMode: 'instant', // 👈 Instant settlement
  // ...
});

Batch Settlement (Default)​

Standard settlement mode:

  • Aggregated with other payments
  • Lower fees
  • 15-30 minute settlement windows
const payment = await pelago.payments.create({
  amount: 100.00,
  settlementMode: 'batch', // 👈 Default behavior
  // ...
});

Scheduled Settlement​

Custom settlement schedules:

  • Daily, weekly, or monthly
  • Scheduled time slots
  • Minimum threshold options
// Configure merchant settlement schedule
await pelago.merchants.updateSettings({
  settlementSchedule: {
    frequency: 'daily',
    time: '18:00',
    timezone: 'UTC',
    minimumAmount: 100.00
  }
});

Settlement Timeline​

Fee Structure​

Settlement TypeFeeProcessing Time
Instant0.5%< 1 minute
Batch (default)0.1%15-30 minutes
Scheduled0.08%Next window

Fee Calculation​

Settlement Fee = Payment Amount × Fee Rate
Network Gas = Shared across batch (minimal per payment)

Example: $100 payment, batch settlement
- Fee: $100 × 0.1% = $0.10
- Merchant receives: $99.90

Settlement Reports​

Accessing Settlement History​

// Get settlement history
const settlements = await pelago.settlements.list({
  startDate: '2025-01-01',
  endDate: '2025-01-31',
  status: 'completed'
});

for (const settlement of settlements.data) {
  console.log(`
    ID: ${settlement.id}
    Amount: $${settlement.amount}
    Payments: ${settlement.paymentCount}
    TX Hash: ${settlement.transactionHash}
    Settled At: ${settlement.settledAt}
  `);
}

Settlement Webhook​

{
  "id": "evt_settle_123",
  "type": "settlement.completed",
  "created": "2025-02-08T22:30:00Z",
  "data": {
    "settlementId": "stl_abc123",
    "merchantId": "mer_xyz789",
    "totalAmount": 1250.00,
    "currency": "USDC",
    "paymentCount": 15,
    "fees": 1.25,
    "netAmount": 1248.75,
    "transactionHash": "abc123...def456",
    "wallet": "GXXXXX..."
  }
}

Settlement Reconciliation​

Payment to Settlement Mapping​

Reconciliation API​

// Get payments in a settlement
const details = await pelago.settlements.getDetails('stl_abc123');

console.log('Settlement:', details.id);
console.log('Total:', details.totalAmount);
console.log('Payments:');

for (const payment of details.payments) {
  console.log(`  - ${payment.id}: $${payment.amount}`);
}

Multi-Currency Settlement​

For merchants accepting multiple currencies:

// Configure preferred settlement currency
await pelago.merchants.updateSettings({
  settlementCurrency: 'USDC',
  autoConvert: true
});

Handling Settlement Failures​

Retry Logic​

  1. Settlement failure detected
  2. Automatic retry after 5 minutes
  3. Up to 3 retry attempts
  4. Manual intervention if all fail

Failure Webhook​

{
  "type": "settlement.failed",
  "data": {
    "settlementId": "stl_abc123",
    "reason": "insufficient_gas",
    "retryCount": 2,
    "nextRetryAt": "2025-02-08T22:45:00Z"
  }
}

Best Practices​

  1. Monitor settlements: Set up alerts for failures
  2. Reconcile daily: Match payments to settlements
  3. Use instant sparingly: Higher fees add up
  4. Set thresholds: Avoid micro-settlements

Next Steps​