Tổng quan API hoàn tiền

Gửi một lệnh hoàn tiền, SePay chuyển sang ngân hàng và trả về refund_id để bạn theo dõi trạng thái tới khi có kết quả cuối cùng.

Quy tắc số tiền

Hạn mức tính trên giao dịch thu hộ gốc

Hạn mức hoàn không tính trên tổng tiền của đơn hàng, mà trên từng giao dịch thu hộ đã vào tài khoản. Tổng các lệnh hoàn của một giao dịch không bao giờ vượt quá số tiền chính giao dịch đó thu được. Lệnh đang pending cũng chiếm hạn mức, nên một lệnh chưa có kết quả không mở đường cho lệnh thứ hai vượt số tiền đã thu.

Điều này quyết định cách endpoint theo đơn hàng hoạt động:

Ví dụ một đơn hàng 500.000đ được khách trả làm hai đợt 300.000đ và 200.000đ: đơn có hai giao dịch thu hộ, nên gọi hoàn theo đơn hàng mà không truyền transaction_id sẽ nhận 422 transaction_required. Chỉ định đợt 300.000đ thì hoàn được tối đa 300.000đ cho đợt đó, muốn hoàn nốt phần còn lại phải gửi lệnh thứ hai chỉ định đợt 200.000đ.

Hoàn theo đơn hàng hay theo giao dịch

Hai endpoint chạy qua cùng một lớp xử lý và cùng một hạn mức, chỉ khác ở cách bạn chỉ ra khoản thu cần hoàn:

Vì hạn mức gắn với giao dịch gốc chứ không gắn với đường gọi, hoàn một khoản thu qua endpoint giao dịch rồi gọi tiếp endpoint đơn hàng cho cùng khoản đó sẽ thấy phần còn lại đã bị trừ. Không có cách nào chi tiền hai lần bằng cách đổi endpoint.

Trạng thái hoàn tiền

Ba trạng thái cuối là kết thúc và không đổi nữa. Một lệnh đã succeeded không bao giờ quay lại pending, nên bạn có thể ghi nhận kết quả ngay khi đọc được.

Các endpoint

Các bước tích hợp

curl -X POST "https://userapi.sepay.vn/v2/bank-accounts/{ba_uuid}/orders/{order_uuid}/refund" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "X-Idempotency-Key: refund-DH20250001-01" \
-d '{"refund_amount": 50000}'

{
  "status": "success",
  "data": {
    "refund_id": "RF-7QK3-M8PZ-4VNW",
    "order_type": "va_order",
    "order_id": "b2c3d4e5-f6a7-8901-bcde-f12345678902",
    "order_code": "DH20250001",
    "xid": "e5f6a7b8-c9d0-1234-ef56-789012345abc",
    "transaction_id": "6398452",
    "original_reference": "164T24200GKAJ7BY",
    "amount": 50000,
    "currency": "VND",
    "scope": "partial",
    "status": "pending",
    "created_at": "2026-08-28 14:05:00"
  }
}

curl -X GET "https://userapi.sepay.vn/v2/bank-accounts/{ba_uuid}/refunds/RF-7QK3-M8PZ-4VNW" \
-H "Authorization: Bearer YOUR_API_TOKEN"

Xem thêm

• Hoàn tiền theo đơn hàng
• Hoàn tiền theo giao dịch
• Danh sách hoàn tiền
• Chống trùng và đối soát
• VA theo đơn hàng