⌨️페이팔 SPB 일반결제
페이팔 SPB(Smart Payment Buttons) 일반결제 연동 방법을 안내합니다.
페이팔 SPB 일반결제는 SDK 1.3.0 부터 사용 가능합니다.
SDK 스크립트의 주소가 https://cdn.iamport.kr/v1/iamport.js 인지 확인해주세요.
기존에 deprecated된 응답들은 모두 제거됐습니다. ⚠️
페이팔 연동시에 사용되는 신규 JS SDK는 기존 모듈에서 제공했던 CallBack 파라미터가 대부분 삭제되었습니다.(특히 dprecated 로 명시된 파라미터는 모두 삭제되었습니다.)
해당 JS SDK 사용시 Callback 으로 내려받을수 있는 데이터는 오직 아래 두가지 입니다.
imp_uid, merchant_uid
따라서 해당 SDK를 사용하실때는 IMP.request_pay로부터 응답된 객체(또는 쿼리 파라미터)에서 imp_uid를 가지고 아임포트 REST API(GET /payments/imp_uid)로 결제 상세 내역(승인 상태, 승인 결과 등등)을 조회하여 응답파라미터중 status 파라미터로 결제 상태를 파악하셔야 합니다.
페이팔 SPB 버튼 렌더링
페이팔 SPB 일반결제는 가맹점 체크아웃 페이지에 페이팔 SPB 버튼(아래 이미지 참고)을 렌더링 한 후, 이 SPB 버튼을 클릭해 페이팔 결제창을 호출하는 방식입니다.
따라서 다른 PG사와 결제 플로우가 상이하기 때문에 가맹점은 체크아웃 페이지가 렌더링 되는 시점에 IMP.request_pay
함수 대신 IMP.loadUI
라는 별도의 함수를 호출해 페이팔 SPB 버튼을 렌더링 해야합니다.
페이팔 SPB 버튼이 보이지 않을 때
portone-ui-container
라는 class 이름을 갖는 div element를 찾지 못할 경우 "portone-ui-container를 찾을 수 없습니다." 라는 에러가 발생합니다.
portone-ui-container
element가 2개 이상인데, data-portone-ui-type
attribute가 paypal-spb
인 element를 찾지 못할 경우, "data-portone-ui-type에 올바른 UI 타입을 입력해주세요."라는 에러가 발생합니다.
portone-ui-container
element가 2개 이상이고, data-portone-ui-type
attribute가 paypal-spb
인 elemente도 2개 이상인 경우, “동일한 data-portone-ui-type을 갖는 DOM element가 2개 이상 존재합니다."라는 에러가 발생합니다.
결제 요청 데이터 업데이트
페이팔 SPB 동작의 특성상, 가맹점 체크아웃 페이지가 렌더링 될 때 결제 요청 데이터가 결정 되어야 합니다. 때문에 가맹점 체크아웃 페이지 등에서 구매자의 정보(이름, 주소 등)를 입력한다거나 포인트 등을 적용 해 결제 금액이 바뀌는 경우에는 그 다음 페이지로 이동해 최종적으로 결정 된 구매 정보를 기준으로 페이팔 버튼을 렌더링 시켜야 합니다. 페이팔 데모 페이지에서도 같은 방식으로 구현되어있습니다.
하지만 페이팔 SPB 때문에 페이지를 하나 더 만드는 것은 가맹점 입장에서 매우 번거로운 일이기 때문에 포트원에서는 처음 페이팔 버튼을 렌더링 시킨 후, 페이팔 버튼을 누르기 전 주문 정보가 바뀌었을때 “결제 요청 데이터”를 업데이트 할 수 있는 IMP.updateLoadUIRequest
함수를 제공하고 있습니다.
구매자 입력으로 인해 결제 요청 데이터가 변경될때 IMP.updateLoadUIRequest
함수를 호출하시면 구매자가 페이팔 결제 버튼을 누를때 최종적으로 변경 된 결제 요청 데이터로 페이팔 결제창이 호출됩니다.
loadUI 요청 객체
파라미터 | 데이터타입 | 필수여부 | 의미 |
---|---|---|---|
merchant_uid | string | required | 가맹점 채번 주문 고유 번호 |
name | string | optional | 제품명 |
amount | number | required | 금액 |
pg | string | required | paypal_v2 |
string | optional | 결제수단 | |
string | optional | 국가 코드 주의: 페이팔 SPB 테스트 모드시에만 유효 | |
customer_id | string | optional | 가맹점이 구매자를 특정하기 위해 채번한 고유 번호 |
buyer_name | string | optional | 구매자 전체 이름 |
string | optional | 구매자 이름 주의: 페이팔에서만 유효하며 buyer_name이 아닌 buyer_first_name과 buyer_last_name 입력을 권장 | |
string | optional | 구매자 성 주의: 페이팔에서만 유효하며 buyer_name이 아닌 buyer_first_name과 buyer_last_name 입력을 권장 | |
buyer_tel | string | optional | 구매자 전화번호 |
buyer_email | string | optional | 구매자 이메일 주소 |
notice_url | string | optional | 결제 창에서 결제 승인 완료 또는 가상계좌 발급 완료시 가맹점에게 노티 될 웹훅 URL string 또는 string[]로 N개 설정 가능 웹훅이 잘 발송 됐는지는 결제 승인 내역에서 아임포트 번호를 눌러봤을때 웹훅 발송 내역을 보고 확인할 수 있음 |
confirm_url | string | optional | 결제창이 호출되고 구매자가 최종 결제 승인을 하기까지 수량 소진 등 모종의 사유로 더이상 결제가 불가능 하게 되는 상황을 대비해, 최종 결제 승인 직전 최종 결제 승인 여부를 질의할 가맹점 웹서버 endpoint 아임포트가 해당 endpoint로 최종 결제 승인 질의시, 200 외의 응답을 받으면 최종 결제 승인을 시키지 않고 결제 실패 상태로 기록함 주의: 아임포트 CS팀으로 해당 기능 사용 신청을 해야 함 |
array | optional | 결제 상품 정보 | |
string | optional | 결제 통화 (기본값: USD) | |
custom_data | object | optional | 결제 정보와 함께 관리하고 싶은 가맹점 커스텀 JSON 데이터 |
파라미터 유의사항
아래 링크로 반드시 유의사항을 숙지하셔야 합니다.
Last updated