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