Create Subscription

Subscriptions are scheduled payments to pay for products or services that occurs frequently. For example, a cardholder paying for an on-demand internet service provider's monthly subscriptions fee without having to manually pay every month.

To create a subscription, you'll need to pass information such as customer, plan, card and start date , customer and plan are both required.

Subscription Details

FieldData typeRequiredDescription
planstringYesPlan code.
customerstringYesCustomer email address
cardstringNoIf customer has multiple cards, you can set the desired card you wish to use for this subscription here. If this is not supplied, the customer's card with the farther expiry year would be used
startDatedateNoManually set the date for the first debit. e.g. 2017-05-16T00:30:13+01:00

After collecting the necessary subscription details. Make a POST request to our subscription endpoint.

Note : Before making a post request, the secret key should be specified in the header.

-H "x-api-key: your_secret_key".

You can make API calls using this sample request. once all parameters are meet you would also get the response below;

  "customer": "",
  "plan": ""
    "data": {
        "customer": {
            "email": "[email protected]",
            "currencyCode": "NGN",
            "firstName": null,
            "lastName": null,
            "phoneNumber": null,
            "customerCode": null,
            "id": "e48419c7-701d-4933-93c7-2e8eeaf09bce",
            "active": true,
            "createdAt": "2024-06-19T15:15:02.849Z",
            "updatedAt": "2024-06-19T15:15:02.849Z",
            "version": 1
        "plan": {
            "id": "4a3fc25a-6056-4daa-b9bb-9380904d5751",
            "name": "TEST",
            "description": "FIEXING",
            "interval": "biannually",
            "amount": "5000.00",
            "code": "PLN_undefined_729NzKoRJQeoYdB",
            "sendSms": false,
            "sendInvoices": false,
            "limit": "0.00",
            "hostedPage": false,
            "isActive": true,
            "createdAt": "2024-05-30T11:10:56.782Z",
            "updatedAt": "2024-05-30T11:10:56.782Z",
            "deletedAt": null,
            "version": 1,
        "code": "SUB_7263269_W-dnE2xtS015ETu",
        "startDate": "2024-12-19T16:15:03.494Z",
        "nextPaymentDate": "2024-12-19T16:15:03.495Z",
        "isActive": true,
        "id": "7697cabd-ee1b-435a-9ae3-82b926cc5334",
        "createdAt": "2024-06-19T15:15:02.849Z",
        "updatedAt": "2024-06-19T15:15:02.849Z",
        "deletedAt": null,
        "version": 1,
        "authorizationUrl": "",
        "accessCode": "lt3sjasau6kb3qm",
        "reference": "KYSHI-1718813703631"
    "status": true,
    "message": "Success",
    "code": 201


There are two variations to creating subscriptions.

  1. customer has one or more cards tokenised: for this use case subscription is created and activated
  2. customer doesn't have a card tokenised: for this use case a authorizationUrl is provided after subscription has been created. You're expected to redirect customers to this page where NGN 100 or KES 5 would be deducted depending on the respective currency.