Skip to main content

Refund order

Refunds a payment order that has been completed. You can refund either the full amount or a part of the payment amount. Funds will be refunded to the credit or debit card that was originally charged.


API URL

UAT : https://uat.test2pay.com/sgs/api/acquire2/refund/placeOrder

Production : https://api.payby.com/sgs/api/acquire2/refund/placeOrder


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

Refund order request time. 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

Attributes
  • refundMerchantOrderNo String Required

    The merchant's referece number of the request. Used to track every request.

    Example value: M965739182419

    Maximum length: 64


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

  • originMerchantOrderNo String

    The merchant order no. of the payment order.

    Example value: M965739182419

    Maximum length: 64


  • originOrderNo String

    The PayBy's unique identification number of the payment order.

    Example value: 131658300517875854

    Maximum length: 64


  • amount Money Required

    Amount to refund. The attributes are:

    • amount Decimal(12,2) Required

      Allow 12 digits before the decimal point. Allow 2 digits after the decimal point.

      Example value: 12.34


    • currency String Required

      The code to identifie the order currency. Currently only AED is supported.

      Example value: AED


  • notifyUrl String

    To receive asynchronous notifications of order status updates, the merchant can pass the notify URL in the request.

    Example value: https://www.yoursite.com

    Maximum length: 200


  • operatorName String

    Name of the employee who initiated the refund order.

    Example value: Daisy Johansson

    Maximum length: 200


  • reason String

    The reson to refund the payment order.

    Maximum length: 64


  • deviceId String

    If the transaction wad made on a terminal or virtual device, the device id can be passed for transaction data statistics. Note that this parameter must be passed if you are using the secondery merchant function, this parameter must be passed.

    Maximum length: 200


  • 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


  • reserved String

    Merchant's notes for the order.

    Example value: June campaign order.

    Maximum length: 200



Request sample

Http Header
{
"Content-Language": "en",
"Content-Type": "application/json",
"sign": "aMs582GhLeRv4fL3xqw7nN4dlzWS+ZVzdsNXT6rKwPpj7qOM4Y7qZBP3Yl6HogILy4IyX1tp8M7D92rK37hUgJg814odd1INIuy4l+KTRPA1Y3F8y0hVGXak0ddeVcOM3XNN+YEhvPClBx4EpmfWVqY3A2qNJTo3ugwr6uZiVGA38OjHRLZthGa+5nea0DtLaZYQnOGWaCI6fPIBZ7qr9HTiVkIsAp3N4m4cHR+3Rvpdbzu2TZoScA358D9wGmF5UOkbHCjwNV03I3O8HzaKUqMe4jnXZ+lJ0TMmxmqLrcMyMztJjZMQB9S4lXMW2+TqMrdNgLQv3GLiQ9IFvhUVEg==",
"Partner-Id": "200000000888"
}

Http Body
{
"requestTime": 1581405399656,
"bizContent": {
"refundMerchantOrderNo": "M818494241569",
"originMerchantOrderNo": "M965739182419",
"amount": {
"currency": "AED",
"amount": 0.01
},
"operatorName": "zxy",
"reason": "refund"
}
}

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.

    Example value: 0


  • msg String

    Description of this code.


  • traceCode String

    No special meaning, PayBy internally used to locate 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 referece 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 amout have been deducted from the merchant's account.

      SUCCESS. The refund has reached the payer's payment account.

      FAILURE. Refund order failed


    • amount Money Required

      The amount to refund.


    • notifyUrl String

      The merchant's referece 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 that this parameter must be passed if you are using the secondery 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",
"traceCode": "1127"
},
"body": {
"refundOrder": {
"refundMerchantOrderNo": "M818494241569",
"orderNo": "191405406113002297",
"originMerchantOrderNo": "M965739182419",
"status": "SUCCESS",
"amount": {
"currency": "AED",
"amount": 0.01
},
"reason": "refund"
},
"refundSummary": {
"acquireAmount": {
"currency": "AED",
"amount": 1.01
},
"remainRefundAmount": {
"currency": "AED",
"amount": 1
}
}
}
}