API Refund
The partner can make refunds for successfully paid cycles within 180 days from the date of successful transaction. Partners can submit a request for total or partial refund. With partial refunds, the partner can make multiple requests provided that the total partial refund is less than or equal to the amount paid.
Endpoint: /api/v1/subs/refunds
Method: POST
Header Params
| Param | Required | Type | Description | Note |
|---|---|---|---|---|
| X-APPOTAPAY-AUTH | required | String | How to generate JWT_TOKEN | |
| Content-Type | required | String | Value: application/json | |
| X-Request-ID | optional | String | UUIDv4 format. Request ID to check when a problem occurs | max:42 |
| Language | optional | String | The value vi or en corresponding to the payment link will be Vietnamese or English, (default: vi) | in:vi,en |
| X-Account-Ref-ID | optional | String | Iidentifier of the sub account provided by AppotaPay. Mandatory be passed over when processing payment for transactions of owner-type sub account |
{
"X-APPOTAPAY-AUTH": "JWT_TOKEN",
"Content-Type": "application/json",
"X-Request-ID": "Your_Unique_id",
"Language": "vi",
"X-Account-Ref-ID": "9723f73b-9295-4acb-884b-ab6310c2e653"
}
Request params
| Param | Required | Type | Description | Note |
|---|---|---|---|---|
| refundRefId | Required | String | Partner's refund transaction reference code | min:1, max: 50, format: alphanumeric |
| attemptId | Required | String | Identifier for the corresponding successful payment attempt of cycle to be refunded. It's returned in cycle callback | |
| amount | Required | Integer | The refunded amount | |
| currency | Required | String | Currency unit | in: VND |
| reason | Required | String | Reason for refund - FRAUDULENT: Fraudulent - DUPLICATE: Duplicate - REQUESTED_BY_CUSTOMER: Requested by customer - CANCELLATION: Cancellation - OTHER: Others |
Example Request
{
"refundRefId": "ASKJLKALK20398141",
"attemptId": "01HY2TRW9EBTPWGPJDGPD9JMA9",
"reason": "REQUESTED_BY_CUSTOMER",
"currency": "VND",
"amount": 10000
}
Response data
Success
Http Status Code
200-OK
Success responses will contain a single Refund object
Failure
HTTP Status Code !=
200
Error response params
| Param | Required | Type | Description |
|---|---|---|---|
| errorCode | required | Integer | Error code |
| message | required | String | Error message |
| errors | optional | Array | Detailed error description |
| errors.*.field | optional | String | Field data is corrupted |
| errors.*.reason | optional | String | Description of the data field in error |
{
"errorCode": 3002,
"message": "Duplicate reference code of partner, please try again"
}
Common error code table
Full error code, please check this error code list
| Error code | Description |
|---|---|
| 0 | Success |
| 1 | Missing or Invalid Params |
| 11 | Partner is not found |
| 13 | Partner has been blocked |
| 14 | API Key is invalid |
| 15 | API Key is not activated or blocked |
| 92 | IP is not allowed to access |
| 99 | Undefined error, please contact AppotaPay for more detailed information |
| 110 | The total refund amount exceeds the transaction amount |
| 125 | Refund cannot be processed due to payment exceeding validity period |
| 401 | Unauthorized |
| 500 | Server error |
| 3002 | Duplicate reference code of partner, please try again |
| 3057 | Cycle attempt id is invalid |