> 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/concepts/payment-details.md). # Chi tiết giao dịch Mặt hàng, người mua, mã đơn hàng, địa chỉ giao hàng, loại hàng hóa và dữ liệu thiết bị. Mỗi payment cho biết nó trả cho cái gì, ai là người mua và hàng gửi đi đâu. Bạn khai báo các thông tin này; Loomgate dùng chúng để đối soát và phát hiện giao dịch bất thường. ## Các trường | Trường | Bắt buộc | Quy tắc | | -------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `items` | **Khi tạo** | 1–100 dòng `{ name, quantity, unit_amount }`. `name` 1–500 ký tự; `quantity` > 0, tối đa 3 chữ số thập phân, tối đa 1 000 000; `unit_amount` số nguyên đơn vị nhỏ nhất, 0–99 999 999 (0 = quà tặng) | | `shipping_amount`, `tax_amount`, `discount_amount` | Không | Số nguyên 0–99 999 999, mặc định 0 | | `goods_type` | Không | `physical` (mặc định) hoặc `non_physical` (hàng số, dịch vụ: không giao hàng) | | `buyer` | **Trước khi người mua trả** | `{ name }`, 1–200 ký tự | | `order_reference` | **Trước khi người mua trả** | Mã đơn hàng của bạn, 1–100 ký tự. Không cần duy nhất (nhiều payment có thể cùng một đơn) | | `shipping_details` | **Trước khi người mua trả**, nếu `physical` | `{ name, phone?, address: { line1, line2?, city?, state?, postal_code?, country } }`. Bắt buộc `name` (người nhận), `line1`, `country` (ISO 3166-1 alpha-2, ví dụ `US`). Chuỗi tối đa 200 ký tự, `postal_code` 20, `phone` 40 | `buyer`, `order_reference` và `shipping_details` có thể gửi ngay khi tạo payment, hoặc sau đó bằng [cập nhật payment](/api-reference/payment-intents.md) khi còn `pending`. Nếu đến lúc xác nhận mà vẫn thiếu, API trả `400 payment_details_missing` (`param` là trường đầu tiên còn thiếu), không gửi gì đi và không tính là một lần thử. Việc hiện form thẻ thì không cần các trường này. ## Mặt hàng chỉ mô tả, không quyết định số tiền Số tiền được tính phí, thu và hoàn luôn là `amount`. API không từ chối khi các dòng hàng cộng lại khác `amount`, chỉ báo độ lệch: ``` items_difference = amount − (tổng amount các dòng + shipping_amount + tax_amount − discount_amount) ``` Trong response, mỗi dòng có thêm `amount` = `unit_amount × quantity`, làm tròn nửa lên một lần. Ví dụ: `quantity: 1.5`, `unit_amount: 3333` → `amount: 5000`. | Khai báo | Giá trị | | -------------------- | ------- | | 2 × áo thun giá 4500 | 9000 | | `shipping_amount` | 1000 | | `amount` | 10000 | | `items_difference` | 0 | ## Cập nhật * Mỗi trường gửi lên **thay nguyên** giá trị cũ (`items` thay cả danh sách). Gửi `null` cho `buyer`, `order_reference`, `shipping_details` để xóa. * Sửa chi tiết giao dịch không làm form thẻ đang hiện phải tải lại. * Đổi `currency` thì phải gửi lại `items` trong cùng request (giá theo tiền tệ mới), và cả `shipping_amount` / `tax_amount` / `discount_amount` nếu giá trị đang lưu khác 0. * Sai định dạng trả `400 invalid_payment_details` với `param` chỉ đúng vị trí, ví dụ `items[0].quantity`. Trường lạ trả `validation_error`. ## Hàng phi vật lý `goods_type: "non_physical"` chỉ dùng được khi tài khoản của bạn được phép bán hàng phi vật lý (mặc định: không). Loomgate hoặc đại lý của bạn bật quyền này; xem trạng thái trong mục **Cài đặt**. Chưa được phép thì tạo, sửa và xác nhận payment loại này đều trả `non_physical_goods_not_allowed`. Hàng phi vật lý không bắt buộc `shipping_details` (gửi kèm vẫn được). ## Dữ liệu thiết bị và quyền riêng tư Khi form thẻ được tải và khi người mua xác nhận, `loomgate.js` thu thông tin về trình duyệt và thiết bị (múi giờ, ngôn ngữ, màn hình, hệ điều hành và trình duyệt, phần cứng, dấu hiệu trình duyệt tự động, mã bam canvas / WebGL / âm thanh, font đã cài) cùng địa chỉ trang; Loomgate ghi thêm địa chỉ IP và User-Agent. Dữ liệu này dùng để chống gian lận và không bao giờ có trong API hay webhook trả về cho bạn. {% hint style="warning" %} Chính sách quyền riêng tư của bạn phải nêu việc thông tin thiết bị của người mua được thu thập để chống gian lận. {% endhint %} Trong dashboard, trang chi tiết giao dịch hiện nguồn tạo payment, các lần tải form và các lần thử thanh toán kèm tóm tắt thiết bị (IP, trình duyệt, hệ điều hành, múi giờ, ngôn ngữ). --- # 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/concepts/payment-details.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.