PayPal 연동하기

해외 고객의 결제를 받을 수 있는 PayPal을 연동하는 방법입니다.

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

1. 결제 요청하기

SDK를 추가한 뒤 클라이언트 키를 사용해 객체를 초기화합니다. 초기화된 객체로 requestPayment()를 실행하면 PayPal 결제 페이지로 이동합니다. 결제 정보, 판매자 보호 및 위험 관리 파라미터는 아래에서 살펴보세요.

<head>
  <title>결제하기</title>
  <meta charset="utf-8" />
  <!-- 토스페이먼츠 결제창 SDK 추가 -->
  <script src="https://js.tosspayments.com/v1/payment"></script>
</head>
<body>
  <script>
    // ------ 클라이언트 키로 객체 초기화 ------
    var clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq'
    var tossPayments = TossPayments(clientKey) // 클라이언트 키로 초기화하기

    // ------ 결제창 띄우기 ------
    tossPayments.requestPayment('해외간편결제', { // 결제 수단 파라미터
      // 결제 정보 파라미터
      amount: 664.98,
      orderId: '',
      orderName: '토스 해외결제 외 1건',
      customerName: '김토스',
      successUrl: 'http://localhost:8080/success',
      failUrl: 'http://localhost:8080/fail',
      provider: 'PAYPAL',
      currency: 'USD',
      country: 'US',
      // ...
      // 판매자 보호 및 위험 관리 파라미터 사용 예시
      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) 123 456 7890',
            sender_country_code: 'US',
            sender_create_date: '2021-01-01T19:14:55.277-0:00'
          }
        }
      }
    })
    .catch(function (error) {
      if (error.code === 'USER_CANCEL') {
        // 결제 고객이 결제창을 닫았을 때 에러 처리
      } else if (error.code === 'INVALID_CARD_COMPANY') {
        // 유효하지 않은 카드 코드에 대한 에러 처리
      }
    })
  </script>
</body>

PayPal 결제창을 띄우기 전에 고객에게 아래 이용약관 동의를 받으세요.

전자금융거래 이용약관: https://pages.tosspayments.com/terms/en/paypal/general_terms_and_conditions
개인정보 수집이용 동의: https://pages.tosspayments.com/terms/en/paypal/collection_use_consent
개인정보 제3자 제공 및 국외 이전 동의: https://pages.tosspayments.com/terms/en/paypal/providing_transmitting_consent

결제 정보 파라미터

amount 필수 · number
결제되는 금액입니다.
orderId 필수 · string
주문 ID입니다. 충분히 무작위한 값을 직접 생성해서 사용하세요. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.
orderName 필수 · string
주문명입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.
successUrl 필수 · string
결제가 성공하면 리다이렉트되는 URL입니다. 결제 승인 처리에 필요한 값들이 쿼리 파라미터로 함께 전달됩니다. 반드시 오리진을 포함해야 합니다. 예를 들면 https://www.example.com/success 같은 형태입니다.
failUrl 필수 · string
결제가 실패하면 리다이렉트되는 URL입니다. 에러 코드 및 에러 메시지가 쿼리 파라미터로 함께 전송됩니다. 반드시 오리진을 포함해야 합니다.
provider 필수 · string
간편결제사 코드입니다. PayPal 연동에서는 PAYPAL 또는 페이팔을 넣어야 합니다.
currency 필수 · string
결제할 때 사용할 통화 단위입니다. PayPal에서 사용할 수 있는 통화 단위는 AUD, EUR, GBP, HKD, JPY, SGD, USD 입니다.
country 필수 · string
결제한 국가 정보입니다. ISO-3166의 두 자리 국가 코드를 모두 지원합니다.
customerName string
고객의 이름입니다. 최대 길이는 100자입니다.
customerEmail string
고객의 이메일 주소입니다. 결제 결과를 알려줄 때 사용합니다. 최대 길이는 100자입니다.
taxFreeAmount number
면세 금액입니다.

판매자 보호 및 위험 관리 파라미터

아래 파라미터는 PayPal에서 필수로 요청한 파라미터로, 판매자를 보호하고 위험한 거래를 관리하기 위해 PayPal에 추가 정보를 제공하는 데 사용됩니다. 이 파라미터를 보내면 PayPal에서 제공하는 판매자 보호를 받을 수 있으니 반드시 보내주세요.

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

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

Q 값을 한글로 보내도 되나요?

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

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

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

products array
고객이 구매한 각 상품의 상세 정보 객체를 담는 배열입니다. 예를 들어 고객이 세 가지 종류의 상품을 구매했다면 길이가 3인 배열이어야 합니다.
products 정보는 필수가 아니지만 이 정보를 보내려면 아래 항목은 모두 필수입니다.
- name 필수 · string
  상품 이름입니다.
- quantity 필수 · number
  상품 구매 수량입니다.
- unitAmount 필수 · number
  상품의 가격입니다. 전체를 합한 가격이 아닌 상품의 개당 가격입니다.
- currency 필수 · string
  상품 가격의 통화 단위입니다.
- description 필수 · string
  상품에 대한 부가적인 설명입니다.

shipping object
고객이 구매한 각 상품의 배송 정보 객체입니다.
- fullName string
  고객의 이름입니다.
- address object
  배송지 주소입니다.
  - country 필수 · string
    배송지 국가 정보입니다.
  - line1 string
    배송지 상세 주소입니다. 도로명 및 건물(Street, Apt), 번지 정보입니다. 예를 들어 2nd St 105 같은 형태입니다.
  - line2 string
    추가적인 배송지 상세 주소입니다. 번지 및 동 호수 정보가 길어질 때 사용합니다. 예를 들어 Unit #105 같은 형태입니다.
  - area1 string
    배송지 주소입니다. 주(State, Province, Region) 정보입니다. 국가 별로 도시 체계에 따라 없는 경우가 있습니다.
  - area2 필수 · string
    배송지 주소입니다. 도시(City) 정보입니다. 예를 들어 San Jose 같은 형태입니다.
  - postalCode string
    배송지 우편번호입니다.

paymentMethodOptions object
간편결제사의 추가 파라미터를 담는 객체입니다. 결제사 별로 파라미터를 제공합니다. PayPal을 연동할 때는 paypal을 사용합니다.
- paypal object
  PayPal의 추가 파라미터를 담는 객체입니다.
  - setTransactionContext object
    PayPal에서 추가로 요청하는 STC(Set Transaction Context) 정보를 객체로 전달하는 필드입니다. 이 정보는 PayPal에서 부정거래, 결제 취소, 환불 등 리스크 관리에 활용합니다. 결제 거래의 안전성과 신뢰성을 확보하려면 이 정보를 전달해야 합니다. PayPal STC 문서를 참고해서 업종에 따라 필요한 파라미터를 추가해주세요. 문서의 표에 있는 ‘Data Field Name’ 컬럼 값을 객체의 ‘key’로, ‘Description’에 맞는 값을 객체의 ‘value’로 넣어주시면 됩니다.
    예를 들어 이벤트/티케팅 업종에 종사하고 있다면, STC 문서 3페이지에 해당하는 모든 파라미터를 setTransactionContext 객체에 추가하세요.
    * 이 정보는 토스페이먼츠에서 관리하지 않습니다.

2. 결제하기

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

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

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

결제 요청이 성공하면 결제창을 열 때 설정한 결제 성공 페이지(successUrl)로 이동합니다.

결제 성공 페이지의 URL에는 paymentKey, orderId, amount 세 가지 쿼리 파라미터가 들어있습니다.

https://{ORIGIN}/success?paymentKey={PAYMENT_KEY}&orderId={ORDER_ID}&amount={AMOUNT}

paymentKey: 결제의 키 값입니다.
orderId: 주문 ID입니다. 결제창을 열 때 requestPayment()에 담아 보낸 값입니다.
amount: 실제로 결제된 금액입니다.

* 결제 요청이 실패하면 결제창을 열 때 설정한 결제 실패 페이지(failUrl)로 이동합니다. 결제 실패 URL을 살펴보세요.

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

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

4. 결제 승인하기

결제 승인 API를 호출해서 마지막 단계를 완료합니다. 먼저 API 인증을 위해 아래와 같이 인증 헤더 값을 만듭니다. 시크릿 키 뒤에 :을 추가하고 base64로 인코딩합니다. 콜론을 빠트리지 않도록 주의하세요.

터미널

echo -n 'test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R' + ':' | base64

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

요청

curl --request POST \
  --url https://api.tosspayments.com/v1/payments/confirm \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --data '{"paymentKey":"{PAYMENT_KEY}","amount":100,"orderId":"J7vA-o2p5dSIF4kezqGFu"}'

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

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

API 호출 결과로 HTTP 200 OK와 함께 Payment 객체가 돌아오면 결제 완료입니다.

응답

{
    "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.00,
    "method": "해외간편결제",
    "version": "2022-11-16"
}

JSON

내 테스트 API 키를 사용했다면 개발자센터 > 테스트 결제내역에서 결제 정보를 확인할 수 있지만, 외화 결제액은 정확히 표시되지 않습니다.

해외 간편결제 취소하기

라이브 환경에서 PayPal 결제를 취소하면 거래 수수료가 반환되지 않습니다.

부분 취소하는 방법

해외 간편결제로 이루어진 결제를 부분 취소할 때는 Request Body 파라미터에 currency 값을 필수로 추가해야 합니다.

요청

curl --request POST \
  --url https://api.tosspayments.com/v1/payments/{paymentKey}/cancel \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --data '{"cancelReason":"고객이 취소를 원함","cancelAmount":0.23,"currency":"USD"}'

응답은 결제 취소 API와 동일하게 Payment 객체의 cancels 필드에 취소한 기록이 쌓입니다.

응답

// Payment 객체
{
  // ...
  "cancels": [
    {
      "cancelAmount": 0.23,
      "cancelReason": "Change purchase item",
      "taxFreeAmount": 0,
      "taxExemptionAmount": 0,
      "refundableAmount": 1,
      "easyPayDiscountAmount": 0,
      "canceledAt": "2023-01-01T17:19:37+09:00",
      "transactionKey": "LRL56XIAWU93EQJUXMS0HXKN0RT5R22U",
    }
  ]
  // ...
}