The Collections Lifecycle

Understanding how payment collections work in NextAPI, from payment link creation to fund settlement and wallet crediting.

Collections Overview

The collections process follows these key stages:

Payment Link Created → Customer Pays → Payment Processed → Funds Settled → Wallet Credited
        ↓                   ↓                ↓               ↓              ↓
   Link Generated    →   Payment Initiated →   Authorization →   Settlement →   Available Balance

Detailed Lifecycle

1. Payment Link Creation

State: link_created

Generate a payment link for collections:

const paymentLink = await nextapi.paymentLinks.create({
  amount: 50000,
  currency: 'PHP',
  description: 'Product Purchase',
  expires_at: '2024-12-31T23:59:59Z',
  customer: {
    email: 'customer@example.com',
    name: 'Juan Dela Cruz'
  }
});

Response:

{
  "id": "plink_123",
  "url": "https://pay.nextapi.com/plink_123",
  "status": "active",
  "amount": 50000,
  "expires_at": "2024-12-31T23:59:59Z"
}

2. Payment Initiation

State: payment_initiated

Customer clicks the payment link and initiates payment:

// Webhook event received
{
  "event": "payment_link.payment_initiated",
  "data": {
    "payment_link_id": "plink_123",
    "payment_id": "pay_456",
    "amount": 50000,
    "customer": {
      "email": "customer@example.com"
    },
    "payment_method": "gcash"
  }
}

3. Payment Processing

State: payment_processing

The payment is processed through the selected channel:

Processing Steps:

1. Customer Authentication: Verify customer identity
2. Payment Authorization: Get approval from payment provider
3. Risk Assessment: Check for fraud and compliance
4. Channel Processing: Send to payment channel (GCash, Maya, etc.)

4. Payment Completion

State: payment_completed

Payment successfully processed:

// Success webhook
{
  "event": "payment_link.completed",
  "data": {
    "payment_link_id": "plink_123",
    "payment_id": "pay_456",
    "amount": 50000,
    "currency": "PHP",
    "fees": {
      "processing_fee": 750,
      "platform_fee": 250
    },
    "net_amount": 49000,
    "payment_method": "gcash",
    "completed_at": "2024-01-15T10:30:00Z"
  }
}

5. Settlement

State: settling

Funds move from payment processor to NextAPI:

Settlement Timeline:

• Digital Wallets: Same day (within 24 hours)
• Bank Transfers: 1-2 business days
• Credit Cards: 2-3 business days
• Alternative Channels: Varies by provider

6. Wallet Credit

State: wallet_credited

Funds are credited to your wallet:

// Wallet credit webhook
{
  "event": "wallet.credited",
  "data": {
    "wallet_id": "wallet_789",
    "amount": 49000,
    "currency": "PHP",
    "reference_id": "plink_123",
    "transaction_id": "txn_101112",
    "balances": {
      "available": 149000,
      "pending": 0,
      "total": 149000
    }
  }
}

Payment Methods and Channels

Supported Payment Methods

Method	Processing Time	Settlement Time	Fees
GCash	Instant	Same day	1.5%
Maya	Instant	Same day	1.5%
Bank Transfer	1-2 days	1-2 days	₱15-25
Credit Card	Instant	2-3 days	2.5% + ₱10
QR Code	Instant	Same day	1.0%

Channel Selection Logic

// Automatic channel optimization
const paymentLink = await nextapi.paymentLinks.create({
  amount: 50000,
  currency: 'PHP',
  // Auto-select best channel based on:
  // - Amount size
  // - Customer preferences
  // - Cost efficiency
  // - Success rates
  channel_optimization: true
});

Fee Structure

Processing Fees

{
  "fee_breakdown": {
    "gross_amount": 50000,
    "processing_fee": 750,    // 1.5% for GCash
    "platform_fee": 250,      // 0.5% platform fee
    "total_fees": 1000,
    "net_amount": 49000
  },
  "fee_schedule": {
    "percentage_fee": 0.015,  // 1.5%
    "fixed_fee": 0,
    "platform_percentage": 0.005, // 0.5%
    "minimum_fee": 0
  }
}

Fee Tiers

Amount Range	Processing Fee	Platform Fee
₱1 - ₱1,000	2.0%	0.5%
₱1,001 - ₱10,000	1.5%	0.5%
₱10,001 - ₱50,000	1.5%	0.5%
₱50,001+	1.0%	0.5%

Error Handling

Common Collection Errors

// Payment expired
{
  "event": "payment_link.expired",
  "data": {
    "payment_link_id": "plink_123",
    "reason": "Payment link expired",
    "expired_at": "2024-12-31T23:59:59Z"
  }
}

// Payment failed
{
  "event": "payment_link.failed",
  "data": {
    "payment_link_id": "plink_123",
    "payment_id": "pay_456",
    "error_code": "INSUFFICIENT_BALANCE",
    "error_message": "Customer has insufficient balance"
  }
}

// Settlement failed
{
  "event": "payment.settlement_failed",
  "data": {
    "payment_id": "pay_456",
    "error_code": "SETTLEMENT_REJECTED",
    "retry_after": "2024-01-16T10:00:00Z"
  }
}

Retry Logic

// Automatic retry configuration
const paymentLink = await nextapi.paymentLinks.create({
  amount: 50000,
  retry_config: {
    "max_attempts": 3,
    "retry_intervals": [3600, 7200, 14400], // seconds
    "retry_on_errors": ["NETWORK_ERROR", "TIMEOUT"]
  }
});

Monitoring and Analytics

Collection Metrics

// Get collection performance
GET /v1/analytics/collections?period=30d

// Response
{
  "metrics": {
    "total_collected": 2500000,
    "total_fees": 37500,
    "net_collected": 2462500,
    "success_rate": 94.5,
    "average_processing_time": 45, // seconds
    "payment_methods": {
      "gcash": { "volume": 1500000, "count": 300 },
      "maya": { "volume": 750000, "count": 150 },
      "bank_transfer": { "volume": 250000, "count": 25 }
    }
  }
}

Real-time Dashboard

// WebSocket connection for real-time updates
const ws = new WebSocket('wss://api.nextapi.com/v1/stream');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  if (data.type === 'payment_update') {
    updateDashboard(data.payment);
  }
};

Best Practices

Payment Link Design

1. Clear descriptions: Help customers understand what they're paying for
2. Reasonable expiry: Balance urgency with convenience
3. Mobile optimization: Most customers pay on mobile devices
4. Multiple payment options: Offer various payment methods

Settlement Management

1. Track pending amounts: Monitor unsettled payments
2. Plan cash flow: Account for settlement delays
3. Reconcile daily: Match payments with bank statements
4. Handle disputes: Respond quickly to payment issues

Customer Experience

1. Send reminders: Notify customers before links expire
2. Provide receipts: Send confirmation after payment
3. Handle failures gracefully: Offer alternative payment methods
4. Support inquiries: Respond to payment questions promptly

Related Concepts

• [Create Your First Payment Link](../guides/quickstarts-tutorials/create-your-first-payment-link
• [Understanding Webhooks](./understanding-webhooks
• [Build an E-commerce Checkout](../guides/how-to/build-an-e-commerce-checkout
• [Take a Commission from Your User's Sale](../guides/how-to/take-a-commission-from-your-users-sale