Retrieve Order Details

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

API URL

• UAT: https://uat.test2pay.com/sgs/api/transfer/getTransferOrder
• Production: https://api.payby.com/sgs/api/transfer/getTransferOrder

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

Code	Message	Cause	Workaround
0	SUCCESS	Success
400	INVALID_PARAMETER	Invalid parameter	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 PayBy
404	SERVICE_NOT_AVAILABLE	API service unavailable	Contact PayBy
500	SYSTEM_ERROR	System error	Contact PayBy, 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	Adjust merchant order number