Loại sự kiện

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; trang này cho biết mỗi nhóm sự kiện đặt gì bên trong data.

Nhóm sự kiện

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

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.

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:

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

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.

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

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

{
  "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

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.

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

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

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 để kiểm tra việc gửi mà không tạo khoản thanh toán.