> 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/en/concepts/payment-details.md). # Payment details Items, buyer, order reference, shipping address, goods type and device data. Each payment states what it pays for, who the buyer is and where the goods are shipped. You provide these details; Loomgate uses them for reconciliation and to detect unusual transactions. ## Fields | Field | Required | Rules | | -------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `items` | **On create** | 1–100 lines `{ name, quantity, unit_amount }`. `name` 1–500 characters; `quantity` > 0, up to 3 decimal places, at most 1,000,000; `unit_amount` an integer in the smallest unit, 0–99,999,999 (0 = free gift) | | `shipping_amount`, `tax_amount`, `discount_amount` | No | Integer 0–99,999,999, default 0 | | `goods_type` | No | `physical` (default) or `non_physical` (digital goods, services: nothing is shipped) | | `buyer` | **Before the buyer pays** | `{ name }`, 1–200 characters | | `order_reference` | **Before the buyer pays** | Your order reference, 1–100 characters. Doesn't have to be unique (several payments can belong to the same order) | | `shipping_details` | **Before the buyer pays**, if `physical` | `{ name, phone?, address: { line1, line2?, city?, state?, postal_code?, country } }`. `name` (the recipient), `line1` and `country` (ISO 3166-1 alpha-2, for example `US`) are required. Strings up to 200 characters, `postal_code` 20, `phone` 40 | `buyer`, `order_reference` and `shipping_details` can be sent when you create the payment, or later by [updating the payment](/en/api-reference/payment-intents.md) while it is still `pending`. If they are still missing at confirmation, the API returns `400 payment_details_missing` (`param` is the first missing field), sends nothing and does not count an attempt. Showing the card form does not require these fields. ## Items describe the payment, they don't set the amount The amount that fees are charged on, that is collected and that is refunded is always `amount`. The API does not reject line items that don't add up to `amount`; it only reports the difference: ``` items_difference = amount − (sum of line amounts + shipping_amount + tax_amount − discount_amount) ``` In the response, each line also has `amount` = `unit_amount × quantity`, rounded half up once. Example: `quantity: 1.5`, `unit_amount: 3333` → `amount: 5000`. | Declared | Value | | ----------------------- | ----- | | 2 × T-shirt priced 4500 | 9000 | | `shipping_amount` | 1000 | | `amount` | 10000 | | `items_difference` | 0 | ## Updating * Each field you send **replaces** the old value in full (`items` replaces the whole list). Send `null` for `buyer`, `order_reference` or `shipping_details` to clear it. * Changing the payment details does not make a card form that is already shown reload. * Changing `currency` requires sending `items` again in the same request (priced in the new currency), and also `shipping_amount` / `tax_amount` / `discount_amount` if their stored value is not 0. * Invalid values return `400 invalid_payment_details` with `param` pointing to the exact location, for example `items[0].quantity`. Unknown fields return `validation_error`. ## Non-physical goods `goods_type: "non_physical"` can only be used when your account is allowed to sell non-physical goods (default: not allowed). Loomgate or your reseller enables this permission; see its status in the **Cài đặt** (Settings) section. Without it, creating, updating and confirming such payments all return `non_physical_goods_not_allowed`. Non-physical goods don't require `shipping_details` (you can still send them). ## Device data and privacy When the card form loads and when the buyer confirms, `loomgate.js` collects information about the browser and device (time zone, languages, screen, operating system and browser, hardware, signs of an automated browser, canvas / WebGL / audio hashes, installed fonts) along with the page URL; Loomgate also records the IP address and User-Agent. This data is used to prevent fraud and is never included in API responses or webhooks sent to you. {% hint style="warning" %} Your privacy policy must state that buyer device information is collected to prevent fraud. {% endhint %} In the dashboard, the payment detail page shows where the payment was created from, the form loads and the payment attempts, each with a device summary (IP, browser, operating system, time zone, language). --- # 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/en/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.