Payment Flow

Understanding the complete lifecycle of a Pelago payment from creation to settlement.

Payment States

State Descriptions

State	Description	Webhook Event
created	Payment request initialized	-
pending	Awaiting customer action	-
processing	Transaction in progress	-
completed	Payment successful	payment.completed
failed	Payment failed	payment.failed
expired	Payment timed out	payment.expired
settled	Funds transferred to merchant	payment.settled
refunded	Payment refunded	payment.refunded

Detailed Flow

Phase 1: Payment Creation

Request:

{
  "amount": 100.00,
  "currency": "USD",
  "cryptocurrency": "USDC",
  "network": "stellar",
  "merchantWallet": "GXXXXX...",
  "redirectUrl": "https://store.com/success",
  "webhookUrl": "https://store.com/webhook",
  "expiresIn": 1800
}

Response:

{
  "id": "pay_abc123",
  "status": "created",
  "amount": 100.00,
  "currency": "USD",
  "cryptoAmount": "100.000000",
  "cryptocurrency": "USDC",
  "network": "stellar",
  "url": "https://pay.pelago.tech/pay_abc123",
  "qrCode": "data:image/png;base64,...",
  "expiresAt": "2025-02-08T22:30:00Z"
}

Phase 2: Customer Payment

Phase 3: Confirmation & Webhook

Webhook Payload:

{
  "id": "evt_xyz789",
  "type": "payment.completed",
  "created": "2025-02-08T22:15:30Z",
  "data": {
    "paymentId": "pay_abc123",
    "status": "completed",
    "amount": 100.00,
    "currency": "USD",
    "cryptoAmount": "100.000000",
    "cryptocurrency": "USDC",
    "network": "stellar",
    "transactionHash": "abc123...def456",
    "merchantWallet": "GXXXXX...",
    "customerWallet": "GCUST...",
    "metadata": {
      "orderId": "order_12345"
    }
  }
}

Phase 4: Settlement

Handling Edge Cases

Network Congestion

If blockchain is congested:

1. Payment stays in processing longer
2. Pelago monitors for confirmation
3. Customer sees "confirming" status
4. Webhook sent only after confirmation

Underpayment

If customer sends less than required:

1. Payment marked as partial
2. Merchant notified via webhook
3. Option to accept partial or request remainder

Overpayment

If customer sends more than required:

1. Payment marked as overpaid
2. Excess automatically refunded
3. Or credited to customer balance

Timeout Handling

Best Practices

1. Idempotency: Use unique orderId in metadata
2. Webhook verification: Always verify signatures
3. Status polling: Backup for missed webhooks
4. Expiration handling: Inform customers of timeout

Next Steps

• Settlement Details
• Error Handling
• Webhook Configuration