Retrieve Order Details

Overview

The getOrder interface enables merchants to query the status of any Botim Money order, helping them actively retrieve order information and proceed with the appropriate business logic based on the order status.

When to Use

When the merchant's backend, network, or server experiences an issue and the system does not receive the payment notification.
When the payment API returns a system error or an unknown transaction status.
Before calling the close or cancel API, to confirm the current payment status.
To check the reversal status of an order. If the field acquireOrder.revoke in the response is true, it indicates that the order has been successfully reversed.

API URL

UAT: https://uat.test2pay.com/sgs/api/acquire2/getOrder
Production: https://api.payby.com/sgs/api/acquire2/getOrder

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
- If the request time is more than 15 minutes away from the current time, the request will be rejected. This parameter is used to prevent repeated requests for orders that should have been cancelled due to timeouts.
- Example value: 1581493898000
bizContent Object
Specifies the order using either merchantOrderNo or orderNo—not both.
- merchantOrderNo String Required
  - The merchant's reference number of the request. Used to track every request.
  - Example value: M965739182419
  - Maximum length: 64
- orderNo String Required
  - The Botim Money's unique identify number of the order.
  - Example value: 131658300517875854

Request Sample

//Http Header
{
  "Content-Language": "en",
  "Content-Type": "application/json",
  "sign": "Tu3fopHy1opsWVTAk12FSr8KsGMcFTQB0dOH4fPGrG8iKvhcGCsmCr4kOy3CBmv7zXpBNfMxoRW33YPz0Zm6503CDnqxlOZGaOCFSmwnsE01vDzZL489wPj5HEKJ7kk70/muDMiUwJubZoXVtmOGhpvvczJDYIhP/5kpwSkucdkjZwrlp7IGqoFHrgKgZXXieOsUlGJHb9xg+HchtCqCYaOvX+gIK/o88SdgogvGm8NW/N4dzBhnfbwPcC7ue3MO8mwCDkJ/5KavK8TEotSeTvFEyhAvzrd41ccg47SWXZ4UnhvwT06iIYZ67G4Xg24Bc97cQe1XFM9CPd+/8w7uDA==",
    "Partner-Id": "200000000888"
}

//Http Body
{
  "requestTime": 1581405884647,
  "bizContent": {
    "merchantOrderNo": "M965739182419"
  }
}

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 the code and msg for 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.
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.

acquireOrder AcquireOrder Required
- Complete order information object.

PaymentInfo

paidTime Timestamp(3) Required
- Timestamp when payment was completed.
- Example value: 1658484202235
payerMid String Required
- Paying merchant identifier.
- Example value: 100000047500
paidAmount Money Required
- Actual amount paid by the customer.
payeeFeeAmount Money Required
- Transaction fee charged to the payee.
payerFeeAmount Money Required
- Transaction fee charged to the payer.
settlementAmount Money Required
- Net amount settled to payee after all deductions.
payChannel String Required
- Payment method used for the transaction.
- Possible values: BALANCE, CARD, BANKCARD, INSTALLMENT, EWALLET, etc.
- Example value: BALANCE
channelParam ChannelParam
- Additional parameters specific to the payment channel.
- eciValue String
- Electronic Commerce Indicator value.
- Example value: 05
- extension Object
- Additional channel extension data.
paymentInfoExtend PaymentInfoExtend
- Extended payment information for additional details.
cardInfo CardInfo
- Card details object (present only for card payments).

CardInfo

brand String
- Card brand name (e.g., Visa, Mastercard, etc.).
last4 String
- Last 4 digits of the card number.
first6 String
- First 6 digits of the card number (BIN).
cardType String
- Type of card (e.g., DEBIT, CREDIT).
issueCountry String
- Country code where the card was issued.
cardLevel String
- Card level or tier (e.g., Standard, Gold, Platinum).
cardToken String
- Tokenized representation of the card for secure storage.
cardTokenExpTime Date
- Expiration time of the card token.
expMonth String
- Card expiration month (MM format).
expYear String
- Card expiration year (YYYY format).

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"
  },
  "body": {
    "acquireOrder": {
      "accessoryContent": {
        "amountDetail": {
          "amount": {
            "amount": 95.00,
            "currency": "AED"
          },
          "discountableAmount": {
            "amount": 100.00,
            "currency": "AED"
          },
          "tipAmount": {
            "amount": 0.00,
            "currency": "AED"
          },
          "vatAmount": {
            "amount": 5.00,
            "currency": "AED"
          }
        },
        "goodsDetail": {
          "body": "Test goods description body",
          "categoriesTree": "Electronics > Mobile > Accessories",
          "goodsCategory": "Electronics",
          "goodsId": "GOODS_001",
          "goodsName": "Test Product",
          "price": {
            "amount": 100.00,
            "currency": "AED"
          },
          "quantity": 1,
          "showUrl": "https://merchant.example.com/product/GOODS_001"
        },
        "terminalDetail": {
          "location": "Dubai, UAE",
          "merchantName": "Test Merchant",
          "operatorId": "OP_001",
          "storeId": "STORE_001",
          "storeName": "Test Store",
          "terminalId": "TERM_001"
        }
      },
      "deviceId": "mock_device_001",
      "expiredTime": 1770451403018,
      "merchantOrderNo": "mock_merchant_order_no",
      "notifyUrl": "https://merchant.example.com/notify",
      "orderNo": "131620641843026270",
      "paySceneCode": "JSAPI",
      "payeeMid": "200000030906",
      "paymentInfo": {
        "cardInfo": {
          "brand": "VISA",
          "cardLevel": "PLATINUM",
          "cardType": "CREDIT",
          "first6": "411111",
          "issueBank": "Emirates NBD",
          "issueCountry": "AE",
          "last4": "1234"
        },
        "channelParam": {
          "eciValue": "05",
          "extension": {
          "AuthCode": "765210",
          "AcquireCode": "00",
          "RRN": "920003454461"
                        }
        },
        "paidAmount": {
          "amount": 100.00,
          "currency": "AED"
        },
        "paidTime": 1770447803018,
        "payChannel": "CARD",
        "payeeFeeAmount": {
          "amount": 1.00,
          "currency": "AED"
        },
        "payerMid": "100000012345",
        "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&amp;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 &amp; 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 &amp; 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 &lt;or if you default on payment&gt;. 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
            }
          }
        },
        "settlementAmount": {
          "amount": 99.00,
          "currency": "AED"
        }
      },
      "promotionInfoList": [
        {
          "appliedRewardId": "REWARD_001",
          "settleFlag": "YES"
        },
        {
          "appliedRewardId": "REWARD_002",
          "settleFlag": "NO"
        }
      ],
      "requestTime": 1770447803018,
      "reserved": "reserved_data",
      "revoked": "false",
      "sharingInfoList": [
        {
          "sharingAmount": {
            "amount": 10.00,
            "currency": "AED"
          },
          "sharingIdentitySeqId": 1,
          "sharingMemo": "Commission for partner 1",
          "sharingMid": "200000012345",
          "sharingSettledAmount": {
            "amount": 10.00,
            "currency": "AED"
          },
          "sharingSettledFeeAmount": {
            "amount": 0.10,
            "currency": "AED"
          },
          "withholdAndRemitFee": false
        },
        {
          "sharingAmount": {
            "amount": 5.00,
            "currency": "AED"
          },
          "sharingIdentitySeqId": 2,
          "sharingMemo": "Commission for partner 2",
          "sharingMid": "200000067890",
          "sharingSettledAmount": {
            "amount": 5.00,
            "currency": "AED"
          },
          "sharingSettledFeeAmount": {
            "amount": 0.05,
            "currency": "AED"
          },
          "withholdAndRemitFee": true
        }
      ],
      "status": "PAID_SUCCESS",
      "subject": "Test Order Subject",
      "subjectAr": "موضوع الاختبار",
      "totalAmount": {
        "amount": 100.00,
        "currency": "AED"
      }
    }
  }
}

Response Codes

Code	Message	Cause	Workaround
0	SUCCESS	Success
400	INVALID_PARAMETER	Invalid parameters	Adjust request parameters
400	REQUESTTIME_TOO_EARLY	Request time is too far in the past	Adjust request time
400	REQUESTTIME_TOO_LATER	Request time is too far in the future	Adjust request time
402	RATE_LIMIT_REJECT	Too many requests	Reduce request frequency
403	UNAUTHORIZED	API not authorized	Contact Botim Money
404	SERVICE_NOT_AVAILABLE	API service unavailable	Contact Botim Money
500	SYSTEM_ERROR	System error	Contact Botim Money, try again later
504	SERVICE_TIMEOUT	Service timeout	Try again later
601	RISK_FAIL	Risk control validation failed	Adjust business logic
62004	MERCHANT_ORDER_NO_NOT_EXIST	Merchant order number does not exist	Correct merchant order number
62035	ORDER_NO_NOT_EXIST	Botim Money order number does not exist	Correct Botim Money order number

Retrieve Order Details

Overview​

When to Use​

API URL​

Request​

Http Header​

Http Body​

Request Sample​

Response​

Http Header​

Http Body​

Response Sample​

Response Codes​

Overview

When to Use

API URL

Request

Http Header

Http Body

Request Sample

Response

Http Header

Http Body

Response Sample

Response Codes