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
POST /api/payments/performTransactionEvery 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: 100immediately. The card is then processed on the terminal and the final outcome is delivered to your registered webhook (see Webhooks). Match the webhook back to your request usingorderId/rrn.
transactionTypecasing is inconsistent across typesThe accepted
transactionTypestring is not uniformly cased — e.g.PURCHASE,Refund,Cash_advance,Authorization,Pre_Authorization,Reversal,Reconciliation,pre_auth_extension,pre_auth_void,Purchase_Advice,Bill_Payment. Send each value exactly as shown in its section below, and ask NamiPay to confirm whether the field is case-sensitive (and ideally to normalise these) before relying on them in production.
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
{
"orderId": "ORDER12345777986586",
"terminalId": "8184000200000077",
"transactionreqbody": {
"amount": "20",
"print": 1,
"transactionType": "PURCHASE"
}
}
Response
{
"transactionid": "BDFA3C612D6848",
"transactionDate": "2026-03-25T12:39:29.875",
"transactionType": "PURCHASE",
"statusMessage": "Transaction Process",
"status": "PROCESS",
"statusCode": 100,
"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
{
"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
{
"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
{
"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
{
"orderId": "ORDER12345777986881",
"terminalId": "8184000200000077",
"transactionreqbody": {
"ecrReferenceNo": "153243634",
"authAmount": "150.50",
"print": 1,
"transactionType": "Pre_Authorization"
}
}
Source example for Pre-Authorization looks off
In the source PDF this example omitted the top-level
orderId/terminalIdand carried a stray"TransactionType": "PRE_AUTHORIZATION"field. The request above is normalised to the common shape used by every other transaction; verify the exact required fields with NamiPay before relying on it.
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
{
"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
{
"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
{
"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
{
"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
{
"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
{
"orderId": "ORDER12345777986597",
"terminalId": "8184000200000077",
"transactionreqbody": {
"rrn": "535018000254",
"print": 1,
"transactionType": "Bill_Payment"
}
}