# Gas Station Wallet Pay + Digital Receipts — Design

**Date:** 2026-07-22  
**Status:** Approved for implementation (Approach A)  
**Architecture:** Ledger pay — debit driver wallet, credit station owner wallet; receipts to both parties.

---

## Scope (v1)

| In | Out |
|----|-----|
| `POST /gas-stations/:id/pay` with Idempotency-Key | Instant Stripe Transfer to Connect |
| Credit station `userId` wallet | PDF generation |
| `GasStationPayment` + receipt number | Auto-refund UI |
| In-app payment detail + lists | Google Place-only stations |
| Email receipt to payer + station owner | |

---

## Money flow

```text
Driver wallet --debit--> ledger
Station owner wallet <--credit-- ledger
Station withdraws later via existing Connect / withdraw APIs
```

## APIs

- `POST /api/v1/gas-stations/:gasStationId/pay`  
  Headers: `Idempotency-Key` (required UUID)  
  Body: `{ amount, note?, tripId? }` (amount in USD dollars)
- `GET /api/v1/payments/:paymentId` — payer or station owner
- `GET /api/v1/payments?page&limit` — payments I made
- `GET /api/v1/gas-stations/my-payments?page&limit` — payments my station received

## Rules

- Station approved + active; registered DB id only
- Cannot pay own station
- Insufficient funds → error
- Idempotent: same payer + Idempotency-Key returns same payment
- Email failures do not fail the payment