Skip to main content
Creating a payment order is the first step in the Star-Pay checkout flow. The API returns a payment_url that you redirect your customer to, where they complete the payment. Endpoint: POST /trdp/order Base URL: https://starpayqa.starpayethiopia.com/v1/starpay-api

​
Request parameters

​
Headers

​
x-api-secret
string
required
Your merchant API secret key provided by CBE. See Authentication.

​
Body

​
amount
number
required
The total payment amount. Example: 1000
​
description
string
required
A short description of the payment. Example: "VANS+"
​
currency
string
required
ISO 4217 currency code. Example: "ETB"
​
customerName
string
required
Full name of the customer. Example: "Jane Doe"
​
customerPhoneNumber
string
required
Customer phone number in E.164 format. Example: "+251987654567"
​
items
object[]
required
Array of line items included in the order. Each item must contain:
  • productId (string, required) — your product identifier
  • quantity (integer, required) — number of units
  • item_name (string, required) — display name of the product
  • unit_price (number, required) — price per unit
​
api_secret
string
required
Your API secret, also included in the request body in addition to the header.
​
callbackURL
string
URL on your server where Star-Pay will POST payment status notifications after the transaction completes. See Webhook callbacks.
​
customerEmail
string
Customer email address. Example: "[email protected]"
​
expiredAt
string
ISO 8601 datetime at which the order expires. Example: "2025-07-01T23:59:59Z"
​
redirectUrl
string
URL where Star-Pay redirects the customer after a successful payment — typically a confirmation or receipt page on your site.

​
Response

A successful request returns HTTP 201 with an OrderCreationResponse body. 
{
  "status": "success",
  "timestamp": "2025-07-01T10:00:00.000Z",
  "message": "Order created successfully",
  "data": {
    "order_id": "5428255034",
    "status": "PENDING",
    "amount": 1000,
    "currency": "ETB",
    "payment_url": "https://checkout.starpayethiopia.com/pay/5428255034",
    "expires_at": "2025-07-01T23:59:59Z",
    "metadata": {
      "merchant_id": "6888dc21ee7cbfe63657144f",
      "customer_id": "656445e6-20fa-440d-b8c9-0a588d1ca05b",
      "description": "VANS+"
    }
  }
}

​
Response fields

​
status
string
required
Top-level request status. Value: "success"
​
timestamp
string
required
ISO 8601 datetime of when the response was generated.
​
message
string
required
Human-readable result message.
​
data
object
required

​
Code examples

curl -X POST https://starpayqa.starpayethiopia.com/v1/starpay-api/trdp/order \
  -H "Content-Type: application/json" \
  -H "x-api-secret: YOUR_SECRET" \
  -d '{
    "amount": 1000,
    "description": "VANS+",
    "currency": "ETB",
    "customerName": "Jane Doe",
    "customerPhoneNumber": "+251987654567",
    "customerEmail": "[email protected]",
    "callbackURL": "https://yoursite.com/payments/callback",
    "redirectUrl": "https://yoursite.com/payments/success",
    "expiredAt": "2025-07-01T23:59:59Z",
    "items": [
      {
        "productId": "6812220726f547936d6c1976",
        "quantity": 2,
        "item_name": "mobile",
        "unit_price": 500
      }
    ],
    "api_secret": "YOUR_SECRET"
  }'

​
Callback payload

If you provide a callbackURL, Star-Pay will POST the following JSON to that URL after the transaction completes.

​
Successful payment

{
  "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": 1000,
  "payment_type": "USSD_PUSH",
  "receipt_url": "https://receipt.starpayethiopia.com/receiptqa/WST-33WJ8946WB"
}

​
Failed payment

{
  "billRefNo": "5I974ZLE60",
  "status": "FAILED",
  "message": "Payment failed"
}
FieldDescription
billRefNoStar-Pay’s internal bill reference number
statusPAID or FAILED
timestampISO 8601 time of transaction completion
merchantIdYour merchant identifier
customerIdCustomer identifier in Star-Pay’s system
externalReferenceIdExternal reference for reconciliation
amountAmount that was charged
payment_typePayment method used, e.g. USSD_PUSH
receipt_urlLink to the payment receipt
Verify the callback signature before trusting the payload. See Webhook callbacks for signature verification instructions.

​
Next steps

Verify a payment

Poll the verification endpoint to check payment status independently of callbacks.

Webhook callbacks

Set up HMAC-SHA256 signature verification for secure callback handling.

Build docs developers (and LLMs) love

Get started for freeTalk to us