Nhảy tới nội dung
Phiên bản: Lastest

Hoàn tiền giao dịch

Endpoint: POST /api/v2/transaction/refund

Header Params​

Tham sốYêu cầuKiểu dữ liệuMô tảLưu ý
X-APPOTAPAY-AUTHrequiredString Cách tạo JWT_TOKEN
Content-TyperequiredStringGiá trị: application/json
X-Request-IDoptionalStringĐịnh dạng UUIDv4. Request ID để kiểm tra yêu cầu khi xảy ra sự cốmax:40
X-LanguageoptionalStringGiá 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-IDoptionalString

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",
    "X-Language": "vi",
    "X-Account-Ref-ID": "9723f73b-9295-4acb-884b-ab6310c2e653"
}

Tham số​

Tham sốYêu cầuKiểu dữ liệuMô tảĐịnh dạng
partnerRefIdrequiredStringMã tham chiếu giao dịch của Partner đối với AppotaPay (không được trùng lặp)max:50,alphanumeric
transactionIdrequiredStringMã giao dịch thanh toán từ AppotaPay trả vềalphanumeric
amountrequiredIntegerSố tiền hoànmin:1000
currencyrequiredStringĐơn vị tiền tệ (chấp nhận VND)in:VND
reasonrequiredStringLý do hoàn tiềnmax:100,alphanumeric

Dữ liệu trả về​

Tham sốYêu cầuKiểu dữ liệuMô tả
refundIdrequiredStringMã giao dịch hoàn tiền phía AppotaPay
transactionIdrequiredStringMã giao dịch thanh toán phía AppotaPay
partnerRefIdrequiredStringMã tham chiếu giao dịch hoàn tiền phía đối tác
amountrequiredIntegerSố tiền hoàn
currencyrequiredStringĐơn vị tiền tệ (chấp nhận VND)
reasonrequiredStringLý do hoàn tiền
statusrequiredStringTrạng thái hoàn tiền
createdAtrequiredStringThời gian thực hiện giao dịch. (định dạng chuẩn RFC-3339)
refundedAtoptionalStringThời gian thực hoàn tiền nếu giao dịch hoàn tiền thành công. (định dạng chuẩn RFC-3339)

Bảng mã trạng thái giao dịch hoàn tiền​

Trạng tháiMô tả
pendingGiao dịch thanh toán không hỗ trợ hoàn tiền tự động AppotaPay tiếp nhận yêu cầu hoàn tiền và xử lý hoàn thủ công trong 1 ngày, đối tác có thể gọi API kiểm tra trạng thái giao dịch. Quá 1 ngày giao dịch vẫn chưa đổi về trạng thái cuối (success, error) thì đối tác vui lòng liên hệ CSKH để được trợ giúp
processingGiao dịch thanh toán hỗ trợ hoàn tiền tự động AppotaPay tiếp nhận yêu cầu hoàn tiền và đang xử lý, đối tác có thể gọi API kiểm tra trạng thái giao dịch. Quá 1 ngày giao dịch vẫn chưa đổi về trạng thái cuối (success, error) thì đối tác vui lòng liên hệ CSKH để được trợ giúp
successGiao dịch hoàn tiền thành công.
errorGiao dịch hoàn tiền thất bại.

Ví dụ​

Request​

{
    "partnerRefId": "5f61cf4f41e2b",
    "transactionId": "AP241453209745",
    "amount": 10000,
    "currency": "VND",
    "reason": "test refund"
}

Response​

{
    "refundId": "f28a4ac3-e407-45f1-902b-bc05c6c50dfa",
    "transactionId": "AP241453209745",
    "partnerRefId": "5f61cf4f41e2b",
    "amount": 10000,
    "currency": "VND",
    "reason": "test refund",
    "status": "success",
    "createdAt": "2024-09-11T11:21:17+07:00",
    "refundedAt": ""
}

Thất bại​

HTTP Status Code != 200 Với errorCode trả về, vui lòng tham khảo bảng mã lỗi tại đây

Error response params​

Tham sốYêu cầuKiểu dữ liệuMô tả
errorCoderequiredIntegerMã lỗi
messagerequiredStringMô tả lỗi
errorsoptionalArray of ObjectMô tả lỗi chi tiết các trường nếu có
errors.fieldrequiredObjectTrường dữ liệu bị lỗi
errors.reasonrequiredObjectMô tả trường dữ liệu bị lỗi
{
  "errorCode": 1,
  "message": "Invalid Params",
  "errors": [
    {
      "field": "transaction.amount",
      "reason": "Field amount is required"
    },
    {
      "field": "transaction.currency",
      "reason": "Field currency is required"
    }
  ]
}

Danh sách nhà cung cấp hỗ trợ refund​

Vendor codeThời gian hỗ trợ refundAuto qua apiRefund một phầnRefund nhiều lầnRefund toàn phầnTime user nhận tiền
Napas1 nămCóCóCó5 - 7 ngày làm việc
Vpbank Visa - Mastercard6 thángCóCóCó10 - 15 ngày làm việc
VnptPayCóKhôngKhôngCó
ONEPAYKhôngKhông
EBILLKhôngKhông
SHOPEE90 ngàyCóCóCóCóReal time
MOCA1 thángCóKhôngKhôngCóReal time
APPOTA WALLETCóKhôngKhôngCóReal time
MOMOCóCóCóCóReal time
ViettelPayKhôngKhôngKhôngKhông
ZaloPay180 ngàyCóCóCóCóReal time
VAKhôngKhôngKhông
VNpayCóCóKhông
CybersourceKhôngKhôngKhôngKhôngKhôngKhông

Bảng mã lỗi​

Mã lỗiMô tả
1Thông tin yêu cầu thiếu hoặc không hợp lệ
31Mã giao dịch bị trùng
36Giao dịch không tồn tại
129Vui lòng chờ {times} để tạo yêu cầu hoàn tiền mới.
135Giao dịch không hỗ trợ hoàn tiền
401Unauthorized
500Hệ thống gặp lỗi, vui lòng thử lại sau