결제 (Payment)
토스페이먼츠 / Stripe 단건 결제 연동 API입니다. 정기결제는 구독(Subscription) 을 사용하세요.
결제 흐름
prepare— 서버에서 결제 정보 등록 (payment_key 와 client key 발급)- 클라이언트에서 토스/Stripe SDK 로 결제 위젯 호출
- 결제 완료 콜백에서
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'
console.log(prepared.toss_client_key) // toss 인 경우
console.log(prepared.stripe_client_secret) // stripe 인 경우토스 위젯 호출 (브라우저)
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
})결제 승인 (콜백)
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모듈에서 관리합니다.