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

Tên	Loại	Bắt buộc	Mô tả
`webhook_url`	string	Không bắt buộc	Lọc theo URL webhook (tìm kiếm một phần)
`api_key`	string	Không bắt buộc	Lọc theo API key
`active`	integer	Không bắt buộc	Lọc theo trạng thái hoạt động (0: không hoạt động, 1: đang hoạt động)
`page`	integer	Không bắt buộc	Số trang, bắt đầu từ 1
`limit`	integer	Không bắt buộc	Số lượng kết quả trên mỗi trang

bash

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
Tên Loại Bắt buộc Mô tả
id
integer Bắt buộc
ID của webhook

Tên	Loại	Bắt buộc	Mô tả
`id`	integer	Bắt buộc	ID của webhook

bash

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}

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

Tên	Loại	Bắt buộc	Mô tả
`bank_account_id`	integer	Bắt buộc	ID của tài khoản ngân hàng
`name`	string	Bắt buộc	Tên của webhook
`event_type`	string	Bắt buộc	Loại sự kiện (All, In_only, Out_only)
`authen_type`	string	Bắt buộc	Kiểu xác thực (No_Authen, OAuth2.0, Api_Key)
`webhook_url`	string	Bắt buộc	URL nhận webhook
`is_verify_payment`	integer	Bắt buộc	Có xác thực thanh toán không (0: không, 1: có)
`skip_if_no_code`	integer	Không bắt buộc	Bỏ qua nếu không có mã thanh toán (0: không, 1: có)
`active`	integer	Không bắt buộc	Trạng thái hoạt động (0: không hoạt động, 1: đang hoạt động)
`retry_conditions`	array	Không bắt buộc	Điều kiện thử lại khi gặp lỗi
`only_va`	integer	Không bắt buộc	Chỉ nhận giao dịch từ tài khoản ảo (0: không, 1: có)
`bank_sub_account_ids`	array	Không bắt buộc	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
  - Các tham số bổ sung cần cấu hình:
    - 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
  - Các tham số bổ sung cần cấu hình:
    - 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
  - Các tham số bổ sung cần cấu hình:
    - request_content_type (bắt buộc) – Kiểu nội dung yêu cầu (Json, multipart_form-data).

Cập nhật webhook

PATCH

/api/v1/webhooks/{id}

Authorization: Bearer {YOUR_ACCESS_TOKEN}

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
Tên Loại Bắt buộc Mô tả
id
integer Bắt buộc
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.

Tên	Loại	Bắt buộc	Mô tả
`id`	integer	Bắt buộc	ID của webhook

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
Tên Loại Bắt buộc Mô tả
id
integer Bắt buộc
ID của webhook

Tên	Loại	Bắt buộc	Mô tả
`id`	integer	Bắt buộc	ID của webhook

Mã lỗi

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

Mã Http	Mã lỗi	Mô tả
400	validation_error	Lỗi xác thực dữ liệu đầu vào
401	unauthorized	Token không hợp lệ hoặc hết hạn
403	forbidden	Không có quyền truy cập vào tài nguyên này
404	not_found	Không tìm thấy webhook