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

# Payments

> Manage the full lifecycle of a payment transaction — initiation, confirmation, and status queries.

## Overview

The Payments API provides a complete workflow for processing payments through CommerceCash.

| Step | Method | Endpoint                                       | Description                           |
| ---- | ------ | ---------------------------------------------- | ------------------------------------- |
| 1    | `POST` | `/api/payments/initiate`                       | Initiate a new payment transaction    |
| 2    | `POST` | `/api/payments/confirm`                        | Confirm a pending payment             |
| 3    | `GET`  | `/api/payments/{transactionId}/status`         | Query status by Transaction ID        |
| 3    | `GET`  | `/api/payments/reference/{referenceNo}/status` | Query status by Merchant Reference No |

***

## Response Envelope

All endpoints return a unified `BaseResponse<T>` envelope.

```json theme={null}
{
  "isSuccess": true,
  "errorCode": null,
  "message": null,
  "data": {}
}
```

| Field       | Type      | Description                                          |
| ----------- | --------- | ---------------------------------------------------- |
| `isSuccess` | `boolean` | `true` if the operation succeeded                    |
| `errorCode` | `string`  | Uppercase error code when `isSuccess` is `false`     |
| `message`   | `string`  | Human-readable outcome or error description          |
| `data`      | `object`  | Response payload; `null` when `isSuccess` is `false` |

***

## Error Codes

| Code                       | HTTP Status | Description                                             |
| -------------------------- | ----------- | ------------------------------------------------------- |
| `VALIDATION_ERROR`         | 400         | Request model validation failed                         |
| `INVALID_REQUEST`          | 400         | Malformed or logically invalid request                  |
| `INVALID_SIGNATURE`        | 400         | Request signature verification failed                   |
| `PRODUCT_NOT_FOUND`        | 400         | The specified product code does not exist               |
| `INVALID_EXTRA_PROPERTIES` | 400         | The `extraProperties` JSON string is malformed          |
| `INVALID_TRANSACTION_ID`   | 400         | `transactionId` is missing or empty                     |
| `INVALID_REFERENCE_NO`     | 400         | `referenceNo` is missing or empty                       |
| `TRANSACTION_NOT_FOUND`    | 404         | No transaction matches the given ID or reference number |
| `INTERNAL_ERROR`           | 500         | An unexpected server-side error occurred                |

***

## Amount Handling

<Warning>
  Payment amounts in the **Initiate** request and response are expressed in the **smallest currency unit** (e.g., cents for MYR) to avoid floating-point precision issues.

  | Value   | Equivalent |
  | ------- | ---------- |
  | `100`   | 1.00 MYR   |
  | `3491`  | 34.91 MYR  |
  | `15000` | 150.00 MYR |

  The `amount` field in **Confirm** and **Status** responses is returned as a standard decimal value (e.g., `150.00`).
</Warning>