# Payment Transactions

One endpoint, every transaction type. Send orderId + terminalId + a transactionreqbody, then get the final result by webhook.

All payment transactions use a single endpoint with different `transactionType` values inside the request body.

## Common endpoint — `POST /api/payments/performTransaction`

Every request includes `orderId` and `terminalId` at the top level, plus a `transactionreqbody` object holding the transaction-specific parameters.

| Parameter            | Type   | Required | Description                                           |
| -------------------- | ------ | -------- | ----------------------------------------------------- |
| `orderId`            | string | Yes      | Unique order identifier for this request              |
| `terminalId`         | string | Yes      | The terminal ID to route the transaction to           |
| `transactionreqbody` | object | Yes      | Transaction-specific parameters (see each type below) |

> 📘 The response is not the final result
>
> A successful call returns `status: PROCESS` / `statusCode: 100` immediately. The card is then processed on the terminal and the **final outcome is delivered to your registered webhook** (see [Webhooks](https://docs.namipay.com.sa/docs/cloud-middleware-webhooks)). Match the webhook back to your request using `orderId` / `rrn`.

## Purchase

Initiates a standard purchase transaction.

| Parameter         | Type    | Required | Description                          |
| ----------------- | ------- | -------- | ------------------------------------ |
| `amount`          | string  | Yes      | Transaction amount                   |
| `print`           | integer | Yes      | Print receipt flag (`1` yes, `0` no) |
| `transactionType` | string  | Yes      | Must be `PURCHASE`                   |

**Request**

```json
{
  "orderId": "ORDER12345777986586",
  "terminalId": "8184000200000077",
  "transactionreqbody": {
    "amount": "20",
    "print": 1,
    "transactionType": "PURCHASE"
  }
}
```

**Response**

```json
{
  "transactionid": "BDFA3C612D6848",
  "transactionDate": "2026-03-25T12:39:29.875",
  "transactionType": "PURCHASE",
  "statusMessage": "Transaction Request Reached to Terminal",
  "status": "SENT_TO_TERMINAL",
  "statusCode": 1,
  "orderId": "ORDER12345777986586",
  "transactionreqbody": {
    "amount": "20",
    "print": "1",
    "transactionType": "PURCHASE"
  }
}
```

## Refund

Processes a refund for a previous transaction.

| Parameter                 | Type    | Required | Description                                 |
| ------------------------- | ------- | -------- | ------------------------------------------- |
| `rrn`                     | string  | Yes      | Retrieval Reference Number of original txn  |
| `originalTransactionDate` | string  | Yes      | Date of original transaction (`YYYY-MM-DD`) |
| `refundAmount`            | string  | Yes      | Amount to refund                            |
| `print`                   | integer | Yes      | Print receipt flag                          |
| `transactionType`         | string  | Yes      | Must be `REFUND`                            |

**Request**

```json
{
  "orderId": "ORDER12345777986878",
  "terminalId": "8184000200000077",
  "transactionreqbody": {
    "rrn": "522314000067",
    "originalTransactionDate": "2025-08-11",
    "refundAmount": "116.50",
    "print": 1,
    "transactionType": "Refund"
  }
}
```

## Cash Advance

Processes a cash advance transaction.

| Parameter         | Type    | Required | Description            |
| ----------------- | ------- | -------- | ---------------------- |
| `cashAdvanceAmt`  | string  | Yes      | Cash advance amount    |
| `print`           | integer | Yes      | Print receipt flag     |
| `transactionType` | string  | Yes      | Must be `CASH_ADVANCE` |

**Request**

```json
{
  "orderId": "ORDER12345777986865",
  "terminalId": "8184000200000077",
  "transactionreqbody": {
    "cashAdvanceAmt": "10.50",
    "print": 1,
    "transactionType": "Cash_advance"
  }
}
```

## Authorization

Authorizes a transaction amount without capturing funds.

| Parameter         | Type    | Required | Description             |
| ----------------- | ------- | -------- | ----------------------- |
| `authAmount`      | string  | Yes      | Authorization amount    |
| `print`           | integer | Yes      | Print receipt flag      |
| `transactionType` | string  | Yes      | Must be `Authorization` |

**Request**

```json
{
  "orderId": "ORDER12345777986880",
  "terminalId": "8184000200000077",
  "transactionreqbody": {
    "authAmount": "150.50",
    "print": 1,
    "transactionType": "Authorization"
  }
}
```

## Pre-Authorization

Places a hold on funds for later capture. Commonly used for hotels and car rentals.

| Parameter         | Type    | Required | Description                 |
| ----------------- | ------- | -------- | --------------------------- |
| `ecrReferenceNo`  | string  | Yes      | ECR reference number        |
| `authAmount`      | string  | Yes      | Pre-authorization amount    |
| `print`           | integer | Yes      | Print receipt flag          |
| `transactionType` | string  | Yes      | Must be `PRE_AUTHORIZATION` |

**Request**

```json
{
  "orderId": "ORDER12345777986881",
  "terminalId": "8184000200000077",
  "transactionreqbody": {
    "ecrReferenceNo": "153243634",
    "authAmount": "150.50",
    "print": 1,
    "transactionType": "Pre_Authorization"
  }
}
```

## Reversal

Reverses a transaction that has not yet been settled.

| Parameter         | Type    | Required | Description                           |
| ----------------- | ------- | -------- | ------------------------------------- |
| `rrn`             | string  | Yes      | Retrieval Reference Number to reverse |
| `refundAmount`    | string  | Yes      | Amount to reverse                     |
| `print`           | integer | Yes      | Print receipt flag                    |
| `transactionType` | string  | Yes      | Must be `REVERSAL`                    |

**Request**

```json
{
  "orderId": "ORDER12345777986882",
  "terminalId": "8184000200000077",
  "transactionreqbody": {
    "rrn": "522314000067",
    "refundAmount": "116.50",
    "print": 1,
    "transactionType": "Reversal"
  }
}
```

## Reconciliation

Initiates end-of-day reconciliation to settle all pending transactions.

| Parameter         | Type    | Required | Description              |
| ----------------- | ------- | -------- | ------------------------ |
| `print`           | integer | Yes      | Print receipt flag       |
| `transactionType` | string  | Yes      | Must be `RECONCILIATION` |

**Request**

```json
{
  "orderId": "ORDER12345777986883",
  "terminalId": "8184000200000077",
  "transactionreqbody": {
    "print": 1,
    "transactionType": "Reconciliation"
  }
}
```

## Pre-Auth Extension

Extends the hold period of an existing pre-authorization.

| Parameter                 | Type    | Required | Description                              |
| ------------------------- | ------- | -------- | ---------------------------------------- |
| `rrn`                     | string  | Yes      | RRN of original pre-authorization        |
| `amount`                  | string  | Yes      | Extended authorization amount            |
| `originalTransactionDate` | string  | Yes      | Date of original pre-auth (`YYYY-MM-DD`) |
| `print`                   | integer | Yes      | Print receipt flag                       |
| `transactionType`         | string  | Yes      | Must be `PRE_AUTH_EXTENSION`             |

**Request**

```json
{
  "orderId": "ORDER12345777986884",
  "terminalId": "8184000200000077",
  "transactionreqbody": {
    "rrn": "535018000254",
    "amount": "150",
    "originalTransactionDate": "2025-12-16",
    "print": 1,
    "transactionType": "pre_auth_extension"
  }
}
```

## Pre-Auth Void

Cancels an existing pre-authorization and releases the held funds.

| Parameter                 | Type    | Required | Description                              |
| ------------------------- | ------- | -------- | ---------------------------------------- |
| `rrn`                     | string  | Yes      | RRN of pre-authorization to void         |
| `amount`                  | string  | Yes      | Original pre-authorization amount        |
| `originalTransactionDate` | string  | Yes      | Date of original pre-auth (`YYYY-MM-DD`) |
| `print`                   | integer | Yes      | Print receipt flag                       |
| `transactionType`         | string  | Yes      | Must be `PRE_AUTH_VOID`                  |

**Request**

```json
{
  "orderId": "ORDER12345777986885",
  "terminalId": "8184000200000077",
  "transactionreqbody": {
    "rrn": "535018000254",
    "amount": "150",
    "originalTransactionDate": "2025-12-17",
    "print": 1,
    "transactionType": "pre_auth_void"
  }
}
```

## Purchase Advice

Completes a pre-authorized transaction by capturing the funds.

| Parameter                 | Type    | Required | Description                              |
| ------------------------- | ------- | -------- | ---------------------------------------- |
| `rrn`                     | string  | Yes      | RRN of pre-authorization to complete     |
| `originalTransactionDate` | string  | Yes      | Date of original pre-auth (`YYYY-MM-DD`) |
| `amount`                  | string  | Yes      | Final capture amount                     |
| `print`                   | integer | Yes      | Print receipt flag                       |
| `transactionType`         | string  | Yes      | Must be `PURCHASE_ADVICE`                |

**Request**

```json
{
  "orderId": "ORDER12345777986886",
  "terminalId": "8184000200000077",
  "transactionreqbody": {
    "rrn": "535018000254",
    "originalTransactionDate": "2025-12-18",
    "amount": "150",
    "print": 1,
    "transactionType": "Purchase_Advice"
  }
}
```

## Bill Payment

> 📘 New in v1.1

Processes a bill payment transaction.

| Parameter         | Type    | Required | Description                |
| ----------------- | ------- | -------- | -------------------------- |
| `rrn`             | string  | Yes      | Retrieval Reference Number |
| `print`           | integer | Yes      | Print receipt flag         |
| `transactionType` | string  | Yes      | Must be `BILL_PAYMENT`     |

**Request**

```json
{
  "orderId": "ORDER12345777986597",
  "terminalId": "8184000200000077",
  "transactionreqbody": {
    "rrn": "535018000254",
    "print": 1,
    "transactionType": "Bill_Payment"
  }
}
```