API Reference Low Balance Service

Low Balance Service(Auto Top-up)

This document provides an overview of the Creditswitch Low Balance Service. It is a subscription-based service that enables customers to seamlessly top up their balance while making calls.

For technical assistance with the CSW API 🛠️, please contact us at techsupport@creditswitch.com ✉️ to ensure a swift response and dedicated support.

Integration Process Flow

This section outlines the recommended integration flow , designed to minimize the risk of transaction disputes and strengthen customer confidence .

1️⃣ Onboarding 🚀:
Authenticate through the Onboard Endpoint to retrieve a token for subsequent API calls, This should be passed using basic auth.

2️⃣ Subscription 📲:
Call the Auto Top-up Subscription Endpoint with the required payload. This step allows the customer to subscribe to the service seamlessly.

3️⃣ Unsubscribe ❌:
If the customer wishes to cancel their Low Balance subscription, call the Unsubscribe Endpoint to deactivate the service.

Onboarding
POST

Generate token for subsequent API calls.

Service Information

baseUrl/api/v1/low/balance/create/vendor
POST
Content-Type: application/json
Parameter Name Type M/O Description
Merchant Login Id String M Merchant LoginId
Merchant Name String M Merchant Name
Notification URL String M Merchant notification callback Url
Account URL String M Merchant account callback Url
Parameter Name Type M/O Description
status String M Status of the request.
statusDescription Integer M Corresponding description for the status.
data Object M An object containing authentication details. 
{
    "statusCode": "00",
    "statusDescription": "Account created successfully",
    "data": "srUNEuasfbs_UtcuwJHIVWO-euJHCHVcggfw"
}
Subscription
POST

To subscribe to the service, call the Auto Top-up Subscription Endpoint 📲 with the required payload. Remember to pass your token using basic auth. Clients must send a POST request 📤 to this endpoint.

Service Information

baseUrl/api/v1/low/balance/subscribe
POST
Content-Type: application/json
Parameter Name Type M/O Description
msisdn String M Customers Msisdn
amount String M amount to top up
AirtimeThreshold String O airtime threshold at which service should trigger
DataThreshold String O data threshold at which service should trigger
Product String M trigger type either airtime or data
network String M customers msisdn network provider
createdAt String O request timestamp
Parameter Name Type M/O Description
status String M Status of the request.
statusDescription String M Corresponding description for the status.
data String O response data if any. 
{
    "statusCode": "00",
    "statusDescription": "Auto Top-up Subscription successful"

}
Unsubscribe
DELETE

If a customer chooses to unsubscribe from the Low Balance Service 📉, call the Unsubscribe Endpoint ❌ to cancel the active subscription. Clients must send a DELETE request 🗑️ to this endpoint.

Service Information

baseUrl/api/v1/low/balance/{{msisdn}}/{{thresholdType}}/unsubscrible
DELETE
Content-Type: application/json
Parameter Name Type M/O Description
msisdn String M Customers Msisdn
Threshold Type String M trigger type whether for airtime or data
Parameter Name Type M/O Description
status String M Status of the request.
statusDescription String M Status Description of the request. 
{
    "statusCode": "00",
    "statusDescription": "Unsubscribed"
}
Notifications Callback

A Low Balance Notification ⚠️ is triggered when a subscriber’s airtime or data balance falls below their set threshold. A successful response will also ensure that the subscriber receives the corresponding top-up value 💳. 

{"subscriberMSISDN": "0803xxxxxxx", "airtimeThreshold": "50", "network": "MTN", "dataThreshold": "",
"thresholdType": "airtime", "transactionId":
"251068796011729491882","requestType":"OneTime/Subscription", "event": "notification"}
                            
{"status":true,"code":200,"message":"Debited Successful","data":
{"isDebited":true,"transaction_reference":"931ATT6715e690775841729488528","amount":100","recipient":"0803xxxxxxxxxxxx"}}
                            
{"statusCode": "00", "statusDescription": "Successful", "confirmCode": "251068796011729491882",
"tranxReference": "931ATT6715e690775841729488528", "event": "update"}
                            
{ "status":true, "code":200, "message":"update Successful" }