> 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/api-reference.md).

# Tham chiếu API

Base URL, xác thực, định dạng, phân trang, idempotency và giới hạn tần suất.

## Base URL

```
https://api.loomgate.io
```

Mọi route của API tích hợp nằm dưới `/partner/v1`, ví dụ `POST https://api.loomgate.io/partner/v1/payment_intents`.

| Nhóm route                     | Xác thực                                                       | Gọi từ                               |
| ------------------------------ | -------------------------------------------------------------- | ------------------------------------ |
| `/partner/v1/*` (trừ `client`) | `Authorization: Bearer sk_live_…`                              | Máy chủ của bạn                      |
| `/partner/v1/client/*`         | `Authorization: Bearer pk_live_…` + `client_secret` trong body | Trình duyệt, thông qua `loomgate.js` |

Xem [Khóa API và xác thực](/getting-started/api-keys.md).

## Định dạng

* Request có body gửi JSON với `Content-Type: application/json`. Response luôn là JSON.
* Tên trường dạng `snake_case`. Thời gian là unix giây. Số tiền là số nguyên đơn vị nhỏ nhất.
* Mỗi đối tượng có `object` cho biết loại (`payment_intent`, `refund`, `list`…).
* Hãy bỏ qua các trường bạn không dùng trong response, để code không hỏng khi API bổ sung trường mới. Trường lạ trong **request** thì bị từ chối (`validation_error`).
* `metadata`: tối đa 50 khóa (mỗi khóa tối đa 40 ký tự), giá trị là chuỗi tối đa 500 ký tự. Metadata chỉ lưu ở Loomgate, không gửi cho bên nào khác.

## Phân trang

Các route danh sách trả mới nhất trước:

```json
{ "object": "list", "data": [ … ], "has_more": true }
```

| Tham số          | Nghĩa                             |
| ---------------- | --------------------------------- |
| `limit`          | 1–100, mặc định 20                |
| `starting_after` | `id` của phần tử cuối trang trước |

Lặp lại với `starting_after` là `id` cuối cùng cho tới khi `has_more` là `false`.

## Idempotency

`POST /partner/v1/payment_intents` và `POST /partner/v1/refunds` nhận header `Idempotency-Key` (1–255 ký tự) để thử lại an toàn:

* Cùng key, cùng body → trả lại kết quả của request đầu, không tạo gì mới (payment: cùng `id` và `client_secret`).
* Cùng key, body khác → `409 idempotency_key_reused`.
* Key thuộc về tài khoản của bạn, dùng chung giữa hai route và không hết hạn: đặt tiền tố khác nhau (`order-…`, `refund-…`).
* Request kết thúc bằng lỗi không lưu gì; gửi lại cùng key sẽ chạy lại.

## Giới hạn tần suất

| Phạm vi                                    | Giới hạn                                                   |
| ------------------------------------------ | ---------------------------------------------------------- |
| Route máy chủ (secret key)                 | 1200 request/phút cho mỗi tài khoản, tính riêng từng route |
| Xác thực sai ở route máy chủ               | 300 lần/phút cho mỗi địa chỉ IP                            |
| Route trình duyệt (`/partner/v1/client/*`) | 60 request/phút cho mỗi địa chỉ IP, tính riêng từng route  |
| Lần thử thanh toán                         | Xem [Payment và trạng thái](/concepts/payments.md)         |

Vượt giới hạn trả `429 rate_limited` kèm header `Retry-After` (giây). Chờ đúng số giây đó rồi thử lại.

## Tiền tố ID

| Tiền tố  | Đối tượng        |
| -------- | ---------------- |
| `lg_pi_` | Payment intent   |
| `lg_cs_` | Client secret    |
| `lg_re_` | Refund           |
| `adj_`   | Khoản điều chỉnh |
| `evt_`   | Sự kiện webhook  |
| `we_`    | Webhook endpoint |

## Các trang tham chiếu

| Trang                                                          | Route                                          |
| -------------------------------------------------------------- | ---------------------------------------------- |
| [Payment intents](/api-reference/payment-intents.md)           | Tạo, đọc, liệt kê, cập nhật, xác nhận, release |
| [Refunds](/api-reference/refunds.md)                           | Hoàn tiền, đọc, liệt kê                        |
| [Fee quotes](/api-reference/fee-quotes.md)                     | Tính phí trước                                 |
| [Balance](/api-reference/balance.md)                           | Số dư                                          |
| [Webhook signing keys](/api-reference/webhook-signing-keys.md) | Khóa công khai xác minh webhook                |
| [Client API](/api-reference/client.md)                         | Route trình duyệt mà `loomgate.js` dùng        |
| [Mã lỗi](/api-reference/errors.md)                             | Định dạng lỗi và danh sách mã                  |


---

# 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/api-reference.md?ask=<question>&goal=<endgoal>
```

`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.