Transaction Inquiry

• Endpoint: POST /aggregate-pay/api/gateway/paymentOrderQry
• Tags: Disbursement Service

Description

This interface is the API payment query interface. Please pay attention to the following matters when returning parameters of this interface, otherwise there may be a risk of capital loss:

1. When "code": "APPLY_SUCCESS" and status is returned, it means the query is successful. Please refer to status for order status;
2. When "code": "ORDER_NOT_EXIST" and the query returns the same result after multiple queries at intervals (5 minutes), you can place an order again without changing outTradeNo;
3. In other scenarios, please check the parameters and re-query, and be careful to reset the requestTime;

Parameters

Field	In	Type	Required	Constraints	Description
Content-Type	header	string	Yes
sign	header	string	Yes		签名信息请参考技术文档

Parameter Examples

• Content-Type: "application/json"
• sign: "FPFVT3o227JrFRbqu19boZCpVVTF9KznxyRawUmxpfXilHV/0yK46haPhAjNu1hPUMy7Vw/ILXhfzffNm4Fj0apWknlTY9OJxnSoQxS9BTFtc61tn5yV1q69x/kkBl82/qwg+XTJ4fOzy7Mar3VaC1E2PlDA6RkkKBUyNE6RYgsdB+Su7an4+4HVTNAnoe74WyvBgxTLMNg28igBTdqxaO3w/UBY6ObVp7vkqkQGdL1Y+HgmMYaAVwrM3+ALWGId0sJ+YqTY4WJ+0xCRGhaSnybiIjZsQEYyID68WNUfuavDLDsEhaMm/HfQvf5p0R1Ltovp3wwJnEbQcjY458iX5A=="

Request Body

Content-Type: application/json

Field	Type	Required	Constraints	Description	Enum
version	string	Yes	maxLength: 8	API version, current value 1.4
keyVersion	string	Yes	maxLength: 8	Key version, current value 1
requestTime	string	Yes	maxLength: 32	Request time, in line with rfc3339 specification, format: yyyy-MM-dd’T’HH:mm:ss.SSSXXX.
appId	string	Yes	maxLength: 64	Merchant AppID, the unique identifier assigned to the merchant app by PayerMax.
merchantNo	string	No	maxLength: 32	MerchantNo, the unique identifier generated when the merchant signs the contract with PayerMax.
data	object	Yes		Request data body.
data.outTradeNo	string	Yes	maxLength: 63, minLength: 1	Merchant Order Id

Example

{
  "version": "1.4",
  "keyVersion": "1",
  "requestTime": "2023-03-08T14:41:47.095+08:00",
  "appId": "6666c83333a24666674497c444a33333",
  "merchantNo": "010213834123456",
  "data": {
    "outTradeNo": "outTradeNo16699809174221"
  }
}

Responses

200

Field	Type	Required	Constraints	Description	Enum
code	string	Yes		API response code, ‘APPLY_SUCCESS’ means the interface call is successful. Indicates that the interface request is successful, but does not indicate the order status.
msg	string	Yes		Response description, ‘Success.’.
data	object	Yes		Response data body.
data.outTradeNo	string	No	maxLength: 64	Merchant Order Id
data.tradeNo	string	No		PayerMax transaction serial Order Number.
data.status	string	No	maxLength: 32	Transaction status, SUCCESS: succeeded;FAILED: failed; PENDING: in progress, BOUNCEBACK: bounceback.
data.subStatus	string	No		Transaction sub-status. When the transaction status of an order is PENDING,PayerMax provides sub-statuses to display the transaction processing progress. For specific enumeration values, please refer to:【Transaction Sub-Status Introduction】. If not returned, please contact technical support for an upgrade.
data.notifyEmail	string	No		Payee notification email address.
data.notifyPhone	string	No		Payee notification phone number.
data.responseCode	string	No		Order failed error code.Refer to details【Error Codes Doc】.
data.responseMsg	string	No		Order failed error code description.
data.reference	string	No		A pass-through parameter, which will be returned the same in the notification callback API. This field is primarily to hold customized data from merchant.
data.redeemCode	string	No		1. FAWRY withdrawal code, 2. Carrier recharge PIN code.
data.expiryTime	string	No		Order expiration time, in line with rfc3339 specification, format: yyyy-MM-dd’T’HH:mm:ss Z.
data.bounceBackTime	string	No		Order bounced back time, in line with rfc3339 specification, format: "yyyy-MM-dd’T’HH:mm:ss Z".
data.transactionUtcTime	string	Yes	maxLength: 32	Transaction creation time, conforming to rfc3339 specification, format: "yyyy-MM-dd’T’HH:mm:ss Z".
data.fundsFreezeTime	string	No		Fund deduct time, conforms to rfc3339 specification, format: "yyyy-MM-dd'T'HH:mm:ss Z".
data.fundsReturnTime	string	No		Fund return time, conforms to rfc3339 specification, format: "yyyy-MM-dd'T'HH:mm:ss Z".
data.payFinishTime	string	No		Transaction completion time, in line with rfc3339 specification, format: "yyyy-MM-dd’T’HH:mm:ss Z".
data.trade	object	Yes		Trading Information.
data.trade.amount	string	Yes		The payment amount input by the merchant in the request.
data.trade.currency	string	Yes		The currency code corresponding to the disbursement amount input by the merchant in the request.
data.source	object	Yes		Payment Information (Merchant).
data.source.amount	string	Yes		Payer - Deduction Amount.
data.source.currency	string	Yes		Payer - Deduction Currency.
data.source.exchangeRate	string	No		The exchange rate for converting the trade currency to the source currency.
data.source.fee	string	No		Payer - handling fee.
data.source.feeCurrency	string	No		Payer - handing fee currency.
data.source.tax	string	No		Payer - Tax fee.
data.source.taxCurrency	string	No		Payer - Tax fee currency.
data.destination	object	Yes		Payee Information (User).
data.destination.amount	string	Yes		Payee received Amount.
data.destination.currency	string	Yes		Payee Currency.
data.destination.exchangeRate	string	No		The exchange rate for converting the trade currency to the deduction currency.
data.destination.fee	string	No		Payee - handling fee.
data.destination.feeCurrency	string	No		Payee - handing fee currency.
data.destination.tax	string	No		Payee - Tax fee.
data.destination.taxCurrency	string	No		Payee - Tax fee Currency.
data.additionalIdentifier	object	No		Additional transaction information, this field will be returned only after the withdrawal callback is upgraded to version 3.0 or above. If necessary, you can contact PayerMax technical support for adjustments.
data.additionalIdentifier.referenceId	string	No		The transaction order number of the receiving bank/institution (based on historical experience, currently only the order number returned by BankTransfer in Saudi Arabia can be used as a voucher to confirm with the receiving bank whether the account has been received. The transaction order number format is such as: 20240418SAARNBARNB1B44410558522170)

Response Example: 1

成功示例

{
  "msg": "Success.",
  "code": "APPLY_SUCCESS",
  "data": {
    "outTradeNo": "outTradeNo1669980917422",
    "tradeNo": "20221202113517PO8822546300427849",
    "status": "SUCCESS",
    "notifyEmail": "example@gmail.com",
    "notifyPhone": "79189772406",
    "responseCode": "",
    "responseMsg": "",
    "reference": "this is reference",
    "redeemCode": "123456",
    "expiryTime": "",
    "bounceBackTime": "",
    "fundsFreezeTime": "2024-04-17T06:35:09 +0000",
    "fundsReturnTime": "2024-04-18T07:13:01 +0000",
    "transactionUtcTime": "2022-12-02T11:35:17 +0000",
    "payFinishTime": "2022-12-02T11:35:23 +0000",
    "trade": {
      "amount": "3223.59",
      "currency": "PHP"
    },
    "destination": {
      "amount": "3223.00",
      "taxCurrency": "PHP",
      "exchangeRate": "1.0000000000",
      "fee": "0.59",
      "feeCurrency": "PHP",
      "currency": "PHP",
      "tax": "0.00"
    },
    "source": {
      "amount": "3223.59",
      "taxCurrency": "PHP",
      "exchangeRate": "1.0000000000",
      "fee": "0.00",
      "feeCurrency": "PHP",
      "currency": "PHP",
      "tax": "0.00"
    },
    "additionalIdentifier": {
      "referenceId": "2024041710121481030100166528590615003"
    }
  }
}

Response Example: 2

异常示例

{
  "msg": "The order does not exist.",
  "code": "ORDER_NOT_EXIST"
}