해외결제 연동하기

결제위젯으로 해외 카드와 PayPal을 연동하는 방법을 알아볼게요. 국내에 거주하는 외국인 또는 해외 구매자에게 상품을 판매할 때 사용하세요.

해외결제 비교

	해외 카드	PayPal
설명	해외 카드는 대한민국이 아닌 국가에서 발급한 카드예요. 국내 카드사가 발급한 BIN에 속하지 않은 모든 카드를 해외 카드로 볼 수 있어요.	PayPal은 전 세계 200여 개 국가에서 4억 명 이상이 사용하는 글로벌 결제수단이에요. 부정거래 방지 시스템을 갖고 있기 때문에 믿고 쓸 수 있어요.
결제수단	해외에서 발행된 VISA, MASTER, JCB, 유니온페이 카드 등	카드
결제 통화	KRW (기본), 다통화(USD, JPY 등) 별도 계약 가능	USD

계약이 완료되면 상점관리자의 결제위젯 어드민에서 해외결제를 설정하세요.

결제수단	어드민 설정 위치
해외 카드(KRW)	국내 카드 MID → 이용서비스 - 일반결제 → 기능 > 카드사 목록에서 확인
외화결제(USD 해외 카드, PayPal 등)	외화결제 MID → 이용서비스 - 외화결제에서 설정 (추가하기 +)

설정을 완료하면 어드민에서 variantKey 값을 확인할 수 있어요. 이 값을 연동 코드에 사용합니다.

* 위 이미지는 "해외간편결제"로 표시되지만, 현재는 "외화결제"로 변경되었어요.

하나의 MID는 하나의 통화만 가질 수 있어요. 원화와 외화를 모두 지원하려면 MID별로 결제위젯을 따로 구성하세요.

MID	함께 사용할 수 있는 결제수단
KRW MID	국내 카드 + 해외 카드(KRW)
USD MID	해외 카드(USD) + PayPal

해외결제 연동은 일반 결제위젯 연동과 동일해요. 핵심은 통화 설정과 variantKey 두 가지예요.

widgets.setAmount()에서 결제 통화를 설정하고, renderPaymentMethods()에 어드민에서 확인한 variantKey를 넣어주세요.

나머지 연동 흐름(결제 요청, 리다이렉트, 승인)은 일반 결제위젯 연동과 동일해요. 자세한 코드는 결제위젯(주문서형) 연동하기 또는 결제위젯(결제창형) 연동하기를 참고하세요.

PayPal 결제는 requestPayment() 호출 시 foreignEasyPay 파라미터가 필요해요. 상품 정보, 배송 정보 등을 포함해야 PayPal의 판매자 보호를 받을 수 있어요. 자세한 코드와 파라미터는 PayPal 연동하기를 참고하세요.

해외 결제를 테스트할 수 있는 테스트용 카드 번호예요. 유니온페이는 테스트 환경에서 사용할 수 없어요.

카드사	카드 번호	유효기간	의미
비자	4242 4242 4242 4242	임의의 미래 날짜, yy/mm 형식	거래 승인
마스터	5555 5555 5555 4444	임의의 미래 날짜, yy/mm 형식	거래 승인
JCB	3530 1113 3330 0000	임의의 미래 날짜, yy/mm 형식	거래 승인

거래 실패 케이스를 테스트하려면 테스트 코드 헤더 사용하기를 사용하세요.

PayPal 결제를 테스트하려면 PayPal Developer Dashboard에서 Sandbox 계정이 필요해요.

PayPal Developer Dashboard에 가입하세요.
Testing Tools > Sandbox Accounts 메뉴에서 Create account 버튼을 눌러 테스트용 개인 계정(Personal)을 만드세요.
생성된 Sandbox 계정의 이메일과 비밀번호로 PayPal 결제창에서 로그인하면 테스트 결제를 완료할 수 있어요.

Sandbox 계정은 실제 결제가 발생하지 않는 테스트 전용 계정이에요.

해외 구매자에게 영문으로 이용약관을 보여주고 싶다면, 상점관리자에서 영문 이용약관을 추가하세요.

이용약관을 렌더링하는 메서드에서 영문 이용약관의 variantKey를 파라미터로 설정하세요.