API Reference Utility Advance Service

Utility Advance Service

This document provides an overview of the Creditswitch Utility Advance Service 💡. It enables business partners to consume existing services on the Creditswitch Platform in a convenient buy now, pay later 🛒 model.

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 contains a description of recommended integration flow which helps minimize the risk of disputing transactions and also increase customer confidence in the system

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

1️⃣ Authentication 🔐: Begin by authenticating through the Login Endpoint to retrieve a Bearer Token ️ for subsequent API calls.


2️⃣ Loan Eligibility Check 📊: Call the Loan Eligibility Endpoint with the required payload. This step confirms eligibility and, if successful, returns available loan offers.


3️⃣ Loan Approval ✅: If the user accepts the terms and conditions from Step 2, the system automatically processes loan disbursement/approval.


4️⃣ Loan Status 🔍: Check the status of an existing loan by calling the Status Endpoint.


5️⃣ Loan Repayment 💸: To close an existing loan, use the Repayment Endpoint as needed.

Authentication
POST

Generate bearer token for subsequent API calls.

Service Information

baseUrl/api/v1/login
POST

Content-Type: application/json

X-Signature: {{encrypted_checksum}}
Parameter Name Type M/O Description
email Email M Configured Email Address
password String M Password
Parameter Name Type M/O Description
status String M Status of the request. true signifies success
code Integer M Corresponding description for the status. 200 = Successful
message String M Description of the api response.
data Object M An object containing authentication details. 
{
    "status":true,
    "code":200,
    "message":"Successful",
    "data": {
        "token_type": "Bearer",
        "access_token": "eyJygurwiyugiwbreugijbiwqhfiywefgibwa",
        "expires_at": 7200,
        "name": "John Doe",
        "email": "john.doe@example.com"
    }
}
Loan Eligibility Check
POST

This action confirms recipient's eligibility using agreed metrics and returns with loan offers where eligible. Client is required to make a POST request to this endpoint.

Service Information

baseUrl/api/v1/loan/eligibility/check
POST

Content-Type: application/json

Bearer: {{access_token}}

X-Signature: {{encrypted_checksum}}
Parameter Name Type M/O Description
loginId String M Merchant Id provided during integration
serviceType String M airtime or data
recipient Numeric M Customers phone number 

{
    "loginId":"17200",
    "serviceType":"airtime",
    "recipient":"09068974869",
    "msisdn":"09068974869"
}
Parameter Name Type M/O Description
status String M Status of the request. true signifies success
code Integer M Corresponding description for the status. 200 = Successful
message String M Description of the api response.
data Object M An object containing check response with available offer(s). 
{
    "status": true,
    "code": 200,
    "message": "Successful",
    "data": {
        "offer1": {
            "amount": "200",
            "serviceId: "A04E",
            "product": "airtime"
        },
        "offer2": {
            "amount": "100",
            "serviceId": "A04E",
            "product": "airtime"
        },
        "isEligible": true,
        "reference": "077416241021064788727052243034"
    },
    "meta": null
}
Disburse Loan
POST

This action confirms recipient's consent to the loan terms and conditions as indicated by the response returned from step 2) above. Client is required to make a POST request to this endpoint.

Service Information

baseUrl/api/v1/loan/apply
POST

Content-Type: application/json

Bearer: {{access_token}}

X-Signature: {{encrypted_checksum}}
Parameter Name Type M/O Description
loginId Numeric M Merchant Id provided during integration
requestId String M Unique transaction Id for the request. Maxlength (36characters)
serviceId Numeric M Corresponding service id for the request type. See "Services" section for the available services and corresponding service codes for each.
amount Numeric M Amount with which to top-up amount customers phone Maximum 100000
recipient Numeric M Customers phone number to top-up 

{
    "amount":"100",
    "loginId": "17200",
    "recipient": "09068974869",
    "msisdn":"09068974869",
    "requestId": "42985192836785",
    "serviceId": "A04E"
}
Parameter Name Type M/O Description
status String M Status of the request. true signifies success
code Integer M Corresponding description for the status. 200 = Successful, 202 = Processing, 422 = Failed
message String M Description of the vend response.
data Object M An object containing vend response details. 
{
    "status": true,
    "code": 200,
    "message": "Loan Advance Approved Successfully",
    "data": {
        "requestId": "jc1bciigdebc",
        "recipient: "08092343261",
        "amount": "90.00"
        "confirmCode": "1705997694210722624497994",
        "network": "9Mobile",
        "tranxDate": "23-01-2024 9:14 am"
        "serviceCharge": 10.00
    },
        "meta": null
}
Get Loan Status
GET

his endpoint is used to confirm the status of a loan application.

Service Information

baseUrl/api/v1/loan/status/{requestId}
GET

Content-Type: application/json

Bearer: {{access_token}}

X-Signature: {{encrypted_checksum}}
Parameter Name Type M/O Description
status String M Status of the request. true signifies success
code Integer M Corresponding description for the status. 200 = Successful
message String M Description of the status check response.
data Object M An object containing utility loan details. 
{
    "status": true,
    "code": 200,
    "message": "Loan Request Retrieved Successfully",
    "data": {
        "requestId": "9a1d44fij437",
        "recipient: "07067729339",
        "amount": "100"
        "confirmCode": "2021063019080126701629681",
        "network": "MTN",
        "tranxDate": "17-01-2024 2:06 pm"
        "serviceCharge": 10.00,
        "status": Open
    },
    "meta": null
}
Repay Utility Loan
POST

This endpoint is used to finalized or close out an outstanding loan. To confirm the outstanding payment, a call the the loan status endpoint will suffice

Service Information

baseUrl/api/v1/loan/repay
POST

Content-Type: application/json

Bearer: {{access_token}}

X-Signature: {{encrypted_checksum}}
Parameter Name Type M/O Description
requestId String M Unique transaction Id for the request. Maxlength (36characters)
amount Numeric M Outstanding Loan Amount. Note: It must be the exact amount as indicated by get loan status. 

{
    "requestId":"42985192836785",
    "amount":"17.57"
}
Parameter Name Type M/O Description
status String M Status of the request. true signifies success
code Integer M Corresponding description for the status. 200 = Successful
message String M Description of the status repayment request.
data Object M An object containing utility loan repayment details. 
{
    "status": true,
    "code": 200,
    "message": "Loan status updated successfully",
    "data": {
        "message": "Loan status updated successfully"
    },
    "meta": null
}

Try It Out

Test this endpoint with your credentials in our interactive API explorer.