API Explanation

Request Type

POST

Request URI

/api/v1/payment/status-query-by-reference

Request

Parameter Type Required Sample Data Description
reference String No PTM3835286374203402 The reference number from 3rd party. This can be used for order IDs that generated by merchant.

Request Example：

{
  "reference": "PTM3835286374203402"
}

Response

Parameter Type Sample Data Description
paymentId String 17043939011796739 Payment ID. A unique identifier associated with the payment transaction. This value helps track and manage individual refund requests.
totalAmount String 10000 Total Transaction Amount. Cent is the unit, “100” means a dollar.
receiptAmount String 10000 Merchant Receipt Amount. Total amount to be receipted by the merchant in cases when coupons or discounts are applied to the transaction amount. Cent is the unit, “100” means a dollar. This field is optional. May apply for cases related to Coupon Example: totalAmount ie total cost of the transaction is $100 and the customer has a $3 off from a coupon or discount applied and the merchant receipt ie. receiptAmount $97 ie. customer pays $97.
payAmount String 10000 User Payment Amount. Total amount including the fees/tax the customer agreed to pay the merchant. Cent is the unit, “100” means a dollar. Example: totalAmount ie total cost of the transaction is $100 and the customer has additional fees or tax of $1 applied on the transaction then the customer pays “payAmount” = $101 where the merchant will receive only receiptAmount of $100.
refundAmount String 10000 Refund Amount. Merchant refund amount being refunded. Cent is the unit, “100” means a dollar. Exists only in refund order queries
paymentStatus String fully_refunded/partial_refund Payment Status. Please see Payment State Code and Status
stateCode String P00004 Payment State Code. Please see Payment State Code and Status
tradeTime String Transaction Time. The timestamp when the transaction was initiated by the client. Time zone is always calculated/displayed in EST irrespective of the merchant location.
payInfo String Transaction Additional Information, this only apply for Chinese Wallet Payment transaction.
reference String PTM3835286374203402 The reference number from 3rd party. This can be used for order IDs that generated by integrate merchant.

Response Example：

{
    "status": "SUCCESS",
    "result": {
        "paymentId": "17042154774331718",
        "totalAmount": "6000",
        "receiptAmount": "6000",
        "payAmount": "6000",
        "refundAmount": "0",
        "paymentStatus": "success",
        "tradeTime": "2023-09-14 16:25:00 EDT",
        "payInfo": "",
        "stateCode": "P00003",
        "reference": "PTM3835286374203402"
    }
}

Payment State Code and Status

State Code Payment Status Description
P00001 init Payment is initiated
P00002 authorised Payment is authorised
P00003 success Payment is successfully captured
P00004 fully_refunded Payment is fully refunded
P00005 partial_refunded Payment is partially refunded
P00006 orderclosed Payment is refused
P00007 orderclosed Payment is voided
P00008 orderclosed Payment is failed
P00009 fully_reversal Payment is fully reversed (EMV transactions only)
P00010 orderclosed Payment is expired, (not being captured for a long time)
P00011 orderclosed Payment capture is failed
P00012 success Refund transaction is successful
P00013 init Refund transaction is initiated
P00014 failure Refund transaction is failed
P00015 init Void request is initiated
P00016 success Void request is successful
P00017 failure Void request is failed

API Response error code

code message description
10005 Invalid parameter Parameter format incorrect
20004 Database error Transaction data induced database error.
20034 Other case Any other errors that not include in the list
90000 Unauthorized The entered access token is invalid