스토어 홈앱 스토어디자인 스토어

앱카드 API 화면 가이드

커스텀 스킨이 앱카드 서비스에서 제공하는 기능을 사용하기 위해 shop API로 로그인/회원가입, 주문서 화면을 어떻게 구현할 수 있을지 안내하기 위한 콘텐츠입니다.

간단소개

  • 기능요약

    • 쇼핑몰 회원의 앱카드 앱을 통해 회원가입/로그인이 가능하며, 해당 앱카드를 자동 등록하여 간편하게 결제할 수 있도록 제공합니다.

    • 대상 솔루션 : 샵바이 전용

    • 적용일자 : 현재 서비스 준비 중으로, 앱카드 서비스 앱 출시 예정입니다.

  • 기능상세

    • 앱카드 서비스를 사용하기 위해서는 앱카드 앱 설치 후 쇼핑몰에서 사용중인 PG 정보로 앱카드 서비스 신청이 완료된 상태여야 합니다.

API 소개 및 화면 가이드

아래 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로 설정

(예시)

const APP_CARD_URL = {
  alpha: 'https://payment.tvhub.co.kr:10488',
  real: 'https://payment.tvhub.co.kr:488',
};

const url : `${APP_CARD_URL[env]}/APPCARD-AUTH/index.html#/?transNo=${transNo}&deviceType=${deviceType}&nativeYN=${nativeYN}&storeTermYN=${storeTermYN}`

<object id='appCard' data='{{url}}' type='text/html' style='z-index:9998; position: fixed; bottom:0; left:0; width:100%; height: 100%'></object>

(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. 주문서

(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}} 위치에 전달 해주시면 됩니다.

<object id='appCard' data='{{returnUrl}}' type='text/html' style='z-index:9998; position: fixed; bottom:0; left:0; width:100%; height: 100%'></object>

주의사항

  • 위 API 응답 값 중 exatrData.authYn 값은 원클릭 설정 여부 값입니다.

    • authYn 값이 Y 인 경우(즉, 원클릭 설정이 되어있는 경우) 샵바이 결제 모듈 NCPPay에서 원클릭 바로 결제가 진행되오니 인증 모듈이 노출되지 않도록 authYn 값을 체크해 주셔야 합니다.

(6) 인증결과 조회

▶ 앱카드 인증결과 조회 GET/app-card/auth/{orderNo} API 보기 > 해당 주문번호의 앱카드 인증 여부를 조회합니다.

  • 위 API로 인증 여부를 확인할 수 있습니다.

  • 앱카드 인증 완료 시 주문 예약하기 API에서 받은 응답결과를 결제 모듈인 NCPPay에 requestAppCardOrder로 전달해주시면 됩니다.

window.NCPPay.requestAppCardOrder(response);

  • PC 쇼핑몰의 경우 쇼핑몰 회원이 [인증완료] 버튼 클릭 시 전송합니다.

    • 완료되지 않은 시점에 호출 시O9104 에러코드가 전달 됩니다.

  • 모바일 쇼핑몰의 경우 window message 이벤트로 인증 성공 콜백 시 전송합니다.

(7) 주문 성공/실패 여부 확인

  • 결제 성공 여부에 따라 주문 예약하기 API 요청 값으로 입력한 clientReturnUrl 로 결과를 전송합니다.

  • 결제 성공 여부에 따라 '주문완료' 또는 '주문 실패' 화면을 출력합니다.

    • 성공 시

      • request parameter 로 결과 값을 SUCCESS 로 전달합니다.

      • 주문이 성공한 주문 번호를 함께 전달합니다.

      • ex)result=SUCCESS&orderNo=123

    • 실패 시

      • request parameter 로 결과 값을 FAIL로 전달합니다.

      • message에 실패 사유를 함께 전달합니다.

      • ex)result=FAIL&message=잔액부족

<참고> 주문서 페이지 개발 방법은 주문서 문서를 참고해 주세요.

2. 상품 상세

(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를 호출하여 등록된 앱카드를 삭제할 수 있습니다.

Previous엑심베이 결제 수단 추가 가이드Next디자인/콘텐츠

Last updated

Was this helpful?