Version 2
새로 나온
해외 간편결제창 연동하기
PayPal과 중국 및 동남아 결제를 결제창 SDK로 연동하는 방법입니다.
해외 간편결제에는 비동기・동기 결제 방법이 있어요. 비동기 연동 방법은 중국 및 동남아(비동기) 결제에 사용됩니다. 동기 연동 방법은 PayPal(동기) 결제에 사용됩니다. 각 방법의 차이점을 먼저 알아보세요.
비동기 결제는 클라이언트에서 결제를 요청하면 인증과 승인이 동시에 요청돼요. 결제 요청이 완료되면 pendingUrl로 이동해요. 결제 승인 결과는 서버에 연결한 웹훅으로 확인할 수 있어요. 결제 요청부터 결제 성공・실패까지 최대 10분이 소요됩니다.
pendingUrl은 Alipay 등 중국 및 동남아(비동기) 결제에서 사용하는 리다이렉트 URL입니다. 중국 및 동남아(비동기) 결제는 결제 요청 이후에 결제가 완료될 때까지 최대 10분이 소요될 수 있어요.
그렇기 때문에 서버에서 PAYMENT_STATUS_CHANGED 웹훅을 연동하고 최종 결제 결과를 웹훅으로 받아야 됩니다. pendingUrl에서 웹훅 서버를 폴링하고 결제 상태가 확정될 때까지 대기한 후에 구매자에게 안내해주세요.
웹훅 서버를 폴링하기 어렵다면 requestPayment() 메서드에 customerEmail 파라미터를 설정하세요. 결제가 완료되면 구매자에게 안내 메일이 발송됩니다.
아니요. 해외 간편결제는 successUrl, failUrl, pendingUrl 리다이렉트 URL로 응답을 확인하세요. 구매자가 결제수단 사이트로 이동하기 때문에 requestPayment() 메서드의 응답을 Promise로 받을 수 없어요.
successUrl, failUrl은 PayPal(동기) 결제에 사용됩니다. pendingUrl은 중국 및 동남아(비동기) 결제에 사용됩니다.
| 결제수단 | 코드 | 현지 통화 | 결제 연동 방법 |
|---|---|---|---|
| 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 | 비동기 |
API 키 준비하기
개발자센터의 API 키 메뉴에서 API 개별 연동 키를 확인하세요.
토스페이먼츠와 전자결제 계약 전이어도 회원가입하면 나만의 테스트 상점 키를 확인하고 테스트 결제내역, 웹훅 등 기능을 사용할 수 있어요. 로그인한 상태라면 코드의 키 값이 테스트 상점 키입니다. 로그인하지 않아도 문서 테스트 키로 테스트 연동할 수 있어요.
토스페이먼츠와 전자결제를 완료했다면 개발자센터의 API 키 메뉴에서 해외 간편결제로 계약된 상점아이디(MID)를 선택한 다음에 클라이언트 키와 시크릿 키를 확인하세요. 테스트 키와 라이브키의 차이점도 확인하고 연동을 시작하세요.
1. 결제창 띄우기
먼저 주문서 페이지에 결제창을 연동할게요. 아래 코드는 주문서 페이지의 예시에요.
스크립트 태그 또는 패키지 매니저로 토스페이먼츠 SDK를 설치하고, 클라이언트 키로 SDK를 초기화하세요. 다음, payment() 메서드로 결제창 인스턴스를 생성하세요. 아래 코드에서는 payment라는 인스턴스를 생성했어요.
그럼 이제 결제창을 띄울 준비가 됐어요. payment.requestPayment() 메서드를 호출하면 결제 요청이 시작되고, 결제창이 열려요. 메서드의 파라미터로 결제수단(FOREIGN_EASY_PAY), 주문번호, 결제금액, successUrl, failUrl, pendingUrl 등 필요한 정보를 설정하세요. 해외 간편결제는 현재 USD만 지원하고 있어요.
그리고 주문서의 '결제하기' 버튼에 결제 요청 메서드를 이벤트로 등록해주세요.
해외 간편결제사 코드입니다. 토스페이먼츠에서 지원하는 해외 간편결제사 코드와 특징은 아래 표에서 확인하세요.
| 결제수단 | 코드 | 현지 통화 | 결제 연동 방법 |
|---|---|---|---|
| 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 | 비동기 |
이용약관 동의를 받지 않고 이루어진 결제는 법적으로 유효하지 않을 수 있고, 동의 없이 개인정보를 처리하는 것은 개인정보보호법에 위배될 수 있습니다. 동의 없이 이루어진 거래로 인해 발생한 피해는 높은 배상 책임을 질 수 있습니다.
| 약관 | 링크 |
|---|---|
| 전자결제 이용약관 | - 국문: 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 |
위 코드를 실행한 다음에 '결제하기' 버튼을 누르면 provider 파라미터로 설정한 간편결제사로 이동합니다. 실제로 결제가 되지 않는 아래 토스페이먼츠 테스트 계정으로 로그인해서 결제 요청을 완료하세요. 토스페이먼츠 테스트 계정에 개인 카드 또는 계좌는 추가하지 마세요.
중국 및 동남아 간편결제는 아래 사이트에서 전용 테스트 앱을 다운로드하세요. 테스트 앱으로 Alipay, Touch 'n Go eWallet 결제수단을 테스트할 수 있어요. PayPal 결제는 별도 앱 다운로드 없이 웹에서 테스트 가능합니다.
| 결제수단 | 이메일 | 비밀번호 |
|---|---|---|
| 중국 및 동남아 간편결제 | tosspayments-antom@toss.im | tosskim123!@# |
| PayPal | tosspayments-paypal@example.com | tosskim123!@# |
2. 리다이렉트 URL로 이동하기
중국 및 동남아 간편결제 요청이 성공하면 pendingUrl로 이동해요. 쿼리 파라미터에 있는 paymentKey, orderId, amount 값을 확인하세요. 이 시점에서 결제 상태는 IN_PROGRESS입니다.
쿼리 파라미터의 amount 값과 requestPayment()의 amount 파라미터 값이 같은지 반드시 확인하세요. 클라이언트에서 결제 금액을 조작하는 행위를 방지할 수 있습니다. 만약 값이 다르다면 결제를 취소하고 구매자에게 알려주세요.
서버에 paymentKey, amount, orderId 값을 저장하세요. paymentKey는 토스페이먼츠에서 각 주문에 발급하는 고유 키 값이에요. 결제 승인, 취소, 조회 등에 사용되기 때문에 꼭 저장해주세요.
3. 결제 완료하기
중국 및 동남아 간편결제(비동기)는 결제를 요청하면 인증과 승인이 동시에 진행돼요. 결제 승인 결과는 웹훅으로 확인할 수 있어요.
개발자센터 웹훅 메뉴에서 웹훅 등록하기를 누르고 PAYMENT_STATUS_CHANGED 이벤트를 선택하세요. 웹훅을 받을 엔드포인트도 등록하세요.
결제가 최종적으로 완료되면 결제 상태가 바뀌고 등록한 엔드포인트로 아래와 같은 웹훅 이벤트가 전달돼요. 결제 요청부터 최대 10분이 소요될 수 있습니다.
웹훅 이벤트의 data 필드에서 최종 응답을 확인하세요.
4. 응답 확인하기
결제 승인이 성공했어요
결제 승인 API의 결과로 HTTP 200 OK와 함께 Payment 객체가 돌아오면 결제가 정상적으로 완료됐어요.
Payment 객체에 구매자가 선택한 결제수단 정보가 있는지 확인하세요. 해외간편결제는 아래와 같이 easyPay 필드에 결제수단 정보를 확인할 수 있어요.
응답으로 받은 Payment 객체가 아래 예시와 다르다면 API 버전을 확인하세요. 개발자센터의 API 키 메뉴에서 설정된 API 버전을 확인하고 변경할 수 있어요. API 버전 업데이트 사항은 릴리즈 노트에서 확인할 수 있습니다.
내 테스트 API 키를 사용했다면 개발자센터 > 테스트 결제내역에서 결제 정보를 확인할 수 있지만, 외화 결제액은 정확히 표시되지 않습니다.
결제 승인이 실패했어요
결제 승인에 실패하면 HTTP 4XX 또는 5XX 코드와 에러 객체를 받습니다. 결제 승인의 전체 오류 목록은 에러 코드를 참고하세요. 테스트 환경에서 결제 승인 실패를 재현해보고 싶다면 토스페이먼츠 API 테스트 헤더를 사용해보세요.
오류원인
결제 승인에서 요청에 문제가 있으면 NOT_FOUND_PAYMENT_SESSION 에러가 발생합니다.
해결 방법
-
결제 요청이 완료된 이후 10분 이내에 결제를 승인해야 됩니다. 10분이 지나면 결제 데이터가 유실되어 승인이 불가합니다.
-
결제 요청했을 때 돌려받은
paymentKey와 결제 승인에 사용한paymentKey가 같은 값인지 확인하세요. -
결제 요청에 사용한 클라이언트 키와 결제 승인에 사용한 시크릿 키가 매칭된 키값인지 확인하세요.
오류원인
카드사에서 해당 카드를 거절했을 때 REJECT_CARD_COMPANY 에러가 발생합니다. 원인은 비밀번호 오류, 한도 초과, 포인트 부족 등 다양합니다.
해결 방법
에러 메시지를 확인해서 원인을 파악하고 고객에게 올바른 안내를 해주세요.
오류원인
API 키값 또는 주문번호가 최초 요청한 값과 다르면 FORBIDDEN_REQUEST가 발생합니다.
해결 방법
-
결제 요청에 사용한 클라이언트 키와 API 호출에 사용한 시크릿 키가 매칭된 키값인지 확인하세요.
-
orderId,paymentKey값이 최초 결제 요청한 값과 같은지 확인하세요.
5. 해외 간편결제 취소하기
라이브 환경에서 취소된 해외 간편결제는 거래 수수료가 반환되지 않습니다. 결제 취소 API를 호출해서 승인된 결제를 취소하세요.
전체 취소하는 방법
결제 취소 API를 호출하세요. 중국 및 동남아 간편결제를 취소하려면 cancelRequestId를 필수로 설정해야 됩니다.
부분 취소하는 방법
해외 간편결제로 이루어진 결제를 부분 취소할 때는 Request Body 파라미터에 currency 값을 필수로 추가해야 합니다.
응답은 결제 취소 API와 동일하게 Payment 객체의 cancels 필드에 취소한 기록이 쌓입니다.
비동기 결제 취소하는 방법
중국 및 동남아 간편결제는 결제 취소도 비동기로 일어날 수 있어요. 비동기 결제 취소 결과는 CANCEL_STATUS_CHANGED 웹훅으로 확인해주세요.
결제 취소 직후 Payment 객체의 cancels.cancelStatus가 IN_PROGRESS이고, 결제 취소가 성공 또는 실패 결과를 웹훅으로 받을 수 있어요.