diff --git a/lib/iamport_payment.dart b/lib/iamport_payment.dart index af66b82..7d2620d 100644 --- a/lib/iamport_payment.dart +++ b/lib/iamport_payment.dart @@ -14,9 +14,20 @@ import 'package:uni_links/uni_links.dart'; class IamportPayment extends StatelessWidget { final PreferredSizeWidget? appBar; + + /// 웹뷰 로딩 컴포넌트 final Widget? initialChild; + + /// 가맹점 식별코드 final String userCode; + + /// 결제 데이터 final PaymentData data; + + /// 콜백 함수 + /// + /// 콜백 함수는 필수입력 필드로, 결제/본인인증 완료 후 라우트 이동을 위해 아래와 같이 로직을 작성할 + /// 수 있습니다. 콜백 함수에 대한 자세한 설명은 [콜백 설정하기](https://github.com/iamport/iamport_flutter/blob/main/example/manuals/CALLBACK.md)를 참고하세요. final callback; IamportPayment({ diff --git a/lib/model/payment_data.dart b/lib/model/payment_data.dart index 9316c5f..d4e1eb9 100644 --- a/lib/model/payment_data.dart +++ b/lib/model/payment_data.dart @@ -7,62 +7,185 @@ part 'payment_data.g.dart'; @JsonSerializable() class PaymentData { - String? pg; // PG사 - + /// PG사 + /// + /// 하나의 아임포트계정으로 여러 PG를 사용할 때 구분자. + /// 누락되거나 매칭되지 않는 경우 관리자 콘솔에서 설정한 기본PG가 호출됨. + /// + /// 값 형식: [PG사 코드값] 또는 [PG사 코드값].[PG사 상점아이디] + /// + /// - html5_inicis(이니시스웹표준) + /// - inicis(이니시스ActiveX결제창) + /// - kcp(NHN KCP) + /// - kcp_billing(NHN KCP 정기결제) + /// - uplus(토스페이먼츠(구 LG U+)) + /// - nice(나이스페이) + /// - jtnet(JTNet) + /// - kicc(한국정보통신) + /// - bluewalnut(블루월넛) + /// - kakaopay(카카오페이) + /// - danal(다날휴대폰소액결제) + /// - danal_tpay(다날일반결제) + /// - mobilians(모빌리언스 휴대폰소액결제) + /// - chai(차이 간편결제) + /// - syrup(시럽페이) + /// - payco(페이코) + /// - paypal(페이팔) + /// - eximbay(엑심베이) + /// - naverpay(네이버페이-결제형) + /// - naverco(네이버페이-주문형) + /// - smilepay(스마일페이) + /// - alipay(알리페이) + /// - paymentwall(페이먼트월) + /// - payple(페이플) + /// - eximbay(엑심베이) + /// - tosspay(토스간편결제) + /// - smartro(스마트로) + /// - settle(세틀뱅크) + String? pg; + + /// 결제수단 + /// + /// - `card`(신용카드) + /// - `trans`(실시간계좌이체) + /// - `vbank`(가상계좌) + /// - `phone`(휴대폰소액결제) + /// - `samsung`(삼성페이 / 이니시스, KCP 전용) + /// - `kpay`(KPay앱 직접호출 / 이니시스 전용) + /// - `kakaopay`(카카오페이 직접호출 / 이니시스, KCP, 나이스페이먼츠 전용) + /// - `payco`(페이코 직접호출 / 이니시스, KCP 전용) + /// - `lpay`(LPAY 직접호출 / 이니시스 전용) + /// - `ssgpay`(SSG페이 직접호출 / 이니시스 전용) + /// - `tosspay`(토스간편결제 직접호출 / 이니시스 전용) + /// - `cultureland`(문화상품권 / 이니시스, 토스페이먼츠(구 LG U+), KCP 전용) + /// - `smartculture`(스마트문상 / 이니시스, 토스페이먼츠(구 LG U+), KCP 전용) + /// - `happymoney`(해피머니 / 이니시스, KCP 전용) + /// - `booknlife`(도서문화상품권 / 토스페이먼츠(구 LG U+), KCP 전용) + /// - `point`(베네피아 포인트 등 포인트 결제 / KCP 전용) + /// - `wechat`(위쳇페이 / 엑심베이 전용) + /// - `alipay`(알리페이 / 엑심베이 전용) + /// - `unionpay`(유니온페이 / 엑심베이 전용) + /// - `tenpay`(텐페이 / 엑심베이 전용) @JsonKey(name: 'pay_method') - String payMethod; // 결제수단 + String payMethod; - bool? escrow; // 에스크로 여부 + /// 에스크로가 적용되는 결제창을 호출할지 여부 + bool? escrow; + /// 가맹점에서 생성/관리하는 고유 주문번호 + /// + /// 이미 결제가 승인 된(status: paid) merchant_uid로는 재결제 불가 @JsonKey(name: 'merchant_uid') - String merchantUid; // 주문번호 + String merchantUid; + + /// 주문명 + /// + /// 원활한 결제정보 확인을 위해 입력 권장 + /// + /// PG사마다 차이가 있지만, 16자이내로 작성 권장 + String? name; - String? name; // 주문명 - int amount; // 결제금액 + /// 결제할 금액 + int amount; + /// 가맹점 임의 지정 데이터 + /// + /// 주문건에 대해 부가정보를 저장할 공간이 필요할 때 사용 @JsonKey(name: 'custom_data') - Map? customData; // 임의 지정 데이터 + Map? customData; + /// [amount] 중 면세공급가액에 해당하는 금액 + /// + /// [자세히보기](https://docs.iamport.kr/tech/vat?lang=ko) @JsonKey(name: 'tax_free') - int? taxFree; // 면세 공급 가액 - - int? vat; // 부가세 - String? currency; // 화폐단위 - String? language; // 언어설정 - + int? taxFree; + + /// [amount] 중 부가세 금액 + /// + /// 복합과세 적용시 더 정확한 계산을 위해 tax_free 파라미터 사용을 권장 + @deprecated + int? vat; + + /// 통화 설정 + /// + /// PayPal은 원화(KRW) 미지원으로 USD가 기본값 + /// + /// PayPal에서 지원하는 통화는 [PayPal 지원 통화](https://developer.paypal.com/docs/reports/reference/paypal-supported-currencies/%20target=/) 참조 + /// + /// - KRW + /// - USD + /// - EUR + /// - JPY + String? currency; + + /// 결제창 화면의 언어 설정 + /// + /// - KG이니시스, 토스페이먼츠(구 LG U+), 나이스페이먼츠 : `en` 또는 `ko`(KG이니시스, 나이스 + /// 페이먼츠는 PC 결제창만 지원됨) + /// - PayPal: 2자리 region code[(PayPal 로케일 코드 참조)](https://developer.paypal.com/api/rest/reference/locale-codes/) + String? language; + + /// 주문자명 @JsonKey(name: 'buyer_name') - String? buyerName; // 구매자 이름 + String? buyerName; + /// 주문자 연락처 + /// + /// (누락되거나 공백일때 일부 PG사[엑심베이]에서 오류 발생) @JsonKey(name: 'buyer_tel') - String buyerTel; // 구매자 연락처 + String buyerTel; + /// 주문자 이메일[페이먼트월 필수] @JsonKey(name: 'buyer_email') - String? buyerEmail; // 구매자 이메일 + String? buyerEmail; + /// 주문자 주소 @JsonKey(name: 'buyer_addr') - String? buyerAddr; // 구매자 주소 + String? buyerAddr; + /// 주문자 우편번호 @JsonKey(name: 'buyer_postcode') - String? buyerPostcode; // 구매자 우편번호 + String? buyerPostcode; + /// 관리자 콘솔에서 설정하는 Notification URL대신 사용할 URL + /// + /// 주문마다 다른 혹은 복수의 Notification URL이 필요한 경우 사용 @JsonKey(name: 'notice_url') String? noticeUrl; + /// 50,000원 이상 금액 결제 시, 할부개월 수 선택 요소 제어 옵션 + /// + /// - 미입력: PG사의 기본 할부개월 수 목록 제공 + /// - `[]`: 일시불만 결제 가능 + /// - `2,3,4,5,6`: 일시불을 포함한 2, 3, 4, 5, 6개월까지 할부개월 선택 가능(KG이니시스, KCP + /// 만 지원) @JsonKey(name: 'display/card_quota') - List? displayCardQuota; // 할부개월수 - bool? digital; // 실물컨텐츠 여부 + List? displayCardQuota; + + /// 결제상품이 컨텐츠인지 여부(휴대폰 소액결제시 필수) + /// + /// 반드시 실물/컨텐츠를 정확히 구분해주어야 함 + bool? digital; + /// 가상계좌 입금기한(`YYYYMMDDhhmm`) @JsonKey(name: 'vbank_due') - String? vbankDue; // 가상계좌 입금기한 + String? vbankDue; + /// 리디렉션 방식으로 호출된 결제창에서 결제 후에 이동 될 주소 @JsonKey(name: 'm_redirect_url') String? mRedirectUrl; + /// 모바일 앱 결제중 앱복귀를 위한 URL scheme(WebView 결제시 필수) + /// + /// ISP/앱카드 앱에서 결제정보인증 후 기존 앱으로 복귀할 때 사용됨 @JsonKey(name: 'app_scheme') - String appScheme; // 앱 스킴 + String appScheme; + /// 계약된 사업자등록번호 10자리(기호 미포함) + /// + /// 다날-가상계좌 결제시 필수 항목 @JsonKey(name: 'biz_num') - String? bizNum; // 사업자번호 + String? bizNum; @JsonKey(name: 'customer_uid') String? customerUid; // 정기결제 카드정보 @@ -88,7 +211,7 @@ class PaymentData { required this.amount, this.customData, this.taxFree, - this.vat, + @deprecated this.vat, this.currency, this.language, this.buyerName, diff --git a/lib/widget/iamport_webview.dart b/lib/widget/iamport_webview.dart index a3d7e6f..4cd5dfa 100644 --- a/lib/widget/iamport_webview.dart +++ b/lib/widget/iamport_webview.dart @@ -13,7 +13,7 @@ class IamportWebView extends StatefulWidget { - +