Skip to main content
Every request to the Star-Pay API must include an x-api-secret header. Without it, the API returns 401 Unauthorized.

​
API secret

The x-api-secret header value is the App Secret issued to your merchant account by CBE through the Star-Pay merchant dashboard. 
x-api-secret: X/2uxXAjJqaai5gRzXHzcFPcx9E6B3pibBbVSoce1U23q5hR2Sr5pxlh6WLQZBep
Your API secret grants full access to your merchant account. Never expose it in frontend code, mobile apps, or public repositories.

​
Passing the header

Include x-api-secret in every request. The examples below show how to do this across common HTTP clients. 
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, "currency": "ETB" }'

​
Bearer JWT (internal flows)

Some internal Star-Pay flows use a Bearer JWT in the Authorization header in addition to, or instead of, x-api-secret. If you are building a direct merchant integration, you only need x-api-secret. Bearer JWT usage is described in the OpenAPI security scheme: 
Authorization: Bearer <JWT>
Third-party merchant integrations authenticate exclusively with x-api-secret. Bearer JWT is used by internal services.

​
Getting your API secret

1

Log in to the merchant dashboard

Sign in to the Star-Pay merchant dashboard provided by CBE.
2

Navigate to API settings

Open the Settings section and locate API credentials or App Secret.
3

Copy your App Secret

Copy the App Secret value. Treat it like a password — store it securely and rotate it if it is ever compromised.

​
Security best practices

  • Store secrets in environment variables. Never hard-code the secret in source files.
  • Never commit secrets to source control. Add .env files to your .gitignore.
  • Never expose secrets in frontend code. All API calls that use x-api-secret must be made from a backend server.
  • Rotate your secret immediately if you suspect it has been leaked.
  • Use separate secrets per environment (staging vs. production) to limit blast radius.

​
Unauthenticated request response

A request with a missing or invalid x-api-secret returns a 401 Unauthorized response using the thirdpartyError schema: 
{
  "status": "error",
  "timestamp": "2025-05-07T07:31:30.824Z",
  "path": "/v1/starpay-api/trdp/order",
  "message": "Something wrong",
  "error": {
    "code": "GEN_004",
    "message": "An unexpected server error occurred."
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us