결제위젯 Flutter SDK

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

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

• Flutter 3.1.0 이상
• Dart 2.18.0 이상
• Android minSdkVersion 17

• flutter_inappwebview
• json_annotation
• url_launcher
• device_info

pubspec.yaml 파일에 가장 최신 버전의 토스페이먼츠 패키지을 추가해주세요.

android/app/src/main/AndroidManifest.xml 파일에 아래 설정을 추가해주세요.

아래 예시 코드를 Flutter 프로젝트에 넣어서 바로 결제위젯을 테스트해보세요.

결제 UI가 표시되는 플러터 위젯입니다. UI 트리의 원하는 위치에 선언해 주세요.

• paymentWidget
  

  생성한 PaymentWidget 객체입니다.

• selector
  

  위젯의 고유한 식별자입니다. renderPaymentMethods() 에서 이 값을 사용합니다.

• onCustomRequested
  

  결제위젯에 커스텀 결제수단을 추가하는 이벤트에 대한 콜백입니다.

• onCustomPaymentMethodSelected
  

  구매자가 커스텀 결제수단을 선택한 이벤트에 대한 콜백입니다.

• onCustomPaymentMethodUnselected
  

  구매자가 커스텀 결제수단을 선택을 해제한 이벤트 대한 콜백입니다.

이용 약관 UI가 표시되는 플러터 위젯입니다. UI 트리의 원하는 위치에 선언해 주세요.

• paymentWidget
  

  생성한 PaymentWidget 객체입니다.

• selector
  

  위젯의 고유한 식별자입니다. renderPaymentMethods() 에서 이 값을 사용합니다.

• onChange
  

  약관 동의 상태 변경 이벤트에 대한 콜백을 지정합니다.

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

• clientKey
  

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

• customerKey
  

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

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

• paymentWidgetOptions
  

  결제위젯 옵션입니다.

• brandPayOption
  

  결제위젯에 브랜드페이를 추가할 때 설정합니다. redirectUrl은 Access Token 발급 과정에서 임시 인증 코드를 받을 URL입니다.

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

• selector
  

  렌더링할 결제 UI의 식별자입니다. UI 트리에 추가한 PaymentMethodWidget의 생성자에 넣은 값을 입력합니다.

• amount
  

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

• value
  

  결제 금액입니다.

• currency
  

  결제 통화입니다. 기본 값은 KRW입니다. PayPal에서 사용할 수 있는 통화는 USD입니다.

• country
  

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

• options
  

  결제위젯의 렌더링 옵션입니다.

• variantKey
  

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

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

• selector
  

  렌더링할 약관 UI의 식별자입니다. UI 트리에 추가한 AgreementWidget의 생성자에 넣은 값을 입력합니다.

• options
  

  이용약관 UI의 렌더링 옵션입니다.

• variantKey
  

  렌더링하고 싶은 이용약관의 키 값을 넣으세요. 결제 UI의 variantKey와 독립적으로 사용됩니다. 이용약관은 결제위젯 어드민에서 추가할 수 있어요.

구매자가 선택한 결제수단의 결제창을 띄우는 메서드입니다.

• paymentInfo
  

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

• orderId
  

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

• orderName
  

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

• customerEmail
  

  구매자의 이메일 주소입니다. 결제 상태가 바뀌면 이메일 주소로 결제내역이 전송됩니다. 최대 길이는 100자입니다.

• customerName
  

  구매자명입니다. 최대 길이는 100자입니다.

• appScheme
  

  내 상점의 앱 스킴을 지정하면 외부 앱(페이북/ISP)에서 상점 앱으로 돌아올 수 있습니다. 예를 들면 testapp://같은 형태입니다.

• taxFreeAmount
  

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

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

• taxExemptionAmount
  

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

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

• cultureExpense
  

  가상계좌, 계좌이체 결제일 때 적용할 수 있는 문화비(도서, 공연 티켓, 박물관·미술관 입장권 등) 지출 여부입니다.

• useEscrow
  

  가상계좌, 계좌이체 결제일 때 적용할 수 있는 에스크로 사용 여부입니다. 값을 주지 않으면 결제창에서 구매자가 직접 에스크로 결제 여부를 선택합니다.

• escrowProducts
  

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

• id
  

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

• name
  

  상품 이름입니다.

• code
  

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

• unitPrice
  

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

• quantity
  

  상품 구매 수량입니다.

• customerMobilePhone
  

  구매자의 휴대폰 번호입니다. 가상계좌 결제에는 입금 안내가 전송되고, 퀵계좌이체창에서는 구매자의 휴대폰 번호를 자동 완성합니다.

• showCustomerMobilePhone
  

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

• mobileCarrier
  

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

• products
  

  구매자가 선택한 각 상품의 상세 정보를 담는 배열입니다. 예를 들어, 세 가지 상품을 구매했다면 배열 길이는 3이어야 합니다.

  products 정보는 선택 사항이지만 포함할 경우 아래 모든 항목은 필수입니다.

  • name 필수 · string
    

    상품 이름입니다.

  • quantity 필수 · number
    

    상품 구매 수량입니다.

  • unitAmount 필수 · number
    

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

  • currency 필수 · string
    

    상품 가격의 통화입니다.

  • description 필수 · string
    

    상품에 대한 부가적인 설명입니다.

• shipping
  

  구매한 각 상품의 배송 정보 객체입니다.

• fullName
  

  구매자명입니다.

• address
  

  배송지 주소입니다. 각 항목의 자세한 설명은 JavaScript SDK를 참고하세요.

• paymentMethodOptions
  

  결제수단의 추가 파라미터를 담는 객체입니다. 결제수단이나 결제사 별로 파라미터를 제공합니다. PayPal을 연동할 때는 paypal을 사용합니다.

• payPal
  

  PayPal의 추가 파라미터를 담는 객체입니다. setTransactionContext는 PayPal에서 추가로 요청하는 STC(Set Transaction Context) 정보를 객체로 전달하는 필드입니다. 이 정보는 PayPal에서 부정거래, 결제 취소, 환불 등 리스크 관리에 활용합니다. 결제 거래의 안전성과 신뢰성을 확보하려면 이 정보를 전달해야 합니다. PayPal STC 문서를 참고해서 업종에 따라 필요한 파라미터를 추가해주세요. 문서의 표에 있는 ‘Data Field Name’ 컬럼 값을 객체의 ‘key’로, ‘Description’에 맞는 값을 객체의 ‘value’로 넣어주시면 됩니다.

  * 이 정보는 토스페이먼츠에서 관리하지 않습니다.

requestPayment() 메서드가 반환하는 결제 요청 결과입니다.

• success
  
• paymentKey
  

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

• orderId
  

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

• amount
  

  결제 금액입니다.

• additionalParameters
  

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

• paymentType
  

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

  • NORMAL: 일반 결제입니다. 코어 결제 승인 API를 호출해서 결제를 완료하세요.
  • BRANDPAY: 브랜드페이 결제입니다. 브랜드페이 결제 승인 API를 호출해서 결제를 완료하세요.
  • KEYIN: 키인 결제입니다. 코어 결제 승인 API를 호출해서 결제를 완료하세요.
• fail
  

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

• errorCode
  

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

• errorMessage
  

  에러 메시지입니다.

• orderId
  

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

renderPaymentMethods() 메서드가 반환하는 결제 UI의 Control입니다.

변경된 결제 금액을 UI에 업데이트하는 메서드입니다.

결제 금액이 바뀌면 할부 적용, 즉시 할인 적용 여부도 바뀔 수 있습니다. updateAmount() 메서드로 결제 금액을 변경하고 결제위젯의 할인 정보도 업데이트하세요.

• amount
  

  새로운 결제 금액입니다.

구매자가 선택한 결제수단을 전달하는 메서드입니다.

• type
  

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

• method
  

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

• easypay
  

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

• provider
  

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

• paymentMethodKey
  

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

renderAgreement() 메서드가 반환하는 이용약관 UI의 Control입니다.

구매자의 필수 이용 약관에 동의 상태를 나타내는 메서드입니다. 메서드를 호출하면 약관 데이터 객체가 돌아옵니다.

• agreedRequiredTerms
  

  구매자가 모든 필수 약관에 동의했는지 알려줍니다.

• terms
  

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

• id
  

  약관의 식별자입니다.

• agreed
  

  구매자의 약관 동의 여부입니다.

• required
  

  약관의 필수 여부입니다.