# Chapa Payment Gateway Integration

Subscription payments for learners use [Chapa](https://developer.chapa.co/docs) hosted checkout, following the same payment-first flow as the previous ArifPay integration.

## Overview

- Subscriptions are created only after Chapa confirms payment (webhook and/or verify).
- `tx_ref` is stored as the payment `nonce` and returned as `session_id` in API responses.
- ArifPay direct-payment routes remain available for legacy flows; subscription checkout uses Chapa.

## Environment Variables

```env
CHAPA_SECRET_KEY=CHASECK_TEST-xxxxxxxx
CHAPA_PUBLIC_KEY=CHAPUBK_TEST-xxxxxxxx
CHAPA_WEBHOOK_SECRET=your_webhook_secret_from_dashboard
CHAPA_BASE_URL=https://api.chapa.co/v1
CHAPA_CALLBACK_URL=https://your-api.example.com/api/v1/payments/chapa/callback
CHAPA_RETURN_URL=https://your-api.example.com/payment/success
CHAPA_RECEIPT_URL=
```

Configure the same webhook URL in the Chapa dashboard:

`https://your-api.example.com/api/v1/payments/webhook`

## Payment Flow

1. Learner calls `POST /api/v1/subscriptions/checkout` or `POST /api/v1/payments/subscribe`.
2. Backend creates a pending payment and calls Chapa `POST /transaction/initialize`.
3. Client redirects the user to `payment_url` (`checkout_url` from Chapa).
4. After payment, Chapa redirects the learner to `return_url` (`/payment/success`) and calls `callback_url`.
5. The success page and callback both verify via Chapa `GET /transaction/verify/{tx_ref}` and activate the subscription when successful.
6. Chapa also sends a webhook; client may poll `GET /api/v1/payments/verify/{tx_ref}` (`session_id` path param is the `tx_ref`).

## API Endpoints

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/api/v1/subscriptions/checkout` | Yes | Initiate subscription payment |
| POST | `/api/v1/payments/subscribe` | Yes | Same as checkout |
| GET | `/api/v1/payments/verify/:session_id` | Yes | Verify by `tx_ref` |
| POST | `/api/v1/payments/webhook` | No | Chapa webhook (HMAC signature required) |
| GET | `/api/v1/payments/chapa/callback` | No | Chapa server callback (JSON) |
| GET | `/api/v1/payments/chapa/success` | No | Chapa learner success page (HTML) |
| GET | `/payment/success` | No | Same HTML success page (`CHAPA_RETURN_URL`) |
| GET | `/api/v1/payments/methods` | No | Supported Chapa methods |
| GET | `/api/v1/admin/payments` | Yes (admin) | List/filter all gateway payments (Chapa + ArifPay) |
| GET | `/api/v1/admin/payments/:id` | Yes (admin) | Get any payment by ID |

### Admin: list all gateway payments

`GET /api/v1/admin/payments` requires permission `payments.list_all` (assigned to `ADMIN` by default).

Query filters (all optional):

| Parameter | Description |
|-----------|-------------|
| `user_id` | Learner user ID |
| `plan_id` | Subscription plan ID |
| `subscription_id` | Linked subscription ID |
| `status` | `PENDING`, `PROCESSING`, `SUCCESS`, `FAILED`, `CANCELLED`, `EXPIRED` |
| `provider` or `payment_method` | `CHAPA` or `ARIFPAY` |
| `currency` | e.g. `ETB` |
| `plan_category` | `LEARN_ENGLISH`, `IELTS`, `DUOLINGO` |
| `reference` | Partial match on `session_id`, `nonce`, or `transaction_id` |
| `created_from`, `created_to` | RFC3339 or `YYYY-MM-DD` |
| `paid_from`, `paid_to` | RFC3339 or `YYYY-MM-DD` |
| `min_amount`, `max_amount` | Amount range |
| `limit`, `offset` | Pagination (default limit 20, max 100) |

Example:

`GET /api/v1/admin/payments?provider=CHAPA&status=SUCCESS&limit=50&offset=0`

### Initiate payment request

```json
{
  "plan_id": 1,
  "phone": "0912345678",
  "email": "learner@example.com"
}
```

### Initiate payment response

```json
{
  "message": "Payment initiated. Complete payment to activate subscription.",
  "data": {
    "payment_id": 42,
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "payment_url": "https://checkout.chapa.co/checkout/payment/...",
    "amount": 500,
    "currency": "ETB",
    "expires_at": "2026-05-21T18:00:00Z"
  }
}
```

## Webhook Security

Chapa signs the raw JSON body with HMAC-SHA256 using your webhook secret. The handler checks `x-chapa-signature` or `chapa-signature` before processing.

## Testing

Use Chapa test keys and [test credentials](https://developer.chapa.co/test/testing-mobile). After checkout, confirm the subscription via verify endpoint or webhook logs.

### Postman

Import `postman/Chapa-Subscription-Payments.postman_collection.json`. Set collection variables (`base_url`, learner credentials, `chapa_webhook_secret`), then run folders **00 → 02** in order.