Hoàn tiền cho giao dịch
https://userapi.sepay.vn/v2/transactions/{transaction_id}/refundDùng khi tiền vào tài khoản mà không có đơn hàng phía sau, ví dụ khách chuyển thẳng vào tài khoản thật hoặc vào một VA tĩnh đã đăng ký.
Lấy ID giao dịch từ Danh sách giao dịch.
Hoàn tiền hiện chỉ áp dụng cho tài khoản VietinBank doanh nghiệp. Tài khoản thuộc ngân hàng khác nhận 422 unsupported_bank, tài khoản chưa được bật nhận 422 not_available. Sandbox không áp dụng khóa này, nên lệnh hoàn chạy được trên Sandbox vẫn có thể trả 422 not_available khi lên thật.
Thiếu header này SePay trả 422 idempotency_key_required. Gửi lại cùng một khóa trả về đúng bản ghi cũ thay vì chi tiền lần hai.
Luồng xử lý
Bước 1, 6 và 10 phía bạn giống hệt đường hoàn theo đơn hàng, xem Chống trùng và đối soát.
Bước 3 xác định luôn ngân hàng xử lý, vì ngân hàng lấy theo tài khoản đã nhận khoản thu đó. Nếu giao dịch thuộc về một đơn hàng VA, đơn hàng đó vẫn được ghi nhận và hạn mức dùng chung với đường hoàn theo đơn hàng.
Tham số đường dẫn
ID giao dịch thu hộ, lấy từ Danh sách giao dịch
Header
Khóa chống trùng do bạn tự sinh, duy nhất cho mỗi yêu cầu hoàn tiền, tối đa 100 ký tự. Gửi lại cùng khóa trả về bản ghi cũ thay vì chi tiền lần hai. Khóa dài hơn 100 ký tự trả 422 validation_error với lỗi trên idempotency_key.
Request body
Số tiền cần hoàn (VND, số nguyên dương). Bỏ trống để hoàn toàn bộ phần còn lại của giao dịch gốc.
Nếu giao dịch thuộc về một đơn hàng VA, đơn hàng đó vẫn được ghi nhận là đối tượng của lệnh hoàn và hạn mức dùng chung với Hoàn tiền theo đơn hàng. Gọi nhầm đường không làm tiền ra hai lần.
Code mẫu
curl --request POST \--url https://userapi.sepay.vn/v2/transactions/6398452/refund \--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \--header 'X-Idempotency-Key: refund-order-DH20250001-01' \--header 'content-type: application/json' \--data '{"refund_amount":50000}'
Response (HTTP 200)
{
"status": "success",
"data": {
"refund_id": "RF-7QK3-M8PZ-4VNW",
"order_type": "va_order",
"order_id": "string",
"order_code": "string",
"xid": "string",
"transaction_id": "string",
"original_reference": "string",
"amount": 50000,
"currency": "VND",
"scope": "full",
"status": "pending",
"created_at": "2026-08-28 14:05:00"
}
}Lỗi
| HTTP | error_code | Mô tả |
|---|---|---|
| 404 | transaction_not_found | Không tìm thấy giao dịch, hoặc giao dịch không thuộc công ty đã xác thực |
| 409 | idempotency_key_reused | Khóa X-Idempotency-Key này đã dùng cho một yêu cầu hoàn tiền khác. Dùng khóa mới. |
| 422 | idempotency_key_required | Thiếu header X-Idempotency-Key, hoặc khóa dài quá 100 ký tự |
| 422 | not_available | Tài khoản chưa được SePay mở hoàn tiền. Liên hệ SePay. |
| 422 | unsupported_bank | Ngân hàng của tài khoản này chưa hỗ trợ hoàn tiền |
| 422 | unsupported_currency | Ngân hàng không hoàn được loại tiền của giao dịch gốc |
| 422 | not_refundable | Giao dịch này không hoàn tiền được |
| 422 | no_original_transaction | Không tìm thấy giao dịch thu hộ gốc |
| 422 | already_refunded | Giao dịch gốc đã được hoàn hết |
| 422 | unsupported_amount_precision | Số tiền gốc không biểu diễn được theo đơn vị của loại tiền đó |
| 422 | validation_error | refund_amount không hợp lệ, hoặc vượt phần còn lại |
| 422 | refund_declined | Ngân hàng từ chối lệnh hoàn tiền |
| 422 | refund_duplicate_reference | Mã hoàn tiền đã tồn tại ở ngân hàng |
| 422 | refund_amount_invalid | Số tiền hoàn không hợp lệ với giao dịch gốc |
| 422 | refund_failed | Ngân hàng nhận lệnh nhưng không thực hiện được |
| 422 | refund_rejected | Ngân hàng không chấp nhận lệnh hoàn tiền |
| 500 | unexpected_error | Lỗi phía SePay, không phải request của bạn. Lệnh có thể đã tới ngân hàng, nên tra lại bằng Danh sách hoàn tiền hoặc gửi lại cùng khóa, đừng sinh khóa mới. |
| 503 | refund_busy | Đang có lệnh hoàn tiền khác chạy cho cùng giao dịch gốc. Chưa có bản ghi nào được tạo, thử lại sau ít giây với cùng khóa. |
| 503 | vietinbank_map_connection_error | Không gọi được sang VietinBank. Bản ghi hoàn đã tạo và đang pending, SePay tự đối soát tiếp. Gửi lại cùng khóa để nhận lại bản ghi đó, đừng sinh khóa mới. |