앱카드 API 화면 가이드
Last updated
Was this helpful?
Last updated
Was this helpful?
커스텀 스킨이 앱카드 서비스에서 제공하는 기능을 사용하기 위해 shop API로 로그인/회원가입, 주문서 화면을 어떻게 구현할 수 있을지 안내하기 위한 콘텐츠입니다.
기능요약
쇼핑몰 회원의 앱카드 앱을 통해 회원가입/로그인이 가능하며, 해당 앱카드를 자동 등록하여 간편하게 결제할 수 있도록 제공합니다.
대상 솔루션 : 샵바이 전용
적용일자 : 현재 서비스 준비 중으로, 앱카드 서비스 앱 출시 예정입니다.
기능상세
앱카드 서비스를 사용하기 위해서는 앱카드 앱 설치 후 쇼핑몰에서 사용중인 PG 정보로 앱카드 서비스 신청이 완료된 상태여야 합니다.
아래 API를 활용하여 앱카드 서비스에서 제공하는 기능 사용이 가능한 화면을 구현할 수 있습니다.
(예시)
(1) 회원가입/로그인 버튼 출력
▶ 몰 정보 조회하기 GET/malls API 보기 > 쇼핑몰 전반에 대한 기본 정보와 설정 데이터를 조회할 수 있습니다.
위 API를 호출하여 받은 응답 값 중 openIdJoinConfig 값에서 간편로그인 설정 정보를 확인할 수 있습니다.
앱을 설치하여 연동 가능한 상태인 경우 providers에 APP_CARD 값이 포함됩니다.
(2) 앱카드 인증 거래번호, 인증 거래 토큰 발급
▶ 앱카드 거래번호 및 토큰 발급하기 GET/oauth/openid/app-card/trans-no API 보기 > 앱카드 회원가입/로그인 시 필요한 인증번호와 인증토큰을 발급 받을 수 있습니다.
[앱카드로 회원가입] 또는 [앱카드로 로그인] 버튼 클릭 시 해당 API를 호출하여 앱카드 인증을 위한 화면을 구현합니다.
PC 쇼핑몰의 경우 QR Code를 통해 앱카드 인증이 가능합니다.
모바일 쇼핑몰의 경우 인증 모듈(앱카드 선택 팝업)을 통해 앱카드 인증이 가능합니다.
인증 결과는 window message 이벤트를 등록하여, 인증 성공/실패 콜백을 받아 처리합니다.
인증 성공 : 0000 / 카드사 앱 호출 : 0001 / 인증 실패 : 0002 / 인증 닫기 : 0003
(2-1) PC - QR Code 생성
▶ 앱카드 QR Code 생성하기 GET/oauth/openid/app-card/qr API 보기 > 인증거래번호(transNo)를 통해 QR Code를 생성하기 위한 API입니다.
앱카드 인증거래번호 transNo 값을 사용하여 API를 호출합니다.
위 API 응답 값으로 base64로 인코딩된 QR code를 확인할 수 있습니다.
예시 코드를 참고하시어 img 태그로 qr 코드를 노출하시면 됩니다.
예시)<img src="data:image/png;base64,{qr}" alt="qrCode"/>
(2-2) 모바일 - 인증 모듈(앱카드 선택 팝업) 호출 앱카드를 선택할 수 있는 인증 모듈 화면을 노출합니다. url 구성 시 아래 구분 값을 상황에 맞게 전달해 주시면 됩니다.
transNo: 앱카드 인증거래번호
deviceType: 디바이스 타입 (1: IOS WEB, 2: IOS APP, 3: AOS WEB, 4: AOS APP, 5: PC)
storeTermYN: 가맹점 약관 노출 여부 (Y/N)
nativeYN: ios/aos 에서 웹뷰를 통해 모듈을 바로 호출 시 Y로 설정
(예시)
(3) Access Token 획득
▶ OpenId Access Token 발급하기 POST/oauth/openid API 보기 > OpenId 회원의 AccessToken 발급하기 위한 post 방식의 API 입니다.
앱카드 앱 인증 완료 시 transNo(code) 와 token(state) 을 사용하여 해당 API를 호출합니다.
PC 쇼핑몰의 경우 쇼핑몰 회원이 [인증완료] 버튼 클릭 시 호출합니다.
모바일 쇼핑몰의 경우 window message 이벤트로 인증 성공 콜백 시 호출합니다.
<참고> OAuth 2.0 적용 방법은 OAuth 2.0 적용 가이드 문서를 참고해 주세요.
(4) 회원 가입 여부 확인
▶ 회원정보 조회하기 GET/profile API 보기 > 회원정보를 조회합니다.
AccessToken을 활용하여 위 API를 호출합니다.
API를 호출하여 받은 응답 값 중 memberStatus(회원상태)가 WAITING 인 경우 쇼핑몰 미가입 상태로 판단합니다.
앱카드 회원인 경우 해당 계정으로 로그인합니다.
앱카드 회원이 아닌 경우 간편 로그인 회원가입 페이지를 출력합니다.
<참고> 간편 로그인 회원가입 페이지 개발 방법은 간편 로그인 문서를 참고해 주세요.
앱카드 결제 버튼은 주문서 페이지와 상품 상세 페이지에 추가할 수 있습니다. (예시) 주문서
(예시) 상품 상세
(1) 앱카드 결제 버튼 출력
▶ 주문서 조회하기 GET/order-sheets/{orderSheetNo} API 보기 > 주문서 번호를 이용하여 주문상품정보를 조회할 수 있습니다.
위 API를 호출하여 받은 응답 값 중 availablePayTypes 값에서 결제 수단 정보를 확인할 수 있습니다.
앱을 설치하여 연동 가능한 상태인 경우 pgTypes에 APP_CARD이 포함됩니다.
(2) 간편결제 카드 목록 조회
▶ 앱카드 간편결제카드 목록 조회 GET/app-card/pay-cards API 보기 > 앱카드 회원의 간편결제카드 목록을 조회할 수 있습니다.
위 API를 호출하여 받은 응답 값 중 cards 에서 등록된 결제 수단 정보를 확인할 수 있습니다.
(3) 간편결제 카드사 목록 조회
▶ 앱카드 간편결제 카드 목록 조회 GET/app-card/cards API 보기 > 쇼핑몰에서 사용할 수 있는 앱카드 카드사 목록을 조회할 수 있습니다.
쇼핑몰에서 사용할 수 있는 앱카드 카드사 목록을 조회할 수 있습니다.
(4) 간편결제 카드 할부정보 조회
▶ 앱카드 할부정보 조회 GET/app-card/inst-plan API 보기 > 쇼핑몰에서 사용할 수 있는 앱카드의 할부정보를 조회할 수 있습니다.
선택한 앱카드의 할부 정보를 제공합니다.
(5) 주문하기
▶ 주문 예약하기 POST/payments/reserve API 보기 > 주문된 결제를 진행합니다.
앱카드 선택 후 [결제하기] 시 해당 API를 호출하여 주문을 생성합니다.
앱카드 결제를 위해서는 위의 API(간편결제 카드 목록 조회, 간편결제 카드사 목록 조회, 간편결제 카드 할부정보 조회)를 통해 필요한 정보를 조회하고, appCardInfo 파라미터에 앱카드 정보를 추가하여 API를 호출해야 합니다.
PC 쇼핑몰의 경우 QR Code를 통해 앱카드 인증이 가능합니다.
모바일 쇼핑몰의 경우 인증 모듈(앱카드 선택 팝업)을 통해 앱카드 인증이 가능합니다.
인증 결과는 window message 이벤트를 등록하여, 인증 성공/실패 콜백을 받아 처리합니다.
인증 성공 : 0000 / 카드사 앱 호출 : 0001 / 인증 실패 : 0002 / 인증 닫기 : 0003
(5-1) PC - QR Code 생성
위 API 응답 값으로 extraData.qr으로 인코딩된 QR 코드가 전달됩니다.
예시 코드를 참고하시어 img 태그로 qr 코드를 노출하시면 됩니다.
예시) <img src="data:image/png;base64,{extraData.qr}" alt="qrCode" />
주의사항
위 API 응답 값 중 exatrData.authYn 값은 원클릭 설정 여부 값입니다.
authYn 값이 Y 인 경우(즉, 원클릭 설정이 되어있는 경우) 샵바이 결제 모듈 NCPPay에서 원클릭 바로 결제가 진행되오니 QR Code 인증 화면이 노출되지 않도록 authYn 값을 체크해 주셔야 합니다.
(5-2) 모바일 - 인증 모듈(앱카드 선택 팝업) 호출
위 API 응답 값 중 returnUrl을 아래 {{returnUrl}} 위치에 전달 해주시면 됩니다.
주의사항
위 API 응답 값 중 exatrData.authYn 값은 원클릭 설정 여부 값입니다.
authYn 값이 Y 인 경우(즉, 원클릭 설정이 되어있는 경우) 샵바이 결제 모듈 NCPPay에서 원클릭 바로 결제가 진행되오니 인증 모듈이 노출되지 않도록 authYn 값을 체크해 주셔야 합니다.
(6) 인증결과 조회
▶ 앱카드 인증결과 조회 GET/app-card/auth/{orderNo} API 보기 > 해당 주문번호의 앱카드 인증 여부를 조회합니다.
위 API로 인증 여부를 확인할 수 있습니다.
앱카드 인증 완료 시 주문 예약하기 API에서 받은 응답결과를 결제 모듈인 NCPPay에 requestAppCardOrder로 전달해주시면 됩니다.
PC 쇼핑몰의 경우 쇼핑몰 회원이 [인증완료] 버튼 클릭 시 전송합니다.
완료되지 않은 시점에 호출 시O9104 에러코드가 전달 됩니다.
모바일 쇼핑몰의 경우 window message 이벤트로 인증 성공 콜백 시 전송합니다.
(7) 주문 성공/실패 여부 확인
결제 성공 여부에 따라 주문 예약하기 API 요청 값으로 입력한 clientReturnUrl 로 결과를 전송합니다.
결제 성공 여부에 따라 '주문완료' 또는 '주문 실패' 화면을 출력합니다.
성공 시
request parameter 로 결과 값을 SUCCESS 로 전달합니다.
주문이 성공한 주문 번호를 함께 전달합니다.
ex)result=SUCCESS&orderNo=123
실패 시
request parameter 로 결과 값을 FAIL로 전달합니다.
message에 실패 사유를 함께 전달합니다.
ex)result=FAIL&message=잔액부족
<참고> 주문서 페이지 개발 방법은 주문서 문서를 참고해 주세요.
(1) 앱카드 결제 버튼 출력
▶ 주문 설정 값 가져오기 GET/order-configs API 보기 > 주문 설정값을 조회하는 API입니다.
위 API를 호출하여 앱카드 사용 여부를 확인합니다.
API 응답 결과 중 useAppCard구분 값으로 확인할 수 있으며 true인 경우에 앱카드 결제 버튼을 출력합니다.
(2) 상품 상세 주문서
[앱카드 결제] 버튼 클릭 시 아래 API들을 호출하여 주문서 생성 및 주문 시 필요한 데이터를 가져옵니다.
(2-1) 주문서 생성
▶ 주문서 작성하기 POST/order-sheets API 보기 > 주문을 진행할 상품 정보를 전달하는 API입니다.
주문을 진행할 상품 정보를 전달하는 API입니다.
주문서 페이지 진입 전 실행합니다.
(2-2) 주문서 조회
▶ 주문서 조회하기 GET/order-sheets/{orderSheetNo} API 보기 > 주문서 번호를 이용하여 주문상품정보를 조회할 수 있습니다.
응답 결과를 사용하여 주문 정보를 보여줍니다.
주문 상품 정보 : deliveryGroups
주문자 정보 : ordererContact
약관 정보 : termsInfos, customTermsInfos 와 주문서 필수 약관 내용
(2-3) 쿠폰 및 배송지 정보가 적용된 금액 조회
▶ 쿠폰 및 배송지 정보가 적용된 금액 조회하기 POST/order-sheets/{orderSheetNo}/calculate API 보기 > 쿠폰 및 배송비 계산이 적용된 주문서 금액을 조회할 수 있습니다.
응답 결과 중 paymentInfo으로 결제 정보를 보여줍니다.
(2-4) 배송지 목록 가져오기
▶ 배송지 목록 가져오기 GET/profile/shipping-addresses API 보기 > 주소지 정보를 조회할 수 있습니다.
응답 결과 중 defaultAddress 기본 배송지 정보로 배송지 정보를 보여줍니다.
(2-5) 회원정보 조회하기
▶ 회원정보 조회하기 GET/profile API 보기 > 회원정보를 조회할 수 있습니다.
기본 배송지가 없는 경우, 위 API 응답 결과 중 address, detailAddress, city, state값인 회원의 주소 정보를 배송지 정보로 보여줍니다.
주문자 정보가 없는 경우, 위 API 응답 결과 중 memberName 값인 회원 이름으로 보여줍니다.
(2-6) 주문하기
▶ 주문 예약하기 POST/payments/reserve API 보기 > 주문된 결제를 진행합니다.
앱카드 선택 후 [결제하기] 시 해당 API를 호출하여 주문을 생성합니다.
<참고> 앱카드 목록 출력, 앱카드 주문 상세 개발 방법은 상단 주문서 내용을 참고해 주세요. <참고> 상품 상세 페이지 개발 방법은 상품 상세 문서를 참고해 주세요.
▶ 앱카드 간편결제 카드 삭제 DELETE/app-card/pay-cards/{acntId} API 보기 > 간편결제 카드를 삭제할 수 있습니다.
API를 호출하여 등록된 앱카드를 삭제할 수 있습니다.
