SDK 추가
예시 코드
PaymentMethodWidget
AgreementWidget
PaymentWidget
PaymentMethodWidgetControl
- updateAmount
- getSelectedPaymentMethod
AgreementWidgetControl
- getAgreementStatus

결제위젯 Flutter SDK

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

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

SDK 추가

요구 사항

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

Flutter 3.1.0 이상
Dart 2.18.0 이상
Android minSdkVersion 17

외부 라이브러리 의존성

패키지 추가하기

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

pubspec.yaml

dependencies:
  tosspayments_widget_sdk_flutter: ^0.X.X

Android 설정

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

...
<uses-permission android:name="android.permission.INTERNET" />
<application
	...
	android:usesCleartextTraffic="true">
</application>
...

예시 코드

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

main.dart

import 'package:flutter/material.dart';
import 'package:tosspayments_widget_sdk_flutter/model/payment_info.dart';
import 'package:tosspayments_widget_sdk_flutter/model/payment_widget_options.dart';
import 'package:tosspayments_widget_sdk_flutter/payment_widget.dart';
import 'package:tosspayments_widget_sdk_flutter/widgets/agreement.dart';
import 'package:tosspayments_widget_sdk_flutter/widgets/payment_method.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      home: PaymentWidgetExamplePage(),
    );
  }
}

class PaymentWidgetExamplePage extends StatefulWidget {
  const PaymentWidgetExamplePage({super.key});

  @override
  State<PaymentWidgetExamplePage> createState() {
    return _PaymentWidgetExamplePageState();
  }
}

class _PaymentWidgetExamplePageState extends State<PaymentWidgetExamplePage> {
  late PaymentWidget _paymentWidget;
  PaymentMethodWidgetControl? _paymentMethodWidgetControl;
  AgreementWidgetControl? _agreementWidgetControl;

  @override
  void initState() {
    super.initState();

    _paymentWidget = PaymentWidget(
      clientKey: "test_gck_docs_Ovk5rk1EwkEbP0W43n07xlzm", 
      customerKey: "",
      // 결제위젯에 브랜드페이 추가하기
      // paymentWidgetOptions: PaymentWidgetOptions(brandPayOption: BrandPayOption("리다이렉트 URL")) // Access Token 발급에 사용되는 리다이렉트 URL
    );

    _paymentWidget
        .renderPaymentMethods(
          selector: 'methods',
          amount: Amount(value: 300, currency: Currency.KRW, country: "KR")),
          options: RenderPaymentMethodsOptions(variantKey: "DEFAULT")
        .then((control) {
      _paymentMethodWidgetControl = control;
    });

    _paymentWidget
      .renderAgreement(selector: 'agreement')
      .then((control) {
        _agreementWidgetControl = control;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: SafeArea(
        child: Column(children: [
      Expanded(
          child: ListView(children: [
        PaymentMethodWidget(
          paymentWidget: _paymentWidget,
          selector: 'methods',
        ),
        AgreementWidget(paymentWidget: _paymentWidget, selector: 'agreement'),
        ElevatedButton(
            onPressed: () async {
              final paymentResult = await _paymentWidget.requestPayment(
                  paymentInfo: const PaymentInfo(orderId: '', orderName: '토스 티셔츠 외 2건'));
              if (paymentResult.success != null) {
                // 결제 성공 처리
              } else if (paymentResult.fail != null) {
                // 결제 실패 처리
              }
            },
            child: const Text('결제하기')),
        ElevatedButton(
            onPressed: () async {
              final selectedPaymentMethod = await _paymentMethodWidgetControl?.getSelectedPaymentMethod();
              print('${selectedPaymentMethod?.method} ${selectedPaymentMethod?.easyPay?.provider ?? ''}');
            },
            child: const Text('선택한 결제수단 출력')),
        ElevatedButton(
            onPressed: () async {
              final agreementStatus = await _agreementWidgetControl?.getAgreementStatus();
              print('${agreementStatus?.agreedRequiredTerms}');
            },
            child: const Text('약관 동의 상태 출력')),
        ElevatedButton(
            onPressed: () async {
              await _paymentMethodWidgetControl?.updateAmount(amount: 300);
              print('결제 금액이 300원으로 변경되었습니다.');
            },
            child: const Text('결제 금액 변경'))
      ]))
    ])));
  }
}

PaymentMethodWidget

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

PaymentMethodWidget(
  {required PaymentWidget paymentWidget,
  required String selector,
  this.onCustomRequested,
  this.onCustomPaymentMethodSelected,
  this.onCustomPaymentMethodUnselected}
)

파라미터

paymentWidget
생성한 PaymentWidget 객체입니다.
selector
위젯의 고유한 식별자입니다. renderPaymentMethods() 에서 이 값을 사용합니다.
onCustomRequested
결제위젯에 커스텀 결제수단을 추가하는 이벤트에 대한 콜백입니다.
onCustomPaymentMethodSelected
고객이 커스텀 결제수단을 선택한 이벤트에 대한 콜백입니다.
onCustomPaymentMethodUnselected
고객이 커스텀 결제수단을 선택을 해제한 이벤트 대한 콜백입니다.

AgreementWidget

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

AgreementWidget(
  {required PaymentWidget paymentWidget, 
  required String selector, 
  this.onChange}
)

파라미터

paymentWidget
생성한 PaymentWidget 객체입니다.
selector
위젯의 고유한 식별자입니다. renderPaymentMethods() 에서 이 값을 사용합니다.
onChange
약관 동의 상태 변경 이벤트에 대한 콜백을 지정합니다.

PaymentWidget

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

class PaymentWidget {
  final String clientKey;
  final String customerKey;
  final PaymentWidgetOptions? paymentWidgetOptions;
}

파라미터

clientKey
API 키 메뉴에서 확인할 수 있는 결제위젯 연동 키 > 클라이언트 키입니다.
customerKey
고객 ID입니다. 다른 사용자가 이 값을 알게 되면 악의적으로 사용될 수 있습니다. 자동 증가하는 숫자 또는 이메일・전화번호・사용자 아이디와 같이 유추가 가능한 값은 안전하지 않습니다. UUID와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @ 를 최소 1개 이상 포함한 최소 2자 이상 최대 50자 이하의 문자열이어야 합니다.
비회원 결제에는 PaymentWidget.ANONYMOUS를 사용하세요.
paymentWidgetOptions
결제위젯 옵션입니다.
```
class PaymentWidgetOptions {
  final BrandPayOption? brandPayOption;
}
```
brandPayOption
결제위젯에 브랜드페이를 추가할 때 설정합니다. redirectUrl은 Access Token 발급 과정에서 임시 인증 코드를 받을 URL입니다.
```
class BrandPayOption {
  final String redirectUrl;
}
```

renderPaymentMethods

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

Future<PaymentMethodWidgetControl> renderPaymentMethods({
  required String selector,
  required Amount amount,
  RenderPaymentMethodsOptions? options,
})

파라미터

selector
렌더링할 결제 UI의 식별자입니다. UI 트리에 추가한 PaymentMethodWidget의 생성자에 넣은 값을 입력합니다.
amount
결제 금액 정보입니다. 결제 금액, 통화, 국가 정보가 들어가는 Amount입니다.
```
class Amount {
  final num value;
  final Currency currency;
  String country;
}
```
value
결제 금액입니다.
currency
결제 통화입니다. 기본 값은 KRW입니다. PayPal에서 사용할 수 있는 통화는 USD입니다.
country
결제한 국가입니다. 기본 값은 KR입니다. ISO-3166의 두 자리 국가 코드를 모두 지원합니다.

options

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

class RenderPaymentMethodsOptions {
  final String variantKey;
}

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

renderAgreement

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

Future<AgreementWidgetControl> renderAgreement({
  required String selector,
  RenderAgreementOptions? options,
})

파라미터

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

options

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

class RenderAgreementOptions {
  final String variantKey;
}

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

requestPayment

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

Future<Result> requestPayment({required PaymentInfo paymentInfo})

paymentInfo

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

class PaymentInfo {
  final String orderId;
  final String orderName;
  final String? customerEmail;
  final String? customerName;
  final String? appScheme;
  final num? taxFreeAmount;
  final String? taxExemptionAmount;
  final bool? cultureExpense;
  final bool? useEscrow;
  final List<EscrowProduct>? escrowProducts;
  final String? customerMobilePhone;
  final bool? showCustomerMobilePhone;
  final List<String>? mobileCarrier;
  final List<Product>? products;
  final Shipping? shipping;
  final PaymentMethodOptions? paymentMethodOptions;
}

orderId
주문을 구분하는 ID입니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.
orderName
주문명입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.
customerEmail
고객의 이메일입니다. 이메일을 파라미터로 전달하면 해당 이메일로 결제 내용을 통보합니다. 최대 길이는 100자입니다.
customerName
고객의 이름입니다. 최대 길이는 100자입니다.
appScheme
내 상점의 앱 스킴을 지정하면 외부 앱(페이북/ISP)에서 상점 앱으로 돌아올 수 있습니다. 예를 들면 testapp://같은 형태입니다.
taxFreeAmount
결제할 금액 중 면세 금액입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다.
* 면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점인 경우에는 적용되지 않습니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.
taxExemptionAmount
과세를 제외한 결제 금액(컵 보증금 등)입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다. 카드 결제 또는 간편결제로 계좌이체할 때 사용하세요.
* 과세 제외 금액이 있는 카드 결제는 부분 취소가 안 됩니다.
cultureExpense
가상계좌, 계좌이체 결제일 때 적용할 수 있는 문화비(도서, 공연 티켓, 박물관·미술관 입장권 등) 지출 여부입니다.
useEscrow
가상계좌, 계좌이체 결제일 때 적용할 수 있는 에스크로 사용 여부입니다. 값을 주지 않으면 결제창에서 고객이 직접 에스크로 결제 여부를 선택합니다.
escrowProducts
각 상품의 상세 정보 객체를 담는 배열입니다. 가상계좌, 계좌이체에서 에스크로를 사용하는 상점이라면 필수 파라미터입니다.
```
class EscrowProduct {
  final String id;
  final String name;
  final String code;
  final num unitPrice;
  final num quantity;
}
```

id
상품의 ID입니다. 이 값은 유니크해야 합니다.
name
상품 이름입니다.
code
상점에서 사용하는 상품 관리 코드입니다.
unitPrice
상품의 가격입니다. 전체를 합한 가격이 아닌 상품의 개당 가격입니다.
quantity
상품 구매 수량입니다.
customerMobilePhone
고객의 휴대폰 번호입니다. 가상계좌 결제에는 입금 안내가 전송되고, 퀵계좌결제창에서는 고객의 휴대폰 번호를 자동 완성합니다.
showCustomerMobilePhone
ㅁ 가상계좌 결제창에서 휴대폰 번호 입력 필드 노출 여부입니다. false를 넘기면 가상계좌 결제창에서 휴대폰 번호 입력 필드를 보여주지 않습니다. 기본값은 true 입니다.
mobileCarrier
휴대폰 결제창에서 선택할 수 있는 통신사를 제한합니다. 배열에 통신사 코드를 추가하면 해당 통신사 코드만 선택할 수 있는 결제창이 뜹니다.
products
고객이 구매한 각 상품의 상세 정보 객체를 담는 배열입니다. 예를 들어 고객이 세 가지 종류의 상품을 구매했다면 길이가 3인 배열이어야 합니다.
products 정보는 필수가 아니지만 이 정보를 보내려면 아래 항목은 모두 필수입니다.
```
class Product {
  final String name;
  final num quantity;
  final num unitamount;
  final String currency;
  final String description;
}
```
- name 필수 · string
  상품 이름입니다.
- quantity 필수 · number
  상품 구매 수량입니다.
- unitAmount 필수 · number
  상품의 가격입니다. 전체를 합한 가격이 아닌 상품의 개당 가격입니다.
- currency 필수 · string
  상품 가격의 통화입니다.
- description 필수 · string
  상품에 대한 부가적인 설명입니다.

shipping

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

class Shipping {
  final String fullName;
  final Address address;
}

fullName
고객의 이름입니다.

address

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

class Address {
  final String country;
  final String? line1;
  final String? line2;
  final String? area1;
  final String area2;
  final String? postalCode;
}

paymentMethodOptions
결제수단의 추가 파라미터를 담는 객체입니다. 결제수단이나 결제사 별로 파라미터를 제공합니다. PayPal을 연동할 때는 paypal을 사용합니다.
```
class PaymentMethodOptions {
  final PayPal? paypal;
}
```
payPal
PayPal의 추가 파라미터를 담는 객체입니다. setTransactionContext는 PayPal에서 추가로 요청하는 STC(Set Transaction Context) 정보를 객체로 전달하는 필드입니다. 이 정보는 PayPal에서 부정거래, 결제 취소, 환불 등 리스크 관리에 활용합니다. 결제 거래의 안전성과 신뢰성을 확보하려면 이 정보를 전달해야 합니다. PayPal STC 문서를 참고해서 업종에 따라 필요한 파라미터를 추가해주세요. 문서의 표에 있는 ‘Data Field Name’ 컬럼 값을 객체의 ‘key’로, ‘Description’에 맞는 값을 객체의 ‘value’로 넣어주시면 됩니다.
* 이 정보는 토스페이먼츠에서 관리하지 않습니다.

Result

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

class Result {
  final Success? success;
  final Fail? fail;
}

success

class Success extends TossPaymentResult {
  final String paymentKey;
  final String orderId;
  final num amount;
  final Map<String, String>? additionalParams;
}

paymentKey
결제를 식별하는 키 값입니다. 결제 승인, 결제 조회, 결제 취소 등 운영에 필요한 값입니다.
orderId
주문 ID입니다. 결제 요청에 담아 보낸 값입니다.
amount
결제 금액입니다.
additionalParameters
브랜드페이를 사용하고 있다면 필요한 파라미터입니다.
paymentType
결제 유형입니다. NORMAL, BRANDPAY, KEYIN 중 하나입니다.
- NORMAL: 일반 결제입니다. 코어 결제 승인 API를 호출해서 결제를 완료하세요.
- BRANDPAY: 브랜드페이 결제입니다. 브랜드페이 결제 승인 API를 호출해서 결제를 완료하세요.
- KEYIN: 키인 결제입니다. 코어 결제 승인 API를 호출해서 결제를 완료하세요.

fail

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

class Fail extends TossPaymentResult {
  final String errorCode;
  final String errorMessage;
  final String orderId;
}

errorCode
에러 코드입니다. SDK 에러가 돌아옵니다. failUrl로 전달되는 에러, 공통 SDK 에러, 결제위젯 SDK 에러가 모두 포함됩니다.
errorMessage
에러 메시지입니다.
orderId
주문 ID입니다. 결제 요청에 담아 보낸 값입니다.

PaymentMethodWidgetControl

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

updateAmount

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

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

Future<void> updateAmount({ 
    required num amount 
})

파라미터

amount
새로운 결제 금액입니다.

getSelectedPaymentMethod

고객이 선택한 결제수단을 전달하는 메서드입니다.

Future<SelectedPaymentMethod> getSelectedPaymentMethod()

SelectedPaymentMethod

class SelectedPaymentMethod {
  final String type;
  final String? method;
  final EasyPay? easyPay;
  final String? paymentMethodKey;
}

type
결제 타입 정보입니다. NORMAL(일반결제), BRANDPAY(브랜드페이), KEYIN(키인 결제), CUSTOM(커스텀 결제수단) 중 하나입니다.
method
결제수단입니다. 카드, 가상계좌, 간편결제, 휴대폰, 계좌이체, 문화상품권, 도서문화상품권, 게임문화상품권 중 하나입니다.
easypay
결제수단이 간편결제일 때 반환되는 간편결제 정보입니다.
```
class EasyPay {
  final String? provider;
}
```
provider
선택한 간편결제사 코드입니다.
paymentMethodKey
결제 타입이 CUSTOM일 때 반환되는 커스텀 결제수단 키입니다.

AgreementWidgetControl

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

getAgreementStatus

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

Future<AgreementStatus> getAgreementStatus()

AgreementStatus

class AgreementStatus {
  final bool agreedRequiredTerms;
  final List<AgreementTerm> terms;
}

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

terms

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

class AgreementTerm {
  final String id;
  final bool agreed;
  final bool required;
}

id
약관의 식별자입니다.
agreed
약관의 고객 동의 여부입니다.
required
약관의 필수 여부입니다.

.css-p1o082{width:calc(0.8em + 8px);height:0.8em;position:absolute;top:calc(50% - 0.4em);left:calc(-0.8em - 8px);padding-right:8px;opacity:0;-webkit-transition:opacity 0.2s ease-in-out;-webkit-transition:opacity 0.2s ease-in-out;transition:opacity 0.2s ease-in-out;}결제위젯 Flutter SDK

요구 사항

외부 라이브러리 의존성

패키지 추가하기

Android 설정

예시 코드

PaymentMethodWidget

파라미터

AgreementWidget

파라미터

PaymentWidget

파라미터

renderPaymentMethods

파라미터

renderAgreement

파라미터

requestPayment

Result

PaymentMethodWidgetControl

updateAmount

파라미터

getSelectedPaymentMethod

SelectedPaymentMethod

AgreementWidgetControl

getAgreementStatus

AgreementStatus

결제위젯 Flutter SDK