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

# Initiate Payment

> Creates a new payment transaction and returns a system-generated Transaction ID.

`POST /api/payments/initiate`

Creates a new payment transaction. On success, a `transactionId` is returned — use it in subsequent [Confirm](/api-reference/payments/confirm) or [Status](/api-reference/payments/get-status) calls.

***

## Request Body

<ParamField body="merchantId" type="string (uuid)" required>
  Merchant unique identifier in UUID format.

  **Example:** `3fa85f64-5717-4562-b3fc-2c963f66afa6`
</ParamField>

<ParamField body="referenceNo" type="string" required>
  Merchant-assigned reference number for this transaction. Must be unique within the merchant.

  **Example:** `MER-20240616-001`
</ParamField>

<ParamField body="description" type="string">
  Optional description or purpose of the payment.
</ParamField>

<ParamField body="amount" type="integer" required>
  Payment amount in the **smallest currency unit** (e.g., cents for MYR).

  | Value   | Equivalent |
  | ------- | ---------- |
  | `100`   | 1.00 MYR   |
  | `3491`  | 34.91 MYR  |
  | `15000` | 150.00 MYR |
</ParamField>

<ParamField body="currencyCode" default="MYR" type="string">
  ISO 4217 currency code.

  **Examples:** `MYR`, `USD`, `SGD`
</ParamField>

<ParamField body="productCode" type="string" required>
  Target product or service code.

  **Examples:** `TNB`, `AIR_SELANGOR`, `STARBUCK`, `RAZER_PIN`
</ParamField>

<ParamField body="quantity" type="integer">
  Number of items. Applicable for products such as gift cards or PINs.
</ParamField>

<ParamField body="countryCode" type="string">
  ISO 3166-1 alpha-2 country code.

  **Examples:** `MY`, `SG`
</ParamField>

<ParamField body="storeId" type="string" required>
  Merchant store identifier originating the payment request.

  **Example:** `STORE-001`
</ParamField>

<ParamField body="deviceId" type="string">
  Device identifier of the terminal or client making the request.

  **Example:** `DEV-12345`
</ParamField>

<ParamField body="payerId" type="string">
  Payer identifier. Accepts a mobile number, bill account number, e-wallet QR code, or any account number.
</ParamField>

<ParamField body="returnUrl" type="string">
  URL to redirect the payer to after the payment is completed or cancelled (for redirect-based flows).
</ParamField>

<ParamField body="extraProperties" type="string (JSON)">
  Additional product-specific properties serialised as a JSON string.

  **Example:** `"{\"accountNumber\":\"123456\"}"`
</ParamField>

***

## Response

### 200 — Payment Initiated

<ResponseField name="isSuccess" type="boolean">
  `true`
</ResponseField>

<ResponseField name="errorCode" type="null">
  `null` on success.
</ResponseField>

<ResponseField name="message" type="string | null">
  Optional informational message.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="PaymentInitiateResponse">
    <ResponseField name="transactionId" type="string">
      System-generated unique transaction ID. Use this in all subsequent calls.

      **Example:** `TXN-20240616143022-A7F9E2`
    </ResponseField>

    <ResponseField name="referenceNo" type="string">
      Merchant reference number echoed from the request.
    </ResponseField>

    <ResponseField name="status" type="string">
      Initial transaction status.

      **Common values:** `PENDING`, `INITIATED`
    </ResponseField>

    <ResponseField name="amount" type="integer">
      Payment amount in the smallest currency unit, echoed from the request.
    </ResponseField>

    <ResponseField name="currencyCode" type="string">
      Currency code echoed from the request.
    </ResponseField>

    <ResponseField name="productCode" type="string">
      Product code echoed from the request.
    </ResponseField>

    <ResponseField name="createdAt" type="string (ISO 8601)">
      UTC timestamp of when the transaction was created.

      **Example:** `2024-06-16T14:30:22Z`
    </ResponseField>

    <ResponseField name="extraProperties" type="string | null">
      Additional response data from the payment provider, serialised as a JSON string.
    </ResponseField>
  </Expandable>
</ResponseField>

### 400 — Bad Request

Model validation failed or the request is logically invalid.

### 500 — Internal Server Error

***

## Examples

<CodeGroup>
  ```json Request theme={null}
  {
    "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "referenceNo": "MER-20240616-001",
    "description": "TNB Electricity Bill Payment",
    "amount": 15000,
    "currencyCode": "MYR",
    "productCode": "TNB",
    "quantity": 1,
    "countryCode": "MY",
    "storeId": "STORE-001",
    "deviceId": "DEV-12345",
    "payerId": "0123456789",
    "returnUrl": "https://merchant.example.com/payment/callback",
    "extraProperties": {
      "accountNumber": "123456"
    }
  }
  ```

  ```json 200 Response theme={null}
  {
    "isSuccess": true,
    "errorCode": null,
    "message": null,
    "data": {
      "transactionId": "TXN-20240616143022-A7F9E2",
      "referenceNo": "MER-20240616-001",
      "status": "INITIATED",
      "amount": 15000,
      "currencyCode": "MYR",
      "productCode": "TNB",
      "createdAt": "2024-06-16T14:30:22Z",
      "extraProperties": null
    }
  }
  ```

  ```json 400 Response theme={null}
  {
    "isSuccess": false,
    "errorCode": "VALIDATION_ERROR",
    "message": "The ReferenceNo field is required; The Amount field must be greater than 0.",
    "data": null
  }
  ```

  ```json 500 Response theme={null}
  {
    "isSuccess": false,
    "errorCode": "INTERNAL_ERROR",
    "message": "An unexpected error occurred. Please try again.",
    "data": null
  }
  ```
</CodeGroup>