Leysys Docs

Hosted checkout ​

이 페이지의 API·SDK·catalog 계약은 Billing Authority를 채택한 제품에 적용됩니다. 다른 실행 구조는 아키텍처 경계를 따릅니다.

제품은 amount, currency, seller, provider, entitlement scope를 보내지 않고 승인된 priceId만 보냅니다. control plane은 로컬 catalog를 조회해 나머지를 결정하고 provider 결제창으로 연결되는 URL을 반환합니다.

예정 소비 계약

SDK 0.1.1의 기존 배포 기록과 staging 실행은 확인됐습니다. 제품별 production API·catalog 활성화는 미확인이므로 아래 예시를 실제 제공 보장으로 해석하지 않습니다. 현재 제공 상태와 채택 대상의 운영 검증 기록을 확인하십시오.

제품 서버 예시 ​

ts
import { createControlPlaneClient } from '@leysys/control-plane-client'

const controlPlane = createControlPlaneClient({
  baseUrl: process.env.LEYSYS_CONTROL_PLANE_URL!,
})

const checkout = await controlPlane.createHostedCheckout({
  priceId: selectedPriceId,
  accessToken: userAccessToken,
  idempotencyKey: crypto.randomUUID(),
  returnUrl: 'https://product.example.invalid/account',
})

return redirect(checkout.checkoutUrl)

returnUrl은 control plane에 사전 등록된 allowlist와 일치해야 합니다. 제품이 임의의 외부 URL을 넘길 수 없어야 합니다.

흐름 ​

  1. 제품 서버가 로그인한 Leysys account와 선택한 priceId로 checkout을 생성합니다.
  2. control plane이 product, seller, price, provider account, entitlement grant를 로컬 catalog에서 고정합니다.
  3. 고객은 반환된 hosted checkout URL로 이동합니다.
  4. 결제 인증·승인·webhook 처리는 control plane이 소유합니다.
  5. 제품 복귀 URL은 이동 신호로만 사용합니다.
  6. 제품은 checkout 상태와 entitlement를 다시 조회합니다.

금지 입력 ​

제품이 checkout 생성 요청에 다음 값을 넣는 계약을 만들지 마십시오.

  • 결제 금액과 통화
  • PG 이름 또는 provider account ID
  • seller ID
  • entitlement scope
  • provider order/payment key
  • redirect에서 받은 결제 성공 여부

이 값은 모두 변조 가능한 제품 입력이 아니라 catalog 또는 control plane이 검증한 provider evidence에서 나와야 합니다.

취소와 환불 ​

취소·환불도 제품이 provider API를 직접 호출하지 않고 control plane의 정규화된 mutation을 사용합니다. 동일 idempotency key의 반복 요청은 동일 결과를 반환해야 하며, timeout 뒤에는 새 provider로 재시도하지 않고 기존 attempt를 조회·대사합니다.

© 2026 Leysys. 무단 복제·배포·판매를 금지합니다.