# Payment Module Notes

Date: 2026-06-30

## Order And Payment Flow

Decision:

- An order is created once.
- Each payment attempt creates a separate payment record.
- One order can have multiple payments, for example failed attempts followed by a successful one.

Example:

```text
Order #100
  Payment #1 failed
  Payment #2 failed
  Payment #3 paid
```

Storefront flow:

```text
POST /api/v1/orders
POST /api/v1/orders/{order}/payments
```

Checkout completion flow:

```text
POST /api/v1/checkout/complete
```

`CompleteCheckout` is the final storefront checkout command. It receives the selected payment
method, creates the order, and returns the next action. The next action can be an online payment
redirect now, and later can represent cash, installment, wallet, bank transfer, or proforma flows.

Retry flow:

```text
POST /api/v1/orders/{order}/payments
```

Do not create another order for a payment retry.

## Module Boundary

- Customer owns order lookup and order ownership checks.
- Payment owns payment records, gateway request, callback verification, and settlement.
- Payment should not query orders directly.