API Reference Low Balance Service (B2C)

Low Balance Service (Auto Top-up) - B2C

This document provides an overview of the Creditswitch Low Balance Service for B2C Users. 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.

Get Services
GET

Service Information

{{baseUrl}}autotopup/services?loginId={{loginId}}&key={{publicKey}}
GET
Parameter Name Type M/O Description
loginId Numeric M Merchant id provided during integration
key String M Merchant’s (public) key
Parameter Name Type M/O Description
statusCode Numeric M Status of the transaction. 00 signifies success
statusDescription String M Corresponding description for the status code. 00 = Successful
detail Collection M Contains additional details or context regarding the response 
{
    "statusCode": "00",
    "statusDescription": "Successful",
    "details": {
        "A02P": {
            "serviceId": "A02P",
            "service": "9MOBILE AUTOTOPUP"
        },
        "A03P": {
            "serviceId": "A03P",
            "service": "GLO AUTOTOPUP"
        },
        "A04P": {
            "serviceId": "A04P",
            "service": "MTN AUTOTOPUP"
        },
        "D04P": {
            "serviceId": "D04P",
            "service": "MTN_DATA AUTOTOPUP"
        }
    }
}

Auto Top Up Register

POST

Service Information

{{baseUrl}}autotopup/register
POST
application/json
Parameter Name Type M/O Description
loginId String M Merchant id provided during integration
key String M Merchant’s (public) key
callbackUrl String M The HTTPS endpoint where threshold notifications will be sent. Must be publicly accessible. 

{
    "loginId": "{{loginId}}",
    "key": "{{publicKey}}",
    "callbackUrl": "https://webhook.site/f9d0197f-67f2-420b-8e93-b2c863e81b9f"
}
Parameter Name Type M/O Description
statusCode String M A response code indicating the result of the webhook registration. "00" typically represents success.
statusDescription String M A human-readable description of the status code.
details Object M A nested object containing additional information about the registration result.
details.message String M A confirmation message indicating the outcome of the registration.
details.callbackUrl String (URL) M The confirmed callback URL that has been registered and will receive threshold notifications. 
{
    "statusCode": "00",
    "statusDescription": "Successful",
    "details": {
        "message": "Merchant registered successfully",
        "callbackUrl": "https://webhook.site/bfa091e5-d7b3-4018-8dde-11109dc0c3ef"
    }
}

Subscribe

POST

Service Information

{{baseUrl}}autotopup/subscribe
POST
application/json
Parameter Name Type M/O Description
loginId Numeric M Merchant id provided during integration
key String M Merchants (public) key
serviceId String M Corresponding service id for the request type. See "Services" section for the available services and corresponding service codes for each.
threshold Numeric M The specified balance level at which the auto top-up will be automatically triggered for the user.
amount Numeric M The amount that will be automatically credited to the customer’s account when the threshold is reached.
msisdn String M The customer’s mobile phone number. 

{
    "loginId": "{{loginId}}",
    "key" : "{{publicKey}}",
    "serviceId": "A04P",
    "threshold": "200",
    "amount": "100",
    "msisdn": "08061387236"

}
Parameter Name Type M/O Description
statusCode Numeric M Status of the transaction. 00 signifies success
statusDescription String M Corresponding description for the status code. 00 = Successful
detail Collection M Contains additional details or context regarding the response 
{
    "statusCode": "00",
    "statusDescription": "Successful",
    "details": {
        "message": "08061387236 has been subscribed successfully to the AutoTopUp service"
    }
}

Unsubscribe

POST

Service Information

{{baseUrl}}autotopup/unsubscribe
POST
application/json
Parameter Name Type M/O Description
loginId Numeric M Merchant id provided during integration
serviceId String M Corresponding service id for the request type. See "Services" section for the available services and corresponding service codes for each.
msisdn String M The customer’s mobile phone number. 

{
    "loginId": "{{loginId}}",
    "key" : "{{publicKey}}",
    "msisdn": "08061387236"
}
Parameter Name Type M/O Description
statusCode Numeric M Status of the transaction. 00 signifies success
statusDescription String M Corresponding description for the status code. 00=Successful
detail Collection M Contains additional details or context regarding the response 
{
    "statusCode": "00",
    "statusDescription": "Successful",
    "details": {
        "message": "08061387236 has been subscribed successfully to the AutoTopUp service"
    }
}
Get Subscriber Status
GET

Service Information

{{baseUrl}}autotopup/status?msisdn=08061387236&loginId={{loginId}}&key={{publicKey}}
GET
Parameter Name Type M/O Description
loginId Numeric M Merchant id provided during integration
key String M Merchant’s (public) key
msisdn String M The customer’s mobile phone number.
Parameter Name Type M/O Description
statusCode Numeric M Status of the transaction. 00 signifies success
statusDescription String M Corresponding description for the status code. 00 = Successful
detail Collection M Contains additional details or context regarding the response 
{
    "statusCode": "00",
    "statusDescription": "Successful",
    "details": {
        "msisdn": "08061387236",
        "subscription_status": null,
        "amount": "100",
        "airtime_threshold": "200",
        "data_threshold": ""
    }
}

Notification Request

POST
You are required to provide a callback URL. This URL will be used by our system to send notifications, which you are expected to process accordingly.

Service Information

{{customerNotificationUrl}}
POST
application/json
Parameter Name Type M/O Description
msisdn String M The subscriber's mobile phone number.
network String M The mobile network operator of the subscriber.
transactionId String M A unique identifier for this transaction, used for tracking and reconciliation.
thresholdType String M The type of threshold that was crossed.
airtimeThreshold String C The airtime balance threshold value that triggered this notification.
dataThreshold String C The data balance threshold value that triggered this notification.
event String M The type of event being reported. 

{
    "msisdn": "08109115512",
    "network": "MTN",
    "transactionId": "3260317716443662673",
    "thresholdType": "airtime",
    "airtimeThreshold": "50",
    "dataThreshold": null,
    "event": "notification"
}
Parameter Name Type M/O Description
status String M The overall status of the request. Possible values: "success" or "failed".
code String M A response code indicating the result. "00" typically represents success, other codes indicate specific error conditions.
message String M A human-readable description of the response status or any additional information.
shouldDebit Boolean M Indicates whether the system should proceed with debiting the subscriber. When true, proceed with auto-top-up; when false, do not debit. 
{
    "status": "success",
    "code": "00",
    "message": "Notification received. Proceed as instructed.",
    "shouldDebit": true
}