​
USSD Charge

This endpoint sends a push notification to the customer’s mobile phone, prompting them to enter their mobile money PIN to approve the payment. Supports M-PESA, Airtel Money, T-KASH, and SasaPay.

​
Channel Codes

Retrieve the list of supported mobile money channels dynamically:

GET https://adapter.cepta.co/api/v1/pay/mobile-money-banks

Use the code field from the response as the bankAccount value in your request.

​
Request

Request
curl --request POST \
  --url https://adapter.cepta.co/api/v1/pay/ussd-charge \
  --header 'X-Access-Ts: <EPOCH Timestamp(seconds)>' \
  --header 'X-Access-Key: <PUBLIC_KEY>' \
  --header 'X-Access-Signature: <HMAC SHA256 signature>' \
  --header 'Content-Type: application/json' \
  --data '{
    "transactionRef": "TXN-MPESA-001",
    "customerEmail": "[email protected]",
    "amount": 100.00,
    "currency": "KES",
    "bankAccount": "63902",
    "phoneNumber": "254712345678",
    "fullName": "Jane Wanjiku"
  }'

transactionRef must be unique per transaction. Use only alphanumeric characters, hyphens (-), underscores (_), or spaces.

​
Request Parameters

​
transactionRef
string
required

Unique reference for this transaction. Pattern: ^[a-zA-Z0-9-_\s]*$

​
customerEmail
string
required

Email address of the customer initiating the payment.

​
amount
number
required

Amount to charge in KES. Must be greater than 0.

​
currency
string
required

Currency code. Must be "KES".

​
bankAccount
string
required

Mobile money channel code. Retrieve available codes from GET /api/v1/pay/mobile-money-banks.

​
phoneNumber
string
required

Customer phone number in 254XXXXXXXXX format.

​
fullName
string

Full name of the customer (optional).

​
Sample Requests by Provider

{
  "transactionRef": "TXN-MPESA-001",
  "customerEmail": "[email protected]",
  "amount": 100.00,
  "currency": "KES",
  "bankAccount": "63902",
  "phoneNumber": "254712345678",
  "fullName": "Jane Wanjiku"
}

​
Response

Success Response
{
  "status": true,
  "message": "MPESA STK sent. Enter your PIN",
  "data": {
    "transactionRef": "TXN-MPESA-001",
    "responseCode": "0",
    "paymentId": "a4184244-7c47-4e2e-951f-5344f58b216e"
  }
}

​
Response Fields

​
status
boolean

true if the STK Push was successfully dispatched to the customer’s phone.

​
message
string

Descriptive message from the provider (e.g., "MPESA STK sent. Enter your PIN").

​
data
object

Contains the transaction details returned by the provider.

​
transactionRef
string

The transaction reference echoed back from your request.

​
responseCode
string

Response code from the mobile money provider. "0" indicates the STK Push was dispatched successfully.

​
paymentId
string

Unique payment identifier generated by Cepta. Use this to track or reference the payment.

​
ussdCode
string

USSD code returned by the provider where applicable.

​
amount
number

Amount charged in KES.

​
Error Responses

HTTPScenarioMessage
400Missing required field"One or more validation errors occurred"
400Invalid amount (0 or negative)"Amount must be greater than 0"
400Invalid transactionRef characters"Reference contains invalid characters"
408Provider timeout"Request timed out"
500Integration service unreachable"An error occurred processing request"

An STK Push response only confirms the prompt was sent — it does not confirm payment. Use your webhook or the verify-payment endpoint to confirm the final transaction status.

OverviewSingle Transfer