This document covers how customers have the option to start a subscription where they will pay a specified amount at regular intervals.

Create a Plan

Every subscription needs to be on a plan. A plan is a framework for subscription given the amount and interval in which the subscription will be paid in. The plan intervals we have are weekly, monthly, quarterly and annually. You can create a Plan via the Chapa Dashboard.

    -H "Authorization: Bearer YOUR_SECRET_KEY"
    -H "Content-Type: application/json"
    -d '{ "name": "Monthly Retainer", 
          "interval": "monthly", 
          "amount": "500000"
    -X POST

You can modify the above code to best suit your application. The invoice_limit issues the request that a user will only be charged X times.

Create a Subscription

When creating a subscription for your website, first add the Subscription Javascript SDK code and modify it.

    -H "Authorization: Bearer YOUR_SECRET_KEY"
    -H "Content-Type: application/json"
    -d '{ "email": "", 
          "amount": "500000", 
          "plan": "PLN_xxxxxxxxxx" 
    -X POST

Listen For Payments

Webhook events are used to track the activity of subscriptions. For instance, subscription.disable event will be sent to your URL if payment was not carried out, disabling your subscription.

    "event": "charge.success",
    "data": {
      "id": 895091250,
      "domain": "test",
      "status": "success",
      "amount": 110000,
      "message": null,
      "gateway_response": "Approved",
      "paid_at": "2020-11-23T11:00:09.000Z",
      "created_at": "2020-11-23T11:00:03.000Z",
      "channel": "card",
      "currency": "ETB",
      "ip_address": null,
      "metadata": { "invoice_action": "cre,
      "log": null,
      "fees": 1650,
      "fees_split": null,
      "authorization": {
        "authorization_code": "AUTH_v56svuyn23",
        "bin": "408408",
        "last4": "4081",
        "exp_month": "12",
        "exp_year": "2020",
        "channel": "card",
        "card_type": "visa ",
        "bank": "TEST BANK",
        "country_code": "ET",
        "brand": "visa",
        "reusable": true,
        "signature": "SIG_H8F4hDXIARayPS41IUwG",
        "account_name": null,
        "receiver_bank_account_number": null,
        "receiver_bank": null
      "customer": {
        "id": 31352593,
        "first_name": "Test",
        "last_name": "Two",
        "email": "",
        "customer_code": "CUS_mfkew13owtwcmb2",
        "phone": "",
        "metadata": null,
        "risk_action": "default",
        "international_format_phone": null
      "plan": {
        "id": 60905,
        "name": "10% off first month",
        "plan_code": "PLN_a5vr5skxg72f4lr",
        "description": null,
        "amount": 110000,
        "interval": "monthly",
        "send_invoices": true,
        "send_sms": true,
        "currency": "ETB"
      "subaccount": {},
      "split": {},
      "order_id": null,
      "paidAt": "2020-11-23T11:00:09.000Z",
      "requested_amount": 110000

Payment Channels
Next →