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

  • The language in which the response message will be used, currently only English is supported.
  • Example value: en
  • Maximum length: 10

• Content-Type String Required

  • The media type. Required for operations with a request body. The value is application/<format>, where format is json.
  • Example value: application/json

• sign String Required

  Requests should be signed using private-key cryptography. This allows the payment gateway to verify that an incoming request is really from your application.

• Partner-Id String Required

  • The 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. The possible values are:

  • SUCCESS - Application successful.
  • FAIL - Application failed. Check the code and msg for exact reason.
  • ERROR - Application error. The signature verification failed. Please check whether the private key used for the signature and the public key uploaded on the PayBy portal are one key pair.

• code String Required

  • Response Codes.
  • Maximum length: 10
  • Example value: 0

• msg String

  • Description of this 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, which the merchant needs to refund.
    • Example value: M965739182419
    • Maximum length: 64

  • status String Required

    The status of the refund order. The possible values are:

    • CREATED. PayBy's server accepts the refund request.
    • REFUNDED_SETTLED. Refund amount have been deducted from the merchant's account.
    • SUCCESS. If payment method is balance, the refund has reached the payer's payment account. If payment method is bank card, the bank has started processing this refund and the fund will take some time to reach the payer's bank account.
    • FAILURE. Refund order failed

  • amount Money Required

    The amount to refund.

  • feeRefunded Money

    In this refund, the transaction fee PayBy needs to refund.

  • sharingInfoList List

    If a refund occurs before the sharing amount is settled into the receiver's account, the receiver will actually receive less funds than the requested amount in the payment order. In this list PayBy will return the original requested sharing amount and the receiver actually obtained.

    The attributes of each item in the list are:

    • sharingIdentitySeqId Money Required

      You can pass multiple account ids to split the payment amount, in order to distinguish them, the serial number is needed. Please start with 1, then 2, 3, 4, etc.

      Example value: 1

    • sharingMid String Required

      If the sharingIdentityType and sharingIdentity passed in the request can correspond to a member id that already exists in the PayBy system, in the response PayBy will return the member id.

    • sharingMemo String Required

      Add some description to this operation.

    • sharingAmount Money Required

      The amount you plan to split to this id.

    • sharingSettledAmount Money Required

      The amount of fund the sharing account finally received. If any refund occurs before settlement, the sharingSettledAmount will be different from the original sharingAmount.

    • notifyUrl String

      • The merchant's reference number of the request. Used to track every request.
        • Maximum length: 200

    • reason String

      • Reason for refund.
      • Maximum length: 64

    • secondaryMerchantId String

      If you are a platform and the transaction was made at a merchant under your platform, you can use this parameter to allocate the funds collected. To learn more about this feature please contact PayBy. The secondary merchant id represents the merchant's member id on your platform.

      Maximum length: 200

    • deviceId String

      If the transaction wad made on a terminal or virtual device, the device id can be passed for transaction data statistics.

      Note: This parameter must be passed if you are using the secondary merchant function, this parameter must be passed.

      Maximum length: `200`

    • failCode String

      • If the order status is FAILURE, the code to identify the exact reason.
      • Example value: 62002

    • failDes String

      • If the order status is FAILURE, the failure reason.
      • Example value: Failed orders cannot be cancelled or refunded

    • reserved String Required

      • The PayBy's unique identify 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