API Hoàn tiền
Đối tác có thể thực hiện hoàn trả với các cycle đã thanh toán thành công trong vòng 180 ngày kể từ ngày giao dịch thành công. Đối tác có thể gửi yêu cầu hoàn trả toàn phần hoặc một phần, với hoàn trả một phần khách hàng có thể thực hiện nhiều lân với điều kiện tổng tiền hoàn trả một phần nhỏ hơn hoặc bằng số tiền đã thanh toán.
Endpoint: /api/v1/subs/refunds
Method: POST
Header Params
| Tham số | Yêu cầu | Kiểu dữ liệu | Mô tả | Lưu ý |
|---|---|---|---|---|
| X-APPOTAPAY-AUTH | required | String | Cách tạo JWT_TOKEN | |
| Content-Type | required | String | Giá trị: application/json | |
| X-Request-ID | optional | String | Định dạng UUIDv4. Request ID để kiểm tra yêu cầu khi xảy ra sự cố | max:42 |
| Language | optional | String | Giá trị vi hoặc en tương ứng với link thanh toán sẽ là tiếng việt hoặc tiếng anh, (mặc định: vi) | in:vi,en |
| X-Account-Ref-ID | optional | String | Mã định danh của tài khoản Sub account do AppotaPay cung cấp. Bắt buộc truyền khi thanh toán giao dịch của Sub account loại owner |
{
"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"
}
Tham số
| Tham số | Yêu cầu | Kiểu dữ liệu | Mô tả | Lưu ý |
|---|---|---|---|---|
| refundRefId | Required | String | Mã tham chiếu giao dịch hoàn tiền phía đối tác | min:1, max: 50, format: alphanumeric |
| attemptId | Required | String | Mã định danh cho attempt thanh toán thành công trong cycle cần thực hiện refund. Mã được trả trong cycle object | |
| amount | Required | Integer | Số tiền hoàn | |
| currency | Required | String | Đơn vị tiền tệ | in: VND |
| reason | Required | String | Lý do hoàn tiền - FRAUDULENT: Lừa đảo - DUPLICATE: Bị trùng - REQUESTED_BY_CUSTOMER: Yêu cầu của khách - CANCELLATION: Hủy bỏ - OTHER: khác |
Example Request
{
"refundRefId": "ASKJLKALK20398141",
"attemptId": "01HY2TRW9EBTPWGPJDGPD9JMA9",
"reason": "REQUESTED_BY_CUSTOMER",
"currency": "VND",
"amount": 10000
}
Dữ liệu trả về
Thành công
Http Status Code
200-OK
Dữ liệu trả về thành công sẽ chứa một Refund object
Thất bại
HTTP Status Code !=
200
Error response params
| Tham số | Yêu cầu | Kiểu dữ liệu | Mô tả |
|---|---|---|---|
| errorCode | required | Integer | Mã lỗi |
| message | required | String | Mô tả lỗi |
| errors | optional | Array | Mô tả lỗi chi tiết các trường nếu có |
| errors.*.field | optional | String | Trường dữ liệu bị lỗi |
| errors.*.reason | optional | String | Mô tả trường dữ liệu bị lỗi |
{
"errorCode": 3002,
"message": "Mã tham chiếu Partner đã bị trùng, vui lòng thực hiện lại"
}
Bảng mã lỗi thường gặp
Mã lỗi đầy đủ vui lòng xem tại đây
| Mã lỗi | Mô tả |
|---|---|
| 0 | Thành công |
| 1 | Thông tin yêu cầu thiếu hoặc không hợp lệ |
| 11 | Partner không tồn tại |
| 13 | Partner đã bị khoá |
| 14 | API Key không tồn tại |
| 15 | API Key chưa được kích hoạt hoặc đã bị khoá |
| 92 | IP không được phép truy cập |
| 99 | Lỗi không xác định, vui lòng liên hệ AppotaPay để biết thêm thông tin chi tiết |
| 110 | Tổng số tiền refund vượt quá số tiền giao dịch |
| 125 | Không thể hoàn tiền cho giao dịch vì đã quá thời hạn hoàn tiền |
| 401 | Lỗi xác thực |
| 500 | Hệ thống gặp lỗi, vui lòng thử lại sau |
| 3002 | Mã tham chiếu Partner đã bị trùng, vui lòng thực hiện lại |
| 3057 | Cycle attempt không hợp lệ |