Retrieve Refund Order Details

Checks the refund status after submitting the refund request.

API URL

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

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

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

refundMerchantOrderNo 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
Maximum length: 32

Request Sample

// Http Header
{
    "Content-Language": "en",
    "Content-Type": "application/json",
    "sign": "C7WdDZhiHV9tt3AYM4zS4jgTr58XmgpNy7ZzGfbAYADGW0XkSw3rNcqkZJWHQcN6yBW+LBTwuGhZhrOUCg/+79hTnhff266avYAiBZ+T+B6kx6FgYu7S9PSGaE9RxksK8mjgPnbwXmWkC541pj/AQac6x2nxj9EPcjl8iprYvu3bhdZTcLCJjCBK1g9bZ426M/JICKId65Bk5OtS9zKa7n+jn+fqZiT60acMOOHM3N8g1Kyzt4bqDdvVe0hPRXGDwCrPZO8WO62NLqejLwNxwPCbFnlbLMtiZyewX72w2Pt0xw/1y6Eh8Or1sIhgy+z4g6c5sUx0SMAPWxpq91oO3g==",
    "Partner-Id": "200000000888"
}

// Http Body
{
    "requestTime": 1581406091642,
    "bizContent": {
        "refundMerchantOrderNo": "M818494241569"
    }
}

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.

refundOrder Object
Attributes
- refundMerchantOrderNo String Required
  The merchant's reference number of the request. Used to track every request.
  Example value: 1581493898000
  Maximum length: 64
- orderNo String Required
  The PayBy's unique identification number of the refund order.
  Example value: M965739182419
  Maximum length: 64
- originMerchantOrderNo String Required
  The merchant order number of the payment order to be refunded.
  Example value: M965739182419
  Maximum length: 64
- status String Required
  Status of the refund order. Possible values:
  CREATED: PayBy's server accepts the refund request.
  REFUNDED_SETTLED: Refund amount has been deducted from the merchant's account.
  SUCCESS: Refund has reached the payer's account or is being processed by the bank.
  FAILURE: Refund order failed.
- amount Money Required
  The amount to refund.
- feeRefunded Money
  Transaction fee refunded by PayBy.
- sharingInfoList List
  Details of refund impact on sharing accounts.
  Each item includes:
  sharingIdentitySeqId Money Required
  Serial number for multiple account IDs.
  Example value: 1
  sharingMid String Required
  Member ID returned if identity matches an existing PayBy member.
  sharingMemo String Required
  Description of the refund operation.
  sharingAmount Money Required
  Original requested sharing amount.
  sharingSettledAmount Money Required
  Actual amount received by the sharing account.
- notifyUrl String
  URL for receiving asynchronous notifications.
  Maximum length: 200
- reason String
  Reason for refund.
  Maximum length: 64
- secondaryMerchantId String
  Merchant's member ID under your platform.
  Maximum length: 200
- deviceId String
  Device ID used for transaction data statistics.
  Note: Required if using the secondary merchant function.
  Maximum length: 200
- failCode String
  Code identifying the reason for failure.
  Example value: 62002
- failDes String
  Description of the failure reason.
  Example value: Failed orders cannot be cancelled or refunded
- reserved String Required
  PayBy's unique identification number of the order.
  Example value: 131658300517875854
refundSummary Object
- acquireAmount Money Required
  The payment amount for the payment order.

remainRefundAmount Money Required
After this refund, how much refundable amount is left.

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": {
    "refundOrder": {
      "refundMerchantOrderNo": "M818494241569",
      "orderNo": "191405406113002297",
      "originMerchantOrderNo": "M965739182419",
      "status": "SUCCESS",
      "amount": {
        "currency": "AED",
        "amount": 0.01
      },
      "feeRefunded": {
        "currency": "AED",
        "amount": 0.01
      },
      "reason": "refund",
      "reserved": "order desc",
      "refundSharingAmount":true,
      "sharingInfoList":[
                {
                    "sharingAmount":{
                        "amount":1,
                        "currency":"AED"
                    },
                    "sharingIdentitySeqId":1,
                    "sharingMemo":"bouns",
                    "sharingMid":"100000047500",
                    "sharingSettledAmount":{
                        "amount":1,
                        "currency":"AED"
                    }
                },
                {
                    "sharingAmount":{
                        "amount":1,
                        "currency":"AED"
                    },
                    "sharingIdentitySeqId":2,
                    "sharingMemo":"cashback",
                    "sharingMid":"100000002005",
                    "sharingSettledAmount":{
                        "amount":1,
                        "currency":"AED"
                    }
                }
            ]
    },
    "refundSummary": {
      "acquireAmount": {
        "currency": "AED",
        "amount": 1.01
      },
      "remainRefundAmount": {
        "currency": "AED",
        "amount": 1
      },
      "sharingRemainRefundInfoList":[
                {
                    "remainRefundAmount":{
                        "amount":1,
                        "currency":"AED"
                    },
                    "memeberId":"100000047500"
                },
                {
                    "remainRefundAmount":{
                        "amount":1,
                        "currency":"AED"
                    },
                    "memeberId":"100000002005"
                }
            ]
    }
  } 
}

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 and retry later
504	SERVICE_TIMEOUT	Service timeout	Retry later
601	RISK_FAIL	Risk control validation failed	Adjust business logic
62007	REFUND_MERCHANT_ORDER_NO_NOT_EXIST	Refund merchant order number does not exist	Correct the refund order number
62035	ORDER_NO_NOT_EXIST	PayBy order number does not exist	Correct the PayBy order number

Retrieve Refund Order Details

API URL​

Request​

Http Header​

Http Body​

Request Sample​

Response​

Http Header​

Http Body​

Response Sample​

Response Codes​

API URL

Request

Http Header

Http Body

Request Sample

Response

Http Header

Http Body

Response Sample

Response Codes