> For the complete documentation index, see [llms.txt](https://docs.loomgate.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.loomgate.io/webhooks/webhook-events.md). # Danh sách sự kiện Các loại sự kiện webhook, khi nào chúng được gửi và payload mẫu. Mọi webhook có cùng dạng: ```json { "id": "evt_…", "object": "event", "type": "payment_intent.succeeded", "created": 1790000000, "data": { "object": { } } } ``` `created` là unix giây; `data.object` là đối tượng tại thời điểm xảy ra sự kiện, cùng dạng với API trả về. | Sự kiện | `data.object` | Khi nào | Nên làm | | -------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------- | | `payment_intent.succeeded` | [payment\_intent](/api-reference/payment-intents.md) | Payment thu tiền thành công | Đánh dấu đơn đã thanh toán, giao hàng | | `payment_intent.canceled` | payment\_intent | Payment bị hủy, không thể thanh toán tiếp | Hủy đơn hoặc tạo payment mới nếu người mua vẫn muốn trả | | `refund.succeeded` | [refund](/api-reference/refunds.md) | Refund đã hoàn xong | Ghi nhận hoàn tiền, báo người mua | | `refund.failed` | refund | Refund đã tạo nhưng không hoàn được | Kiểm tra, hoàn lại bằng request mới nếu cần | | `adjustment.created` | adjustment | Loomgate ghi một khoản điều chỉnh vào số dư (ví dụ khiếu nại từ ngân hàng) | Đối soát kế toán | | `unlock_step.available` | unlock\_step | Một mốc tiền của payment vừa chuyển sang số dư khả dụng (chỉ khi mốc còn tiền) | Đối soát số dư khả dụng | {% hint style="info" %} Khi lệnh tạo refund bị từ chối ngay (lỗi trong response), `refund.failed` chỉ được gửi nếu request có `Idempotency-Key`: khi đó một request trùng key chạy song song có thể đã nhận refund ở trạng thái `pending`. {% endhint %} ## payment\_intent.succeeded ```json { "id": "evt_9fK2mQ7xR4tL1vB8nC3d", "object": "event", "type": "payment_intent.succeeded", "created": 1790000125, "data": { "object": { "id": "lg_pi_4Qx9ZcM2LwT8rKv1bN3a", "object": "payment_intent", "status": "succeeded", "currency": "usd", "amount": 10000, "fee_buyer": 320, "amount_total": 10320, "processing_fee": 290, "bank_fee": 30, "fee_bearer": "buyer", "amount_refunded": 0, "amount_refundable": 10000, "confirmation_attempts": 1, "description": null, "metadata": { "order_id": "1042" }, "order_reference": "1042", "goods_type": "physical", "buyer": { "name": "Jane Doe" }, "shipping_details": { "name": "Jane Doe", "phone": null, "address": { "line1": "1 Market St", "line2": null, "city": "San Francisco", "state": "CA", "postal_code": "94105", "country": "US" } }, "items": [{ "name": "T-shirt", "quantity": 2, "unit_amount": 4500, "amount": 9000 }], "shipping_amount": 1000, "tax_amount": 0, "discount_amount": 0, "items_difference": 0, "billing_details": { "email": "buyer@example.com", "name": "Jane Doe", "address": { "line1": "1 Market St", "line2": null, "city": "San Francisco", "state": "CA", "postal_code": "94105", "country": "US" } }, "created": 1790000000, "succeeded_at": 1790000120, "unlock_schedule": [ { "step": 1, "days": 14, "percent_bps": 8000, "available_at": 1791210600, "amount": 8000, "deducted": 0, "remaining": 8000, "rescheduled": false }, { "step": 2, "days": 30, "percent_bps": 2000, "available_at": 1792593000, "amount": 2000, "deducted": 0, "remaining": 2000, "rescheduled": false } ] } } } ``` Webhook không chứa `client_secret`. Người mua chịu phí nên payment mang về cho bạn đúng `amount` (10320 − 290 − 30 = 10000), chia theo lịch mở khóa ví dụ 80 % sau 14 ngày và 20 % sau 30 ngày; xem [Số dư và giờ mở khóa](/concepts/balance.md). ## refund.succeeded ```json { "id": "evt_2hD8sP5wK1yN6qZ3tF9g", "object": "event", "type": "refund.succeeded", "created": 1790100300, "data": { "object": { "id": "lg_re_8Hs2PzQ1YtR5nWc7mK0d", "object": "refund", "payment_intent": "lg_pi_4Qx9ZcM2LwT8rKv1bN3a", "amount": 2500, "refund_fee": 25, "status": "succeeded", "reason": "requested_by_customer", "created": 1790100000 } } } ``` ## adjustment.created ```json { "id": "evt_6mV3cX8bN2kJ7pL4rT1q", "object": "event", "type": "adjustment.created", "created": 1790500000, "data": { "object": { "id": "adj_7Tn2KqL9WmX4cV8bR1sD", "object": "adjustment", "currency": "usd", "amount": -1500, "reason": "Chargeback for order 1042", "payment_intent": "lg_pi_4Qx9ZcM2LwT8rKv1bN3a", "created": 1790500000 } } } ``` `amount` có dấu: âm là trừ vào số dư của bạn, dương là cộng. `payment_intent` là `null` khi khoản điều chỉnh không gắn với payment nào. ## unlock\_step.available ```json { "id": "evt_3sR7vB2nK9qL5xM1cT8w", "object": "event", "type": "unlock_step.available", "created": 1791210601, "data": { "object": { "object": "unlock_step", "payment_intent": "lg_pi_4Qx9ZcM2LwT8rKv1bN3a", "currency": "usd", "step": 1, "days": 14, "percent_bps": 8000, "available_at": 1791210600, "amount": 8000, "deducted": 2525, "remaining": 5475 } } } ``` Gửi một lần cho mỗi mốc, khi tiền của mốc thực sự chuyển sang `available`. `remaining` là số vừa vào số dư khả dụng: ở ví dụ, refund 2500 kèm phí 25 ở trên đã trừ vào mốc 1 vì mốc này còn khóa lúc hoàn tiền. Mốc không còn tiền (đã hoàn hết) không gửi sự kiện này. Khi Loomgate đổi giờ mở khóa của một mốc, không có webhook riêng: sự kiện được gửi khi mốc mở khóa theo giờ mới. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.loomgate.io/webhooks/webhook-events.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.