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 việc ký request và Lỗi cho hình dáng error envelope.

Trang này liệt kê các endpoint cho tích hợp merchant. Nếu một endpoint không có trang riêng, nó được mô tả trong trang khái niệm liên quan.

Các endpoint dưới /b2b/v1/* được ký HMAC với khóa secret (sk_…) của bạn. Đây là surface mà backend của bạn gọi. Dashboard merchant và trang checkout do hệ thống host dùng các endpoint riêng, không thuộc API tích hợp.

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.

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 link thanh toán 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. Bạn có thể phát hành token từ backend (bên dưới) hoặc từ dashboard merchant. Renewal và hủy được xử lý trong dashboard.

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

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 chính 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 Pay 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`	Currency được chấp nhận cho `order.currency`.

Health

Method	Path	Auth	Mục đích
`GET`	`/health`	Không (public)	Kiểm tra liveness. Trả về `{"status":"ok"}`. Point uptime monitor của bạn ở đây.

Cursor pagination

Mọi endpoint list chấp nhận cùng các query param, trả về cùng envelope. Cursor là opaque và được dùng thay vì offset, để một trang không bao giờ shift khi một row mới vào trong lúc bạn đang phân trang.

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. Hãy coi cursor là một chuỗi opaque.

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

Trang này cover các endpoint dành cho tích hợp merchant. Nếu bạn cần một endpoint không được liệt kê, hoặc một spec OpenAPI, hãy liên hệ support.