> ## Documentation Index
> Fetch the complete documentation index at: https://docs.momentco.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Examples

> Common authorisation and capture flow examples

## Common Examples

### E-commerce: authorise at checkout, capture at shipment

```
1. Customer places order for R1 500.00
2. Create session with capture_method: manual → authorise R1 500.00
3. Webhook: payment.succeeded (funds reserved)
4. Warehouse confirms stock and ships → POST /captures (full amount)
5. Webhook: payment.captured
```

### Hotel: authorise estimated stay, capture actual amount

```
1. Guest checks in, estimated 3-night stay at R500/night
2. Authorise R1 500.00
3. Webhook: payment.succeeded (funds reserved)
4. Guest checks out after 2 nights → capture R1 000.00
5. Void remaining authorisation
6. Webhooks: payment.captured, then payment.voided
```

### Pre-order: authorise, void if unavailable

```
1. Customer pre-orders limited item for R2 000.00
2. Authorise R2 000.00
3. Webhook: payment.succeeded (funds reserved)
4. Item becomes unavailable → void full amount
5. Webhook: payment.voided
```

### Partial fulfillment: capture per shipment

```
1. Customer orders 3 items totalling R3 000.00
2. Authorise R3 000.00
3. Webhook: payment.succeeded (funds reserved)
4. Ship item 1 (R1 200.00) → capture R1 200.00
5. Ship item 2 (R800.00) → capture R800.00
6. Item 3 out of stock → void remaining authorisation
7. Webhooks: payment.captured (x2), payment.voided
```

### Fraud review: authorise, review, then decide

```
1. Customer places R5 000.00 order
2. Authorise R5 000.00
3. Webhook: payment.succeeded (funds reserved)
4. Fraud team reviews (within authorisation window)
5a. Approved → capture full amount
5b. Flagged → void full amount
```

### Tip adjustment: authorise base amount, capture with gratuity

```
1. Customer finishes meal for R500.00
2. Authorise R500.00
3. Webhook: payment.succeeded (funds reserved)
4. Customer adds R75.00 tip → capture R575.00 (within authorised amount)
5. Webhook: payment.captured
```

### Rental deposit: authorise deposit, capture actual charges

```
1. Customer rents a car, R5 000.00 deposit required
2. Authorise R5 000.00
3. Webhook: payment.succeeded (funds reserved)
4. Customer returns car, rental fee is R2 500.00 → capture R2 500.00
5. Void remaining R2 500.00 deposit
6. Webhooks: payment.captured, then payment.voided
```

## Detailed End-to-End Example

A merchant selling electronics wants to authorise at checkout and capture at shipment.

**Step 1: Create payment session**

```json theme={"system"}
POST /collect/payment_sessions

{
  "amount": 250000,
  "currency": "ZAR",
  "type": "one_time",
  "options": {
    "customer": {
      "name": "Lara",
      "email": "lara@example.com"
    },
    "checkout_options": {
      "return_url": "https://shop.example/order/ord_789/status"
    },
    "payment_method_options": {
      "card": {
        "capture_method": "manual"
      }
    }
  },
  "external_reference": "ord_789",
  "metadata": {
    "order_id": "ord_789",
    "items": "laptop,mouse"
  }
}
```

**Step 2: Customer authorises (webhook received)**

```json theme={"system"}
{
  "id": "evt_92847561234",
  "type": "payment.succeeded",
  "data": {
    "id": "pay_Xk9mPqR3sTuV7w",
    "status": "succeeded",
    "amount": 250000,
    "currency": "ZAR",
    "capture_method": "manual",
    "authorised_amount": 250000,
    "paid_amount": 0,
    "voided_amount": 0,
    "country": "ZA",
    "payment_method_details": {
      "type": "card",
      "card": {
        "type": "CREDIT",
        "scheme": "VISA",
        "bin": "411111",
        "last4": "1234"
      }
    },
    "external_reference": "ord_789",
    "mode": "live",
    "metadata": {
      "order_id": "ord_789",
      "items": "laptop,mouse"
    },
    "created_at": "2026-03-18T14:30:00.000Z",
    "updated_at": "2026-03-18T14:30:45.123Z"
  }
}
```

**Step 3: Laptop ships, capture R2 200.00**

```json theme={"system"}
POST /collect/payments/pay_Xk9mPqR3sTuV7w/captures
Idempotency-Key: capture_ord_789_laptop

{
  "amount": 220000
}
```

**Step 4: Mouse out of stock, void remaining authorisation**

```json theme={"system"}
POST /collect/payments/pay_Xk9mPqR3sTuV7w/voids
Idempotency-Key: void_ord_789_mouse

// No request body needed
```

Final payment state:

```json theme={"system"}
{
  "authorised_amount": 250000,
  "paid_amount": 220000,
  "voided_amount": 30000
}
```