The Refund Submission API allows merchants to initiate refund requests through application integration. The PayEase platform responds with the result in JSON format. This API performs the same function as the manual refund request option in the PayEase merchant portal.
https://apis.5upay.com/onlinePay/refund
| Name | Type& Length | Description | Required |
|---|---|---|---|
| merchantId | varchar(9) | >The unique ID assigned to the merchant in the PayEase system. It can be viewed in the merchant backend./td> | M |
| requestId | varchar(50) | The order ID is defined by the merchant and must be unique within their platform. For orders that have already been paid or canceled in the PayEase system, the same order ID cannot be reused. | M |
| partnerId | varchar(9) | The unique ID assigned to the service provider in the PayEase system. It can be viewed in the merchant backend. | C |
| amount | decimal(18) | Order amount. Unit: cents (1 CNY = 100 cents) | M |
| orderId | varchar(32) | serialNumber of the original order | M |
| notifyUrl | varchar(200) | Server notification URL: PayEase will send a notification to this URL once the refund reaches a final state. Parameters can be included, e.g., “www.5upay.com/callback.action?test=test” | M |
| isCollect | Fixed value | If aggregate: 1 - Enable fund aggregation |
C |
| 0 - Do not aggregate | |||
| Default: Not aggregated | |||
| refundCollectDetail | Json(Array) | Aggregation information. See table below |
C |
| remark | varchar(300) | Remarks | O |
| refundSubsidy | Fixed value | Refund Subsidy Identifier: 1 Subsidy refund |
O |
| 0 No subsidy refund | |||
| Default: no subsidy refund | |||
| subsidyMoney | varchar(18) | Refund Subsidy Amount. Unit: cents (1 CNY = 100 cents) | O |
| refundSubsidyDetail | Json(Array) | Refund Subsidy Details Specifies which subsidy providers from the original order should receive the refunded subsidy amounts. If this field is omitted, the refund will be applied to the default subsidy provider by default. |
O |
| hmac | varchar(500) | The HMAC signature generated by the merchant. For details on how to generate the HMAC, please refer to the encryption request process. | M |
Note: The parameter values above must not contain the following special characters: ' " & < > ( ) [space]
| Name | Type& Length | Description | Required |
|---|---|---|---|
| collectAccType | Fixed value | Collection Account Type: SPLIT_ACC - Split Recipient Account |
M |
| PLAT_ACC - Platform Fund Account | |||
| WAIT_ACC - Pending Split Fund Account | |||
| collectAmount | varchar(18) | Amount to be collected, in cents (1 CNY = 100 cents) | M |
| subSplitRequestId | varchar(50) | Custom split order ID defined by the merchant. Must be unique. Required when collectAccType is SPLIT_ACC; otherwise, omit. | C |
| remark | varchar(300) | Remark related to the split | O |
| Parameter Name | Type & Length | Description | Required |
|---|---|---|---|
| subsidyMerchantId | varchar(30) | Original Subsidy Merchant ID — The merchant ID of the original subsidy detail order for which the subsidy amount needs to be refunded. | O |
| refundSubsidyAmount | varchar(18) | Refund Subsidy Amount — The subsidy amount to be refunded, in cents (1 CNY = 100 cents). | O |
| Parameter Name | Description |
|---|---|
| merchantId | Merchant ID — Same as the request parameter. |
| requestId | Order ID — Same as the request parameter. |
| partnerId | Partner ID — Same as the request parameter. |
| serialNumber | Transaction Serial Number — The transaction's unique reference number. |
| status | Transaction Status — SUCCESS: Request was successfully submitted to Geoswift (not necessarily refunded yet). |
| FAILED: Submission failed. | |
| ERROR: An error occurred (see error handling documentation for details). | |
| amount | Refund Amount — Amount refunded, in cents (1 CNY = 100 cents). |
| currency | Refund Currency — Defaults to Chinese Yuan (CNY). |
| hmac | Parameter Signature — Signature generated by Geoswift. Please refer to the decryption process for verification. |
Note: These parameters are sent to the merchant’s server via the notifyUrl.
| Name | Description |
|---|---|
| merchantId | Merchant ID — Same as the request parameter. |
| requestId | Order ID — Same as the request parameter. |
| partnerId | Partner ID — Same as the request parameter. |
| amount | Refund Amount — In cents. 1 CNY = 100 cents. |
| serialNumber | Transaction Serial Number — Unique identifier for the transaction. |
| status | Transaction status: SUCCESS |
| FAILED | |
| completeDateTime | Refund Completion Time — The time when the refund was successfully processed. |
| currency | Refund Currency — Default is CNY (Chinese Yuan). |
| errorMessage | Error Message — Returned only if the refund fails. |
| hmac | Parameter Signature — Signature generated by PayEase. For verification, please refer to the decryption process. |