해외간편결제 (PayPal) 연동 및 진단

API 개별 연동 키를 사용해 PayPal 결제창 호출, 최종 승인 및 상점아이디(MID) 수단 개통 상태를 검증합니다.

API 개별 연동 키

필수

테스트(`test_`) 또는 라이브(`live_`) 클라이언트 키와 시크릿 키를 입력하세요.

클라이언트 키

시크릿 키

결제 요청 파라미터

주문번호는 매 결제 시도마다 중복 방지를 위해 자동 생성됩니다.

주문번호 (Order ID)

자동생성

결제 금액 (USD)

연동 / 검증 모드

트랜잭션 응답 & 진단 로그

JSON / Report

// Awaiting transaction payload...
// API 키를 입력한 후 "PayPal 결제창 호출하기" 또는 "수단 개통 진단" 버튼을 클릭하세요.

Toss Payments PayPal 연동 및 진단 가이드

1. 클라이언트 연동 (새 창 팝업 브릿지 & WASM 수수료 연산)

브라우저 팝업 차단을 방지하기 위해 클릭 이벤트 내부에서 동기적으로 빈 팝업 창을 먼저 생성한 뒤, WASM 모듈(/math.wasm)로 수수료 합산 금액을 계산하고 /paypal-checkout 브릿지 경로로 이동시켜 windowTarget: 'self'로 호출합니다.

// [메인 페이지] 1. 팝업 차단 방지를 위한 동기식 팝업 오픈 및 WASM 연산 후 이동
const popup = window.open('about:blank', 'TossPayPalCheckoutPopup', 'width=540,height=720');
const wasmModule = await WebAssembly.instantiate(await (await fetch('/math.wasm')).arrayBuffer());
const totalAmount = wasmModule.instance.exports.calculateTotal(baseAmount, 5);

const params = new URLSearchParams({
    mode: 'launch',
    sdkMode: 'v2_paypal', // v2_paypal | v1_paypal | v2_usd_card
    clientKey: 'test_ck_...',
    customerKey: 'TOSS_PAYMENTS_TEST_CUSTOMER',
    orderId: `ORDER_${Date.now()}`,
    orderName: 'PayPal Test Order',
    amount: String(totalAmount)
});
popup.location.href = '/paypal-checkout?' + params.toString();

// [팝업 브릿지 (/paypal-checkout) 내부] 2. V2 SDK 초기화 및 self 리다이렉트 호출
const tossPayments = await TossPayments(clientKey);
const payment = tossPayments.payment({ customerKey });

await payment.requestPayment({
    method: 'FOREIGN_EASY_PAY',
    foreignEasyPay: {
        provider: 'PAYPAL',
        country: 'US' // 국가 코드 지정 (필수)
    },
    amount: {
        currency: 'USD',
        value: Number(amount) // 1 USD 이상 필수
    },
    orderId: orderId,
    orderName: orderName,
    successUrl: window.location.origin + '/paypal-checkout?mode=success',
    failUrl: window.location.origin + '/paypal-checkout?mode=fail',
    customerEmail: 'customer@tosspayments.com',
    customerName: 'Toss Tester',
    windowTarget: 'self' // 팝업 창 내부에서 PayPal로 자연스럽게 이동
});

주의사항: PayPal은 보안 정책상 iframe 내부 렌더링이 차단되거나 부모 창이 리다이렉트될 수 있으므로, 반드시 새 창 브릿지 안에서 windowTarget: 'self'로 호출하고 완료 후 BroadcastChannel / localStorage / window.opener.postMessage로 부모 창에 결과를 전달해야 합니다.

2. 서버(백엔드) 연동 (결제 최종 승인)

결제창 완료 후 successUrl로 리다이렉트되면, 해당 파라미터들로 토스페이먼츠 서버에 최종 승인(Confirm)을 요청합니다.

// Node.js (Express) 기반 결제 최종 승인 (/api/confirm)
app.post('/api/confirm', async (req, res) => {
    const { paymentKey, orderId, amount, secretKey } = req.body;
    
    // 시크릿 키 뒤에 콜론(:)을 붙여 Base64로 인코딩 (Basic Auth)
    const basicToken = Buffer.from(secretKey + ':').toString('base64');

    try {
        const response = await axios.post(
            'https://api.tosspayments.com/v1/payments/confirm',
            { paymentKey, orderId, amount: Number(amount) },
            {
                headers: {
                    Authorization: `Basic ${basicToken}`,
                    'Content-Type': 'application/json'
                }
            }
        );
        res.status(200).json(response.data);
    } catch (error) {
        res.status(error.response ? error.response.status : 500).json(
            error.response ? error.response.data : { message: error.message }
        );
    }
});

3. 라이브 키(MID) 수단 개통 교차 검증 및 진단

라이브 키(live_ck_...) 사용 시 INVALID_PAYMENT_METHOD 오류가 발생한다면, 대시보드의 연동 / 검증 모드를 변경하여 원장 설정 누락 여부를 즉시 교차 검증할 수 있습니다.

교차 검증 방법:
1. 외화 인증 달러 카드 (V2 SDK - CARD + USD) 모드로 호출했을 때 해외카드 결제창은 정상 오픈되는데 PayPal (V1 / V2 SDK) 모드에서만 INVALID_PAYMENT_METHOD가 발생한다면, 해당 상점아이디(MID)에 달러(USD) 카드는 열려 있으나 해외간편결제(PAYPAL) 수단 권한이 누락된 상태입니다.
2. 하단의 MID 수단 개통 진단 및 문의 양식 생성 버튼을 클릭하면 시크릿 키 인증 상태 확인 및 토스페이먼츠 기술지원팀 전달용 리포트가 자동 생성됩니다.