Skip to main content

Retrieve Order Details

Retrieves the order detail with order number or merchant order number.

API URL

Request

Http Header

Attributes
  • Content-Language String

    • Language in which the response message will be used.
    • Currently, only English is supported.
    • 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/<format> (e.g., application/json)
    • Example value: application/json
  • sign String Required

    • Request signature using private-key cryptography.
    • Ensures the payment gateway can verify the request origin.
  • Partner-Id String Required

    • Merchant ID of your account.
    • 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

You can use either merchantOrderNo or orderNo to specify an order. But you can't use the two parameters at the same time.

  • 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 PayBy's unique identify number of the order.

    Example value: 131658300517875854

Request Sample

// Http Header
{
"Content-Language": "en",
"Content-Type": "application/json",
"Partner-Id": "200000018132",
"sign": "WF34t3rh4wuBuiUqlAte0PErySJBrwWEuNAgP5DYTZnI5fah0xC0desDOcLAakN1E6UccD8Yq4zuNBtkmLdA74eSkk2lb5+k+lP9/a5Aa7h12UtLc62JDpzQL/O3NgvPJCDBCat2Mmso5ihNOWKGyw/L4YhaqSrqHGfVEimiyrY/giBPJ5Ktof6Qyy2AiSNMAJPNzYFu73Kmc3ogYUKh487hLTNHGPPBsqPTIOO10+wG9/q0I3P90uOqXCYkoq7JyU3j1WkRZp5YmKTvIcfe4EJ/tsVtvBPVOw4ParnWD6nMlA59/y8K4D+wwZd7exbA/r85FRBkW+JdsY1z+yQJ7Q=="
}

// Http Body
{
"bizContent": {
"merchantOrderNo": "M021482754853"
},
"requestTime": "1585143324254"
}

Response

Http Header

sign String Required

When PayBy sends response, PayBy will use its own private key to sign the message, and the merchant uses PayBy 's public key to verify the signature. If the verification is passed, it proves that the response was sent by PayBy 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 PayBy 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.

  • transferOrder Object

    Attributes
    • requestTime Timestamp Required

      • Request time passed by the merchant when placing the order.
      • Example value: 1581493898000
    • 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 PayBy's unique identification number of the order.
      • Example value: 131658300517875854
    • product String Required

      • The product name of the API method used in the order. Used for PayBy internal classification.
      • Maximum length: 100
    • status Enum Required

      • Possible values:
        • CREATED: The order has been created.
        • SUCCESS: The transfer completed.
        • FAILURE: The order has been cancelled or expired.
    • paymentInfo Object

      • payerFeeAmount Money Required
        • Fee that the payer needs to pay in this transfer.
      • arrivalTime Timestamp Required
        • Estimated time of fund arrival (not actual arrival time).
        • Example value: 1581493898000
    • beneficiaryIdentityType String Required

      • Method used to identify the beneficiary.
      • Possible values:
        • PHONE_NO: Transfer through mobile phone number
        • MEMBER_ID: Transfer through PayBy member ID
      • Maximum length: 20
    • beneficiaryIdentity String Required

      • Value passed based on the selected identity type.
      • Should be encrypted using SHA-256.
      • Example values:
        • +971-585812345 (for PHONE_NO)
        • 100006514321 (for MEMBER_ID)
      • Maximum length: 20
    • beneficiaryFullName String

      • If provided, PayBy verifies it against the beneficiary's KYC info.
      • If not provided, no verification is performed.
      • Should be encrypted using SHA-256.
      • Maximum length: 100
    • memo String Required

      • Description of the transfer.
      • Maximum length: 128
    • notifyUrl String

      • URL to receive asynchronous notifications of order status updates.
      • Example value: https://www.yoursite.com
      • Maximum length: 200
    • failCode String

      • Code identifying the reason for failure (if status is FAILURE).
      • Example value: 504
    • failDes String

      • Description of the failure reason (if status is FAILURE).
      • Example value: SERVICE_TIMEOUT

Response Sample

// Http Header
{
"sign": "I1zfK8Bdfti5+PS0Q1PEdPlS77jF4SaJLRMbgWaisFgUSIW0It03Mk2YCTamWWzVN9ElGd1ditgvWS5/Kjff+yZofnVGc1UQQ2x3sfyz7Z8IL1lLz9KiM4c55b02gILe7VEecJox/Yu6fgURKb0GK3GRxgeUbzoqsIrDlHZ4cy5A1tNf5lAhaVOQ1Zfao0jc+l6nIW7gRhcZb/gOBrEGT5MkNLPbnwUxSkWDISlN3/IOBYgE5Eoaq+lbZO2ji7Xr0AsfKoC9sueVLeubbDRHWgN6fi1vewqA5FFKACS1+UUeXqR/x95MTR0cR6qnfOodf0c09GGyrTIR+x3M0vkFPw=="
}

// Http Body
{
"head": {
"applyStatus": "SUCCESS",
"code": "0",
"msg": "SUCCESS",
"traceCode": "1125"
},
"body": {
"transferOrder": {
"amount": {
"amount": 1.21,
"currency": "AED"
},
"beneficiaryFullName": "5a0d9e4fd01a40ff3ab89dfde84c2253b5ea07c4ba8b4e5f25b81df3b73b9db0",
"beneficiaryIdentity": "a25c5bff2fabf6bccf8ff13a940f5d05d3927c1501373ac6fa129d4fa688417c",
"memo": "company single pay",
"merchantOrderNo": "M021482754853",
"notifyUrl": "http://www.yoursite.com",
"orderNo": "911585142879004849",
"paymentInfo": {
"arrivalTime": 1585142880000,
"payerFeeAmount": {
"amount": 0,
"currency": "AED"
}
},
"product": "Transfer",
"requestTime": 1585142886252,
"status": "SUCCESS"
}
}
}

Response Codes

CodeMessageCauseWorkaround
0SUCCESSSuccess
400INVALID_PARAMETERInvalid parameterAdjust request parameters
400REQUESTTIME_TOO_EARLYRequest time is too far in the pastAdjust request time
400REQUESTTIME_TOO_LATERRequest time is too far in the futureAdjust request time
402RATE_LIMIT_REJECTToo many requestsReduce request frequency
403UNAUTHORIZEDAPI not authorizedContact PayBy
404SERVICE_NOT_AVAILABLEAPI service unavailableContact PayBy
500SYSTEM_ERRORSystem errorContact PayBy, try again later
504SERVICE_TIMEOUTService timeoutTry again later
601RISK_FAILRisk control validation failedAdjust business logic
62004MERCHANT_ORDER_NO_NOT_EXISTMerchant order number does not existAdjust merchant order number