Cashonrails - Developer Documentation

Pay with USSD

Overview

Pay with USSD allows customers to make payments using USSD codes directly from their mobile phones. This payment method is popular in Nigeria and other African countries where USSD banking is widely adopted.

Base URL

https://mainapi.cashonrails.com/api/v1/s2s

Integration Steps

1. Get Available Banks

First, retrieve the list of supported banks with their USSD codes:

curl --location --request POST '{{baseurl}}/paywithussd/list' \
--header 'Authorization: Bearer YOUR_SECRET_KEY' \
--data ''

Sample Response

{
    "success": true,
    "message": "Banks fetched",
    "data": [
        {
            "bankName": "Access Bank",
            "ussd": "901",
            "ussdString": "*901*000*RefCode#",
            "url": "https://res.cloudinary.com/sudo-africa/image/upload/v1695123466/Banks/ajwmrhepb0smqyuf2hm2.png"
        },
        {
            "bankName": "EcoBank",
            "ussd": "326",
            "ussdString": "*326*000*RefCode#",
            "url": "https://res.cloudinary.com/sudo-africa/image/upload/v1695123466/Banks/g8bhbf21teommljk6yz3.png"
        },
        {
            "bankName": "FCMB",
            "ussd": "329",
            "ussdString": "*329*000*RefCode#",
            "url": "https://res.cloudinary.com/sudo-africa/image/upload/v1695123466/Banks/xwsqxepfesnhkqg3bbyo.png"
        },
        {
            "bankName": "Fidelity Bank",
            "ussd": "770",
            "ussdString": "*770*000*RefCode#",
            "url": "https://res.cloudinary.com/sudo-africa/image/upload/v1695123466/Banks/vsuhpb2kqecszb3n4gdg.png"
        },
        {
            "bankName": "First Bank of Nigeria",
            "ussd": "894",
            "ussdString": "*894*000*RefCode#",
            "url": "https://res.cloudinary.com/sudo-africa/image/upload/v1695123467/Banks/imwza5fjsm2zwqjpzaop.png"
        }
    ]
}

2. Initialize Payment

Make a POST request to initialize the USSD payment using the ussd code from the available banks:

curl --location '{{baseurl}}/paywithussd/initialize' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_KEY' \
--data-raw '{
    "email": "customer@email.com",
    "amount": "100",
    "currency": "NGN",
    "reference": "{{reference}}",
    "phone_number": "08012345678",
    "code": "901"
}'

Request Parameters

Parameter	Type	Required	Description
email	string	Yes	Customer’s email address
amount	string	Yes	Amount to charge
currency	string	Yes	Currency code (e.g., NGN)
reference	string	Yes	Unique transaction reference
phone_number	string	Yes	Customer’s phone number
code	string	Yes	USSD code from available banks list

Sample Response

{
    "success": true,
    "message": "USSD Transaction reference generated successfully",
    "data": {
        "_links": {
            "url": "https://mainapi.cashonrails.com/api/v1/s2s/transaction/verify/VRZ_PYI_13405902833290200383",
            "method": "GET"
        },
        "code": "*901*000*1436#"
    }
}

3. Customer Payment Process

The customer needs to dial the USSD code provided in the response on their mobile phone to complete the payment. The USSD code contains all the necessary payment information.

Customer steps:

Dial the USSD Code: Customer dials the code (e.g., *901*000*1436#) on their phone
Follow Bank Prompts: Customer follows the prompts from their bank
Enter PIN: Customer enters their banking PIN to authorize the payment
Confirmation: Customer receives confirmation of the transaction

⚠️

Make sure to clearly display the USSD code to the customer and provide instructions on how to complete the payment.

4. Verify Transaction

After the customer completes the USSD payment, verify the transaction status using either the verification URL from the response or the standard endpoint:

curl -X GET '{{baseurl}}/transaction/verify/{reference}' \
-H "Authorization: Bearer YOUR_SECRET_KEY"

You can also use the direct verification link from the response:

curl -X GET 'https://mainapi.cashonrails.com/api/v1/s2s/transaction/verify/{reference}' \
-H "Authorization: Bearer YOUR_SECRET_KEY"

Sample Success Response

{
    "status": true,
    "message": "Transaction verified successfully",
    "data": {
        "reference": "VRZ_PYI_13405902833290200383",
        "amount": "100",
        "currency": "NGN",
        "status": "success",
        "payment_method": "ussd",
        "bank_name": "Access Bank",
        "transaction_date": "2024-02-21T12:34:56Z"
    }
}

Sample Pending Response

{
    "status": true,
    "message": "Transaction is being processed",
    "data": {
        "reference": "VRZ_PYI_13405902833290200383",
        "status": "pending",
        "payment_method": "ussd"
    }
}

Sample Failed Response

{
    "status": false,
    "message": "Transaction failed",
    "data": {
        "reference": "VRZ_PYI_13405902833290200383",
        "status": "failed",
        "reason": "Payment was declined or timed out"
    }
}

⚠️

USSD payments may take a few minutes to process. Always verify the transaction status before confirming payment to the customer.

5. Cancel Transaction

You can cancel a transaction that is still pending:

curl -X GET {{baseurl}}/transaction/cancel/{reference} \
-H "Authorization: Bearer YOUR_SECRET_KEY"

Replace {reference} with your transaction reference.

Cancel Transaction Response

Success Response:

{
    "success": true,
    "message": "Transaction cancelled successfully",
    "data": {
        "reference": "VRZ_PYI_13405902833290200383",
        "status": "cancelled",
        "amount": "100",
        "currency": "NGN",
        "cancelledAt": "2024-02-21T12:34:56Z"
    }
}

Cancellation Rules

⚠️

Only pending transactions can be cancelled
Once the customer has completed the USSD payment, it cannot be cancelled
Completed transactions cannot be cancelled (contact support for refunds)
Failed transactions are already inactive and don’t need cancellation

Best Practices

Clear Instructions: Provide clear instructions on how to dial the USSD code
Timeout Handling: USSD payments typically have a 10-15 minute timeout
Status Polling: Check transaction status periodically for pending payments
Error Handling: Implement proper handling for failed or timed-out USSD payments
User Experience: Display the bank logo and name to help customers identify their bank

Important Notes

USSD payments work on all mobile phones, including basic feature phones
Customers must have sufficient balance in their bank account
USSD codes are specific to each bank and may vary
Processing times depend on the customer’s bank and network conditions
Always use the verification endpoint to confirm final payment status

Security Considerations

USSD transactions are processed through secure banking channels
Customer banking PINs are entered directly on their phone
No sensitive banking information is shared with your application
Banks implement their own fraud detection and security measures

Bank Transfer Pay with Wallet