Version 2

해외결제 연동하기

주문서형, 결제창형으로 해외 카드와 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를 파라미터로 설정하세요.