API Webhooks qua OAuth 2.0

Cấu hình và dùng API Webhooks SePay qua xác thực OAuth 2.0. Nhận thông báo theo thời gian thực cho giao dịch và sự kiện tài khoản một cách an toàn.

||

Giới thiệu

API Webhooks của SePay cho phép bạn quản lý các webhook để nhận thông báo thời gian thực về giao dịch. Webhook là một cách hiệu quả để tự động hóa quy trình thanh toán, giúp hệ thống của bạn nhận được thông báo ngay khi có giao dịch mới.

Để sử dụng API này, bạn cần có các quyền tương ứng trong phạm vi (scope) của Access Token: webhook:read để xem, webhook:write để tạo/cập nhật, và webhook:delete để xóa webhook.

Các Endpoints

API Webhooks cung cấp các endpoints sau:

GET
/api/v1/webhooks
GET
/api/v1/webhooks/{id}
POST
/api/v1/webhooks
PATCH
/api/v1/webhooks/{id}
DELETE
/api/v1/webhooks/{id}

Lấy danh sách webhooks

GET
https://my.sepay.vn/api/v1/webhooks
Authorization: Bearer {YOUR_ACCESS_TOKEN}

Endpoint này trả về danh sách webhooks của công ty bạn. Bạn có thể lọc kết quả theo nhiều tiêu chí khác nhau.

Quyền yêu cầu:

  • Scope: webhook:read
  • Quyền người dùng: Webhooks (Xem danh sách webhooks)

Tham số truy vấn:

webhook_urlstring
Lọc theo URL webhook (tìm kiếm một phần)
api_keystring
Lọc theo API key
activeinteger
Lọc theo trạng thái hoạt động (0: không hoạt động, 1: đang hoạt động)
pageinteger
Số trang, bắt đầu từ 1
limitinteger
Số lượng kết quả trên mỗi trang
>
>
>
>
>
curl -G "https://my.sepay.vn/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --data-urlencode "active=1" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"
RESPONSE
{
    "status": "success",
    "data": [
        {
            "id": 23,
            "bank_account_id": 19,
            "name": "Tích hợp với shop online",
            "event_type": "In_only",
            "authen_type": "HMAC_SHA256",
            "webhook_url": "https://example.com/webhook/payment",
            "is_verify_payment": true,
            "skip_if_no_code": true,
            "prefix_filters": [],
            "retry_conditions": { "non_2xx_status_code": 0 },
            "only_va": true,
            "va_mode": "list",
            "bank_mode": "single",
            "alert_threshold": 3,
            "alert_event_types": ["failure", "recovery"],
            "active": true,
            "created_at": "2025-02-15 14:23:56",
            "secret_key": "whsec_a7c3b4e5f6a7b8c9d0e1f2a3b4c5d6e7",
            "request_content_type": "Json",
            "bank_sub_account_ids": [25, 26]
        },
        {
            "id": 22,
            "bank_account_id": 0,
            "name": "Webhook toàn công ty",
            "event_type": "All",
            "authen_type": "OAuth2.0",
            "webhook_url": "https://crm.example.com/webhook/transactions",
            "is_verify_payment": false,
            "skip_if_no_code": false,
            "prefix_filters": ["SEVQR", "ORDER"],
            "retry_conditions": { "non_2xx_status_code": 0 },
            "only_va": false,
            "va_mode": "all",
            "bank_mode": "multi",
            "alert_threshold": null,
            "alert_event_types": null,
            "active": true,
            "created_at": "2025-02-10 09:45:32",
            "oauth2_client_id": "client_id_example",
            "oauth2_client_secret": "client_secret_example",
            "oauth2_access_token_url": "https://crm.example.com/oauth/token"
        }
    ],
    "meta": {
        "pagination": {
            "total": 5,
            "per_page": 20,
            "current_page": 1,
            "last_page": 1
        }
    }
}

Lấy chi tiết webhook

GET
https://my.sepay.vn/api/v1/webhooks/{id}
Authorization: Bearer {YOUR_ACCESS_TOKEN}

Endpoint này trả về thông tin chi tiết của một webhook dựa trên ID.

Quyền yêu cầu:

  • Scope: webhook:read
  • Quyền người dùng: Webhooks (Xem danh sách webhooks)

Tham số đường dẫn:

idintegerrequired
ID của webhook
>
>
curl -X GET "https://my.sepay.vn/api/v1/webhooks/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
RESPONSE
{
    "status": "success",
    "data": {
        "id": 23,
        "bank_account_id": 19,
        "name": "Tích hợp với shop online",
        "event_type": "In_only",
        "authen_type": "Api_Key",
        "webhook_url": "https://example.com/webhook/payment",
        "is_verify_payment": true,
        "skip_if_no_code": true,
        "prefix_filters": [],
        "retry_conditions": {
            "non_2xx_status_code": 0
        },
        "only_va": true,
        "va_mode": "list",
        "bank_mode": "single",
        "alert_threshold": null,
        "alert_event_types": null,
        "active": true,
        "created_at": "2025-02-15 14:23:56",
        "api_key": "a7c3b4e5f6a7b8c9d0e1f2a3b4c5d6e7",
        "request_content_type": "Json",
        "bank_sub_account_ids": [25, 26]
    }
}

Tạo webhook mới

POST
https://my.sepay.vn/api/v1/webhooks
Authorization: Bearer {YOUR_ACCESS_TOKEN}
Content-Type: application/json

Endpoint này cho phép bạn tạo một webhook mới để nhận thông báo về giao dịch.

Quyền yêu cầu:

  • Scope: webhook:write
  • Quyền người dùng: Webhooks (Thêm webhooks)

Tham số yêu cầu:

bank_account_idinteger
ID tài khoản ngân hàng. Bắt buộc khi không truyền `bank_mode`.
bank_account_idsarray
Danh sách ID tài khoản ngân hàng. Bắt buộc khi `bank_mode=multi`.
bank_modestring
`single`: một tài khoản. `multi`: nhiều tài khoản. `all`: toàn bộ tài khoản công ty.
namestringrequired
Tên webhook
event_typestringrequired
Loại sự kiện: `All`, `In_only`, `Out_only`
authen_typestringrequired
`No_Authen`, `Api_Key`, `HMAC_SHA256`, `OAuth2.0`
webhook_urlstringrequired
URL nhận webhook. Phải là URL public. IP nội bộ hoặc localhost không được chấp nhận.
is_verify_paymentintegerrequired
Xác thực thanh toán (0 hoặc 1)
skip_if_no_codeinteger
Bỏ qua giao dịch không có mã thanh toán (0 hoặc 1)
activeinteger
Trạng thái hoạt động (0 hoặc 1)
retry_conditionsobject
Điều kiện thử lại, ví dụ `{"non_2xx_status_code": 1}`
prefix_filtersarray<string>
Lọc theo tiền tố mã thanh toán. Chỉ gửi khi mã bắt đầu bằng một trong các tiền tố. Tối đa 50 tiền tố, mỗi tiền tố 100 ký tự.
only_vainteger
Chỉ nhận giao dịch tài khoản ảo (0 hoặc 1)
va_modestring
`all`: cả tài khoản chính và tài khoản ảo. `list`: chỉ các tài khoản ảo liệt kê. `none`: chỉ tài khoản chính.
bank_sub_account_idsarray<integer>
ID các tài khoản ảo. Bắt buộc khi `only_va=1` hoặc `va_mode=list`.
alert_thresholdinteger
Số lần lỗi liên tiếp trước khi gửi cảnh báo (1-20). Không truyền = không cảnh báo.
alert_event_typesarray<string>
Loại sự kiện cảnh báo: `failure`, `recovery`.
alert_channel_idsarray<integer>
ID các kênh cảnh báo đã tạo trước (Telegram, Email, Slack, Discord).

Thêm tham số theo kiểu xác thực:

Api_Key

  • api_key (bắt buộc): API Key, tối đa 1000 ký tự
  • request_content_type (bắt buộc): Json, multipart_form-data, hoặc application_x-www-form-urlencoded

HMAC_SHA256 (khuyến nghị)

  • secret_key (bắt buộc): Secret Key, tối đa 500 ký tự. SePay ký payload bằng HMAC-SHA256 và gửi chữ ký trong header X-SePay-Signature, kèm X-SePay-Timestamp.
  • request_content_type (bắt buộc): Json, multipart_form-data, hoặc application_x-www-form-urlencoded

Hướng dẫn xác minh chữ ký xem tại tài liệu SePay Webhooks, mục HMAC-SHA256.

OAuth2.0

  • oauth2_access_token_url (bắt buộc): URL lấy access token. Phải là URL public.
  • oauth2_client_id (bắt buộc): Client ID
  • oauth2_client_secret (bắt buộc): Client Secret

No_Authen

  • request_content_type (bắt buộc): Json, multipart_form-data, hoặc application_x-www-form-urlencoded
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
curl -X POST "https://my.sepay.vn/api/v1/webhooks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "bank_account_id": 19,
    "name": "Tích hợp với shop online",
    "event_type": "In_only",
    "authen_type": "Api_Key",
    "webhook_url": "https://example.com/webhook/payment",
    "is_verify_payment": 1,
    "skip_if_no_code": 1,
    "active": 1,
    "only_va": 1,
    "bank_sub_account_ids": [25, 26],
    "retry_conditions": {"non_2xx_status_code": 1},
    "api_key": "a7c3b4e5f6a7b8c9d0e1f2a3b4c5d6e7",
    "request_content_type": "Json"
  }'
RESPONSE
{
    "status": "success",
    "message": "Webhook created successfully",
    "data": { "id": 23 }
}

Cập nhật webhook

PATCH
https://my.sepay.vn/api/v1/webhooks/{id}
Authorization: Bearer {YOUR_ACCESS_TOKEN}
Content-Type: application/json

Endpoint này cho phép bạn cập nhật thông tin của một webhook hiện có.

Quyền yêu cầu:

  • Scope: webhook:write
  • Quyền người dùng: Webhooks (Sửa webhooks)

Tham số đường dẫn:

idintegerrequired
ID của webhook

Tham số yêu cầu: giống khi tạo webhook, nhưng tất cả đều tùy chọn. Chỉ gửi các trường muốn thay đổi.

Lưu ý:

  • Webhook dùng bank_mode=multi hoặc bank_mode=all không đổi được bank_account_id qua API. Hãy chỉnh qua giao diện web.
  • Gửi bank_account_id=0 phải kèm bank_mode=all.
>
>
>
>
>
>
>
curl -X PATCH "https://my.sepay.vn/api/v1/webhooks/{id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "active": 0,
    "skip_if_no_code": 0
  }'
RESPONSE
{
    "status": "success",
    "message": "Webhook updated successfully",
    "data": { "active": 0, "skip_if_no_code": 0 }
}

Xóa webhook

DELETE
https://my.sepay.vn/api/v1/webhooks/{id}
Authorization: Bearer {YOUR_ACCESS_TOKEN}

Endpoint này cho phép bạn xóa một webhook.

Quyền yêu cầu:

  • Scope: webhook:delete
  • Quyền người dùng: Webhooks (Xóa webhooks)

Tham số đường dẫn:

idintegerrequired
ID của webhook
>
>
curl -X DELETE "https://my.sepay.vn/api/v1/webhooks/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
RESPONSE
Code
1
HTTP/1.1 204 No Content

Ví dụ: webhook HMAC-SHA256

{
  "bank_account_id": 19,
  "name": "Webhook HMAC",
  "event_type": "In_only",
  "authen_type": "HMAC_SHA256",
  "webhook_url": "https://example.com/webhook/payment",
  "secret_key": "whsec_a1b2c3d4e5f6...",
  "request_content_type": "Json",
  "is_verify_payment": 1
}

SePay ký payload bằng HMAC-SHA256 và gửi chữ ký trong header X-SePay-Signature, kèm X-SePay-Timestamp. Cách xác minh xem ở tài liệu SePay Webhooks, mục HMAC-SHA256.

Ví dụ: webhook nhiều tài khoản

{
  "bank_account_ids": [19, 20, 21],
  "bank_mode": "multi",
  "name": "Webhook nhiều tài khoản",
  "event_type": "In_only",
  "authen_type": "Api_Key",
  "webhook_url": "https://example.com/webhook/payment",
  "api_key": "a7c3b4e5f6a7b8c9d0e1f2a3b4c5d6e7",
  "request_content_type": "Json",
  "is_verify_payment": 1
}

Áp dụng cho toàn bộ tài khoản của công ty:

{
  "bank_mode": "all",
  "name": "Webhook toàn công ty",
  "event_type": "All",
  "authen_type": "HMAC_SHA256",
  "webhook_url": "https://example.com/webhook/all",
  "secret_key": "whsec_...",
  "request_content_type": "Json",
  "is_verify_payment": 1
}

Ví dụ: bật cảnh báo

Bật cảnh báo khi webhook lỗi liên tiếp và khi webhook phục hồi, gửi tới các kênh đã tạo trong trang Webhooks (tab Kênh cảnh báo):

{
  "bank_account_id": 19,
  "name": "Webhook có cảnh báo",
  "event_type": "In_only",
  "authen_type": "HMAC_SHA256",
  "webhook_url": "https://example.com/webhook/payment",
  "secret_key": "whsec_...",
  "request_content_type": "Json",
  "is_verify_payment": 1,
  "alert_threshold": 3,
  "alert_event_types": ["failure", "recovery"],
  "alert_channel_ids": [5, 7]
}

Mã lỗi

400validation_error

Dữ liệu đầu vào không hợp lệ (ví dụ: `webhook_url` không public, `bank_account_id=0` thiếu `bank_mode=all`).

401unauthorized

Token không hợp lệ hoặc hết hạn.

403forbidden

Không có quyền truy cập tài nguyên này.

404not_found

Không tìm thấy webhook.

500delete_failed

Xóa webhook thất bại. Gọi lại an toàn.

Trước
—
Tiếp theo
—