checkoutPayment

토스페이 결제창을 띄워 사용자 인증을 수행합니다. 인증이 완료되면 성공 여부와 실패 사유를 담아 resolve됩니다. 이 함수는 결제창에서 사용자 인증만 처리하며, 실제 결제 처리는 인증 성공 후 서버에서 별도로 진행해야 합니다.

IAP 네임스페이스의 SKU 기반 결제(IAP.createOneTimePurchaseOrder / IAP.createSubscriptionPurchaseOrder)와는 다른 흐름입니다 — checkoutPayment는 사전에 발급한 payToken을 사용해 임의 금액·임의 항목의 결제 인증을 처리하는 토스페이 일반 결제 진입점입니다.

시그니처

import { checkoutPayment } from '@apps-in-toss/web-framework';

declare function checkoutPayment(options: {
  params: CheckoutPaymentOptions;
}): Promise<CheckoutPaymentResult>;

interface CheckoutPaymentOptions {
  /** 서버에서 발급한 결제 토큰. */
  payToken: string;
}

interface CheckoutPaymentResult {
  /** 인증 성공 여부. */
  success: boolean;
  /** `success: false`일 때 실패 사유. */
  reason?: string;
}

파라미터

이름	타입	필수	설명
options.params.payToken	string	✓	서버에서 발급한 결제 토큰. 토스페이 결제창에 전달되어 결제 컨텍스트를 식별합니다.

반환값

• Promise<CheckoutPaymentResult> — 결제창에서 사용자 인증이 끝나면 resolve됩니다.
  • success: true — 인증이 성공했습니다. 서버 측 결제 실행 API를 호출해 실제 결제를 마무리하세요.
  • success: false + reason — 인증이 실패했습니다. reason을 사용자에게 표시하거나 로깅하세요.

인증 ≠ 결제 완료

success: true는 결제창에서 사용자 인증이 통과했다는 의미입니다. 실제 결제 처리(서버 측 승인·정산)는 별도 API 호출로 마무리해야 합니다. 인증 성공만으로 결제가 끝났다고 가정하지 마세요.

권한

권한이 필요하지 않습니다. checkoutPayment는 별도의 PermissionName에 바인딩되지 않습니다.

예제

최소 예제

import { checkoutPayment } from '@apps-in-toss/web-framework';

async function pay(payToken: string) {
  const { success, reason } = await checkoutPayment({ params: { payToken } });

  if (success) {
    // 서버 측 결제 실행 API 호출
    await fetch('/api/payment/execute', {
      method: 'POST',
      body: JSON.stringify({ payToken }),
      headers: { 'Content-Type': 'application/json' },
    });
  } else {
    console.warn('결제 인증 실패:', reason);
  }
}

실전 예제 — 결제 버튼

import { checkoutPayment } from '@apps-in-toss/web-framework';
import { useCallback, useState } from 'react';

export function PayButton({ amount }: { amount: number }) {
  const [status, setStatus] = useState<'idle' | 'pending' | 'success' | 'error'>('idle');
  const [message, setMessage] = useState('');

  const handlePay = useCallback(async () => {
    setStatus('pending');
    setMessage('');
    try {
      // 1. 서버에서 결제 토큰 발급
      const { payToken } = await fetch('/api/payment/create', {
        method: 'POST',
        body: JSON.stringify({ amount }),
        headers: { 'Content-Type': 'application/json' },
      }).then((res) => res.json());

      // 2. 토스페이 결제창 띄우기 + 인증 처리
      const { success, reason } = await checkoutPayment({ params: { payToken } });

      if (!success) {
        setStatus('error');
        setMessage(`결제 인증 실패: ${reason ?? '알 수 없는 오류'}`);
        return;
      }

      // 3. 서버 측 결제 실행
      await fetch('/api/payment/execute', {
        method: 'POST',
        body: JSON.stringify({ payToken }),
        headers: { 'Content-Type': 'application/json' },
      });

      setStatus('success');
      setMessage('결제가 완료됐어요.');
    } catch (error) {
      setStatus('error');
      setMessage('결제 처리 중 오류가 발생했어요.');
      console.error(error);
    }
  }, [amount]);

  return (
    <div>
      <button type="button" onClick={handlePay} disabled={status === 'pending'}>
        {status === 'pending' ? '결제 진행 중…' : `${amount.toLocaleString()}원 결제`}
      </button>
      {message && <p role="status">{message}</p>}
    </div>
  );
}

직접 실행해 보기

sdk-example의 IAP 페이지에서 checkoutPayment 카드를 실행해 결과를 확인할 수 있습니다.

→sdk-example에서 실행해 보기

관련 API

• IAP.createOneTimePurchaseOrder — SKU 기반 단건 인앱결제 흐름.
• IAP.createSubscriptionPurchaseOrder — SKU 기반 구독 결제 흐름.

관련 가이드

• Guides — 토스페이 결제 흐름

외부 참조

• @apps-in-toss/web-framework — 상위 SDK 패키지. 실제 export는 내부적으로 @apps-in-toss/web-bridge에서 가져옵니다.