Yimaru-BackEnd/docs/CHAPA_INTEGRATION.md

Chapa Payment Gateway Integration

Subscription payments for learners use Chapa 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

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

Initiate payment request

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

Initiate payment response

{
  "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. 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.