Version 1

해외 간편결제창 연동하기

결제창 SDK v1은 더 이상 업데이트되지 않습니다. 토스페이먼츠 SDK v2 연동을 추천합니다.

API 키 준비하기

결제창은 API 개별 연동 키로 연동하세요. 토스페이먼츠에 회원가입하기 전이라면, 다음 문서 테스트 키로 연동할 수 있어요. 토스페이먼츠에 회원가입했다면, 로그인 후 다음 내 테스트 키로 결제를 연동하고 개발자센터에서 테스트 결제내역을 확인하세요.

비동기・동기 결제 방법

비동기 연동 방법은 중국 및 동남아(비동기) 결제에 사용됩니다. 동기 연동 방법은 PayPal(동기) 결제에 사용됩니다. 각 방법의 차이점을 먼저 알아보세요. 인증과 승인을 더 깊이 이해하고 싶다면 결제 흐름 이해하기를 참고하세요.

반면 비동기 결제는 클라이언트에서 결제를 요청하면 인증과 승인이 동시에 요청돼요. 결제 요청이 완료되면 pendingUrl로 이동해요. 결제 승인 결과는 서버에 연결한 웹훅으로 확인할 수 있어요. 결제 요청부터 결제 성공・실패까지 최대 10분이 소요됩니다.

pendingUrl은 뭔가요?

pendingUrl은 Alipay 등 중국 및 동남아(비동기) 결제에서 사용하는 리다이렉트 URL입니다. 중국 및 동남아(비동기) 결제는 결제 요청 이후에 결제가 완료될 때까지 최대 10분이 소요될 수 있어요.

그렇기 때문에 서버에서 PAYMENT_STATUS_CHANGED 웹훅을 연동하고 최종 결제 결과를 웹훅으로 받아야 됩니다. pendingUrl에서 웹훅 서버를 폴링하고 결제 상태가 확정될 때까지 대기한 후에 구매자에게 안내해주세요.

웹훅 서버를 폴링하기 어렵다면 requestPayment() 메서드에 customerEmail 파라미터를 설정하세요. 결제가 완료되면 구매자에게 안내 메일이 발송됩니다.

결제 요청 결과를 Promise로 받을 수 있나요?

아니요. 해외 간편결제는 successUrl, failUrl, pendingUrl 리다이렉트 URL로 응답을 확인하세요. 구매자가 결제수단 사이트로 이동하기 때문에 requestPayment() 메서드의 응답을 Promise로 받을 수 없어요.

successUrl, failUrl은 PayPal(동기) 결제에 사용됩니다. pendingUrl은 중국 및 동남아(비동기) 결제에 사용됩니다.

1. 결제창 띄우기

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

결제창을 띄우기 전에 구매자의 이용약관 동의를 반드시 받으세요

이용약관 동의를 받지 않고 이루어진 결제는 법적으로 유효하지 않을 수 있고, 동의 없이 개인정보를 처리하는 것은 개인정보보호법에 위배될 수 있습니다. 동의 없이 이루어진 거래로 인해 발생한 피해는 높은 배상 책임을 질 수 있습니다.

약관	링크
전자결제 이용약관	- 국문: https://pages.tosspayments.com/terms/user - 영문: https://pages.tosspayments.com/terms/user/en/
개인(신용)정보 수집·이용 동의	- 국문: https://pages.tosspayments.com/terms/privacy/consent1/kr - 영문: https://pages.tosspayments.com/terms/privacy/consent1/en
개인(신용)정보 제3자 제공 동의	- 국문: https://pages.tosspayments.com/terms/privacy/consent2/kr - 영문: https://pages.tosspayments.com/terms/privacy/consent2/en
개인(신용)정보 국외 이전 동의	- 국문: https://pages.tosspayments.com/terms/privacy/consent_overseas/kr - 영문: https://pages.tosspayments.com/terms/privacy/consent_overseas/en

결제 정보 파라미터

amount 필수 · number
결제되는 금액입니다.
orderId 필수 · string
주문번호입니다. 주문을 구분하는 ID입니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.
orderName 필수 · string
구매상품입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.

provider 필수 · string

해외 간편결제사 코드입니다. 토스페이먼츠에서 지원하는 해외 간편결제사 코드와 특징은 아래 표에서 확인하세요.

결제수단	코드	현지 통화	결제 연동 방법
Alipay	`ALIPAY`	CNY	비동기
AlipayHK	`ALIPAYHK`	HKD	비동기
BillEase	`BILLEASE`	PHP	비동기
Boost	`BOOST`	MYR	비동기
BPI	`BPI`	PHP	비동기
DANA	`DANA`	IDR	비동기
GCash	`GCASH`	PHP	비동기
PayPal	`PAYPAL`/`페이팔`	구매자의 현지 통화	동기
Rabbit LINE Pay	`RABBIT_LINE_PAY`	THB	비동기
Touch 'n Go eWallet	`TOUCHNGO`	MYR	비동기
TrueMoney Wallet	`TRUEMONEY`	THB	비동기

currency 필수 · string
결제 통화입니다. 해외 간편결제는 USD만 지원해요. USD로 금액을 올리면 결제창에서 자동으로 현지 통화로 환전됩니다.
country 필수 · string
구매자의 결제 국가입니다. ISO-3166의 두 자리 국가 코드를 모두 지원합니다.
successUrl string
PayPal(동기) 결제가 성공하면 리다이렉트되는 URL입니다. 결제 승인 처리에 필요한 값들이 쿼리 파라미터로 함께 전달됩니다. 반드시 오리진을 포함해야 합니다. 예를 들면 https://www.example.com/success와 같은 형태입니다.
failUrl string
PayPal(동기) 결제가 실패하면 리다이렉트되는 URL입니다. 에러 코드 및 에러 메시지가 쿼리 파라미터로 함께 전송됩니다. 반드시 오리진을 포함해야 합니다.
pendingUrl string
중국 및 동남아 간편결제(비동기)의 결제 요청이 완료되면 리다이렉트되는 URL입니다. 반드시 오리진을 포함해야 합니다.
customerName string
구매자명입니다. 최대 길이는 100자입니다.
customerEmail string
구매자의 이메일 주소입니다. 결제 상태가 바뀌면 이메일 주소로 결제내역이 전송됩니다. 최대 길이는 100자입니다.
taxFreeAmount number
면세 금액입니다.

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

PayPal에서 제공하는 판매자 보호 및 위험 거래 관리 서비스를 사용하고 싶다면 아래 파라미터를 필수로 보내세요.

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

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

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

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

구매자의 'full_name'을 수집하고 있는데, 이 경우 전체 이름을 한 필드에 보내도 되나요?

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

products array
고객이 구매한 각 상품의 상세 정보 객체를 담는 배열입니다. 예를 들어 고객이 세 가지 종류의 상품을 구매했다면 길이가 3인 배열이어야 합니다.
- 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
    배송지 우편번호입니다. 중국, 일본, 프랑스, 독일 등 일부 국가에서 일어나는 PayPal 거래에는 postalCode가 필수 파라미터입니다.

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. 결제 요청하기

결제 요청 메서드를 호출하면 결제창이 열려요. 실제로 결제가 되지 않는 아래 테스트 계정으로 로그인해서 결제 요청을 완료하세요. 결제 금액은 현지 통화로 노출됩니다.

중국 및 동남아 간편결제는 아래 사이트에서 전용 테스트 앱을 다운로드하세요. 테스트 앱으로 Alipay, Touch 'n Go eWallet 결제수단을 테스트할 수 있어요. PayPal 결제는 별도 앱 다운로드 없이 웹에서 테스트 가능합니다.

테스트 앱 다운로드하기

테스트 앱 사용하기

결제수단	이메일	비밀번호
중국 및 동남아 간편결제	tosspayments-antom@toss.im	tosskim123!@#
PayPal	tosspayments-paypal@example.com	tosskim123!@#

3. 리다이렉트 URL로 이동하기

중국 및 동남아 간편결제 요청이 성공하면 pendingUrl로 이동해요. 쿼리 파라미터에 있는 paymentKey, orderId, amount 값을 확인하세요. 이 시점에서 결제 상태는 IN_PROGRESS입니다.

쿼리 파라미터를 확인하고 저장하세요.

paymentKey: 토스페이먼츠에서 발급하는 결제의 키 값입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 값이 유지됩니다. 결제 승인에 사용됩니다.
orderId: 주문번호입니다. requestPayment()에 담아 보낸 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 값이 유지됩니다.
amount: 실제로 결제된 금액입니다. requestPayment() 메서드에 담아 보낸 결제 금액과 같은지 반드시 확인해보세요. 만약 값이 다르다면 결제를 취소하고 구매자에게 알려주세요.

4. 결제 완료하기

중국 및 동남아 간편결제(비동기)는 결제 요청으로 인증과 승인이 동시에 요청돼요. 결제 승인 결과는 웹훅으로 확인할 수 있어요.

웹훅으로 결과받기

개발자센터 웹훅 메뉴에서 웹훅 등록하기를 누르고 PAYMENT_STATUS_CHANGED 이벤트를 선택하세요. 웹훅을 받을 엔드포인트도 등록하세요. 결제가 최종적으로 완료되면 결제 상태가 바뀌고 등록한 엔드포인트로 아래와 같은 웹훅 이벤트가 전달돼요. 결제 요청부터 최대 10분이 소요될 수 있습니다.

웹훅 이벤트의 data 필드에서 Payment 객체를 확인하세요.

totalAmount가 requestPayment() 메서드에 담아 보낸 결제 금액과 같은지 반드시 확인해보세요. 만약 값이 다르다면 결제를 취소하고 구매자에게 알려주세요.
해외 간편결제의 easyPay 필드에는 고객이 선택한 결제수단 코드가 문자열로 돌아옵니다.

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

5. 결제 취소하기

라이브 환경에서 취소된 해외 간편결제는 거래 수수료가 반환되지 않습니다. 결제 취소 API를 호출해서 승인된 결제를 취소하세요.

Path 파라미터

paymentKey 필수 · string
결제 승인 결과에서 확인한 결제의 키 값입니다. 최대 길이는 200자입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다.

Request Body 파라미터

cancelReason 필수 · string
결제를 취소하는 이유입니다. 최대 길이는 200자입니다.
cancelRequestId string
취소 거래를 구분하는 값입니다. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열을 발급하세요. 각 취소 거래에 고유 값을 발급하세요. 중국 및 동남아(비동기) 결제에만 필수로 사용되는 특수 값입니다.
cancelAmount string
취소할 금액입니다. 값이 없으면 전액 취소됩니다.
currency string
취소 통화입니다. 해외 간편결제를 부분 취소할 때는 필수입니다.

비동기 결제 취소하는 방법

중국 및 동남아 간편결제는 결제 취소도 비동기로 일어날 수 있어요. 비동기 결제 취소 결과는 CANCEL_STATUS_CHANGED 웹훅으로 확인해주세요. 결제 취소 직후 Payment 객체의 cancels.cancelStatus가 IN_PROGRESS이고, 결제 취소가 성공 또는 실패 결과를 웹훅으로 받을 수 있어요.