PayPal 연동하기

PayPal이란?

PayPal은 전 세계 200여 개 국가에서 4억 명 이상이 사용하는 글로벌 결제수단이에요. 부정거래 방지 시스템을 갖고 있기 때문에 믿고 쓸 수 있어요.

토스페이먼츠 결제위젯 SDK로 PayPal 해외 간편결제를 연동할 수 있어요. PayPal은 자동결제(빌링), 정산 API를 지원하지 않아요.

PayPal은 추가 계약 후 사용할 수 있습니다. 추가 계약을 하고 싶다면 토스페이먼츠 고객센터(1544-7772)로 문의해주세요.

설정하기

결제위젯 어드민

상점관리자의 결제위젯 어드민로 들어가세요. 결제 UI의 이용서비스에 해외 간편결제가 있는지 확인하세요.

개발자센터

API 키 메뉴에서 결제위젯 연동 키를 확인하세요. 토스페이먼츠 계약 이후에만 PayPal을 결제위젯으로 사용할 수 있어요.

1. 결제위젯 그리기

아래 예제 코드는 HTML 페이지에 결제위젯, 이용약관 UI를 연동합니다. 결제하기 버튼을 눌러서 결제창을 띄워보세요. 실제로 결제되지 않으니 안심하세요.

<head>
  <meta charset="utf-8" />
  <!-- 결제위젯 SDK 추가 -->
  <script src="https://js.tosspayments.com/v1/payment-widget"></script>
</head>
<body>
  <!-- 결제위젯, 이용약관 영역 -->
  <div id="payment-method"></div>
  <div id="agreement"></div>
  <!-- 결제하기 버튼 -->
  <button id="payment-button">결제하기</button>
  <script>
    const clientKey = 'test_gck_docs_Ovk5rk1EwkEbP0W43n07xlzm'
    const customerKey = "" // 내 상점에서 고객을 구분하기 위해 발급한 고객의 고유 ID
    const button = document.getElementById('payment-button')

    // ------  결제위젯 초기화 ------
    // 비회원 결제에는 customerKey 대신 ANONYMOUS를 사용하세요.
    const paymentWidget = PaymentWidget(clientKey, customerKey) // 회원 결제
    // const paymentWidget = PaymentWidget(clientKey, PaymentWidget.ANONYMOUS) // 비회원 결제

    // ------  결제 UI 렌더링 ------
    // 결제위젯 UI를 렌더링할 위치를 지정합니다. `#payment-method`와 같은 CSS 선택자와 결제 금액 객체를 추가하세요.
    // 해외 결제에는 currency, country 정보가 필수입니다.
    // https://docs.tosspayments.com/reference/widget-sdk#renderpaymentmethods선택자-결제-금액-옵션
    paymentWidget.renderPaymentMethods(
      '#payment-method',
      {
        value: 664.98,
        currency: 'USD', // USD 통화만 지원
        country: 'US', // ISO-3166의 두 자리 국가 코드 모두 지원
      },
      // 렌더링하고 싶은 결제 UI의 variantKey
      // 아래 variantKey는 문서용 테스트키와 연동되어 있습니다. 멀티 UI를 직접 만들고 싶다면 계약이 필요해요.
      // https://docs.tosspayments.com/guides/payment-widget/admin#멀티-결제-ui
      { variantKey: 'PAYPAL' } // PayPal이 추가된 결제 UI의 variantKey
    )

    // ------  이용약관 UI 렌더링 ------
    // 이용약관 UI를 렌더링할 위치를 지정합니다. `#agree`와 같은 CSS 선택자를 추가하세요.
    // https://docs.tosspayments.com/reference/widget-sdk#renderagreement선택자-옵션
    paymentWidget.renderAgreement(
      '#agreement',
      { variantKey: 'AGREEMENT-EN' } // 영문 이용약관 UI 렌더링
    )

    // ------ '결제하기' 버튼 누르면 결제창 띄우기 ------
    // 더 많은 결제 정보 파라미터는 결제위젯 SDK에서 확인하세요.
    // https://docs.tosspayments.com/reference/widget-sdk#requestpayment결제-정보
    button.addEventListener('click', function () {
      paymentWidget.requestPayment({
        // 결제 정보 파라미터
        orderId: '',
        orderName: '토스 티셔츠 외 2건',
        successUrl: 'http://localhost:8080/success',
        failUrl: 'http://localhost:8080/fail',
        customerEmail: 'toss@sample.com',
        customerName: '김토스',
        // 판매자 보호 및 위험 관리 파라미터
        // 판매자를 보호하고 위험한 거래를 관리하기 위해 PayPal에 제공되는 정보입니다.
        // https://docs.tosspayments.com/reference/widget-sdk#판매자-보호-및-위험-관리-파라미터
        products: [
          {
            name: 'NeoPhone',
            quantity: 1,
            unitAmount: 114.86,
            currency: 'USD',
            description: 'Green color, 2023',
          },
          {
            name: 'NeoPad',
            quantity: 1,
            unitAmount: 550.12,
            currency: 'USD',
            description: 'Grey color',
          },
        ],
        shipping: {
          fullName: 'Toss Kim',
          address: {
            country: 'US',
            line1: '2nd st 105',
            line2: 'unit #105',
            area1: 'CA',
            area2: 'San Jose',
            postalCode: '16328',
          },
        },
        paymentMethodOptions: {
          // PayPal에서 요구하는 추가 파라미터
          paypal: {
            setTransactionContext: {
              // PayPal STC 파라미터 예시 (구매자의 로그인 정보)
              sender_account_id: 'kimToss01',
              sender_first_name: 'Toss',
              sender_last_name: 'Kim',
              sender_email: 'toss@sample.com',
              sender_phone: '(1) 562 254 5591',
              sender_country_code: 'US',
              sender_create_date: '2012-12-09T 19:14:55.277-0:00',
            },
          },
        },
      })
    })
  </script>
</body>

판매자 보호 및 위험 관리 파라미터가 왜 필요한가요?

PayPal은 위험 관리를 위해 많은 방법을 사용합니다. 가장 일반적인 방법 중 하나는 거래에 대한 상세 정보를 수집하고 분석하여 위험을 감지하는 것입니다. 정보를 사용하여 판매자와 구매자 간의 거래를 평가합니다. 상품 정보가 제공되면 PayPal은 해당 제품이 금전적 가치가 높은 제품인지, 불법 또는 위험한 제품인지, 또는 상품에 대한 보증이 있는지 등을 확인할 수 있습니다. 배송 정보도 중요한 정보입니다. PayPal은 배송 정보를 사용하여 거래를 평가하고 보호합니다. 예를 들어, 구매자가 상품을 받지 못한 경우 PayPal은 구매자를 보호하기 위해 배송 정보를 사용하여 거래에 대한 분쟁 처리를 합니다.

판매자 보호 및 위험 관리 파라미터 값을 한글로 보내도 되나요?

영어로 전달할 것을 권장하지만, 일부 값을 한글로 보내도 괜찮습니다.

제 사이트에서는 성과 이름 대신 `full_name`을 별도로 수집하고 있는데, 이 경우 전체 이름을 한 필드에 보내도 되나요?

네, 한 필드에 보내도 됩니다. 판매자는 sender_first_name, sender_last_name 대신 full_name 하나의 필드로 보내도 됩니다.

통화 및 국가 설정하기

PayPal 해외결제에는 amount.currency, amount.country 파라미터가 필수입니다. amount.value는 소수점 두 번째 자리까지만 허용됩니다.

JavaScript

paymentWidget.renderPaymentMethods('#payment-method', {
  value: 664.98, // 소수점 두 번째 자리까지 허용
  currency: 'USD',
  country: 'US',
})

amount.currency: PayPal 결제는 USD 통화를 지원합니다. KRW는 지원하지 않습니다.
amount.country: ISO-3166의 두 자리 국가 코드를 모두 지원합니다.

결제 금액 업데이트하기

결제 금액이 바뀐다면 updateAmount()를 사용해서 결제위젯을 업데이트하세요.

JavaScript

const paymentMethodsWidget = paymentWidget.renderPaymentMethods()

// 새로운 결제 금액을 넣어주세요
paymentMethodsWidget.updateAmount(550.12)

2. 결제 요청하기

결제하기 버튼을 누르면 PayPal 로그인 페이지로 이동합니다. 실제로 결제가 되지 않는 아래 토스페이먼츠 테스트 계정으로 로그인해서 결제 요청을 완료하세요. 토스페이먼츠 테스트 계정에 개인 카드 또는 계좌는 추가하지 마세요.

이메일: tosspayments-paypal@example.com
비밀번호: tosskim123!@#

3. 결제 요청 결과 확인하기

결제 요청 결과를 확인할 차례에요. 결제 요청이 성공하면 requestPayment()의 파라미터로 설정했던 (successUrl)을 통해 결제 성공 페이지로 이동합니다. 성공 리다이렉트 URL을 나타내는 success 뒤에 네 가지 쿼리 파라미터가 들어있습니다.

https://my-store.com/success?paymentKey={PAYMENT_KEY}&orderId={ORDER_ID}&amount={AMOUNT}&paymentType={PAYMENT_TYPE}

paymentType: 결제 유형입니다. PayPal 결제는 항상 NORMAL입니다.
paymentKey: 결제의 키 값입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 값이 유지됩니다. 결제 승인에 사용됩니다.
orderId:주문번호입니다. 주문한 결제를 식별하는 역할로, 결제를 요청할 때 가맹점에서 만들어서 requestPayment()에 담아 보낸 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 중복되지 않는 고유한 값을 발급해야 합니다. 결제 상태가 변해도 값이 유지됩니다.
amount: 실제로 결제된 금액입니다.

결제 요청이 실패했을 때

결제 요청이 실패하면 설정했던 결제 실패 페이지(failUrl)로 이동합니다. 에러 목록을 확인하세요.

https://my-store.com/fail?code={ERROR_CODE}&message={ERROR_MESSAGE}&orderId={ORDER_ID}

renderPaymentMethods() 메서드에 담아 보낸 결제 금액과 successUrl로 돌아온 amount 값이 같은지 반드시 확인해보세요. 클라이언트에서 결제 금액을 조작해 승인하는 행위를 방지할 수 있습니다.

만약 값이 다르다면 결제를 취소하고 구매자에게 알려주세요. 적립금이나 쿠폰이 적용된 금액이 맞는지도 확인해보세요.

4. 결제 승인하기

결제 승인 API를 호출해서 마지막 단계를 완료합니다. 먼저 API 인증을 위해 아래와 같이 인증 헤더 값을 만듭니다.

시크릿 키 뒤에 :을 추가하고 base64로 인코딩합니다. :을 빠트리지 않도록 주의하세요.

base64('test_gsk_docs_OaPz8L5KdmQXkzRz3y47BMw6:')
        ─────────────────┬───────────────── ┬
                     secretKey              :
                   발급받은 시크릿 키           콜론

아래 명령어를 터미널에서 실행하면 인코딩된 값을 얻을 수 있습니다.

echo -n 'test_gsk_docs_OaPz8L5KdmQXkzRz3y47BMw6:' | base64

인코딩된 값을 Basic 인증 헤더에 넣고 요청 본문도 추가하세요. 앞 단계에서 리다이렉트 URL로 받은 paymentKey, orderId, amount를 넣어주세요. 아래 예제 코드에는 내 테스트 결제의 paymentKey 값을 넣어 실행해주세요.

성공 페이지로 리다이렉트 된 후 10분 이내에 결제 승인 API를 호출해야 합니다. 10분이 지나면 결제가 만료되어 결제 승인을 할 수 없습니다.

5. 결제 완료 후 응답 확인하기

결제 승인에 성공하면 HTTP 200 OK와 Payment 객체를 받습니다.

응답

JSON

{
  "mId": "tgmimgr14sn",
  "lastTransactionKey": "",
  "paymentKey": "",
  "orderId": "",
  "orderName": "토스 해외결제 외 1건",
  "taxExemptionAmount": 0,
  "status": "DONE",
  "requestedAt": "2023-05-18T16:15:08+09:00",
  "approvedAt": "2023-05-18T16:17:47+09:00",
  "useEscrow": null,
  "cultureExpense": false,
  "card": null,
  "virtualAccount": null,
  "transfer": null,
  "mobilePhone": null,
  "giftCertificate": null,
  "cashReceipt": null,
  "cashReceipts": null,
  "discount": null,
  "cancels": null,
  "secret": "",
  "type": "NORMAL",
  "easyPay": "페이팔",
  "country": "US",
  "failure": null,
  "isPartialCancelable": true,
  "receipt": null,
  "checkout": {
    "url": "https://api.tosspayments.com/v1/payments//checkout"
  },
  "currency": "USD",
  "totalAmount": 664.98,
  "balanceAmount": 664.98,
  "suppliedAmount": 604.53,
  "vat": 60.45,
  "taxFreeAmount": 0.0,
  "method": "해외간편결제",
  "version": "2022-11-16"
}

응답 객체에 원하는 필드가 없어요.

응답 객체의 필드는 API 버전에 따라 조금씩 달라집니다. 개발자센터에 설정된 API 버전을 확인하고, 원하는 필드가 있는 버전으로 변경해보세요.

API 버전 업데이트 사항은 릴리즈 노트에서 확인할 수 있습니다.

.css-p1o082{width:calc(0.8em + 8px);height:0.8em;position:absolute;top:calc(50% - 0.4em);left:calc(-0.8em - 8px);padding-right:8px;opacity:0;-webkit-transition:opacity 0.2s ease-in-out;-webkit-transition:opacity 0.2s ease-in-out;transition:opacity 0.2s ease-in-out;}PayPal 연동하기