Kết nối SePay với omniVN

Chỉ webhook

Thiết kế webhook đã có verifier HMAC; runtime ingress production và API key backfill chưa mở.

Chỉ hỗ trợ webhook

Chỉ webhook. Giao dịch ngân hàng real-time qua webhook. API backfill chưa được nối vào UI. Trang này chưa được mở trong workspace.

Kết nối SePayTạo tài khoản và làm theo hướng dẫn bên dưới — dùng thử 14 ngày.

Giới hạn hiện tại

Những điểm này ảnh hưởng đến khả năng kết nối hoàn chỉnh.

Chưa có UI nhập webhook secret hoặc API key backfill.
Đã có verifier HMAC timestamped raw-body nhưng chưa có route ingress production; merchant vẫn cần tự tạo webhook trên SePay sau khi Omni0 mở endpoint.

Tổng quan

SePay gửi giao dịch ngân hàng real-time qua webhook HTTPS. Merchant cấu hình webhook trên my.sepay.vn (Integrations → Webhooks), chọn tài khoản, bộ lọc mã thanh toán và phương thức xác thực (API Key, HMAC hoặc OAuth). Omni0 hiện chưa provision route ingress production; credential backfill chưa nối UI.

Điều kiện trước khi bắt đầu

Tài khoản SePay và tài khoản ngân hàng đã liên kết.
Endpoint HTTPS do Omni0 cung cấp sau khi runtime ingress được mở.

Các bước lấy credential

1. Mở trang Webhooks

Đăng nhập SePay Dashboard → Integrations → Webhooks (https://my.sepay.vn/webhooks). Nhấn Add webhook để mở wizard 4 bước.

SePay — trang quản lý Webhooks · SePay Developer

2. Bước 1 — Thông tin cơ bản

Đặt tên webhook, URL HTTPS endpoint, loại sự kiện (Money in / Money out / Both), Content-Type application/json, bật Auto retry nếu cần.

SePay webhook wizard — bước Basics · SePay Developer

3. Bước 2 — Tài khoản và bộ lọc

Chọn tài khoản ngân hàng (tất cả hoặc từng tài khoản). Cấu hình prefix mã thanh toán và tùy chọn bỏ qua giao dịch không có mã (theo cấu trúc mã tại Company → General settings).

4. Bước 3 — Bảo mật

Chọn None (chỉ test), API Key (header Authorization: Apikey …), HMAC-SHA256 (khuyến nghị), hoặc OAuth 2.0 Bearer. Lưu secret/key để Omni0 xác thực chữ ký. Backend đã có primitive HMAC timestamped raw-body; route webhook và API v2 backfill vẫn chưa mở production.

SePay webhook wizard — bước Security · SePay Developer

5. Test send và hiện trạng Omni0

Chỉ dùng ⋮ → Test send sau khi Omni0 provision endpoint. Khi route hoạt động, yêu cầu response 200 với body {"success": true}. API key backfill qua userapi.sepay.vn chưa có chỗ nhập trong UI workspace.

Ánh xạ credential với omniVN

Cột "Lấy từ đâu" cho biết giá trị do người dùng nhập, do provider cấp, do omniVN quản lý, hay do OAuth sinh ra.

Field omniVN	Tên trong tài liệu official	Bắt buộc	Lấy từ đâu
API Key	API key	Tùy chọn	not_exposed Dùng cho backfill qua API, hiện chưa có chỗ nhập trong UI.
Webhook Secret	Webhook secret / HMAC key	Tùy chọn	not_exposed Dùng để xác thực chữ ký webhook, hiện là placeholder.

apiKey → API Key (backfill, chưa UI); webhookSecret → secret HMAC/API Key/OAuth cấu hình trên webhook SePay.

Vòng đời token

Webhook secret/key do SePay cấp khi tạo webhook. Clone webhook không copy secret — cần nhập lại.

Nguồn chính thức

SePay - Tạo webhook

developer.sepay.vn·Công khai·Đã kiểm chứng 2026-08-29

SePay - Tích hợp webhook

developer.sepay.vn·Công khai·Đã kiểm chứng 2026-08-29