Refund Order

Overview

Merchants may initiate a full or partial refund within a specified period after an order is created, due to reasons attributable to either the customer or the merchant. Upon receipt and successful verification of the refund request, PayBy will process the refund to the customer’s account via the original payment method (credit card or debit card), in accordance with the applicable refund policy.

Note: Refunds can only be processed for orders placed within the last 180 days. For example, if the order was created at 1:01:01 AM on January 1st, a refund can be issued within the following 180 days.

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

  • 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

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 reference 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 both parameters at the same time.

• originMerchantOrderNo String

  • The merchant order number 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 and 2 digits after.
      • Example value: 12.34
    • currency String Required
      • The code to identify the order currency. Currently only AED is supported.
      • Example value: AED

• refundSharingAmount Boolean

  • Indicates whether to refund from sharing accounts.
  • Default value: false
  • If true and sharingParamList is not specified, PayBy will proportionally refund from the payee, sharing account, and PayBy fee account.

• sharingParamList List

  • Used to specify refund amounts for different sharing accounts. Only effective if refundSharingAmount is true.
  • Each item includes:
    • sharingIdentitySeqId Money Required
      • Serial number for multiple account IDs.
      • Example value: 1
    • sharingIdentityType String Required
      • Identity type for fund transfer.
      • Possible values: PHONE_NO, MEMBER_ID, BOTIM_ID
      • Maximum length: 64
    • sharingIdentity String Required
      • Encrypted identity value.
      • Example values: +971-585812345, 100006514321
      • Maximum length: 200
    • sharingMemo String Required
      • Description of the refund operation.
      • Maximum length: 128
    • sharingAmount Money Required
      • Amount to refund from this ID.
    • withholdAndRemitFee Boolean
      • Indicates whether the transaction fee is withheld and remitted on behalf of the split party.
      • Example values: true, false
      • Note: If used during order creation, only proportional refunds are allowed.

• notifyUrl String

  • URL to receive asynchronous notifications of order status updates.
  • 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

  • Reason for refunding the payment order.
  • Maximum length: 64

• deviceId String

  • Device ID used for transaction data statistics.
  • Required if using the secondary merchant function.
  • Maximum length: 200

• secondaryMerchantId String

  • Merchant's member ID under 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": {
    "merchantOrderNo": "M818494241569",
    "originMerchantOrderNo": "M965739182419",
    "amount": {
      "currency": "AED",
      "amount": 0.01
    },
    "refundSharingAmount":true,
    "operatorName": "zxy",
    "reason": "refund",
    "reserved": "order desc",
    "sharingParamList":[
            {
                "sharingAmount":{
                    "amount":1,
                    "currency":"AED"
                },
                "sharingIdentity":"Q/HF/NMMCJHYy9Kf88GHJ9wusUJohFwgNIOJo1ZVWF8CqlPsKrcHwqtDQC2oAcHuRX9CH/V+w9A+0tTKWQFyYsEV/mdxNlxs3dzWinUXoS3TsDWUXHUZ9vun3MPA6fMdJ9/3IPcxgJwL0wnqjL7h2oBKoNWHeZlDxGa9pYsy+YWtM0KpGs3YLzeqorRFxdcerXi0m0TPfynCZw54Go/wCSOL85jpIItV1C6Np09PUwPo/dS7b8hgjrm82V8Xh43IMX/svf+Q/SKiUWLvG6MsgsJLQYWcO9PwAIkvw1JVsQrZsqt631pU5u87vI4zAAKZAuujzKG3fL1kpj/QhDdXlQ==",
                "sharingIdentitySeqId":1,
                "sharingIdentityType":"PHONE_NO",
                "sharingMemo":"bouns"
            },
            {
                "sharingAmount":{
                    "amount":1,
                    "currency":"AED"
                },
                "sharingIdentity":"yMJ5a66KNby5S+TfCp3shACYst9ZeMUWLQrBTn05+ctFw82xJc8CbelAp25XlQOmzfOGkt6Jmxhjb+yCeRZfA3GM5rydFP6t/eT+7DiTT73VVSEeugGhktmOGEUzxv5rIAe3BDnvKELGqXGrolhZGn3JhAk6tqUlLrtzq+pH1AdPpWAtQbstKII2vkMx4leEYEQE0CH6lAj9OtbpWvnXsxRj+PKSolNXl2YsU0l12jAjNY1oYUeVsl9XwZjpjUsr8rm6rMdVNt1hiutL0YLdsazEiBwrf+xCLVSxnj4KfLmpPkAqx7Jy09lnBOduVUhBfPpSbywaF/PMlun6C6F05Q==",
                "sharingIdentitySeqId":2,
                "sharingIdentityType":"MEMBER_ID",
                "sharingMemo":"cashback"
            }
        ]
  }
}

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",
        "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
            }
        }
    }
}

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	Requests are too frequent	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 verification failed	Adjust business logic
62002	ORDER_FAILURE	Refund attempted on a failed order	Modify merchant order number
62004	MERCHANT_ORDER_NO_NOT_EXIST	Order with the merchant order number does not exist	Modify merchant order number
62006	REFUND_AMOUNT_EXCEEDED	Refund amount exceeds refundable amount (original amount - refunded - pending refunds)	Adjust refund amount
62015	ORDER_NOT_PAID	Refund attempted on an unpaid order	Adjust business logic
62017	REFUND_MERCHANT_ORDER_NO_EXIST	Refund request with same order number but different business parameters	Modify refund merchant order number
62035	ORDER_NO_NOT_EXIST	Order with the PayBy order number does not exist	Modify PayBy order number
62036	MERCHANT_DEVICE_NOT_EXIST	Merchant device does not exist	Modify sub-merchant number or device ID
62038	INVALID_SECONDARY_MERCHANT	Refund sub-merchant does not match original acquiring merchant	Modify sub-merchant number
62040	ACQUIRE_ORDER_REVOKED	Order has been reversed	Modify merchant order number
62045	REFUND_REJECTED	Refund was rejected	Adjust business logic
62083	SHARING_MEMBER_NOT_EXIST	Split payment member does not exist	Adjust request parameters
62084	REFUND_SHARING_MEMBER_MISMATCH	Refund split member does not match	Adjust request parameters