Initiate USSD Payment with Reference

POST /payments/webhook/{paymentmethod}

Description

Initiate a USSD payment with a reference for a specific user.

Required Headers

	Type	Description
apiKey	string	(Required). Wallet API key for authentication. Include in the request header.
Authorization	string	(Required). Authentication token. Include in the request header using the "Bearer" scheme. Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiI2NGQ2Nm...

Request Body

• Media Type: application/json

Name	Type	Description
requestId*	string	(Required) Unique identifier for the USSD request.
accountId*	string	(Required) Identifier for the user's account.
userId*	string	(Required) Identifier for the user initiating the USSD payment.
amount*	number	(Required) Amount to be paid using USSD.
bankCode*	string	(Required) Bank code for processing the USSD payment.

Example

Request Body

{
  "requestId": "ussd_request_123",
  "accountId": "user_account_456",
  "userId": "user_id_789",
  "amount": 100,
  "bankCode": "bank_code_xyz"
}

Try yourself;

cURL

curl --location 'http://20.87.230.105/platform/wallets///payments/ussd/invokereference' \
--header "apiKey: yourApiKey" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer yourAccessToken" \
--data '{
  "requestId": "ussd_request_123",
  "accountId": "user_account_456",
  "userId": "user_id_789",
  "amount": 100,
  "bankCode": "bank_code_xyz"
}'

Success Response (200)

Field	Type	Description
status	Boolean	Indicates the success of the USSD payment request.
statusCode	Integer	Numeric code representing the status of the response (e.g., 0 for success).
message	String	A message indicating the outcome of the operation.
data	Object	An empty object, as no additional data is returned in a successful response.
errors	Array	An array of objects providing details about any errors encountered during the request.

Example:

json{
  "status": true,
  "statusCode": 0,
  "message": "USSD payment request initiated successfully",
  "data": {},
  "errors": []
}

Error Response

Field	Type	Description
status	Boolean	Indicates the success of the USSD payment request.
statusCode	Integer	Numeric code representing the status of the response (e.g., 400 for client error).
message	String	A message indicating the type of error.
data	Object	An empty object, as no additional data is returned in an error response.
errors	Array	An array of objects providing details about specific errors encountered during the request.

Example:

{
  "status": false,
  "statusCode": 400,
  "message": "Validation Error",
  "data": {},
  "errors": [
    {
      "message": "Invalid amount",
      "descriptiveMessage": "The 'amount' parameter should be a positive integer."
    },
    {
      "message": "Invalid bank code",
      "descriptiveMessage": "The specified 'bankCode' is not valid."
    }
  ]
}

Method: POST

>http://20.87.230.105/platform/wallets///payments/ussd/invokereference

Headers

Content-Type	Value
apiKey	{{apiKey}}

Body (raw)

{
  "requestId": "ussd_request_123",
  "accountId": "user_account_456",
  "userId": "user_id_789",
  "amount": 100,
  "bankCode": "bank_code_xyz"
}

🔑 Authentication bearer

Param	value	Type
token	{{accessCode}}	string