Merchant Management Service
API Reference
Transaction

Transaction API

The Transaction API allows you to manage payment transaction operations such as retrieving transaction history, viewing transaction details, sending email receipts, voiding transactions, and processing refunds.

List Transactions

Retrieves a list of transactions with optional filtering parameters.

GET /api/v2/order
Authorization: Bearer {jwt}
Accept: application/json

Parameters

NameInTypeRequiredDescription
AuthorizationheaderstringtrueBearer Token
createdStartquerystring(date)falseStart date for filtering
createdEndquerystring(date)falseEnd date for filtering
transactionIdquerystringfalseTransaction ID filter
acquirerRefNoquerystringfalseAcquirer reference number
deviceIdquerystringfalseTerminal device ID
pageSizequerynumberfalseDefault 10, use -1 to query all
pageNumberquerynumberfalseDefault 1
settleStatequerynumberfalseSettlement state (see details below)
statequerynumberfalseTransaction state (see details below)

Transaction States

  • settleState:

    • 0: WAIT_FOR_SETTLE
    • 1: SETTLED
    • 2: SETTLE_FAILED
  • state:

    • 0: INIT
    • 1: PROCESSING
    • 2: APPROVED
    • 3: DECLINED
    • 4: VOIDED
    • 5: REFUNDED
    • 6: CLOSED
    • 7: REVERSED

Response

StatusMeaningDescriptionSchema
200OK (opens in a new tab)SuccessWrapper: Response<T>

Example Response (200)

{
  "msg": "SUCCESS",
  "code": 0,
  "data": {
    "total": 25,
    "current": 1,
    "records": [
      {
        "tranId": "T20230615123456",
        "amount": {
          "currency": "USD",
          "value": 1000
        },
        "approvalCode": "123456",
        "batchNo": "001",
        "cvmPerformed": "NO_CVM",
        "appName": "Visa",
        "linkedTranId": "",
        "mchName": "Demo Merchant",
        "tsi": "E800",
        "acqTid": "10001234",
        "rrn": "123456789012",
        "tc": "ABCD1234EFGH5678",
        "tranStatus": "APPROVED",
        "tranType": "SALE",
        "atc": "001A",
        "tvr": "0000000000",
        "trace": "000123",
        "acqMid": "123456789012345",
        "accountMasked": "************1234",
        "sdkId": "SDK-123456",
        "paymentMethod": "VISA",
        "hostMessageFormat": "ISO8583",
        "aid": "A0000000031010",
        "entryMode": "CONTACTLESS"
      }
    ],
    "hasNext": true
  }
}

Get Transaction Details

Retrieves detailed information for a specific transaction.

GET /api/v2/order/{transactionId}
Authorization: Bearer {jwt}
Accept: application/json

Parameters

NameInTypeRequiredDescription
AuthorizationheaderstringtrueBearer Token
transactionIdpathstringtrueTransaction ID

Response

StatusMeaningDescriptionSchema
200OK (opens in a new tab)SuccessWrapper: Response<T>

Example Response (200)

{
  "msg": "SUCCESS",
  "code": 0,
  "data": {
    "tranId": "T20230615123456",
    "approvalCode": "123456",
    "cvmPerformed": "NO_CVM",
    "tsi": "E800",
    "tranStatus": "APPROVED",
    "tranType": "SALE",
    "atc": "001A",
    "trace": "000123",
    "acqMid": "123456789012345",
    "callbackUrl": "https://merchant.example.com/callback",
    "entryMode": "CONTACTLESS",
    "amount": {
      "currency": "USD",
      "value": 1000
    },
    "batchNo": "001",
    "appName": "Visa",
    "linkedTranId": "",
    "mchName": "Demo Merchant",
    "acqTid": "10001234",
    "rrn": "123456789012",
    "tc": "ABCD1234EFGH5678",
    "tvr": "0000000000",
    "accountMasked": "************1234",
    "sdkId": "SDK-123456",
    "paymentMethod": "VISA",
    "hostMessageFormat": "ISO8583",
    "actions": [
      {
        "tranId": "T20230615123456",
        "actionType": "SALE",
        "reason": "",
        "amount": {
          "currency": "USD",
          "value": 1000
        },
        "trace": "000123",
        "actionStatus": "APPROVED",
        "hostRespCode": "00",
        "actionId": "A123456789"
      }
    ],
    "aid": "A0000000031010"
  }
}

Send Receipt Email

Sends a transaction receipt to the specified email address.

POST /api/v2/order/email/{transactionId}
Content-Type: application/json
Authorization: Bearer {jwt}

Parameters

NameInTypeRequiredDescription
AuthorizationheaderstringtrueBearer Token
transactionIdpathstringtrueTransaction ID
emailbodystringtrueEmail recipient address

Request Body Example

{
  "email": "customer@example.com"
}

Response

StatusMeaningDescriptionSchema
200OK (opens in a new tab)SuccessWrapper: Response<T>

Example Response (200)

{
  "msg": "SUCCESS",
  "code": 0,
  "data": {
    "id": 12345
  }
}

Void Transaction

Voids (cancels) a previously approved sale or refund transaction.

POST /api/v2/order/void/{transactionId}
Content-Type: application/json
Authorization: Bearer {jwt}

Parameters

NameInTypeRequiredDescription
AuthorizationheaderstringtrueBearer Token
transactionIdpathstringtrueTransaction ID
adminPwdbodystringtrueAdmin password for authorization

Request Body Example

{
  "adminPwd": "123456"
}

Response

StatusMeaningDescriptionSchema
200OK (opens in a new tab)SuccessWrapper: Response<T>

Example Response (200)

{
  "msg": "SUCCESS",
  "code": 0,
  "data": {
    "id": 12345
  }
}

Process Refund

Issues a refund for a previously completed transaction. Supports partial refunds.

POST /api/v2/order/refund/{transactionId}
Content-Type: application/json
Authorization: Bearer {jwt}

Parameters

NameInTypeRequiredDescription
AuthorizationheaderstringtrueBearer Token
transactionIdpathstringtrueTransaction ID
refundAmountbodynumbertrueAmount to refund (can be less than original transaction)
refundReasonbodystringtrueReason for the refund
adminPwdbodystringtrueAdmin password for authorization

Request Body Example

{
  "refundAmount": 500,
  "refundReason": "Customer request",
  "adminPwd": "123456"
}

Response

StatusMeaningDescriptionSchema
200OK (opens in a new tab)SuccessWrapper: Response<T>

Example Response (200)

{
  "msg": "SUCCESS",
  "code": 0,
  "data": {
    "id": 12345
  }
}