# Tank Track — Gas Station Wallet Pay + Digital Receipts

Pay a **registered** gas station from the driver’s wallet. Money moves on the **platform ledger** (debit driver → credit station owner). Station owner withdraws later via existing Stripe Connect / wallet withdraw. Digital receipts go to **both** parties (in-app + email).

**Frontend integration guide:** [`gas-station-payment-frontend-README.md`](./gas-station-payment-frontend-README.md)

## Auth

```http
Authorization: Bearer <jwt>
Content-Type: application/json
Idempotency-Key: <uuid>   # required on pay
```

**Station id:** use `_id` / `id` from `GET /gas-stations`, `/nearest?source=registered`, or `/along-route` — **not** a Google `place_id`.

---

## 1. Pay station

```http
POST /api/v1/gas-stations/:gasStationId/pay
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
```

```json
{
  "amount": 45.5,
  "note": "Pump 3",
  "tripId": "optional_trip_object_id"
}
```

| Field | Notes |
|-------|--------|
| `amount` | USD dollars (max $10,000) |
| `note` | optional, max 255 |
| `tripId` | optional; must belong to payer |
| `Idempotency-Key` | required header (or body `idempotencyKey`); **same key is safe to retry** |

**Retries / crash safety:**
- Same key + `completed` → returns same payment (no second debit)
- Same key + `pending` (interrupted) → **resumes** debit/credit via idempotent wallet refs, then completes
- Same key + `failed` (insufficient funds, or already refunded) → **same error again** (400); use a **new** key after you top up / to retry
- Response always includes `gasStation` + `walletBalance` / `walletBalanceCents`

**Success (200):**

```json
{
  "_id": "...",
  "receiptNumber": "TT-20260722-AB12CD",
  "amount": 45.5,
  "amountCents": 4550,
  "status": "completed",
  "paidAt": "...",
  "gasStation": { "_id": "...", "name": "...", "address": "..." },
  "walletBalance": 120.0,
  "walletBalanceCents": 12000
}
```

| HTTP | When |
|------|------|
| 400 | Own station, unavailable, insufficient funds, missing Idempotency-Key |
| 404 | Station / trip not found |
| 500 | Transient settle failure (retry **same** Idempotency-Key to resume) |

---

## 2. Payment detail (receipt)

```http
GET /api/v1/payments/:paymentId
```

Accessible by **payer** or **station owner**.

---

## 3. List payments I made

```http
GET /api/v1/payments?page=1&limit=20
```

---

## 4. List payments my station received

```http
GET /api/v1/gas-stations/my-payments?page=1&limit=20
```

---

## Receipts

On successful pay:

1. In-app via payment APIs above  
2. Email to driver + station owner (best-effort; pay still succeeds if email fails)

---

## Money model (v1)

- Debit: wallet `payment_debit`  
- Credit: station owner wallet `payment_credit`  
- No instant Stripe Transfer to Connect on pay  
- Station uses existing withdraw / Connect flow to bank