결제 (Payment)

토스페이먼츠 / Stripe / PayApp 단건 결제 연동 API입니다. 앱 결제 설정에서 프로바이더를 선택합니다(기본: 토스, PayApp은 사업자 등록 없이 결제 가능). 정기결제는 구독(Subscription) 을 사용하세요.

결제 흐름

prepare — 서버에서 결제 정보 등록 (payment_key 와 client key 발급)
클라이언트에서 토스/Stripe SDK 로 결제 위젯 호출 (PayApp은 위젯 없이 payapp_pay_url 로 리다이렉트)
결제 완료 콜백에서 confirm 호출 → 최종 승인

결제 준비

typescript

const prepared = await cb.payment.prepare({
  amount: 50000,
  order_name: '상품명',
  order_id: 'order_123',                  // 선택, 미지정 시 자동 생성
  customer_name: '홍길동',
  customer_email: '[email protected]',
  metadata: { user_id: 'member_xxx' }
})

console.log(prepared.payment_id)
console.log(prepared.payment_provider)   // 'toss' | 'stripe' | 'payapp'
console.log(prepared.toss_client_key)    // toss 인 경우
console.log(prepared.stripe_client_secret) // stripe 인 경우
console.log(prepared.payapp_pay_url)     // payapp 인 경우 — 이 URL 로 리다이렉트

토스 위젯 호출 (브라우저)

typescript

import { loadTossPayments } from '@tosspayments/payment-sdk'

const tossPayments = await loadTossPayments(prepared.toss_client_key)
await tossPayments.requestPayment('카드', {
  amount: prepared.amount,
  orderId: prepared.order_id,
  orderName: prepared.order_name,
  customerKey: prepared.customer_key,
  successUrl: prepared.success_url,
  failUrl: prepared.fail_url
})

PayApp 결제 (리다이렉트)

PayApp은 위젯이 없습니다. prepare 응답의 payapp_pay_url 로 이동시키면 PayApp 호스팅 결제창이 열리고, 결제 결과는 서버 webhook 으로 확정됩니다. PayApp은 customer_phone(결제요청 수신 번호)이 필수입니다.

typescript

const prepared = await cb.payment.prepare({
  amount: 50000,
  order_name: '상품명',
  customer_name: '홍길동',
  customer_phone: '01012345678'   // PayApp 필수
})

if (prepared.payment_provider === 'payapp' && prepared.payapp_pay_url) {
  window.location.href = prepared.payapp_pay_url
}

결제 승인 (콜백)

successUrl 로 리다이렉트되면 query 파라미터에 payment_key 등이 들어옵니다.

typescript

// 콜백 페이지에서
const params = new URLSearchParams(window.location.search)

const result = await cb.payment.confirm({
  payment_key: params.get('paymentKey')!,
  order_id: params.get('orderId')!,
  amount: Number(params.get('amount'))
})

if (result.status === 'done') {
  console.log('결제 완료!', result.receipt_url)
}

결제 조회

typescript

// 주문 ID 로 조회 (Payment ID 가 아닙니다)
const payment = await cb.payment.getByOrderId('order_123')

console.log(payment.status)        // 'pending' | 'done' | 'canceled' | ...
console.log(payment.amount)
console.log(payment.receipt_url)

📌 SDK 에는 결제 목록 조회 메서드(listPayments)가 없습니다. 결제 목록은 콘솔에서 확인하거나, 자체 데이터베이스에 결제 결과를 저장한 뒤 cb.database.queryData(...) 로 조회하세요.

결제 취소

typescript

// 전액 취소
const canceled = await cb.payment.cancel(payment.payment_id, {
  cancel_reason: '고객 요청'
})

// 부분 취소
const partial = await cb.payment.cancel(payment.payment_id, {
  cancel_reason: '부분 환불',
  cancel_amount: 10000
})

console.log(partial.canceled_amount, '/', partial.original_amount)

📌 빌링키(자동 결제)는 cb.payment 가 아닌 cb.subscription 모듈에서 관리합니다.

푸시 (Push)

구독 (Subscription)