# Loại sự kiện (/vi/webhooks/events)



Chọn trong số 23 loại sự kiện này hoặc bật đăng ký tất cả các loại. Mọi thông báo đều sử dụng [cấu trúc chung của sự kiện](/webhooks#event-envelope); trang này cho biết mỗi nhóm sự kiện đặt gì bên trong `data`.

## Nhóm sự kiện [#event-families]

| Nhóm                                        | Sự kiện | `data` chứa           |
| ------------------------------------------- | ------- | --------------------- |
| [Thanh toán](#payments)                     | 7       | `payment`             |
| [Hoàn tiền](#refunds)                       | 6       | `payment` và `refund` |
| [Merchant](#merchants)                      | 2       | `merchant`            |
| [Onboarding merchant](#merchant-onboarding) | 8       | `onboarding`          |

Hầu hết các tích hợp bắt đầu với `payment.succeeded`, `payment.failed` và `payment.refund.succeeded`. Các nền tảng onboarding merchant bổ sung thêm `merchant.onboarding.approved` và `merchant.onboarding.action_required`.

## Thanh toán [#payments]

Các sự kiện này mô tả toàn bộ khoản thanh toán, trên các đơn vị xử lý thanh toán và kênh được hỗ trợ. Chúng chứa `data.payment`, bao gồm `status` và `statusId` của khoản thanh toán.

| Sự kiện                                                              | Thời điểm gửi                                                                                                                            |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| <span className="whitespace-nowrap">`payment.created`</span>         | Một khoản thanh toán được lưu.                                                                                                           |
| <span className="whitespace-nowrap">`payment.updated`</span>         | Trạng thái chuyển sang `pending` hoặc trạng thái khác không có tên sự kiện riêng. Đây không phải thông báo cho mỗi lần chỉnh sửa trường. |
| <span className="whitespace-nowrap">`payment.succeeded`</span>       | Trạng thái chuyển sang `success`.                                                                                                        |
| <span className="whitespace-nowrap">`payment.failed`</span>          | Toàn bộ khoản thanh toán chuyển sang `failed`, thay vì một lần thử thanh toán riêng lẻ thất bại.                                         |
| <span className="whitespace-nowrap">`payment.canceled`</span>        | Trạng thái chuyển sang `cancelled`.                                                                                                      |
| <span className="whitespace-nowrap">`payment.refunded`</span>        | Tapaya đánh dấu khoản thanh toán là `refunded`.                                                                                          |
| <span className="whitespace-nowrap">`payment.action_required`</span> | Trạng thái chuyển sang `actionNeeded`.                                                                                                   |

Tạo khoản thanh toán ở trạng thái không phải đang chờ sẽ gửi cả `payment.created` lẫn sự kiện trạng thái tương ứng nếu bạn đăng ký cả hai. Lưu lại cùng một trạng thái không gửi sự kiện trạng thái mới hay `payment.updated`.

`status` và `statusId` nhận các giá trị sau trong bản lưu (snapshot) của thanh toán và hoàn tiền:

| `statusId` | `status`       | Ý nghĩa                                           |
| ---------- | -------------- | ------------------------------------------------- |
| `1`        | `pending`      | Quá trình xử lý chưa có kết quả cuối cùng.        |
| `2`        | `success`      | Thanh toán hoặc hoàn tiền đã thành công.          |
| `3`        | `cancelled`    | Thanh toán hoặc hoàn tiền đã bị hủy.              |
| `4`        | `refunded`     | Tapaya đánh dấu khoản thanh toán là đã hoàn tiền. |
| `5`        | `failed`       | Thanh toán hoặc hoàn tiền đã thất bại.            |
| `6`        | `actionNeeded` | Cần thực hiện thêm hành động.                     |

Các ID trạng thái mới chưa được nhận diện trong tương lai sử dụng `status: "unknown"` và giữ nguyên giá trị số `statusId`. Tên sự kiện sử dụng `succeeded` và `canceled`; giá trị trạng thái sử dụng `success` và `cancelled`.

## Hoàn tiền [#refunds]

Sự kiện hoàn tiền chứa cả `data.payment` và `data.refund`. Khoản hoàn tiền có ID, token, trạng thái, số tiền và loại tiền tệ yêu cầu cũng như quyết toán riêng. Sử dụng ID của khoản hoàn tiền để theo dõi khoản đó độc lập với khoản thanh toán gốc.

| Sự kiện                                                                     | Thời điểm gửi                                                                     |
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| <span className="whitespace-nowrap">`payment.refund.created`</span>         | Một khoản hoàn tiền được lưu.                                                     |
| <span className="whitespace-nowrap">`payment.refund.updated`</span>         | Trạng thái chuyển sang `pending` hoặc trạng thái khác không có tên sự kiện riêng. |
| <span className="whitespace-nowrap">`payment.refund.succeeded`</span>       | Trạng thái chuyển sang `success`.                                                 |
| <span className="whitespace-nowrap">`payment.refund.failed`</span>          | Trạng thái chuyển sang `failed`.                                                  |
| <span className="whitespace-nowrap">`payment.refund.canceled`</span>        | Trạng thái chuyển sang `cancelled`.                                               |
| <span className="whitespace-nowrap">`payment.refund.action_required`</span> | Trạng thái chuyển sang `actionNeeded`.                                            |

Tạo khoản hoàn tiền ở trạng thái không phải đang chờ cũng có thể gửi sự kiện trạng thái tương ứng. Một khoản hoàn tiền thành công tự nó không mô tả trạng thái cuối cùng của toàn bộ khoản thanh toán: hãy kiểm tra `data.payment.status` và mọi thông báo `payment.refunded` riêng biệt.

## Merchant [#merchants]

Sự kiện merchant chứa `data.merchant` với `id`, `token` và bản lưu trạng thái merchant đã lưu.

| Sự kiện                                                              | Thời điểm gửi                                                                                                                                                |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <span className="whitespace-nowrap">`merchant.created`</span>        | Một merchant được tạo trong tổ chức của bạn.                                                                                                                 |
| <span className="whitespace-nowrap">`merchant.status_changed`</span> | Có thay đổi về kích hoạt, trạng thái bản ghi merchant cơ bản, sự hiện diện của hồ sơ hoặc tài khoản, việc gửi hồ sơ, phê duyệt hay từ chối tại đơn vị xử lý. |

```json title="data"
{
  "merchant": {
    "id": "019a0000-0000-7000-8000-000000000005",
    "token": "example_merchant_token",
    "status": {
      "isActive": true,
      "isShellMerchant": false,
      "profileOnboarded": true,
      "processors": [
        {
          "paymentProcessorId": 2,
          "hasAccount": true,
          "submitted": true,
          "approved": true,
          "rejected": false,
          "submittedAt": "2026-10-29T10:00:00+00:00",
          "approvedAt": "2026-10-30T12:00:00+00:00",
          "rejectedAt": null
        }
      ]
    }
  }
}
```

* `profileOnboarded` có nghĩa là hồ sơ tồn tại. Điều này không có nghĩa đơn vị xử lý đã phê duyệt merchant hoặc mọi phương thức thanh toán đều sẵn sàng.
* Payload không bao gồm mã định danh tài khoản tại đơn vị xử lý và thông báo từ chối riêng tư của đơn vị xử lý. ID đơn vị xử lý ở trên chỉ có tính minh họa.
* Cập nhật các giá trị không thay đổi hoặc chỉnh sửa thông tin merchant không liên quan không gửi sự kiện nào. Không có sự kiện `merchant.updated` hay sự kiện xóa merchant.

## Onboarding merchant [#merchant-onboarding]

Sự kiện onboarding chứa `data.onboarding`. `status` của đối tượng này khớp với phần cuối của tên sự kiện, và một số sự kiện bổ sung các trường được nêu bên dưới.

| Sự kiện                                                                                | Thời điểm gửi                                                                                                                           |
| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| <span className="whitespace-nowrap">`merchant.onboarding.started`</span>               | Hồ sơ merchant đầu tiên và dữ liệu onboarding được lưu.                                                                                 |
| <span className="whitespace-nowrap">`merchant.onboarding.profile_completed`</span>     | Hồ sơ merchant đầy đủ đầu tiên được lưu.                                                                                                |
| <span className="whitespace-nowrap">`merchant.onboarding.document_added`</span>        | Một tài liệu mới được lưu. Bổ sung `documentId`, `documentTypeId`, `paymentProcessorId` và `source: "cache"` cho tài liệu được lưu tạm. |
| <span className="whitespace-nowrap">`merchant.onboarding.stakeholder_completed`</span> | Dữ liệu onboarding của một bên liên quan được hoàn thành. Bổ sung `stakeholderId`.                                                      |
| <span className="whitespace-nowrap">`merchant.onboarding.submitted`</span>             | Onboarding đã sẵn sàng để gửi đến một đơn vị xử lý. Bổ sung `paymentProcessorId`.                                                       |
| <span className="whitespace-nowrap">`merchant.onboarding.approved`</span>              | Một tài khoản tại đơn vị xử lý được phê duyệt lần đầu tiên. Bổ sung `paymentProcessorId`.                                               |
| <span className="whitespace-nowrap">`merchant.onboarding.rejected`</span>              | Tapaya từ chối onboarding sau khi xét duyệt thủ công. Bổ sung `reason`, với `requiredAction` được đặt thành `null`.                     |
| <span className="whitespace-nowrap">`merchant.onboarding.action_required`</span>       | Tapaya yêu cầu thêm thông tin sau khi xét duyệt thủ công. Bổ sung `reason` và `requiredAction`.                                         |

```json title="data"
{
  "onboarding": {
    "status": "action_required",
    "reason": "The submitted company document is no longer valid.",
    "requiredAction": "Upload a current company registration document."
  }
}
```

<Accordions>
  <Accordion title="Các trường hợp đặc biệt của từng sự kiện" id="onboarding-edge-cases">
    * Hiện tại, `profile_completed` đến cùng với `started`. Cả hai đều không có nghĩa đơn vị xử lý đã phê duyệt.
    * `document_added` chứa siêu dữ liệu, không chứa tệp. Chuyển tài liệu đã lưu tạm sang đơn vị xử lý không gửi lại sự kiện này.
    * `stakeholder_completed` cũng bao gồm việc hoàn thành qua lời mời. Lưu lặp lại cùng dữ liệu hoàn thành không gửi lại sự kiện này.
    * `submitted` là thông báo về mức độ sẵn sàng; sự kiện này không xác nhận rằng yêu cầu đã đến đơn vị xử lý. Không có sự kiện `merchant.onboarding.ready` riêng biệt.
    * `approved` được gửi theo từng đơn vị xử lý. Phê duyệt của một đơn vị xử lý không đồng nghĩa với phê duyệt của tất cả các đơn vị xử lý.
    * `rejected` và `action_required` chỉ xuất phát từ việc xét duyệt thủ công của Tapaya, không bao giờ trực tiếp từ đơn vị xử lý thanh toán. Lặp lại cùng một quyết định không gửi sự kiện mới, danh tính người xét duyệt không được cung cấp và quyết định không thay đổi cờ phê duyệt của đơn vị xử lý.
  </Accordion>
</Accordions>

Sự kiện onboarding và trạng thái merchant mô tả các khía cạnh khác nhau của một thay đổi. Cùng một hồ sơ được lưu hoặc phê duyệt của đơn vị xử lý có thể tạo ra cả hai nhóm sự kiện khi bạn đăng ký cả hai; không giả định thứ tự giữa chúng. Sự kiện không được bổ sung hồi tố cho hoạt động onboarding trước đây.

## Kiểm tra chẩn đoán [#diagnostic-tests]

Sử dụng thao tác kiểm tra của Platform để gửi `webhook.test`. Sự kiện này bao gồm `test: true`, `merchantId: null` và `data.message`, không có trạng thái thanh toán hay merchant. Không thể chọn sự kiện này làm đăng ký sự kiện.

Xem [Xác thực và kiểm tra](/webhooks/receiving#send-a-test-webhook) để kiểm tra việc gửi mà không tạo khoản thanh toán.