Create order

Request Body

application/jsonRequired

The request body(payload) includes the following fields:

sign
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'
}

Do you know how to generate RSA signature (sign:)?

You can follow the RSA signature guide to get started.

If you follow the guide, you will receive a response in the following format

 {
 
  "status": "success",
  "timestamp": "2025-08-07T13:18:21.040Z",
  "message": "Signature generated successfully",
  "data": {
      "signature": "RVepgh4hiwaF6jVRyAAcIyVM3r80BKb1jQNKIJAumQF97x17TtbfK8fWgcdd8tB3uXJhflgXoUV601F/oLh0GIOZ7+NHN4Km9IthCLal8XVgLnMvL9dZr/08vUPQ3/owlMMQS34wpAuImFacBfGiy43En3fPcDgA2/joGwJLW/74UPmRnFbVwCRQCHvsb0HeCoGmrRRlcHehfb2sAL6w7P3stN24+GeIrywyNMOV25mpi66rmSVvY+CkRnNPmpl6aLXgsWTITCI08fHNn/3xC40s9LzR0L8DRrLMvnhiZG9OS9xLsoseKH3aqk/I5h95yW4uH1NTG4F2Jiz6FmUxGA=="
  }
}

assign signature to sign property on the payload

amountRequirednumber

descriptionRequiredstring

currencyRequiredstring

customerNameRequiredstring

customerPhoneNumberRequiredstring

callbackURLstring

-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.

customerEmailstring

Format: "email"

expiredAtstring

redirectUrlstring

itemsRequiredarray<object>

api_secretRequiredstring

signRequiredstring

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://stardev.starpayethiopia.com/v1/starpay-api/trdp/order" \
  -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
      }
    ],
    "api_secret": "X/2uxXAjJqaai5gRzXHzcFPcx9E6B3pibBbVSoce1U23q5hR2Sr5pxlh6WLQZBep",
    "sign": "IacM+ISzbftKgLk4DzSErGEj/AevDlKkHheiM9Ik0+TuGak4vf9mlAqqSvC5UJj06J7Jc7cEab9qwj4yiGdLjsuGPdNhe2lq/jiFX95MoR65l8JFaSp7KXKG+cYeOSHvglAHcOf9puxTJFkXiaSXXH3FaAQJSaI2433M00GtLa4wXmexEdd6Dye7Yzr+pdzOAuyqWzmt1ia//SJfEDYCA3VsoR4SszjFBnz3QcRHa1hYfSDCjqCIfskHm41hnfVzoZXzmuWJUZjJGVbncyOafMyH6Gl/4CE94E8oJWpypgsKxDejXSr32ytgHJRgZFAU7PSzAZnAxxv6Wgvn1wmarQ=="
  }'

{
  "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"
    }
  }
}