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 reference number of the request. Used to track every request.
Example value: M965739182419
Maximum length:
64
You can use either
merchantOrderNoororderNoto 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:
64originOrderNo String
The PayBy's unique identification number of the payment order.
Example value: 131658300517875854
Maximum length:
64amount 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 identify the order currency. Currently only AED is supported.
Example value: AED
refundSharingAmount Boolean
The sharing amount are not automatically refunded when initiating a refund. You can refund mony from the sharing account by passing a value of true in this parameter. If the following
sharingParamListparameter is not specified, PayBy will refund the fee from the Payee & Sharing account & PayBy transaction fee account in proportion. For example, a payment of 100 AED, 2 AED for transaction fee, 20 AED transfered to the sharing account, the payee got 78 AED. In a refund of 50 AED, 39 AED of the payee account, 10 AED of the sharing account and 1 AED of PayBy transaction fee will be returned.Default value: False
sharingParamList List
You can use this parameter if you want to specify the refund amount of different sharing accounts in the request. Note that only if the
refundSharingAmountis true, this parameter takes effect.Note:
If the parameter withholdAndRemitFee is used in the order creation request, when a refund is initiated, only the proportional refund can be made, and the refund amount of each sharing account cannot be specified.
The attributes of each item in the list are:
sharingIdentitySeqId Money Required
You can pass multiple account ids to refund from different sharing accounts, in order to distinguish them, the serial number is needed. Please start with 1, then 2, 3, 4, etc.
Example value:
1sharingIdentityType String Required
The fund can be transferred to the beneficiary through mobile phone number, PayBy member id or BOTIM member id.
The possible values are:
PHONE_NO. Transfer through mobile phone number.MEMBER_ID. Transfer through PayBy member id.
Maximum length: `20`
<br/>
sharingIdentity String Required
After selecting the identity type, what value should be passed. The parameter needs to be encrypted when passed, and SHA-256 algorithm is recommended.
For
PHONE_NO, example value: +971-585812345For
MEMBER_ID, example value: 100006514321Maximum length:
20sharingMemo String Required
Add some description to this operation.
sharingAmount Money Required
The amount you plan to refund from this id.
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:
200operatorName String
Name of the employee who initiated the refund order.
Example value: Daisy Johansson
Maximum length:
200reason String
The reason to refund the payment order.
Maximum length:
64deviceId String
If the transaction was 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 secondary merchant function, this parameter must be passed.
Maximum length:
200secondaryMerchantId 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:
200reserved 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 thecodeandmsgfor 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 reference number of the request. Used to track every request.
Example value: 1581493898000
Maximum length:
64orderNo String Required
The PayBy's unique identification number of the refund order.
Example value: M965739182419
Maximum length:
64originMerchantOrderNo String Required
The merchant order number of the payment order, which the merchant needs to refund.
Example value: M965739182419
Maximum length:
64status 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 failedamount 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:
1sharingMid 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:
200reason String
Reason for refund.
Maximum length:
64secondaryMerchantId 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:
200deviceId 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 secondary merchant function, this parameter must be passed.
Maximum length:
200failCode 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
}
}
}
}