결제위젯 SDK/Android
목차

결제위젯 Android SDK는 Android 환경에서 사용할 수 있는 결제위젯 메서드를 제공합니다. SDK를 추가하고 메서드를 사용하는 방법을 알아봅니다.

샘플 프로젝트토스페이먼츠 Android SDK 샘플 프로젝트를 확인하세요.

SDK 추가

요구 사항

결제위젯 Android SDK를 설치하기 전에 최소 요구 사항을 확인하세요.

  • minSdk 21 이상

Gradle 설정

프로젝트의 Gradle 설정을 아래와 같이 설정하면 결제위젯 Android SDK를 사용하실 수 있습니다.

Android SDK의 버전 정보는 Changelog를 참고하세요.

Layout 설정

res/layout 디렉토리에 결제 화면의 Layout XML 파일을 생성하세요. 파일 안에 PaymentMethod을 추가해주세요.

PaymentWidget

토스페이먼츠 결제위젯입니다.

생성자

파라미터

  • activity

    Native SDK가 적용된 Activity입니다.

  • clientKey

    API 키 메뉴에서 확인할 수 있는 결제위젯 연동 키 > 클라이언트 키입니다.

  • customerKey

    구매자 ID입니다. 다른 사용자가 이 값을 알게 되면 악의적으로 사용될 수 있습니다. 자동 증가하는 숫자 또는 이메일・전화번호・사용자 아이디와 같이 유추가 가능한 값은 안전하지 않습니다. 와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @ 를 최소 1개 이상 포함한 최소 2자 이상 최대 50자 이하의 문자열이어야 합니다.

    비회원 결제에는 PaymentWidget.ANONYMOUS를 사용하세요.

  • options optional

    결제위젯 옵션입니다.


  • PaymentWidgetOptions
  • Builder

    PaymentWidgetOptions 객체를 생성하는 Builder 클래스입니다.

  • build

    PaymentWidgetOptions 객체를 생성합니다.

  • brandPayOption

    결제위젯에 브랜드페이를 추가할 때 설정합니다. redirectUrl을 파라미터로 넘기세요.

    리다이렉트 URL에는 Access Token 발급 과정에 필요한 값이 돌아옵니다. Access Token은 브랜드페이 고객을 식별하고 고객의 결제 권한을 증명합니다. 값을 넣지 않으면 개발자센터 > 브랜드페이 페이지에 최초로 등록한 리다이렉트 URL이 기본값으로 들어갑니다.

renderPaymentMethods

결제 UI를 렌더링하는 메서드입니다.

파라미터

  • method

    PaymentMethod 객체입니다.

  • context

    Context입니다.

  • attrs

    AttributeSet입니다.

  • amount

    결제 금액 정보입니다. 결제 금액, 통화, 국가 정보가 들어가는 PaymentMethod.Rendering.Amount 객체입니다.

  • value

    결제 금액입니다.

  • currency

    결제 통화입니다. PaymentMethod.Rendering.Currency를 사용하세요.

  • country

    결제한 국가입니다. 기본 값은 KR입니다. ISO-3166의 두 자리 국가 코드를 모두 지원합니다.

  • options

    결제위젯 추가 옵션입니다. PaymentMethod.Rendering.Options 객체입니다.

  • variantKey

    멀티 결제 UI를 사용할 때 설정합니다. 렌더링하고 싶은 결제 UI의 키 값을 넣으세요.

  • paymentWidgetStatusListener

    결제위젯의 렌더링 상태를 감지하는 리스너입니다.

  • onLoad

    위젯 렌더링이 완료되면 호출되는 메서드입니다.

  • onFail

    구매자가 결제 정보(카드사 선택, 계좌번호 등)를 입력하지 않으면 호출되는 메서드입니다. NEED_CARD_PAYMENT_DETAIL, NEED_REFUND_ACCOUNT_DETAIL 에러를 안내합니다.

    결제 UI에 자동으로 에러 안내가 나타나지만 세로로 긴 화면에서는 구매자가 문제를 인식하기 어렵습니다. 반드시 해당 메서드를 사용해서 구매자에게 에러를 안내해주세요.

updateAmount

파라미터

  • amount

    새로운 결제 금액입니다.

getSelectedPaymentMethod

결제위젯에서 선택된 결제수단을 확인하는 메서드입니다.

응답

  • type

    결제 타입 정보입니다. NORMAL(일반결제), BRANDPAY(브랜드페이), KEYIN(키인 결제), CUSTOM(커스텀 결제수단) 중 하나입니다.

  • method

    결제수단입니다. 카드, 가상계좌, 간편결제, 휴대폰, 계좌이체, 문화상품권, 도서문화상품권, 게임문화상품권, 해외간편결제 중 하나입니다.

  • easyPay

    결제수단이 간편결제일 때 반환되는 정보입니다.

  • provider

    선택한 간편결제사 코드입니다.

  • paymentMethodKey

    결제 타입이 CUSTOM일 때 반환되는 커스텀 결제수단 키입니다.

requestPayment

고객이 선택한 결제수단의 결제창을 호출하는 메서드입니다.

파라미터

  • paymentInfo

    결제 정보가 담긴 PaymentMethod.PaymentInfo입니다.

  • orderId

    주문번호입니다. 주문을 구분하는 ID입니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.

  • orderName

    구매상품입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.

  • taxFreeAmount

    결제 금액 중 면세 금액입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다.

    * 면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점에는 적용되지 않습니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.

  • taxExemptionAmount

    과세를 제외한 결제 금액(컵 보증금 등)입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다. 카드 결제 또는 간편결제로 계좌이체할 때 사용하세요.

    * 과세 제외 금액이 있는 카드 결제는 부분 취소가 안 됩니다.

  • useEscrow

    , 결제일 때 적용할 수 있는 사용 여부입니다. 값을 주지 않으면 결제창에서 고객이 직접 에스크로 결제 여부를 선택합니다.

  • escrowProducts

    각 상품의 상세 정보 객체를 담는 배열입니다. 가상계좌, 계좌이체에서 를 사용하는 상점이라면 필수 파라미터입니다.

    예를 들어 사용자가 세 가지 종류의 상품을 구매했다면 길이가 3인 배열이어야 합니다.

  • id

    상품의 ID입니다. 이 값은 유니크해야 합니다.

  • name

    상품 이름입니다.

  • code

    상점에서 사용하는 상품 관리 코드입니다.

  • unitPrice

    상품의 가격입니다. 전체를 합한 가격이 아닌 상품의 개당 가격입니다.

  • quantity

    상품 구매 수량입니다.

  • customerMobilePhone

    구매자의 휴대폰 번호입니다. 가상계좌 입금 안내가 전송되는 번호입니다.

  • showCustomerMobilePhone

    가상계좌 결제창에서 휴대폰 번호 입력 필드 노출 여부입니다. false를 넘기면 가상계좌 결제창에서 휴대폰 번호 입력 필드를 보여주지 않습니다. 기본값은 true 입니다.

  • mobileCarrier

    휴대폰 결제창에서 선택할 수 있는 통신사를 제한합니다. 배열에 통신사 코드를 추가하면 해당 통신사 코드만 선택할 수 있는 결제창이 뜹니다. 값을 넣지 않으면 모든 통신사 코드를 선택할 수 있는 결제창이 뜹니다.

  • paymentCallback

    결제 승인 결과를 수신하는 Callback입니다.

  • onPaymentSuccess

    결제가 성공하면 호출되는 메서드입니다. TossPaymentsResult.Success를 전달합니다.

    TossPaymentsResult.Success로 돌아온 결제 정보를 검증하고, 결제 승인을 요청하세요.

  • onPaymentFailed

    결제가 실패하면 호출되는 메서드입니다. TossPaymentsResult.Fail을 전달합니다.

TossPaymentResult

  • Success

    결제 성공 결과 정보입니다.

  • paymentKey

    결제를 식별하는 키 값입니다. 결제 승인, 결제 조회, 결제 취소 등 운영에 필요한 값입니다.

  • orderId

    주문번호입니다. 결제 요청에 담아 보낸 값입니다.

  • amount

    결제할 금액입니다.

  • additionalParmeters

    브랜드페이를 사용하고 있다면 필요한 파라미터입니다.

  • paymentType

    결제 유형입니다. NORMAL, BRANDPAY, KEYIN 중 하나입니다.

  • Fail

    결제 실패 결과 정보입니다.

  • errorCode

    에러 코드입니다. SDK 에러가 돌아옵니다. failUrl로 전달되는 에러, 공통 SDK 에러, 결제위젯 SDK 에러가 모두 포함됩니다.

  • errorMessage

    에러 메시지입니다.

  • orderId

    주문번호입니다. 결제 요청에 담아 보낸 값입니다.

addPaymentMethodEventListener

결제위젯 커스텀 결제수단・간편결제 직연동에 이벤트 리스너를 추가합니다.

  • listener

    아래 이벤트를 수신하는 리스너입니다.

    • onCustomRequested: 고객이 커스텀 결제수단으로 결제 요청을 하면 발생하는 이벤트입니다.
    • onCustomPaymentMethodSelected: 고객이 커스텀 결제수단을 선택하면 발생하는 이벤트입니다.
    • onCustomPaymentMethodUnselected: 고객이 커스텀 결제수단 선택을 해제하면 발생하는 이벤트입니다.

renderAgreement

이용약관 UI를 렌더링하는 메서드입니다. 이용약관 UI에는 토스페이먼츠의 필수 이용약관이 있습니다. 결제위젯 어드민에서 내 상점의 필수 약관, 회원·비회원 약관, 영문 약관 등 약관을 자유롭게 커스터마이징할 수 있습니다.

  • agreement

    화면에 렌더링할 이용약관 UI 객체입니다.

  • context

    Context입니다.

  • attrs

    AttributeSet입니다.

  • paymentWidgetStatusListener

    이용약관 UI의 렌더링 상태를 감지하는 리스너입니다.

  • onLoad

    위젯 렌더링이 완료되면 호출되는 메서드입니다.

addAgreementStatusListener

고객 이용약관 동의 이벤트에 리스너를 추가합니다.

  • listener

    이용약관 상태 변경을 수신하는 리스너입니다.


  • AgreementStatusListener
  • onAgreementStatusChanged

    이용약관 동의 상태가 변경되면 호출되는 메서드입니다.

  • AgreementStatus
  • agreedRequiredTerms

    고객이 모든 필수 약관에 동의했는지 알려줍니다.

  • terms

    개별 약관에 동의했는지 알려줍니다.

  • id string

    약관의 식별자입니다.

  • agreed boolean

    약관의 고객 동의 여부입니다.

  • required boolean

    약관의 필수 여부입니다.

  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    실시간 문의|이메일 보내기