POST https://starpayqa.starpayethiopia.com/v1/starpay-api/trdp/orderRequest Your App Secret provided by CBE.
Body Payment amount. Example: 1000
Order description. Example: "VANS+"
Currency code. Example: "ETB"
Customer’s full name. Example: "test"
Customer’s phone number in E.164 format. Example: "+251987654567"
Array of items included in the order. Product identifier. Example: "6812220726f547936d6c1976"
Number of units. Example: 1
Item name. Example: "mobile"
Price per unit. Example: 500
URL for the post-payment webhook callback. Star-Pay will POST the payment result to this URL after the transaction completes.
Customer’s email address.
Order expiry timestamp in ISO 8601 format. Example: "2025-07-01T23:59:59Z"
URL to redirect the customer to after payment is completed. Use this to return the customer to a confirmation or receipt page.
Response 201 Created Response status. Value: "success"
ISO 8601 timestamp of when the response was generated.
Human-readable result message. Value: "Order created successfully"
Unique identifier for the created order.
Currency code, e.g. "ETB".
URL the customer visits to complete payment. Redirect your customer to this URL.
ISO 8601 datetime at which the order expires.
Your merchant identifier.
Order description passed in the request.
Error responses Status Meaning 400Bad request — missing or invalid request parameters 401Unauthorized — invalid or missing x-api-secret 404Not found — the requested resource does not exist 500Server error — an unexpected error occurred on the Star-Pay side
Code examples curl -X POST https://starpayqa.starpayethiopia.com/v1/starpay-api/trdp/order \ -H "Content-Type: application/json" \ -H "x-api-secret: YOUR_API_SECRET" \ -d '{ "amount": 1000, "description": "Order payment", "currency": "ETB", "customerName": "Abebe Kebede", "customerPhoneNumber": "+251987654567", "api_secret": "YOUR_API_SECRET", "callbackURL": "https://yoursite.com/payment/callback", "redirectUrl": "https://yoursite.com/payment/success", "items": [ { "productId": "6812220726f547936d6c1976", "quantity": 1, "item_name": "Product Name", "unit_price": 1000 } ] }'
Example response { "status" : "success" , "timestamp" : "2025-07-01T10:00:00.000Z" , "message" : "Order created successfully" , "data" : { "order_id" : "ORD-9876543210" , "status" : "PENDING" , "amount" : 1000 , "currency" : "ETB" , "payment_url" : "https://pay.starpayethiopia.com/checkout/ORD-9876543210" , "expires_at" : "2025-07-01T23:59:59Z" , "metadata" : { "merchant_id" : "6888dc21ee7cbfe63657144f" , "customer_id" : "656445e6-20fa-440d-b8c9-0a588d1ca05b" , "description" : "Order payment" } } }
Webhook callback The callback is only sent if you provide a callbackURL in your request.
When payment is completed, Star-Pay sends a POST request to your callbackURL with the following payload:
{ "billRefNo" : "33WJ8946WB" , "status" : "PAID" , "timestamp" : "2025-12-10T11:05:37.566Z" , "message" : "Payment successful" , "merchantId" : "6888dc21ee7cbfe63657144f" , "customerId" : "656445e6-20fa-440d-b8c9-0a588d1ca05b" , "externalReferenceId" : "CLA9SR5XR9" , "amount" : 1 , "payment_type" : "USSD_PUSH" , "receipt_url" : "https://receipt.starpayethiopia.com/receiptqa/WST-33WJ8946WB" }
If the payment fails, Star-Pay sends:
{ "billRefNo" : "5I974ZLE60" , "status" : "FAILED" , "message" : "Payment failed" }
Use the billRefNo in the callback to match the payment against your own records. You can also call the verify payment endpoint to confirm the order status at any time. 