Create Transaction

Request Body

application/jsonRequired

The request body(payload) includes the following fields:

api_secret
callbackURL

If you want to receive the customer back in your application after the transaction, you can provide a callback URL. Starpay will automatically redirect the user to your URL when the payment is completed successfully or Failed.

If you provide a callbackURL, StarPay will send the following response to that URL after a 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: 1,
 payment_type: 'USSD_PUSH',
 receipt_url: 'https://receipt.starpayethiopia.com/receiptqa/WST-33WJ8946WB'
}

The error response for failed payments.

 {
 
  billRefNo: '5I974ZLE60',
  status: 'FAILED',
  message: 'Payment failed'
}

amountRequirednumber

descriptionRequiredstring

currencyRequiredstring

customerNameRequiredstring

customerPhoneNumberRequiredstring

callbackURLstring

customerEmailstring

Format: "email"

expiredAtstring

redirectUrlstring

-The URL where the payment gateway will automatically redirect the customer after a successful payment. This is used to bring the customer back to your website or app to show a confirmation page, receipt, or next steps.

itemsRequiredarray<object>

Header Parameters

x-api-secretRequiredstring

The App Secret provided by CBE.

x-api-keyRequiredstring

Version of the Mini-App running on the device.

Response Body

The request was successful, and a new resource was created.

TypeScript Definitions

Use the response body type in TypeScript.

statusRequiredstring

timestampRequiredstring

Format: "date-time"

messageRequiredstring

dataRequiredobject

curl -X POST "https://starpayqa.starpayethiopia.com/v1/starpay-api/trdp/order" \
  -H "x-api-secret: X/2uxXAjJqaai5gRzXHzcFPcx9E6B3pibBbVSoce1U23q5hR2Sr5pxlh6WLQZBep" \
  -H "x-api-key: i5gRzXHzcFPcx9E6B" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "description": "VANS+",
    "currency": "ETB",
    "customerName": "test",
    "customerPhoneNumber": "+251987654567",
    "callbackURL": "https://example.com/start_pay_callback",
    "customerEmail": "test12@gmail.com",
    "expiredAt": "2025-07-01T23:59:59Z",
    "redirectUrl": "https://google.com",
    "items": [
      {
        "productId": "6812220726f547936d6c1976",
        "quantity": 1,
        "item_name": "mobile",
        "unit_price": 500
      }
    ]
  }'

{
  "status": "success",
  "timestamp": "2019-08-24T14:15:22Z",
  "message": "Order created successfully",
  "data": {
    "order_id": "string",
    "status": "string",
    "amount": 0,
    "currency": "string",
    "payment_url": "http://example.com",
    "expires_at": "2019-08-24T14:15:22Z",
    "metadata": {
      "merchant_id": "string",
      "customer_id": "string",
      "description": "string"
    }
  }
}