아임포트 JavaScript SDK


아임포트 JavaScript SDK를 사용하면 웹사이트 또는 앱에서 결제창 또는 본인인증창과 연동할 수 있습니다.

버전 내역 및 각 버전의 주요 변경 사항은 릴리스 노트를 참조하세요.

SDK Library 로드하기

아임포트 JavaScript SDK를 사용하기 위해서 먼저 해당 라이브러리를 다음과 같이 페이지에 추가해야 합니다. 해당 라이브러리는 CDN(https://cdn.iamport.kr/js/iamport.payment-{SDK-최신버전}.js)을 통한 사용을 권장합니다. 라이브러리가 로드되면, IMP 전역 객체를 window 객체의 프로퍼티로 접근하여 IMP의 함수들을 호출할 수 있습니다.

최신 라이브러리 버전 정보아임포트 JavaScript SDK Release Notes 페이지에서 확인하세요.
  <!-- jQuery -->
  <script type="text/javascript" src="https://code.jquery.com/jquery-1.12.4.min.js" ></script>
  <!-- iamport.payment.js -->
  <script type="text/javascript" src="https://cdn.iamport.kr/js/iamport.payment-{SDK-최신버전}.js"></script>

jQuery 1.0 이상이 설치되어 있어야 합니다.

전역 객채: IMP

IMP 함수

request_pay

certification

request_pay(param, callback)

PG사의 결제창을 호출한다. PG사 또는 결제 환경에 따라서 iframe 또는 리디렉션 방식으로 결제창을 호출합니다.

파라미터

param (Object)

결제 승인에 필요한 정보.

속성

속성

* 필수항목
타입

(기본값)
설명
pg

(v1.1.0부터 지원)
string 하나의 아임포트계정으로 여러 PG를 사용할 때 구분자

누락되거나 매칭되지 않는 경우 관리자 콘솔에서 설정한 기본PG가 호출됨

값 형식: [PG사 코드값] 또는 [PG사 코드값].[PG사 상점아이디]

PG사 코드값
  • html5_inicis(이니시스웹표준)
  • inicis(이니시스ActiveX결제창)
  • kcp(NHN KCP)
  • kcp_billing(NHN KCP 정기결제)
  • uplus(토스페이먼츠(구 LG U+))
  • nice(나이스페이)
  • jtnet(JTNet)
  • kicc(한국정보통신)
  • bluewalnut(블루월넛)
  • kakaopay(카카오페이)
  • danal(다날휴대폰소액결제)
  • danal_tpay(다날일반결제)
  • mobilians(모빌리언스 휴대폰소액결제)
  • chai(차이 간편결제)
  • syrup(시럽페이)
  • payco(페이코)
  • paypal(페이팔)
  • eximbay(엑심베이)
  • naverpay(네이버페이-결제형)
  • naverco(네이버페이-주문형)
  • smilepay(스마일페이)
  • alipay(알리페이)


pay_method*string

(card)
결제수단

옵션 값
  • card(신용카드)
  • trans(실시간계좌이체)
  • vbank(가상계좌)
  • phone(휴대폰소액결제)
  • samsung(삼성페이 / 이니시스, KCP 전용)
  • kpay(KPay앱 직접호출 / 이니시스 전용)
  • kakaopay(카카오페이 직접호출 / 이니시스, KCP, 나이스페이먼츠 전용)
  • payco(페이코 직접호출 / 이니시스, KCP 전용)
  • lpay(LPAY 직접호출 / 이니시스 전용)
  • ssgpay(SSG페이 직접호출 / 이니시스 전용)
  • tosspay(토스간편결제 직접호출 / 이니시스 전용)
  • cultureland(문화상품권 / 이니시스, 토스페이먼츠(구 LG U+), KCP 전용)
  • smartculture(스마트문상 / 이니시스, 토스페이먼츠(구 LG U+), KCP 전용)
  • happymoney(해피머니 / 이니시스, KCP 전용)
  • booknlife(도서문화상품권 / 토스페이먼츠(구 LG U+), KCP 전용)
  • point(베네피아 포인트 등 포인트 결제 / KCP 전용)
escrowboolean

(false)
에스크로가 적용되는 결제창을 호출할지 여부
merchant_uid*string가맹점에서 생성/관리하는 고유 주문번호

이미 결제가 승인 된(status: paid) merchant_uid로는 재결제 불가
namestring주문명

원활한 결제정보 확인을 위해 입력 권장

PG사마다 차이가 있지만, 16자이내로 작성 권장
amount*number결제할 금액
custom_dataobject가맹점 임의 지정 데이터

주문건에 대해 부가정보를 저장할 공간이 필요할 때 사용

json notation(string)으로 저장됨
tax_freenumberamount 중 면세공급가액에 해당하는 금액

자세히 보기
vat

Deprecated
numberamount 중 부가세 금액

복합과세 적용시 더 정확한 계산을 위해 tax_free 파라미터 사용을 권장
currencystring

(KRW)
통화 설정

PayPal은 원화(KRW) 미지원으로 USD가 기본값

PayPal에서 지원하는 통화는 PayPal 지원 통화 참조

옵션 값
  • KRW
  • USD
  • EUR
  • JPY


languagestring

(ko)
결제창 화면의 언어 설정
  • KG이니시스, 토스페이먼츠(구 LG U+), 나이스페이먼츠 : en 또는 ko(KG이니시스, 나이스페이먼츠는 PC 결제창만 지원됨)
  • PayPal: 2자리 region code(PayPal 로케일 코드 참조)
buyer_namestring주문자명
buyer_tel*string주문자 연락처(누락되거나 공백일때 일부 PG사에서 오류 발생)
buyer_emailstring주문자 이메일
buyer_addrstring주문자 주소
buyer_postcodestring주문자 우편번호
notice_urlstring /

array of string
관리자 콘솔에서 설정하는 Notification URL대신 사용할 URL

주문마다 다른 혹은 복수의 Notification URL이 필요한 경우 사용
displayobject결제화면 구성 설정

param.display (Object)

속성

* 필수항목
타입

(기본값)
설명
card_quotaarray of integer50,000원 이상 금액 결제 시, 할부개월 수 선택 요소 제어 옵션
  • 미입력: PG사의 기본 할부개월 수 목록 제공
  • []: 일시불만 결제 가능
  • 2,3,4,5,6: 일시불을 포함한 2, 3, 4, 5, 6개월까지 할부개월 선택 가능(KG이니시스, KCP만 지원)

추가 속성

속성

* 필수항목
타입

(기본값)
설명
digitalboolean

(false)
결제상품이 컨텐츠인지 여부(휴대폰 소액결제시 필수)

반드시 실물/컨텐츠를 정확히 구분해주어야 함
vbank_duestring가상계좌 입금기한(YYYYMMDDhhmm)
m_redirect_urlstring리디렉션 방식으로 호출된 결제창에서 결제 후에 이동 될 주소
app_schemestring모바일 앱 결제중 앱복귀를 위한 URL scheme(WebView 결제시 필수)

ISP/앱카드 앱에서 결제정보인증 후 기존 앱으로 복귀할 때 사용됨
biz_numstring계약된 사업자등록번호 10자리(기호 미포함)

다날-가상계좌 결제시 필수 항목

callback (Function)

  function (rsp) { ... }
iframe 방식으로 호출된 결제창에서 결제 후 호출되는 함수.

파라미터

rsp (Object)

결제 요청에 대해 반환되는 응답 정보.

PG사/결제수단 별 속성

PG사 또는 결제수단에 따라서 반환되는 속성들이 상이합니다. 기본적으로 반환되는 속성들은 필수항목(*)으로 표시됩니다.

응답 필드 추가에 대한 아임포트 정책 안내

아임포트 서비스 성능 개선을 위해서 응답 필드 추가 작업은 상시로 발생할 수 있습니다. 가맹점에서 서비스 영향 여부 확인이 필요하다고 판단될 경우, 아임포트 공지사항에 공유됩니다.

속성

속성

* 필수항목
타입설명
success*

(PG사/결제수단에 따라 imp_success로 반환됨)
boolean결제의 성공여부

결제승인 혹은 가상계좌 발급이 성공한 경우, True
error_code*string결제가 실패한 경우 단축 메세지(현재 코드체계는 없음)
error_msg*string결제가 실패한 경우 상세 메세지
imp_uid*string아임포트 고유 결제번호

success가 false이고 사전 validation에 실패한 경우, imp_uid는 null일 수 있음
merchant_uid*string가맹점에서 생성/관리하는 고유 주문번호
pay_methodstring결제수단

옵션 값
  • card(신용카드)
  • trans(실시간계좌이체)
  • vbank(가상계좌)
  • phone(휴대폰소액결제)
  • kakaopay (이니시스, KCP, 나이스페이먼츠를 통한 카카오페이 직접 호출)
  • payco (이니시스, KCP를 통한 페이코 직접 호출)
  • lpay (이니시스를 통한 LPAY 직접 호출)
  • ssgpay (이니시스를 통한 SSG페이 직접 호출)
  • tosspay (이니시스를 통한 토스간편결제 직접 호출)
  • point (카카오페이, PAYCO, 이니시스, 나이스페이먼츠 내 간편결제 시 해당 간편결제 자체 포인트 100% 결제)

paid_amountnumber결제금액

결제승인된 또는 가상계좌 입금예정 금액
statusstring결제상태

옵션 값
  • ready(브라우저 창 이탈, 가상계좌 발급 완료 등 미결제 상태)
  • paid(결제완료)
  • failed(신용카드 한도 초과, 체크카드 잔액 부족, 브라우저 창 종료 또는 취소 버튼 클릭 등 결제실패 상태)


namestring주문명
pg_providerstring결제승인/시도된 PG사

옵션 값
  • html5_inicis(웹표준방식의 KG이니시스)
  • inicis(일반 KG이니시스)
  • kakaopay(카카오페이)
  • uplus(토스페이먼츠(구 LG U+))
  • nice(나이스정보통신)
  • jtnet(JTNet)
  • danal(다날)


emb_pg_providerstring결제창에서 간편결제 호출시 결제 승인된 PG사KG이니시스, NHN KCP에서 pay_method = card 일때, 결제창에서 선택한 간편결제 PG사( Naver Pay, Kako Pay, Payco, Samsung Pay, SSG Pay, L.pay, Kpay )
pg_tidstringPG사 거래고유번호
buyer_namestring주문자 이름
buyer_emailstring주문자 Email
buyer_telstring주문자 연락처
buyer_addrstring주문자 주소
buyer_postcodestring주문자 우편번호
custom_dataobject가맹점 임의 지정 데이터
paid_atnumber결제승인시각(UNIX timestamp)
receipt_urlstringPG사에서 발행되는 거래 매출전표 URL

전달되는 URL을 클릭하면 매출전표 확인가능

추가 속성

속성타입설명
apply_numstring카드사 승인번호(신용카드결제에 한하여 제공)
vbank_numstring가상계좌 입금계좌번호

PG사로부터 전달된 정보 그대로 제공하므로 숫자 외 dash(-)또는 기타 기호가 포함되어 있을 수 있음
vbank_namestring가상계좌 은행명
vbank_holderstring가상계좌 예금주

계약된 사업자명으로 표시됨, 단, 일부 PG사의 경우 null을 반환하므로 자체 처리 필요
vbank_datenumber가상계좌 입금기한(UNIX timestamp)


certification(param, callback)

PG사의 휴대폰 또는 신용카드 본인인증 창을 호출한다.

파라미터

param (Object)

본인인증 요청에 필요한 정보.

속성

속성

* 필수항목
타입

(기본값)
설명
merchant_uid

(v1.1.4부터 지원)
string가맹점에서 생성/관리하는 고유 주문번호
min_age

(v1.1.4부터 지원)
number허용하는 최소 만 나이 (생일기준)
name

(v1.1.4부터 지원)
string고객 이름

본인인증 화면 내 이름 필드에 자동입력됨
phone

(v1.1.4부터 지원)
string고객 전화번호 (-, . 등 구분자 포함가능)

본인인증 화면 내 전화번호 필드에 자동입력됨
carrier

(v1.1.4부터 지원)
string본인인증 통신사

본인인증 화면에서 선택 가능한 통신사 설정

옵션 값
  • SKT : SKT
  • KT : KTF
  • LGU+ : LGT
  • 알뜰폰 : MVNO

birth

(v1.1.4부터 지원)
string본인인증 대상 생년월일 지정 다날 정책에 의해 더이상 해당 파라미터는 지원하지 않습니다

본인인증 화면 내 생년월일 필드를 자동입력합니다. 통신사 규약에 맞게 숫자 이외의 값은 아임포트 차원에서 제거하기때문에 19821231 또는 1982-12-31YYYYMMDD생년월일 8자리 숫자가 포함 된 문자열을 자유로운 형태로 지정가능합니다.
company

(v1.1.4부터 지원)
string

(본 함수가 호출되는 URL)
서비스 도메인 URL 또는 명칭

  • 서비스의 대표 도메인 URL(예 : https://www.iamport.co.kr) 또는 서비스 명칭(예 : 아임포트)으로 설정
  • 본인인증 동작에 영향을 주지는 않지만, KISA의 ePrivacy Clean 서비스 연동을 위해 설정 권장
  • ReactNative / Ionic 등 앱 내 local html을 통해 본 함수가 호출되는 경우, URL 도메인을 인식할 수 없으므로 설정 권장(미 설정 시: 아임포트)

m_redirect_url

(v1.1.7부터 지원)
string모바일 환경에서 본인인증 후 리디렉션될 URL

리디렉션될 때, query string 으로 imp_uid, merchant_uid, success 가 전달됨
popup

(모바일에만 적용, v1.1.7부터 지원)
boolean

(false)
새 창에 본인인증 화면 생성 여부

PC: popup : true 옵션이 강제 적용됨

모바일: popup : false 사용시, m_redirect_url 필수 입력

callback (Function)

  function (rsp) { ... }
iframe 방식으로 호출된 본인 인증창에서 인증 후 호출되는 함수.

파라미터

rsp (Object)

본인인증 요청에 대해 반환되는 응답 정보.

속성

속성

* 필수항목
타입설명
success*boolean본인인증의 성공여부

true/false
error_code*string본인인증이 실패한 경우 단축 메세지(현재 코드체계는 없음)
error_msg*string본인인증이 실패한 경우 상세 메세지
imp_uid*string아임포트 고유 본인인증 번호
merchant_uid*string가맹점에서 생성/관리하는 고유 주문번호