API Webhooks

Tài liệu về cách sử dụng API webhooks thông qua OAuth2 trong SePay.

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

Lấy danh sách webhooks với các tùy chọn lọc

GET
/api/v1/webhooks/{id}

Lấy thông tin chi tiết về một webhook cụ thể

POST
/api/v1/webhooks

Tạo webhook mới

PATCH
/api/v1/webhooks/{id}

Cập nhật thông tin webhook

DELETE
/api/v1/webhooks/{id}

Xóa webhook

Lấy danh sách webhooks

GET
/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
1
2
3
4
5
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": "Api_Key",
            "webhook_url": "https://example.com/webhook/payment",
            "is_verify_payment": true,
            "skip_if_no_code": true,
            "retry_conditions": {
                "non_2xx_status_code": 0
            },
            "only_va": true,
            "active": true,
            "created_at": "2025-02-15 14:23:56",
            "api_key": "a7c3b4e5f6a7b8c9d0e1f2a3b4c5d6e7",
            "request_content_type": "Json",
            "bank_sub_account_ids": [25, 26]
        },
        {
            "id": 22,
            "bank_account_id": 18,
            "name": "Tích hợp với CRM",
            "event_type": "All",
            "authen_type": "OAuth2.0",
            "webhook_url": "https://crm.example.com/webhook/transactions",
            "is_verify_payment": false,
            "skip_if_no_code": false,
            "retry_conditions": {
                "non_2xx_status_code": 0
            },
            "only_va": false,
            "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
/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
1
2
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,
        "retry_conditions": {
            "only_va": true,
            "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
/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_idintegerrequired
ID của tài khoản ngân hàng
namestringrequired
Tên của webhook
event_typestringrequired
Loại sự kiện (All, In_only, Out_only)
authen_typestringrequired
Kiểu xác thực (No_Authen, OAuth2.0, Api_Key)
webhook_urlstringrequired
URL nhận webhook
is_verify_paymentintegerrequired
Có xác thực thanh toán không (0: không, 1: có)
skip_if_no_codeinteger
Bỏ qua nếu không có mã thanh toán (0: không, 1: có)
activeinteger
Trạng thái hoạt động (0: không hoạt động, 1: đang hoạt động)
retry_conditionsarray
Điều kiện thử lại khi gặp lỗi
only_vainteger
Chỉ nhận giao dịch từ tài khoản ảo (0: không, 1: có)
bank_sub_account_idsarray
Danh sách ID tài khoản ảo (bắt buộc nếu only_va=1)

Thêm tham số cho từng kiểu xác thực:

OAuth2.0:

  • oauth2_access_token_url (bắt buộc) – URL để lấy access token
  • oauth2_client_id (bắt buộc) – Client ID
  • oauth2_client_secret (bắt buộc) – Client Secret

Api_Key:

  • api_key (bắt buộc) – API Key dùng để xác thực
  • request_content_type (bắt buộc) – Kiểu nội dung yêu cầu (Json, multipart_form-data)

No_Authen:

  • request_content_type (bắt buộc) – Kiểu nội dung yêu cầu (Json, multipart_form-data)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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
{
  "message": "Thêm WebHooks thành công",
  "id": 23
}

Cập nhật webhook

PATCH
/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: Tham số yêu cầu giống như khi tạo webhook, nhưng tất cả đều là tùy chọn. Bạn chỉ cần cung cấp các tham số cần thay đổi.

1
2
3
4
5
6
7
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
{
    "message": "Cập nhật WebHooks thành công",
    "id": "23"
}

Xóa webhook

DELETE
/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
1
2
curl -X DELETE "https://my.sepay.vn/api/v1/webhooks/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
RESPONSE
{
    "message": "Xóa WebHooks thành công"
}

Mã lỗi

Dưới đây là các mã lỗi có thể gặp khi sử dụng API webhooks:

400validation_error

Lỗi xác thực dữ liệu đầu vào

401unauthorized

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

403forbidden

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

404not_found

Không tìm thấy webhook

Trước
—
Tiếp theo
—