Skip to main content
This guide walks you through creating a payment order, redirecting a customer, and verifying the result — the three steps every Star-Pay integration follows.
1

Get your API secret

Log in to the Star-Pay merchant dashboard provided by CBE and copy your API secret from the Settings → API Keys section.You will pass this value in the x-api-secret header on every request.
Use your sandbox API secret while testing. Switch to your production key only when you are ready to go live.
2

Create a payment order

Call POST /trdp/order with the customer’s details and the transaction amount. Star-Pay creates an order and returns a hosted payment_url to redirect the customer to.
curl --request POST \
  --url https://starpayqa.starpayethiopia.com/v1/starpay-api/trdp/order \
  --header "Content-Type: application/json" \
  --header "x-api-secret: YOUR_API_SECRET" \
  --data '{
    "amount": 500,
    "description": "Order #1042",
    "currency": "ETB",
    "customerName": "Abebe Bekele",
    "customerPhoneNumber": "+251900000000",
    "callbackURL": "https://yourapp.com/payments/callback",
    "redirectUrl": "https://yourapp.com/payments/success",
    "items": [
      {
        "productId": "6812220726f547936d6c1976",
        "quantity": 1,
        "item_name": "Premium Plan",
        "unit_price": 500
      }
    ]
  }'
A successful request returns HTTP 201 with the new order:
{
  "status": "success",
  "timestamp": "2025-07-01T10:00:00.000Z",
  "message": "Order created successfully",
  "data": {
    "order_id": "5428255034",
    "status": "PENDING",
    "amount": 500,
    "currency": "ETB",
    "payment_url": "https://pay.starpayethiopia.com/checkout/5428255034",
    "expires_at": "2025-07-01T10:30:00.000Z"
  }
}
Save the order_id — you will need it to verify the payment later.
3

Redirect the customer to the payment page

Take the payment_url from the response and redirect the customer’s browser to it. Star-Pay hosts the payment page where the customer enters their phone number and approves the USSD Push prompt.
Node.js
// Express example
res.redirect(data.data.payment_url);
After the customer completes or declines payment, Star-Pay redirects them back to your redirectUrl. If you provided a callbackURL, Star-Pay also sends a POST request to that URL with the payment result.
Store the order_id in your session or database before redirecting so you can look it up when the customer returns.
4

Verify payment status

Call POST /trdp/verify with the order_id to confirm the payment outcome. Use this endpoint when the customer returns to your site or as a fallback if your webhook does not arrive.
curl --request POST \
  --url https://starpayqa.starpayethiopia.com/v1/starpay-api/trdp/verify \
  --header "Content-Type: application/json" \
  --header "x-api-secret: YOUR_API_SECRET" \
  --data '{
    "orderId": "5428255034"
  }'
A paid order returns:
{
  "status": "success",
  "timestamp": "2025-07-01T10:12:00.000Z",
  "message": "Payment verified successfully",
  "data": {
    "order_id": "5428255034",
    "status": "PAID",
    "amount": 500,
    "currency": "ETB",
    "updated_at": "2025-07-01T10:11:45.000Z"
  }
}
Check data.status in your code before fulfilling the order:
StatusMeaning
PAIDPayment completed — safe to fulfill
PENDINGCustomer has not yet completed payment
FAILEDPayment was declined or timed out
Always verify payment server-side before fulfilling orders. Do not rely solely on the redirect or client-side state.

​
Next steps

Authentication

Learn how to rotate your API secret and manage credentials securely.

Webhooks

Set up real-time payment notifications with HMAC-SHA256 signature verification.

API Reference

Full endpoint documentation with all request fields and response schemas.

Testing

Use sandbox test numbers to simulate successful and failed payments.

Build docs developers (and LLMs) love

Get started for freeTalk to us