# Payment Lifecycle

This page describes the complete flow from session creation to payment confirmation.

## Flow overview

```
Your Server                    ZevPay API                  Customer
    │                              │                          │
    │  POST /initialize            │                          │
    │─────────────────────────────▶│                          │
    │  { session_id, checkout_url }│                          │
    │◀─────────────────────────────│                          │
    │                              │                          │
    │  Return checkout_url or      │                          │
    │  pass public key to SDK      │                          │
    │─────────────────────────────────────────────────────────▶│
    │                              │                          │
    │                              │  POST /payment-method    │
    │                              │◀─────────────────────────│
    │                              │  { account_number, ... } │
    │                              │─────────────────────────▶│
    │                              │                          │
    │                              │      Customer pays       │
    │                              │◀─────────────────────────│
    │                              │                          │
    │  Webhook: charge.success     │                          │
    │◀─────────────────────────────│                          │
    │                              │                          │
    │  GET /verify (optional)      │                          │
    │─────────────────────────────▶│                          │
    │  { status: "completed" }     │                          │
    │◀─────────────────────────────│                          │
```

## Step-by-step

### 1. Initialize session

Your server calls `POST /v1/checkout/session/initialize` with your **secret key**, the amount, and customer email.

### 2. Customer selects payment method

The checkout UI (inline modal or standard page) presents the available payment methods. When the customer selects one, the SDK calls `POST /v1/checkout/session/:id/payment-method`.

For **bank transfer**, this returns a virtual account number. For **PayID**, this returns a dynamic PayID.

### 3. Customer completes payment

The customer transfers money (via bank or ZevPay app). ZevPay detects the transfer automatically.

### 4. Payment confirmed

ZevPay:
- Marks the session as `completed`
- Sends a `charge.success` webhook to your server
- The checkout UI detects the completion via polling and shows a success screen

### 5. You verify and fulfill

Your server verifies the payment via the webhook or the `/verify` endpoint, then fulfills the order.

## Polling

Both the inline and standard checkout SDKs poll the `/verify` endpoint every 5 seconds after the customer selects a payment method. When the status changes to `completed`, the success screen is shown automatically.

## Idempotency

- Each session can only be completed once
- Duplicate bank transfers to the same virtual account are rejected
- The `reference` parameter on initialization helps you prevent duplicate sessions

## Error handling

| Scenario | What happens |
|----------|-------------|
| Session expires (30 min) | Status set to `expired`, customer shown expiry screen |
| Transfer amount mismatch | Transfer may not be matched to the session |
| Network error during polling | SDK retries silently on next poll interval |
| Webhook delivery fails | Logged in dashboard, you should poll `/verify` as backup |