호스티드 체크아웃

팝업 SDK

호스티드 JavaScript SDK로 브라우저에서 RANTAN Checkout을 엽니다.

Checkout V2 SDK는 특정 세션에 연결된 RANTAN Checkout 팝업을 엽니다. iframe 삽입 방식이 아니라 팝업 또는 직접 이동 방식으로 설계됐습니다.

#호스티드 SDK 불러오기

RANTAN 앱 도메인에서 Checkout 스크립트를 불러옵니다. 변경할 수 없는 RantanCheckout 전역 객체가 제공됩니다.

HTML

<script src="https://app.rantan.xyz/checkout-v2.js"></script>

#Checkout 팝업 열기

브라우저 팝업 차단을 피하려면 사용자 동작 안에서 open을 호출하세요. 서버가 생성한 sessionId가 필수입니다.

Browser

<button id="buy">Buy with RANTAN</button>
<script src="https://app.rantan.xyz/checkout-v2.js"></script>
<script>
  document.querySelector("#buy").addEventListener("click", async () => {
    const result = await RantanCheckout.open({
      productId: 123,
      sessionId: "c8a9d48e-68b2-48dd-a754-75635cae71d6",
      clientReferenceId: "order_20260730_001",
    });

    // UI notification only. Verify this session from your backend.
    await fetch("/api/orders/20260730_001/verify", { method: "POST" });
  });
</script>

#옵션

옵션	필수 여부	설명
`productId`	필수	세션에 고정된 RANTAN 상품 ID입니다.
`sessionId`	필수	서버에서 생성한 Checkout Session UUID입니다.
`clientReferenceId`	선택	브라우저에서 한 번 더 비교할 판매자 주문 참조값입니다.
`timeoutMs`	선택	대기 시간(ms)입니다. 기본 30분이며 최대 60분으로 제한됩니다.
`closeOnComplete`	선택	완료 후 팝업을 유지하려면 false로 지정합니다.
`onComplete / onClose / onTimeout`	선택	완료, 닫기, 시간 초과에 대한 선택 UI 콜백입니다.

#직접 URL 만들기

RantanCheckout.url(options)은 창을 열지 않고 호스티드 URL을 반환합니다. 전체 페이지 이동이나 링크에 사용할 수 있습니다.

Hosted URL

https://app.rantan.xyz/checkout/123?session_id=c8a9d48e-68b2-48dd-a754-75635cae71d6

#완료 결과

SDK는 resolve 전에 event.origin, 팝업 창, 프로토콜 버전, 상품, 세션, 선택 주문 참조값을 검사합니다.

postMessage

{
  "type": "rantan:checkout:complete",
  "version": "v2",
  "product_id": 123,
  "purchase_id": "bfaf2aa4-dd86-4356-92db-ae0431806867",
  "status": "completed",
  "client_reference_id": "order_20260730_001",
  "checkout_session_id": "c8a9d48e-68b2-48dd-a754-75635cae71d6"
}

#SDK 오류

코드	설명
`CHECKOUT_SESSION_REQUIRED`	서버가 생성한 sessionId가 없습니다.
`CHECKOUT_ALREADY_OPEN`	같은 Checkout Session이 이미 열려 있습니다.
`CHECKOUT_CLOSED`	완료 전에 구매자가 팝업을 닫았습니다.
`CHECKOUT_TIMEOUT`	완료 전에 제한된 대기 시간이 끝났습니다.