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 thecode
andmsg
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.
- 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.
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.
- Possible values:
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
- payerFeeAmount Money Required
beneficiaryIdentityType String Required
- Method used to identify the beneficiary.
- Possible values:
PHONE_NO
: Transfer through mobile phone numberMEMBER_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
(forPHONE_NO
)100006514321
(forMEMBER_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
- Code identifying the reason for failure (if status is
failDes String
- Description of the failure reason (if status is
FAILURE
). - Example value:
SERVICE_TIMEOUT
- Description of the failure reason (if status is
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 |