Every request to the Star-Pay API must be authenticated. The API uses two complementary mechanisms: an API secret key sent as a request header, and Bearer JWT tokens in the Authorization header for certain flows.
API secret key
Star-Pay issues an API secret key to each merchant through the CBE merchant dashboard. You must include this key in the x-api-secret header on every request.
Your merchant API secret key, provided by CBE or your Star-Pay merchant dashboard.
How to include it
Add the x-api-secret header to every API call:
curl -X POST https://starpayqa.starpayethiopia.com/v1/starpay-api/trdp/order \
-H "Content-Type: application/json" \
-H "x-api-secret: YOUR_SECRET" \
-d '{ ... }'
Example request
curl -X POST https://starpayqa.starpayethiopia.com/v1/starpay-api/trdp/order \
-H "Content-Type: application/json" \
-H "x-api-secret: X/2uxXAjJqaai5gRzXHzcFPcx9E6B3pibBbVSoce1U23q5hR2Sr5pxlh6WLQZBep" \
-d '{
"amount": 1000,
"description": "VANS+",
"currency": "ETB",
"customerName": "Jane Doe",
"customerPhoneNumber": "+251987654567",
"items": [
{
"productId": "6812220726f547936d6c1976",
"quantity": 1,
"item_name": "mobile",
"unit_price": 1000
}
],
"api_secret": "X/2uxXAjJqaai5gRzXHzcFPcx9E6B3pibBbVSoce1U23q5hR2Sr5pxlh6WLQZBep"
}'
Bearer JWT tokens
Some Star-Pay flows also use a Bearer JWT in the Authorization header. When a session token is issued, include it as follows:
curl -X POST https://starpayqa.starpayethiopia.com/v1/starpay-api/trdp/order \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "x-api-secret: YOUR_SECRET" \
-H "Content-Type: application/json"
Check the specific endpoint documentation to determine whether a Bearer JWT is required in addition to the x-api-secret header.
Security best practices
Never expose your API secret key in frontend JavaScript, mobile app source code, or any public repository. Treat it with the same care as a password.
Use environment variables
Store your API secret in an environment variable (STARPAY_API_SECRET) rather than hardcoding it in source code.
Keep secrets server-side
Only make Star-Pay API calls from your backend server. Never call the API directly from a browser or mobile client where the secret could be extracted.
Rotate keys when compromised
If you suspect your secret key has been leaked, rotate it immediately from the CBE merchant dashboard and update your environment configuration.
Restrict access
Limit which services and team members have access to the API secret. Use secrets management tools (e.g., AWS Secrets Manager, HashiCorp Vault) in production environments.
