IMP.request_pay - param, rsp 객체

아임포트 JavaScript 라이브러리의 IMP.request_pay(param, callback)함수를 호출하면 일반 결제 프로세스를 시작할 수 있습니다. 이 때, 함수의 인자로 사용되는 param과 callback을 활용하여 원하는 내용으로 결제를 요청하고 그 결제 후의 로직을 작성할 수 있습니다.

param 객체

IMP.request_pay()함수의 첫번째 인자에는 JavaScript 객체를 지정합니다. 이를 param이라고 부르며, 결제 승인에 필요한 정보를 담게됩니다. 어떤 고객이 주문하는 것인지, 어떠한 상품을 얼마에 결제할 것인지, 해당 주문번호는 무엇인지 등, 결제에 필요한 다양한 정보를 미리 약속된 속성에 지정할 수 있습니다.

param 객체 속성

공통 속성

속성명자료형설명기본값비고
pg

(v1.1.0부터 지원)		string하나의 아임포트계정으로 여러 PG를 사용할 때 구분자undefined(선택항목) 누락되거나 매칭되지 않는 경우 아임포트 관리자페이지에서 설정한 "기본PG"가 호출됨

kakaopay, html5_inicis 와 같이 PG사명 만 지정

html5_inicis.INIpayTest 와 같이 PG사명.상점아이디 로 지정
  • html5_inicis(이니시스웹표준)
  • inicis(이니시스ActiveX결제창)
  • kcp(NHN KCP)
  • kcp_billing(NHN KCP 정기결제)
  • uplus(LGU+)
  • nice(나이스페이)
  • jtnet(JTNet)
  • kicc(한국정보통신)
  • bluewalnut(블루월넛)
  • kakaopay(카카오페이)
  • danal(다날휴대폰소액결제)
  • danal_tpay(다날일반결제)
  • mobilians(모빌리언스 휴대폰소액결제)
  • chai(차이 간편결제)
  • syrup(시럽페이)
  • payco(페이코)
  • paypal(페이팔)
  • eximbay(엑심베이)
  • naverpay(네이버페이-결제형)
  • naverco(네이버페이-주문형)
  • smilepay(스마일페이)
  • alipay(알리페이)
pay_methodstring결제수단card
  • card(신용카드)
  • trans(실시간계좌이체)
  • vbank(가상계좌)
  • phone(휴대폰소액결제)
  • samsung(삼성페이 / 이니시스, KCP 전용)
  • kpay(KPay앱 직접호출 / 이니시스 전용)
  • kakaopay(카카오페이 직접호출 / 이니시스, KCP, 나이스페이먼츠 전용)
  • payco(페이코 직접호출 / 이니시스, KCP 전용)
  • lpay(LPAY 직접호출 / 이니시스 전용)
  • ssgpay(SSG페이 직접호출 / 이니시스 전용)
  • tosspay(토스간편결제 직접호출 / 이니시스 전용)
  • cultureland(문화상품권 / 이니시스, LGU+, KCP 전용)
  • smartculture(스마트문상 / 이니시스, LGU+, KCP 전용)
  • happymoney(해피머니 / 이니시스, KCP 전용)
  • booknlife(도서문화상품권 / LGU+, KCP 전용)
  • point(베네피아 포인트 등 포인트 결제 / KCP 전용)
escrowboolean에스크로 결제여부false(선택항목) 에스크로가 적용되는 결제창을 호출
merchant_uidstring가맹점에서 생성/관리하는 고유 주문번호random(필수항목) 결제가 된 적이 있는 merchant_uid로는 재결제 불가
namestring주문명undefined(선택항목) 원활한 결제정보 확인을 위해 입력 권장 (PG사마다 차이가 있지만) 16자이내로 작성하기를 권장
amountnumber결제할 금액undefined(필수항목)
custom_dataobject가맹점 임의 지정 데이터undefined(선택항목) 주문건에 대해 부가정보를 저장할 공간이 필요할 때 사용. json notation(string)으로 저장됨
tax_freenumberamount 중 면세공급가액undefined(선택항목) 면세공급가액을 지정합니다. amount 중에서 면세공급가액에 해당하는 금액을 지정합니다.

자세히 보기
vatnumberamount 중 부가세 금액undefined(Deprecated) 복합과세 적용시 더 정확한 계산을 위해 tax_free파라메터 사용을 권장합니다. 부가세금액을 지정합니다. vat와 무관하게 amount는 고객으로부터 결제될 금액을 의미합니다.
currencystring화폐단위KRW(페이팔의 경우에는 USD가 기본값)(선택항목) KRW / USD / EUR / JPY(참조)페이팔정책상 KRW는 지원되는 결제화폐가 아니므로 USD가 기본 적용됩니다.
languagestring결제창의 언어 설정ko(선택항목) 구매자에게 제공되는 결제창 화면의 언어 설정
  1. KG이니시스, LGU+, 나이스페이먼츠 : 아래 값으로 적용 가능(KG이니시스, 나이스페이먼츠는 PC결제창만 지원됨)en 또는 ko
  2. Paypal의 경우 2자리 코드 적용 (Paypal 언어 설정 코드 참조)
buyer_namestring주문자명undefined(선택항목)
buyer_telstring주문자 연락처undefined(필수항목) 누락되거나 blank일 때 일부 PG사에서 오류 발생
buyer_emailstring주문자 Emailundefined(선택항목)
buyer_addrstring주문자 주소undefined(선택항목)
buyer_postcodestring주문자 우편번호undefined(선택항목)
notice_urlstring / array of stringNotification URLundefined(선택항목) 아임포트 관리자 페이지에서 설정하는 Notification URL을 overwrite할 수 있음. 주문마다 다른 Notification URL이 필요하거나 복수의 Notification URL이 필요한 경우 사용
displayobject결제화면과 관련한 옵션 설정undefined(선택항목) 구매자에게 제공되는 결제창 화면에 대한 UI옵션.

display 객체의 속성 항목

속성명자료형설명기본값비고
card_quotaarray of integer할부개월수 선택 UI제어옵션undefined(선택항목) 50,000원 이상금액 결제 시 PG사 결제창에서 선택할 수 있는 할부개월목록 UI 제어.
  1. undefined이면 PG사가 기본 제공하는 할부개월 수 목록을 출력
  2. []이면 일시불만 결제 가능
  3. 2,3,4,5,6이면 일시불을 포함한 2, 3, 4, 5, 6개월까지 할부개월 선택 가능. KG이니시스, KCP만 지원하는 옵션

추가 속성 - 특별한 상황에만 필요한 속성

속성명자료형설명기본값비고
digitalboolean결제상품이 컨텐츠인지 여부false(선택항목) 휴대폰소액결제시 필수. 반드시 실물/컨텐츠를 정확히 구분해주어야 함
vbank_duestring가상계좌 입금기한undefined(선택항목) YYYYMMDDhhmm 형식
m_redirect_urlstring모바일 결제 후 이동될 주소undefined(선택항목) 모바일 결제시에만 사용됨
app_schemestring모바일 앱 결제도중 앱복귀를 위한 URL schemeundefined(선택항목) WebView 결제시 필수. ISP/앱카드 앱에서 결제정보인증 후 원래 앱으로 복귀할 때 사용됨
biz_numstring계약된 사업자등록번호 10자리(기호를 포함하면 안됨)undefined(선택항목) 다날-가상계좌 결제시 반드시 설정되어야 합니다.

callback함수의 rsp 인자

IMP.request_pay()함수의 두번째 인자에는 JavaScript 함수를 지정합니다. 이를 callback함수라고 부르며, 결제 프로세스 완료 후 호출되는 함수입니다. 해당 함수가 호출될 때 결제 결과의 정보를 담고있는 rsp객체를 인자로써 가집니다. 해당 객체를 통해 결제 성공여부, 결제 에러 메시지, 결제 승인 시각 등의 정보를 확인할 수 있습니다.

rsp객체 속성

기본 속성

rsp 속성명자료형설명비고
successboolean결제처리가 성공적이었는지 여부실제 결제승인이 이뤄졌거나, 가상계좌 발급이 성공된 경우, True
error_codestring결제처리에 실패한 경우 단축메세지현재 코드체계는 없음
error_msgstring결제처리에 실패한 경우 상세메세지
imp_uidstring아임포트 거래 고유 번호아임포트에서 부여하는 거래건 당 고유한 번호(success:false일 때, 사전 validation에 실패한 경우라면 imp_uid는 null일 수 있음)
merchant_uidstring가맹점에서 생성/관리하는 고유 주문번호
pay_methodstring결제수단card(신용카드), trans(실시간계좌이체), vbank(가상계좌), phone(휴대폰소액결제), kakaopay (이니시스, KCP, 나이스페이먼츠를 통한 카카오페이 직접 호출), payco (이니시스, KCP를 통한 페이코 직접 호출), lpay (이니시스를 통한 LPAY 직접 호출), ssgpay (이니시스를 통한 SSG페이 직접 호출), tosspay (이니시스를 통한 토스간편결제 직접 호출), point (카카오페이, PAYCO, 이니시스, 나이스페이먼츠 내 간편결제 시 해당 간편결제 자체 포인트 100% 결제)
paid_amountnumber결제금액실제 결제승인된 금액이나 가상계좌 입금예정 금액
statusstring결제상태ready(미결제), paid(결제완료), cancelled(결제취소, 부분취소포함), failed(결제실패)
namestring주문명
pg_providerstring결제승인/시도된 PG사html5_inicis(웹표준방식의 KG이니시스), inicis(일반 KG이니시스), kakaopay(카카오페이), uplus(LGU+), nice(나이스정보통신), jtnet(JTNet), danal(다날)
pg_tidstringPG사 거래고유번호
buyer_namestring주문자 이름
buyer_emailstring주문자 Email
buyer_telstring주문자 연락처
buyer_addrstring주문자 주소
buyer_postcodestring주문자 우편번호
custom_dataobject가맹점 임의 지정 데이터
paid_atnumber결제승인시각UNIX timestamp
receipt_urlstringPG사에서 발행되는 거래 매출전표 URL전달되는 URL을 그대로 open하면 매출전표 확인가능

추가 속성

rsp 속성명자료형설명비고
apply_numstring카드사 승인번호신용카드결제에 한하여 제공
vbank_numstring가상계좌 입금계좌번호PG사로부터 전달된 정보 그대로 제공하므로 숫자 외 dash(-)또는 기타 기호가 포함되어 있을 수 있음
vbank_namestring가상계좌 은행명
vbank_holderstring가상계좌 예금주계약된 사업자명으로 항상 일정함. 단, 일부 PG사의 경우 null반환하므로 자체 처리 필요
vbank_datenumber가상계좌 입금기한UNIX timestamp