JavaScript / 브라우저 SDK

@lartech/infraio-checkout-js는 현재 공개된 유일한 SDK입니다. 브라우저에서 실행되며 호스팅 체크아웃을 엽니다. 백엔드 SDK(Node, Go, Python)는 로드맵에 있습니다. 그때까지는 게이트웨이와 직접 통신하세요 — HMAC 서명 헬퍼는 빠른 시작을 참조하세요.

• 현재 버전: 0.1.1-beta.17 (pre-1.0; 마이너 변경 예상)
• 포맷: ESM (index.js), CJS (index.cjs), IIFE (index.global.js)
• 타입 번들됨 (index.d.ts)
• 런타임 피어 없음 — React, jQuery 또는 기타 종속성 없음

설치

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?)

Promise<InfraIoInstance>를 반환합니다.

import { loadInfraIo } from "@lartech/infraio-checkout-js";
 
const sdk = await loadInfraIo("pk_live_yourkeyhere", {
  // 선택. 비프로덕션 환경을 가리킬 때만 오버라이드하세요.
  checkoutUrl: "https://checkout-dev.infraio.xyz",
});

sdk.checkout({ … })

호스팅 체크아웃을 엽니다. void를 반환합니다(상태는 콜백 사용).

sdk.close()

열려 있는 팝업이나 임베드를 프로그래밍 방식으로 해제합니다. 리디렉션 모드에서는 no-op입니다.

sdk.checkout({ sessionId, mode: "popup", /* … */ });
// 나중에, 예를 들어 사용자가 페이지를 떠날 때
sdk.close();

sdk.openRefundRequest({ … })

백엔드가 POST /b2b/v1/merchants/{merchant_id}/refund-requests로 발급한 일회성 토큰에 대해 호스팅 환불 요청 양식을 엽니다. 구매자는 저희 페이지에서 환불 목적지 주소 + 사유 + (선택) 메타데이터를 입력합니다. 가맹점 페이지는 열기/닫기 라이프사이클만 처리합니다. close() 함수를 반환합니다 — 호출하여 팝업을 프로그래밍 방식으로 해제하거나 임베드 iframe을 분리합니다. 리디렉션 모드에서 반환된 함수는 no-op입니다.

import { loadInfraIo } from "@lartech/infraio-checkout-js";
 
const sdk = await loadInfraIo("pk_live_yourkeyhere");
 
// 서버 측에서 토큰을 발급한 다음, 브라우저의 SDK에 전달합니다.
const { token } = await fetch("/api/mint-refund-token", { method: "POST" }).then(r => r.json());
 
const close = sdk.openRefundRequest({
  token,
  mode: "popup",
  onSuccess: ({ linkToken, refundId }) => {
    // 구매자가 양식을 제출했습니다.
    // linkToken → /r/:linkToken 상태 페이지(구매자와 공유).
    // refundId  → 승인/거부에 B2B API와 함께 사용.
    window.location.href = `/r/${linkToken}`;
  },
  onCancel: () => { /* 구매자가 제출 없이 닫음 */ },
});
 
// 나중에 필요하면 프로그래밍 방식으로 팝업 해제:
// close();

onError를 통해 노출되는 토큰 상태

구매자가 만료된 토큰을 열면 페이지 자체가 표시를 처리하며(“만료됨 — 새 링크 요청” 안내 등을 렌더링), SDK는 이러한 경우 onError를 발생시키지 않습니다 — 구매자는 양식 흐름 내에 있고 가맹점 코드는 반응할 필요가 없습니다. onError는 가맹점 코드가 조치할 수 있는 경우(잘못된 인수, iframe 로드 시 네트워크 실패) 에만 발생합니다.

오류 클래스

import { InfraIoError } from "@lartech/infraio-checkout-js";
 
sdk.checkout({
  sessionId,
  onError: (err: InfraIoError) => {
    switch (err.code) {
      case "invalid_request_error":   /* 잘못된 sessionId / 인수 */ break;
      case "iframe_load_error":       /* iframe 로드 실패 */ break;
      case "iframe_timeout_error":    /* timeoutMs 초과 */ break;
      case "already_open_error":      /* 다른 체크아웃이 이미 열려 있음 */ break;
      case "network_error":           /* 체크아웃 오리진과 통신 중 일시적인 네트워크 문제 */ break;
      case "api_error":               /* SDK 발급 호출에 대해 백엔드가 non-2xx 반환 */ break;
    }
  },
});

sdk.openRefundRequest()는 invalid_request_error(누락 또는 잘못된 토큰/인수)만 동기적으로 throw합니다. iframe_load_error(환불 요청 iframe 로드 실패)는 throw되지 않고 onError를 통해 비동기적으로 전달됩니다. iframe_timeout_error 또는 already_open_error는 발생시키지 않습니다 — 환불 요청 팝업에는 로드 타임아웃이 없으며 여러 동시 팝업을 허용합니다.

모드 비고

팝업

• 어두운 반투명 배경의 중앙 정렬 오버레이
• z-index: 2147483647 (max int32) — 다른 모든 것 위에 위치
• 열려 있는 동안 본문 스크롤 잠금. 닫히면 복원
• 닫기 버튼이 초기 포커스를 받음. Tab은 팝업 내에 트랩됨
• 닫기 방법: 닫기 버튼, Escape, 외부 클릭, sdk.close(). 이들 모두 onCancel을 호출
• 체크아웃 페이지는 postMessage로 리사이즈를 요청할 수 있음 — SDK가 width/height 제한 내로 클램프

리디렉션

• window.location.href를 통한 하드 내비게이션
• ?return_url=<current-page>를 자동으로 추가하여 구매자가 출발점으로 돌아오게 함. 세션의 success_url / cancel_url이 이미 이를 처리하면 왕복은 return_url을 무시

임베드

• allow="payment; clipboard-write"가 있는 iframe (HTML5 Feature Policy 지시문 — sandbox 속성이 아님). iframe은 체크아웃 오리진에서 제공되므로 구매자 측 지갑 팝업과 클립보드 쓰기는 추가 옵트인 없이 동작
• 컨테이너 너비는 100%. 높이는 INFRAIO_RESIZE postMessage를 통해 자동 조정, [200, 2000]px 범위로 클램프
• iframe 경계 외에 CSS 격리 없음 — 부모 페이지 스타일은 누출되지 않음
• 체크아웃이 상호작용 가능해질 때 자체 로딩 상태를 숨길 수 있도록 항상 onReady를 연결

TypeScript

모든 타입이 번들됩니다. 가장 유용한 익스포트:

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

VERSION은 SDK 자체의 버전 문자열입니다 — 버그 리포트에 유용합니다.

다음 단계

• React / Vue 프레임워크 래퍼 — 파일럿 가맹점 전반에서 vanilla JS 표면이 안정화된 후 출시 이후 반복을 위해 계획되었습니다. 현재 vanilla SDK는 React 내부에서 잘 동작합니다 — 래퍼는 수동 useRef + 라이프사이클 플러밍을 제거할 것입니다.
• 크로스 탭 세션 재개 — 탭 A에서 체크아웃을 열고 탭 B에서 완료. 구매자가 흐름 중간에 매직 링크를 따라갈 때 유용합니다. 다음 마이너 릴리스에서 추적됩니다.
• CSS 변수를 통한 테마 — iframe에 작은 디자인 토큰 세트(radius, accent color)를 노출하여 가맹점이 페이지를 포크하지 않고 브랜드에 맞출 수 있게 합니다.
• 서버 측 헬퍼 — 백엔드 코드가 HMAC 의식을 복사하지 않도록 verifyWebhook() + signedRequest()를 노출하는 작은 @lartech/infraio-server 패키지. 출시 전까지 서명 검증 페이지에 TypeScript, Go, Python, Ruby의 드롭인 구현이 나와 있습니다.