Startbutton Product API
  • Startbutton API doc
    • Get Started
    • Accept Payments
    • Server-to-Server Integration
      • S2S Integration for Virtual Accounts
        • S2S Virtual account (NGN)
        • S2S Virtual account (GHS)
        • S2S EFT (ZAR)
      • S2S Integration for Mobile Money
        • S2S MoMo (KES and GHS)
        • S2S MoMo (TZS and UGX)
        • S2S MoMo (RWF)
        • S2S MoMo XOF and XAF
    • Re-charge Card
    • Subscriptions
    • Payment Links
    • Currency Conversion
    • Get Wallet Balance
    • Transfer
      • Bank List
    • Security Measures.
      • IP Whitelisting
    • Webhook
    • Transaction Status
    • Get FX Rate
    • Under and Overpayments
    • Refunds
      • Refund Transaction Status (TSQ)
    • Available Currencies
    • FAQs
  • Advanced Security
    • Signed Payload for Transfer Requests.
Powered by GitBook
On this page
  • Create Subscription Plan
  • Cancel Subscription
  • Get Subscribers
  • Cancel Subscriber
  • Subscription FAQs
  1. Startbutton API doc

Subscriptions

You can create subscription plans with customizable billing frequencies (daily, weekly, monthly, etc.) and amounts using just a single endpoint.

We currently support creation of subscription plans for NGN, GHS, ZAR, KES, and USD only.

Authorization
Set value to `Bearer SECRET_KEY`

Content-type

Set value to application/json

The secret key can be gotten from the 'Settings' page on your Startbutton dashboard.

Post a request to the URL below, where the base URL is determined by the environment you are in.

BaseUrls

PROD : https://api.startbutton.tech

DEV/ Staging: https://api-dev.startbutton.tech

Create Subscription Plan

POST: {{baseUrl}}/subscription/api

Sample code:

{
    "name": "Free trial subscription 7",
    "description": "This is a Free trial Subscription Test",
    "frequency": "monthly",
    "currency": "NGN",
    "type": "fixed",
    "amount": 1000,
    "freeTrial": true,
    "freeTrialPeriod": 5,
    "endDate": "2025-06-30", //this is optional
    "notificationSettings": {
        "freeTrial": {
            "enabled": true,
            "period": 3
        }
    }
}

Sample response:

{
    "success": true,
    "message": "Success",
    "data": {
        "subscription": {
            "name": "Free trial subscription 7",
            "description": "This is a Free trial Subscription Test",
            "amount": 10,
            "frequency": "monthly",
            "merchantId": "64xxxxxxxx",
            "link": "http:subscription/3935daxxx",
            "currency": "NGN",
            "code": "39xxxxxx",
            "status": "active",
            "deleted": false,
            "endDate": "2025-06-30T00:00:00.000Z",
            "type": "fixed",
            "notificationSettings": {
                "freeTrial": {
                    "enabled": false,
                    "period": 3
                }
            },
            "_id": "67xxxxxxxxxxxxxxxx",
            "createdAt": "2025-04-02T06:11:42.501Z",
            "updatedAt": "2025-04-02T06:11:42.501Z",
            "__v": 0
        }
    }
}

Cancel Subscription

POST: {{baseUrl}}/subscription/api/:planId

Path variable
Required?

planId

Yes

Sample Code:

{
    "status": "canceled",
    "reason": "completed"
}

Sample Response:

{
    "success": true,
    "message": "Success",
    "data": {
            
            },
            "type": "fixed",
            "_id": "67xxxxxxxxxxxxx",
            "name": "Test",
            "description": "Testing subs",
            "amount": 500,
            "frequency": "monthly",
            "merchantId": "66xxxxxxxxxxxxx",
            "link": "http://pay.startbuttonsubscription/b7xxxxxx",
            "currency": "NGN",
            "code": "b7xxxxxx",
            "status": "canceled",
            "deleted": false,
            "numberOfPaymentsExpected": 5,
        }
    }
}

Get Subscribers

This endpoint retrieves details of all subscribers on a subscription plan and allows filtering by status.

GET: {{baseUrl}}/subscribers

Query Params
Required?
Description

subscriptionPlanId

Yes

the subscription plan id

status

No

should be activated, 'completed', or 'cancelled',

Sample Response:

The Subscription Plan detail associated with the subscriber is also returned, but for the scope of this DOC we will only share the Subscriber's detail. Additionally, if a Subscription Plan isn't created with an endDate— then no endDate is returned for the Plan.

{
    "_id": "609xxxxxxxxxxx", //this is the subscriber's Id
    "subscriberId": {
    "email": "test@test.com",
    "nameOnCard": null,
    "deleted": false,
    "createdAt": "2025-03-07T01:28:47.314Z",
    "updatedAt": "2025-03-08T04:07:50.929Z",
    "id": "67xxxxxxxxxxxxxxx"
    }
}

Cancel Subscriber

With this endpoint, you can cancel a subscriber from a subscription plan. It allows you to remove a subscriber's access to a previously active subscription plan. You need to retrieve the subscriber's Id using the Get-subscriber endpoint first.

PATCH : {{baseUrl}}/subscribers/:subscriberId/update-status

Path Variable
Required?
Description

subscriberId

Yes

the subscriber's id

Sample Payload

{
    "status": "canceled",
    "reason": "this is the end"
}

Sample Response

{
    "success": true,
    "message": "success",
    "data": {
        "subscriber": {
            "_id": "678xxxxxxxxxxxxx",
            "subscriberId": "678xxxxxxxxxxxx",
            "planId": "678xxxxxxxxxxxxxxxxxxxx",
            "merchantId": "678xxxxxxxxxx",
            "frequency": "monthly",
…            "updatedAt": "2025-xxxxxxxxxxxxxxxxxx",
            "reason": "I don't Know"
        }
    }
}

Subscription FAQs

  1. How can we identify the subscription plan the user paid for - from the webhook response? ANS: The payment code returned in the webhook response would be the same as the code on the subscription link.

  2. If a subscription charge attempt fails, will it be retried in the next billing cycle? ANS: Yes, until the number of expected payment cycles is completed— we retry in the next billing cycle.

PreviousRe-charge CardNextPayment Links

Last updated 1 month ago