> ## Documentation Index
> Fetch the complete documentation index at: https://developer.starpayethiopia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Transaction

# Create a Transaction

Creates a new payment session and returns a payment URL that can be used to collect payment from a customer.

Use this endpoint whenever you want to initiate a payment through StarPay.

## Endpoint

```
POST /trdp/order
```

## Authentication

Include your API secret in the request header.

Header

* `x-api-secret` (string) — Required for merchant endpoints. Your StarPay API secret key. Generate this key from the Merchant Portal under **API Keys**.

Example:

```
x-api-secret: X/2uxXAjJqaai5gRzXHzcFPcx9E6B3pibBbVSoce1U23q5hR2Sr5pxlh6WLQZBep
```

***

## Request Body

### amount

The amount to be charged to the customer.

Type: `number` — Required

Example:

```
1000
```

***

### description

A short description of the payment. This may be displayed to the customer during checkout.

Type: `string` — Required

Example:

```
"Purchase of VANS Shoes"
```

***

### currency

The currency used for the transaction.

Currently supported: `ETB`

Type: `string` — Required

Example:

```
"ETB"
```

***

### customerName

The full name of the customer making the payment.

Type: `string` — Required

Example:

```
"John Doe"
```

***

### customerPhoneNumber

The customer's phone number. This number may be used for payment verification and payment initiation.

Type: `string` — Required

Example:

```
"+251987654567"
```

***

### items

List of products or services included in the transaction.

Type: `array` — Required

Example:

```
[
	{
		"name": "VANS Shoe",
		"quantity": 1,
		"price": 1000
	}
]
```

***

### callbackURL

A server-to-server notification URL that StarPay will call when the payment status changes. Use this to automatically update your system after a successful or failed payment.

Type: `string` — Optional

Example:

```
"https://example.com/webhooks/starpay"
```

### Successful Callback Example

```json theme={null}
{
	"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"
}
```

### Failed Callback Example

```json theme={null}
{
	"billRefNo": "5I974ZLE60",
	"status": "FAILED",
	"message": "Payment failed"
}
```

***

### redirectUrl

The URL where customers will be redirected after completing payment. Typically a success or order confirmation page.

Type: `string` — Optional

Example:

```
"https://yourstore.com/payment-success"
```

***

### customerEmail

Customer email address.

Type: `string` — Optional

Example:

```
"customer@example.com"
```

***

### expiredAt

The date and time when the payment session expires (ISO 8601 format). After expiration, the customer can no longer complete the payment.

Type: `string` — Optional

Example:

```
"2025-07-01T23:59:59Z"
```

***

### metadata

Additional custom data associated with the transaction. Returned in callbacks and transaction status responses.

Type: `object` — Optional

Example:

```json theme={null}
{
	"order_reference": "ORD-2025-001",
	"customer_type": "premium"
}
```

***

## Example Request

```bash theme={null}
curl --request POST \
	--url https://api.starpayethiopia.com/trdp/order \
	--header 'Content-Type: application/json' \
	--header 'x-api-secret: YOUR_API_SECRET' \
	--data '{
		"amount": 1000,
		"currency": "ETB",
		"description": "Purchase of VANS Shoes",
		"customerName": "John Doe",
		"customerPhoneNumber": "+251987654567",
		"callbackURL": "https://example.com/webhooks/starpay",
		"redirectUrl": "https://yourstore.com/payment-success"
	}'
```

***

## Response

### Success Response

```json theme={null}
{
	"status": "success",
	"timestamp": "2025-07-01T10:30:00Z",
	"message": "Order created successfully",
	"data": {
		"billRefNo": "33WJ8946WB",
		"paymentUrl": "https://pay.starpayethiopia.com/checkout/33WJ8946WB"
	}
}
```

***

## Next Steps

After creating a transaction:

1. Redirect the customer to the `paymentUrl`.
2. Wait for a callback notification from StarPay.
3. Verify the callback signature using your Callback Key (see [Callback Signature Verification](../sign)).
4. Update the payment status in your system.
5. Optionally query the Transaction Status API for additional verification.

***

This endpoint documentation follows the structure developers expect: overview, authentication, request parameters, examples, and webhook guidance.


## OpenAPI

````yaml POST /trdp/order
openapi: 3.1.0
info:
  title: StarPay API
  version: 1.0.0
  description: >
    StarPay API is a RESTful API that provides access to various functionalities
    of the StarPay system.

    This API allows users to manage product categories, including creating,
    updating, deleting, and retrieving product categories.

    The API uses JWT for thirdparty and supports various response formats.
servers:
  - url: https://sandbox-api.starpayethiopia.com/v1/starpay-api
    description: Sandbox server
security: []
tags:
  - name: thirdparty
paths:
  /trdp/order:
    post:
      tags:
        - thirdparty
      summary: create order
      operationId: setorder
      parameters:
        - in: header
          name: x-api-secret
          required: true
          description: The App Secret provided by CBE.
          schema:
            type: string
            example: X/2uxXAjJqaai5gRzXHzcFPcx9E6B3pibBbVSoce1U23q5hR2Sr5pxlh6WLQZBep
      requestBody:
        required: true
        description: >-
          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.


          ```json 
           {
           
           billRefNo: '33WJ8946WB',
           status: 'PAID' OR 'SETTLED',
           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.


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


          ```
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createOrder'
      responses:
        '201':
          description: The request was successful, and a new `resource` was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderCreationResponse'
                required:
                  - status
                  - timestamp
                  - message
                  - data
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      x-codeSamples:
        - lang: csharp
          label: C#
          source: >
            using System.Net.Http;


            using var client = new HttpClient();

            var response = await
            client.GetAsync("https://sandbox-api.starpayethiopia.com/v1/starpay-api/trdp/orde");

            Console.WriteLine(await response.Content.ReadAsStringAsync());
components:
  schemas:
    createOrder:
      description: Create session.
      allOf:
        - $ref: '#/components/schemas/PaymentRequest'
          description: |
            The payload includes the following fields:
            you can use the following example to create a payload:


                Attention!:

                - `merchant_id`


                - `api_secret`
    OrderCreationResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        timestamp:
          type: string
          format: date-time
        message:
          type: string
          example: Order created successfully
        data:
          type: object
          properties:
            order_id:
              type: string
            status:
              type: string
            amount:
              type: number
            currency:
              type: string
            payment_url:
              type: string
              format: uri
            expires_at:
              type: string
              format: date-time
            metadata:
              type: object
              description: >-
                Additional custom information that can be sent with the order.
                This field allows you to include extra data that will be
                returned in the payment response and webhook notifications.
              example:
                merchant_id: '12345'
                customer_id: cust_67890
                order_reference: ORD-2025-001
              properties:
                merchant_id:
                  type: string
                customer_id:
                  type: string
                description:
                  type: string
    PaymentRequest:
      type: object
      properties:
        amount:
          type: number
          example: 1000
        description:
          type: string
          example: VANS+
        currency:
          type: string
          example: ETB
        customerName:
          type: string
          example: test
        customerPhoneNumber:
          type: string
          example: '+251987654567'
        callbackURL:
          type: string
          example: https://example.com/start_pay_callback
        customerEmail:
          type: string
          format: email
          example: test12@gmail.com
        expiredAt:
          type: string
          example: '2025-07-01T23:59:59Z'
        redirectUrl:
          type: string
          example: https://google.com
          description: >-
            -`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.`
        metadata:
          type: object
          description: >-
            Additional custom information that you can send with the order. This
            field allows you to include extra data (e.g., order reference,
            custom fields) that will be returned in the payment response and
            webhook notifications.
          example:
            order_reference: ORD-2025-001
            custom_field: any value
          additionalProperties: true
        items:
          type: array
          items:
            type: object
            properties:
              productId:
                type: string
                example: 6812220726f547936d6c1976
              quantity:
                type: integer
                example: 1
              item_name:
                type: string
                example: mobile
              unit_price:
                type: number
                example: 500
            required:
              - productId
              - quantity
              - item_name
              - unit_price
      required:
        - amount
        - description
        - currency
        - customerName
        - customerPhoneNumber
        - items
        - api_secret
    BadRequestError:
      type: object
      properties:
        status:
          type: string
          example: error
        timestamp:
          type: string
          example: '2025-05-07T07:31:30.824Z'
        path:
          type: string
          example: /v2/starpay-api/
        error:
          type: object
          properties:
            code:
              type: string
              example: BadRequestException
            message:
              type: string
              example: Missing required payload data, pk and payload is required
    thirdpartyError:
      type: object
      properties:
        message:
          type: string
          example: Something wrong
        status:
          type: string
          example: error
        timestamp:
          type: string
          example: '2025-05-07T07:31:30.824Z'
        path:
          type: string
          example: /v2/starpay-api/
        error:
          type: object
          properties:
            code:
              type: string
              example: GEN_004
            message:
              type: string
              example: An unexpected server error occurred.
    NotFoundError:
      type: object
      properties:
        message:
          type: string
          example: Something wrong
        status:
          type: string
          example: error
        timestamp:
          type: string
          example: '2025-05-07T07:31:30.824Z'
        path:
          type: string
          example: /v2/starpay-api/
        error:
          type: object
          properties:
            code:
              type: string
              example: ABC_001
            message:
              type: string
              example: not found
    serverError:
      type: object
      properties:
        message:
          type: string
          example: Something wrong
        status:
          type: string
          example: error
        timestamp:
          type: string
          example: '2025-05-07T07:31:30.824Z'
        path:
          type: string
          example: /v2/starpay-api/
        error:
          type: object
          properties:
            code:
              type: string
              example: GEN_004
            message:
              type: string
              example: An unexpected server error occurred.
  responses:
    BadRequest:
      description: Bad request.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BadRequestError'
    Unauthorized:
      description: Unauthorized.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/thirdpartyError'
    NotFound:
      description: Not found.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
    ServerError:
      description: internal.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/serverError'

````