Phiên bản: Lastest

API Hoàn tiền

Chat với AI▼

Đố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ệ

Code Examples

curl --location 'https://gateway.dev.appotapay.com/api/v1/subs/refunds' \
  --header 'X-APPOTAPAY-AUTH: JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'X-Request-ID: Your_Unique_id' \
  --header 'Language: vi' \
  --header 'X-Account-Ref-ID: 9723f73b-9295-4acb-884b-ab6310c2e653' \
  -d '{
  "refundRefId": "ASKJLKALK20398141",
  "attemptId": "01HY2TRW9EBTPWGPJDGPD9JMA9",
  "reason": "REQUESTED_BY_CUSTOMER",
  "currency": "VND",
  "amount": 10000
}'

Request

REQUEST

Base URL

Development server

Path

Auth REQUIRED

Bearer Token

Language — header

Giá trị tương ứng với payment link có thể là tiếng Việt hoặc tiếng Anh (mặc định: vi)

Parameters

Body REQUIRED

Example (from schema)

API Hoàn tiền

Header Params​

Tham số​

Example Request​

Dữ liệu trả về​

Thành công​

Thất bại​

Error response params​

Bảng mã lỗi thường gặp​

Code Examples​

Request​