Query Order Page
Overview
The queryOrderPage interface enables merchants to query multiple orders in a paginated format, helping them retrieve order information based on date ranges, device IDs, and order statuses.
API URL
- UAT: https://uat.test2pay.com/sgs/api/acquire2Query/queryOrderPage
- Production: https://api.payby.com/sgs/api/acquire2Query/queryOrderPage
Request
Http Header
Attributes
- Content-Language String
- The language for the response message. Defaults to English.
- Example value:
en - Maximum length:
10
- Content-Type String Required
- Media type of the request body.
- Required for operations with a request body.
- Format:
application/json
- sign String Required
- Request signature using private-key cryptography.
- Ensures the payment gateway can verify the request origin.
- Example value:
RSA_SIGNATURE_BASE64_STRING
- Partner-Id String Required
- Unique partner identifier.
- Example value:
200001200101 - Maximum length:
12
Http Body
requestTime Timestamp Required
- This parameter is used to prevent repeated requests for orders that should have been cancelled due to timeouts.
- Example value: 1581404947666
bizContent Object Required
Contains the main query parameters for filtering and pagination.
startDate String Required
- Query start date in YYYY-MM-DD format.
- Example value: 2022-07-22
- Maximum length:
10
endDate String Required
- Query end date in YYYY-MM-DD format.
- Example value: 2022-07-22
- Maximum length:
10
deviceIdList List
- Filter by specific device IDs. Empty array returns all devices.
- Example value: []
includeStatusList List
- Filter by order status. Empty array returns all statuses.
- Possible values:
CREATED,PAID_SUCCESS,SETTLED,FAILURE - Example value: []
sortPageParam Object Required
Pagination and sorting configuration.
number Int
- Page number starting from 0.
- Default value: 0
- Example value: 0
size Int Required
- Number of records per page.
- Example value: 20
Request Sample
//Http Header
{
"Content-Language": "en",
"Content-Type": "application/json",
"sign": "IXJI/QicPQotIsIDBcSGIg6jtJUXs1rTuifQFZUNd3KDTl25GKmpYO7OrkaKkTV0shDRitLmkxJCe3Z60zHE2ZSeVczrhwrnmuMG+bX9N22Hw821H6MydsXetYHRnyf5dPbgpmVja582w49grA6jRlVFAVMYdxKJDPSCb2X/IpltvyrLQ1Wt+lqr+fnpYXvyON6/PIZIQIknC8BVddVahxJnaC6HEagvJf6gskz22/DFfPHT1mlMA9pg8qrbh4O7DYZahf8TB3nIzAPc/FHOUZkYYTT2c8m4eLL8740nJVK7D3IOSqSnBAU/iJ2omjPPFvRCCSqzz17pkGsT7AW91w==",
"Partner-Id": "200000000888"
}
//Http Body
{
"requestTime": 1581404947666,
"bizContent": {
"startDate": "2022-07-22",
"endDate": "2022-07-22",
"deviceIdList": [],
"includeStatusList": [],
"sortPageParam": {
"number": 0,
"size": 20
}
}
}
Response
Http Header
sign String Required
When Botim Money sends response, Botim Money will use its own private key to sign the message, and the merchant uses Botim Money's public key to verify the signature. If the verification is passed, it proves that the response was sent by Botim Money and not faked by others.
Http Body
head
Attributes
applyStatus Enum Required
- The result of the request. Possible values:
SUCCESS: Application successful.FAIL: Application failed. Check thecodeandmsgfor the exact reason.ERROR: Application error. Signature verification failed. Ensure the private key used for the signature and the public key uploaded on the Botim Money portal are a valid key pair.
- The result of the request. Possible values:
code String Required
- Response code.
- Example value:
0 - Maximum length:
10
msg String
- Description of the response code.
- Maximum length:
200
traceCode String
- Internal code for locating the error.
body
Notice
Body is returned only when applystatus = success, and code = 0.
If applystatus = error or failed; or applystatus = success, code !=0 , that indicates an error. Please check errors and try again.
totalElements Int Required
- Total number of records found in the query.
- Example value: 6
totalPages Int Required
- Total number of pages available.
- Example value: 1
sortPageParam Object Required
Pagination configuration.
number Int Required
- Current page number (0-based).
- Example value: 0
size Int Required
- Records per page configuration.
- Example value: 20
items List Required
Array of order records.
merchantOrderNo String Required
- The merchant's reference number of the request.
- Example value: b7023000-fb84-4259-9870-8dff62c7299c
- Maximum length:
64
orderNo String Required
- The Botim Money's unique identify number of the order.
- Example value: 131658483622183687
deviceId String Required
- Payment device identifier.
- Example value: 20001019
status String Required
- Order status.
- Possible values:
CREATED,PAID_SUCCESS,SETTLED,FAILURE - Example value: SETTLED
product String Required
- Payment product type.
- Example value: Basic Payment Gateway
totalAmount Money Required
Order total amount with currency.
amount Decimal Required
- Example value: 100.00
currency String Required
- Example value: AED
payeeMid String Required
- Receiving merchant identifier.
- Example value: 200000030906
expiredTime Timestamp Required
- Order expiration timestamp.
- Example value: 1658487222029
subject String
- Order description or subject.
- Example value: Test
requestTime Timestamp Required
- Order creation timestamp.
- Example value: 1658519999999
paySceneCode String Required
- Payment scenario identifier.
- Example value: PAYPAGE
notifyUrl String
- Callback URL for order notifications.
revoked String
- Indicates if order was revoked.
- Example value: false
reserved String
- Reserved field for future use.
paymentInfo Object
Payment details (present for completed orders).
paidTime Timestamp Required
- Timestamp when payment was completed.
- Example value: 1658484202235
settledTime Timestamp Required
- Timestamp when payment was settled.
payerMid String Required
- Paying merchant identifier.
- Example value: 100000047500
paidAmount Money Required
- Actual amount paid.
payeeFeeAmount Money Required
- Fee charged to payee.
payerFeeAmount Money Required
- Fee charged to payer.
settlementAmount Money Required
- Net amount settled to payee.
payeeFeeAmountBeforeTax Money Required
- Payee fee amount before tax.
payeeFeeVat Money Required
- VAT amount on payee fee.
payChannel String Required
- Payment method used.
- Possible values:
BALANCE,CARD - Example value: BALANCE
channelParam Object
Channel-specific parameters.
eciValue String
- Electronic Commerce Indicator value.
- Example value: 05
extension Object
- Additional channel extension data.
paymentInfoExtend Object
Extended payment information.
installment Object
Installment plan details.
installmentNumber String
- Number of installments.
- Example value: 3
installmentPlan String
- Installment plan provider.
- Example value: VISA
installmentPlanAccpId String
- Installment plan acceptance ID.
installmentTotalAmount Money
- Total installment amount.
installmentFirstTotalAmount Money
- First installment amount.
installmentUpfrontFee Money
- Upfront fee for installment.
installmentTAndC String
- Installment terms and conditions.
installmentTermsVersion String
- Version of installment terms.
cardInfo Object
Card details (present for card payments).
brand String Required
- Card brand.
- Example value: VISA
last4 String
- Last 4 digits of card number.
- Example value: 1234
first6 String
- First 6 digits of card number.
- Example value: 411111
cardType String
- Type of card.
- Possible values:
CREDIT,DEBIT
issueCountry String
- Card issuing country.
- Example value: AE
cardLevel String
- Card level.
- Example value: GOLD
Response Sample
//Http Header
{
"sign": "nDdClX1tAyV3qcX/Epay6AXFNRGSsWd8ysWO9SgwPrNTetSePLA9C39mGp6qRbjJeqXLEnYLwSkBu5eKdtyVX3tflGLiV2kvRjVfYpTCjXdVL2Pcnv2w+ghjHe2jL988iklk7q5AjAgdtXNphpHcTes9pk6W3bVCbvijH6at0fExUtZ91L1LrnPGELT1IJm/lFW3w4KLh0Gxs7FzDPI9RDfUemObNlRzV8kCtkWahwPgs/hBnS69GyYDKN7ihQX2UiLuP239wl6IA+VG/ZZKHPhLs8bbuOS+LKWORIp6jRt+JsAx7c/Ot1RNyOnHKxPRKJ8bVTohEp39yUz/HwG8oA=="
}
//Http Body
{
"head": {
"applyStatus": "SUCCESS",
"code": "0",
"msg": "SUCCESS",
"traceCode": "000000"
},
"body": {
"totalElements": 6,
"totalPages": 1,
"sortPageParam": {
"number": 0,
"size": 20
},
"items": [
{
"deviceId": "DEVICE001",
"expiredTime": 1770455591940,
"merchantOrderNo": "REQ20230415001",
"notifyUrl": "https://example.com/notify",
"orderNo": "20230415000001",
"paySceneCode": "JSAPI",
"payeeMid": "M200000030906",
"paymentInfo": {
"cardInfo": {
"brand": "VISA",
"cardLevel": "GOLD",
"cardType": "CREDIT",
"first6": "411111",
"issueCountry": "AE",
"last4": "4321"
},
"channelParam": {
"eciValue": "05",
"extension": {
"AuthCode": "765210",
"AcquireCode": "00",
"RRN": "920003454461"
}
},
"paidAmount": {
"amount": 100.00,
"currency": "AED"
},
"paidTime": 1770455591940,
"payChannel": "VISA",
"payeeFeeAmount": {
"amount": 2.50,
"currency": "AED"
},
"payeeFeeAmountBeforeTax": {
"amount": 2.38,
"currency": "AED"
},
"payeeFeeVat": {
"amount": 0.12,
"currency": "AED"
},
"payerFeeAmount": {
"amount": 1.50,
"currency": "AED"
},
"payerMid": "PAYER001",
"paymentInfoExtend": {
"installment": {
"installmentFirstTotalAmount": {
"currency": "AED",
"amount": 333.34
},
"installmentNumber": "3",
"installmentPlan": "VISA",
"installmentPlanAccpId": "2617c281-891c-4c95-80ca-1de398ae7701",
"installmentTAndC": " [Test Bank] This is a sample T&C text containing Special Ch@racters that govern the Visa Installment services. Refer to https://www.visa.com for more information. 1) Eligibility: To be eligible for \"Visa installment\" payments, you must hold a valid and active Visa credit card issued by an authorized bank. Your credit limit and repayment capacity will determine your eligibility for installment plans. 2) Installment Plan: Installments can be availed for purchases at participating merchants, subject to a minimum transaction amount. The specific installment plan (number of months, interest rate, etc.) will be determined at the time of purchase. 3) Interest & Fees: 20% Interest will be charged on the unpaid principal amount. If you fail to pay any installment by the due date, a late payment fee will be charged. All fees/charges are non-refundable and subject to change. 4) Prepayment & Cancellation: You may choose to prepay the entire outstanding amount at any time. However, prepayment may attract a fee. The installment plan can be cancelled if your Visa card is cancelled <or if you default on payment>. 5) Changes to Terms: Visa reserves the right to change these terms and conditions at any time. Any changes will be communicated to you via email or through our website. It is your responsibility to keep yourself updated with the latest terms and conditions. Please note that these terms are subject to change and it's always recommended to read the actual terms and conditions provided by the card issuer.",
"installmentTermsVersion": "5",
"installmentTotalAmount": {
"currency": "AED",
"amount": 1000.00
},
"installmentUpfrontFee": {
"currency": "AED",
"amount": 0.00
}
}
},
"settledTime": 1770455591940,
"settlementAmount": {
"amount": 97.50,
"currency": "AED"
}
},
"requestTime": 1770455591940,
"reserved": "reserved_data",
"revoked": "false",
"status": "PAID_SUCCESS",
"subject": "Test Order Payment",
"totalAmount": {
"amount": 100.00,
"currency": "AED"
}
},
{
"merchantOrderNo": "991d90e1-a0c4-4460-bdac-db876eb6d78f",
"orderNo": "131658481358170925",
"deviceId": "20001019",
"status": "CREATED",
"product": "Basic Payment Gateway",
"totalAmount": {
"amount": 2.25,
"currency": "AED"
},
"payeeMid": "200000030906",
"expiredTime": 1658484958908,
"subject": "test",
"requestTime": 1658481358908,
"paySceneCode": "PAYPAGE"
},
{
"merchantOrderNo": "c4ccbb32-6420-42ea-bc6c-14e8b3f39f33",
"orderNo": "131658480856167343",
"deviceId": "20001019",
"status": "CREATED",
"product": "Basic Payment Gateway",
"totalAmount": {
"amount": 2.25,
"currency": "AED"
},
"payeeMid": "200000030906",
"expiredTime": 1658480977540,
"subject": "test",
"requestTime": 1658480856968,
"paySceneCode": "PAYPAGE"
},
{
"merchantOrderNo": "cc63d61e-8caf-436d-a3c6-314318c8c6ad",
"orderNo": "131658479615162180",
"deviceId": "20001019",
"status": "FAILURE",
"product": "Basic Payment Gateway",
"totalAmount": {
"amount": 2.25,
"currency": "AED"
},
"payeeMid": "200000030906",
"expiredTime": 1658479736247,
"subject": "test",
"requestTime": 1658479615457,
"paySceneCode": "PAYPAGE"
},
{
"merchantOrderNo": "39918222-77f8-4a86-a33f-94d3095dfae1",
"orderNo": "131658478925159905",
"deviceId": "20001019",
"status": "FAILURE",
"product": "Basic Payment Gateway",
"totalAmount": {
"amount": 2.25,
"currency": "AED"
},
"payeeMid": "200000030906",
"expiredTime": 1658479046213,
"subject": "test",
"requestTime": 1658478925581,
"paySceneCode": "PAYPAGE"
},
{
"merchantOrderNo": "67a74918-95f4-4367-a265-c06b24bfd335",
"orderNo": "131658478570157755",
"deviceId": "20001019",
"status": "CREATED",
"product": "Basic Payment Gateway",
"totalAmount": {
"amount": 2.25,
"currency": "AED"
},
"payeeMid": "200000030906",
"expiredTime": 1658478690961,
"subject": "test",
"requestTime": 1658433600000,
"paySceneCode": "PAYPAGE"
},
{
"deviceId": "",
"expiredTime": 1769685049527,
"merchantOrderNo": "aaff0b71b5b54945a33dfa4da227ab20",
"notifyUrl": "https://example.com/notify",
"orderNo": "131769658643041813",
"paySceneCode": "DIRECTPAY",
"payeeMid": "200000030906",
"paymentInfo": {
"cardInfo": {
"brand": "VISA",
"first6": "54323",
"last4": "1234",
"cardLevel": "PLATINUM",
"cardType": "DC",
"issueCountry": "UAE"
},
"paidAmount": {
"currency": "AED",
"amount": 100.00
},
"paidTime": 1769685049527,
"payChannel": "CARD",
"payeeFeeAmount": {
"currency": "AED",
"amount": 5.00
},
"payeeFeeAmountBeforeTax": {
"currency": "AED",
"amount": 4.50
},
"payeeFeeVat": {
"currency": "AED",
"amount": 0.50
},
"payerFeeAmount": {
"currency": "AED",
"amount": 2.00
},
"payerMid": "PAYER_TEST",
"settledTime": 1769685049527,
"settlementAmount": {
"currency": "AED",
"amount": 95.00
}
},
"requestTime": 1769685049527,
"reserved": "reserved",
"revoked": "false",
"status": "CREATED",
"subject": "Test Order",
"totalAmount": {
"amount": 100.00,
"currency": "AED"
}
}
]
}
}