JavaScript / SDK trình duyệt

@lartech/infraio-checkout-js là SDK duy nhất chúng tôi phát hành cho đến nay. Nó chạy trong trình duyệt và mở checkout do hệ thống host. SDK backend (Node, Go, Python) nằm trong roadmap; cho đến lúc đó, hãy nói chuyện trực tiếp với gateway — xem Bắt đầu nhanh để có helper ký HMAC.

• Phiên bản hiện tại: 0.1.1-beta.17 (pre-1.0; có thể có thay đổi minor breaking)
• Định dạng: ESM (index.js), CJS (index.cjs), IIFE (index.global.js)
• Types được bundle (index.d.ts)
• Không có runtime peer — không React, jQuery, hay dependency khác

Cài đặt

npm install @lartech/infraio-checkout-js

pnpm add @lartech/infraio-checkout-js

yarn add @lartech/infraio-checkout-js

bun add @lartech/infraio-checkout-js

<script src="https://unpkg.com/@lartech/infraio-checkout-js/dist/index.global.js"></script>
<script>
  const sdk = await InfraIo.loadInfraIo("pk_live_yourkeyhere");
  sdk.checkout({ sessionId, checkoutUrl });
</script>

loadInfraIo(publicKey, options?)

Trả về Promise<InfraIoInstance>.

import { loadInfraIo } from "@lartech/infraio-checkout-js";
 
const sdk = await loadInfraIo("pk_live_yourkeyhere", {
  // Tùy chọn. Chỉ override khi trỏ đến môi trường không phải prod.
  checkoutUrl: "https://checkout-dev.infraio.xyz",
});

sdk.checkout({ … })

Mở checkout do hệ thống host. Trả về void (dùng callback cho trạng thái).

sdk.close()

Đóng programmatically popup hoặc embed đang mở. No-op cho chế độ redirect.

sdk.checkout({ sessionId, mode: "popup", /* … */ });
// sau đó, ví dụ khi người dùng điều hướng đi
sdk.close();

sdk.openRefundRequest({ … })

Mở form refund-request do hệ thống host cho một token dùng một lần mà backend của bạn đã phát hành qua POST /b2b/v1/merchants/{merchant_id}/refund-requests. Người mua điền địa chỉ đích refund + lý do + metadata (tùy chọn) trên trang của chúng tôi; trang của bạn chỉ xử lý vòng đời mở/đóng. Trả về một hàm close() — gọi nó để programmatically đóng popup hoặc detach embed iframe. Trong chế độ redirect, hàm trả về là no-op.

import { loadInfraIo } from "@lartech/infraio-checkout-js";
 
const sdk = await loadInfraIo("pk_live_yourkeyhere");
 
// Phát hành token phía server, rồi giao nó cho SDK trong trình duyệt.
const { token } = await fetch("/api/mint-refund-token", { method: "POST" }).then(r => r.json());
 
const close = sdk.openRefundRequest({
  token,
  mode: "popup",
  onSuccess: ({ linkToken, refundId }) => {
    // Người mua đã submit form.
    // linkToken → trang trạng thái /r/:linkToken (chia sẻ cho người mua).
    // refundId  → dùng với B2B API để approve / reject.
    window.location.href = `/r/${linkToken}`;
  },
  onCancel: () => { /* người mua đã đóng mà không submit */ },
});
 
// Đóng popup programmatically sau đó nếu cần:
// close();

Trạng thái token được surface qua onError

Nếu người mua mở một token đã cũ, bản thân trang xử lý hiển thị (render prompt “Expired — request new link”, v.v.), và SDK không phát onError cho các trường hợp đó — người mua đang ở trong luồng form và code của bạn không cần phản ứng. onError chỉ phát cho những thứ code của bạn có thể xử lý (args sai, network failure khi load iframe).

Class Error

import { InfraIoError } from "@lartech/infraio-checkout-js";
 
sdk.checkout({
  sessionId,
  onError: (err: InfraIoError) => {
    switch (err.code) {
      case "invalid_request_error":   /* sessionId / args sai */ break;
      case "iframe_load_error":       /* iframe load fail */ break;
      case "iframe_timeout_error":    /* vượt timeoutMs */ break;
      case "already_open_error":      /* một checkout khác đang mở */ break;
      case "network_error":           /* vấn đề mạng tạm thời với origin checkout */ break;
      case "api_error":               /* backend trả về non-2xx cho call do SDK phát */ break;
    }
  },
});

sdk.openRefundRequest() chỉ throw invalid_request_error (thiếu hoặc token / args không hợp lệ), đồng bộ. iframe_load_error (iframe refund-request load fail) được giao bất đồng bộ qua onError, không throw. Nó không phát iframe_timeout_error hay already_open_error — popup refund-request không có load-timeout và cho phép nhiều popup đồng thời.

Ghi chú chế độ

Popup

• Overlay căn giữa với backdrop nửa trong suốt tối
• z-index: 2147483647 (max int32) — nằm trên mọi thứ khác
• Cuộn body bị khóa khi mở; phục hồi khi đóng
• Nút close nhận focus ban đầu; Tab bị bẫy trong popup
• Đóng bởi: nút close, Escape, click bên ngoài, sdk.close(). Tất cả đều gọi onCancel
• Trang checkout có thể yêu cầu resize qua postMessage — SDK kẹp trong giới hạn width/height

Redirect

• Điều hướng cứng qua window.location.href
• Tự động nối thêm ?return_url=<current-page> để người mua quay về nơi họ đến. Nếu success_url / cancel_url trên session đã cover điều này, round-trip bỏ qua return_url

Embed

• iframe với allow="payment; clipboard-write" (chỉ thị HTML5 Feature Policy — không phải thuộc tính sandbox). iframe được serve từ origin checkout, nên popup ví và clipboard write từ phía người mua hoạt động mà không cần opt-in thêm.
• Container width 100%; height tự sizing qua postMessage INFRAIO_RESIZE, kẹp [200, 2000]px
• Không có CSS isolation ngoài biên iframe — style trang parent của bạn không bleed vào
• Luôn wire onReady để bạn có thể ẩn loading state của riêng mình khi checkout trở nên interactive

TypeScript

Tất cả types được bundle. Các export hữu ích nhất:

import type {
  CheckoutOptions,
  RefundRequestOptions,
  LoadOptions,
  InfraIoInstance,
  InfraIoErrorCode,
} from "@lartech/infraio-checkout-js";
import { loadInfraIo, InfraIoError, VERSION } from "@lartech/infraio-checkout-js";

VERSION là chuỗi phiên bản của SDK — hữu ích trong bug report.

Tiếp theo

• Wrapper framework React / Vue — đang được lên kế hoạch cho lần lặp post-launch khi surface vanilla JS ổn định qua các merchant pilot. SDK vanilla hoạt động ổn trong React hôm nay; các wrapper sẽ chỉ loại bỏ phần useRef thủ công + vòng đời.
• Khôi phục session đa tab — mở checkout ở tab A, hoàn tất ở tab B. Hữu ích khi một người mua follow một magic-link giữa luồng. Đang được theo dõi cho bản minor tiếp theo.
• Theming qua CSS variable — surface một bộ design token nhỏ (radius, accent colour) trên iframe để merchant có thể match brand mà không phải fork trang.
• Helper server-side — một gói nhỏ @lartech/infraio-server expose verifyWebhook() + signedRequest() để code backend không cần copy thao tác HMAC. Cho đến khi nó được ship, trang xác thực chữ ký liệt kê các cài đặt drop-in trong TypeScript, Go, Python, và Ruby.