Tham chiếu API

Mọi endpoint dưới đây nói JSON, sống dưới https://api.infraio.xyz (prod) hoặc https://api-dev.infraio.xyz (test), và xác thực qua HMAC-SHA256 — xem Xác thực cho thao tác ký và Lỗi cho hình dáng error envelope.

Trang này là index. Mỗi row link đến write-up sâu nhất đang tồn tại; nếu một row chỉ tham chiếu một path, endpoint tồn tại hôm nay nhưng được tài liệu hóa inline trong trang khái niệm liên quan thay vì trang tham chiếu riêng.

Path prefix gateway và mô hình auth của chúng:

/b2b/v1/* — ký HMAC với khóa secret của bạn (sk_…). Surface backend merchant.
/payment/v1/* — Bearer JWT (session dashboard). Dùng bởi frontend dashboard merchant; không phải cho integrator bên thứ ba.
/pub/v1/* — Bearer-of-truth trong path (một token rfqt_… cho refund request). Không creds. An toàn để gọi từ trình duyệt.
/checkout/:key/* — Prefix public cho luồng checkout do hệ thống host. key là session key cst_… trả về tại thời điểm tạo; trình duyệt của người mua là caller duy nhất. Không creds.

Checkout

Method	Path	Mục đích	Ghi chú
`POST`	`/b2b/v1/checkout-sessions/quick`	Tạo session trong một lệnh — order + checkout-session được mint cùng nhau.	Xem Bắt đầu nhanh cho request body và sample.
`POST`	`/b2b/v1/checkout-sessions`	Tạo session ứng với order đã có. Dùng khi platform của bạn đã có mô hình order riêng và bạn muốn một session cho mỗi lần thử.	Luồng hai bước.
`GET`	`/b2b/v1/checkout-sessions/by-order/{order_id}`	Liệt kê mọi session từng được mint cho một order.	Hữu ích khi người mua từ bỏ session và bạn muốn surface các lần thử trước trong dashboard của mình.
`GET`	`/checkout/{session_key}`	Public — trang checkout do hệ thống host fetch endpoint này. Chỉ các trường buyer-facing (không có reference nội bộ).	Không ký; lấy `session_key` làm bearer-of-truth.
`POST`	`/checkout/{session_key}/intent`	Public — chọn phương thức thanh toán trên trang do hệ thống host. Phát `PaymentIntent` với địa chỉ deposit.	Được checkout-web gọi khi user chọn phương thức.
`POST`	`/checkout/{session_key}/verify`	Public — cho phép người mua paste tx hash để ngắn mạch chờ confirmation.	Fall-through đến chain watcher nếu hash sai.

Orders

Order là entity tính phí trường tồn. Một order có thể đứng sau nhiều checkout session (ví dụ người mua từ bỏ, retry).

Method	Path	Mục đích	Ghi chú
`POST`	`/b2b/v1/orders`	Tạo order mà không có session.	Dùng khi bạn muốn gửi cho người mua một payment link sau này thay vì redirect họ ngay.
`GET`	`/b2b/v1/orders/{id}`	Đọc một order với line items + trạng thái.	Trạng thái: `PENDING` → `PAID` \| `PARTIAL_PAID` \| `CANCELED`. Sau refund: `PARTIALLY_REFUNDED` \| `REFUNDED`.
`GET`	`/b2b/v1/orders/by-merchant/{merchant_id}`	Liệt kê order của bạn, cursor-paginated.	Xem Cursor pagination cho protocol cursor.
`PATCH`	`/b2b/v1/orders/{id}/cancel`	Đánh dấu một order chưa thanh toán là canceled. Phát `order.canceled`.	Fail nếu order đã thanh toán.
`PATCH`	`/b2b/v1/orders/{id}/reopen`	Đảo ngược một auto-cancel (`canceled_reason=payment_timeout`).	Hữu ích nếu người mua quay lại sau khi TTL hết.

Refunds

Xem trang khái niệm Hoàn tiền cho luồng saga và vòng đời token.

Merchant khởi tạo

Method	Path	Mục đích	Ghi chú
`POST`	`/b2b/v1/merchants/{merchant_id}/refunds`	Refund do merchant khởi tạo. Auto-approve (bỏ qua `PENDING`).	Phát `payment.refund.approved` ngay lập tức.

Khách hàng khởi tạo — token refund-request

Người mua điền form refund trên trang do hệ thống host của chúng tôi; bạn chỉ phát hành token và giao URL. Hai path phát hành (HMAC cho backend, JWT cho dashboard), ba path token public (đọc context, submit, yêu cầu renewal), và hai path chỉ dashboard để xử lý renewal.

Method	Path	Auth	Mục đích
`POST`	`/b2b/v1/merchants/{merchant_id}/refund-requests`	HMAC (`sk_…`)	Phát hành token từ backend của bạn. Body: `{ref_type, ref_value, amount, ttl_seconds?, metadata?, hide_summary?, hide_header?}`. `ref_type` là một trong `order_id` / `order_number` / `session_id` / `session_key`; `ref_value` là định danh tương ứng. `amount` là bắt buộc và khóa số tối đa mà người mua có thể submit. TTL mặc định 30 phút. Phát `refund_request.created` (`source: b2b`).
`POST`	`/payment/v1/merchants/{merchant_id}/refund-requests`	JWT (dashboard)	Phát hành token từ modal Issue Refund của dashboard merchant. Cùng cấu trúc body như biến thể B2B. TTL mặc định 24 h. Phát `refund_request.created` (`source: dashboard`).
`GET`	`/pub/v1/refund-requests/{token}`	Token trong path	Public — checkout-web đọc context form (tóm tắt order, amount bị khóa, trạng thái hiệu lực hiện tại).
`POST`	`/pub/v1/refund-requests/{token}/submit`	Token trong path	Public — người mua submit form. Body: `{reason, refund_to_address, amount?, metadata?}`. `amount` là tùy chọn — khi bỏ qua, dùng amount của link bị merchant khóa; khi có, server enforce `amount ≤ amount bị khóa`. Tạo row `Refund`, phát `payment.refund.requested`, trả về `{link_token, refund_id}` cho trang receipt.
`POST`	`/pub/v1/refund-requests/{token}/request-renewal`	Token trong path	Public — người mua yêu cầu link mới sau khi hết hạn. Body: `{customer_note?}`. Phát `refund_request.renewal_requested`.
`GET`	`/payment/v1/merchants/{merchant_id}/refund-requests/renewals`	JWT (dashboard)	Liệt kê các token `RENEWAL_REQUESTED` pending cho widget renewal của merchant. Cursor-paginated.
`POST`	`/payment/v1/merchants/{merchant_id}/refund-requests/renewals/{token}/issue-new`	JWT (dashboard)	Approve một renewal — phát hành một token `ACTIVE` mới, retire cái cũ. Phát `refund_request.renewed` + `refund_request.created` (`source: renewal`).
`GET`	`/payment/v1/merchants/{merchant_id}/refund-requests/by-order/{order_id}`	JWT (dashboard)	Liệt kê mọi token refund-request từng được phát hành ứng với một order với trạng thái hiệu lực. Mới nhất trước.
`POST`	`/payment/v1/merchants/{merchant_id}/refund-requests/{token}/send-email`	JWT (dashboard)	Xếp hàng đợi gửi email link refund-request đến khách hàng. Body: `{to}`. Phát `refund_request.email_send_requested`.
`POST`	`/payment/v1/merchants/{merchant_id}/refund-requests/{token}/cancel`	JWT (dashboard)	Kill-switch của merchant — flip `ACTIVE` hoặc `RENEWAL_REQUESTED` → `CANCELED`. Body: `{reason?}`. Idempotent: lệnh gọi thứ hai sau khi trạng thái đã chuyển trả về success mà không phát lại event. Phát `refund_request.canceled` trên transition đầu tiên.

Vòng đời refund (sau khi tạo)

Áp dụng cho cả hai luồng. Các endpoint bên dưới thao tác trên row Refund (id bắt đầu rfn_…), không phải request token.

Method	Path	Mục đích	Ghi chú
`GET`	`/b2b/v1/refunds/{id}`	Đọc một refund.	Trạng thái: `PENDING` → `APPROVED` → `EXECUTED` \| `REJECTED`.
`GET`	`/b2b/v1/refunds/by-merchant/{merchant_id}`	Liệt kê refund của bạn, cursor-paginated.	—
`POST`	`/b2b/v1/refunds/{id}/approve`	Approve một refund `PENDING` (chỉ do khách hàng khởi tạo — do merchant khởi tạo đã ở `APPROVED`).	Crypto: vào `APPROVED`, bạn gọi `/submit-tx` tiếp theo.
`POST`	`/b2b/v1/refunds/{id}/reject`	Từ chối một refund `PENDING`.	Phát `payment.refund.rejected`.
`POST`	`/b2b/v1/refunds/{id}/submit-tx`	Chỉ crypto — đóng dấu tx hash on-chain bạn đã broadcast.	Body: `{tx_hash, network, token_address}` — cả ba bắt buộc.

Catalog (chỉ đọc)

Method	Path	Mục đích
`GET`	`/v1/supported/networks`	Mọi chain InfraIO có thể settle (mainnet + testnet, được filter theo env).
`GET`	`/v1/supported/tokens`	Mọi stablecoin trên các chain đó.
`GET`	`/v1/supported/currencies`	Fiat currency được chấp nhận cho `order.currency`.
`GET`	`/v1/merchants/payment-methods`	Phương thức MÀ merchant này đã enable — kết hợp của catalog platform + toggle theo từng merchant. Dùng bởi checkout-web.
`GET`	`/v1/public/merchants/{merchant_id}/branding`	Public — những gì trang checkout đọc để skin chính nó.

Health

Method	Path	Auth	Mục đích
`GET`	`/health`	Không (public)	Probe liveness đơn giản — trả về `{"status":"ok"}`. Cái này (không có prefix `/v1`) là endpoint health không cần auth duy nhất — point k8s / uptime monitor của bạn ở đây.
`GET`	`/payment/v1/merchants/{merchant_id}/health`	Dashboard JWT	Health view theo từng merchant — tỷ lệ settlement intent gần đây, sweep backlog. Hữu ích cho status page của riêng bạn. Yêu cầu token session dashboard, không phải API key B2B. Chỉ reachable dưới prefix gateway `/payment/` — path trần `/v1/...` không được route công khai.
`GET`	`/payment/v1/stats/health`	Dashboard JWT	Health tổng hợp trên cây workspace của một merchant. Không phải probe liveness public — nó nằm sau cùng auth JWT dưới prefix gateway `/payment/`.

Cursor pagination

Mọi endpoint list chấp nhận cùng các query param, trả về cùng envelope. Chúng tôi dùng cursor opaque (base64url-encoded (created_at, id)) thay vì offset để một trang không bao giờ shift khi một row vào ở giữa scroll.

Query param	Type	Mặc định	Ghi chú
`cursor`	`string`	—	Opaque — copy `next_cursor` nguyên văn từ response trước.
`limit`	`int`	`20`	`1..100`.
`sort_dir`	`'asc' \| 'desc'`	`desc`	Sort theo `(created_at, id)`.
`from` / `to`	`RFC3339`	—	Filter cửa sổ thời gian tùy chọn.
`search`	`string`	—	Filter tự do nơi được hỗ trợ.

Envelope response:


{
  "orders": [ /* page rows */ ],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0...",
  "has_next": true
}

has_next luôn có mặt. next_cursor bị bỏ qua khi has_next là false. Đừng cố parse cursor — hình dáng của nó là nội bộ và sẽ thay đổi.

Thiếu gì trên trang này

Index này cover surface hướng merchant — endpoint dưới /admin/* (tool dashboard, review KYB, quản lý network) và route gRPC nội bộ được chủ ý không liệt kê. Spec OpenAPI sinh bởi swag cover toàn bộ surface; nếu bạn cần nó, ping support và chúng tôi sẽ chia sẻ snapshot hiện tại.