통합 연동 가이드 (포인트 시스템 포함)

Last Update：2025-01-15

🦋 Flutter 연동 가이드

돈나무 서버 정보

Flutter 연동 가이드

돈나무 Flutter SDK 사용법을 소개합니다.

돈나무 서버 정보

개발 서버 URI: https://sandbox-api.moneytree.bz 운영 서버 URI: https://api.moneytree.bz

설치 가이드

moneytree SDK를 설치하기 위해 터미널에서 아래 명령어를 실행합니다.

flutter pub add moneytree
Shell
복사

예제 코드

아래 예제는 돈나무 위젯(웹뷰)과 결제 위젯(웹뷰)을 같이 사용하는 경우를 고려하여 작성되었습니다.

돈나무 위젯을 조건부 연산자를 이용할 경우 위젯이 초기화되는 현상을 방지하기 위하여 Parent Widget을 Stack으로 사용하실 것을 권장합니다.

import 'package:moneytree/moneytree.dart';

...

  Widget build(BuildContext context) {
	  late MoneytreeController controller;
	  
	 final jwtToken = '돈나무 sign-in API(Endpoints 항목 참고)를 호출하여 얻은 토큰 값';
  
    return const MaterialApp(
      home: Scaffold(
        body: Stack(
          children: [
            MoneytreeWebview(
		          // (1) Mode
		          mode: MoneytreeMode.test,
		          // (2) JWT TOKEN
	            jwtToken: jwtToken,
		          // (3) onInit: 돈나무 웹뷰 초기 설정 완료를 알리는 상태
	            onInit: (newController) {            
	                controller = newController;
	            },
	            // (4) onEventReceived: 돈나무 웹뷰 이벤트 리스너
	            onEventReceived: (event) {
	              switch (event.type) {
	                case MoneytreeEventType.payment:
	                  String orderId = event.data.orderId;
	                  controller.confirmPayment(orderId);
	                  break;
	              }
	            },
	            // (5) onPressedBackInMain: 메인 페이지에서 백 버튼을 눌렀을 때
	            //     호출됩니다.
	            onPressedBackInMain: () {
	              // To do
	            },
	          ),
						PaymentWidget(
						  // 결제 위젯
						  ...
						),
          ],
        ),
      ),
    );
  }
Dart
복사

Name	Type	Description	Default	Required
jwtToken	String	- Moneytree 플랫폼에 인증하기 위위해 JWT 토큰입니다. Sign-in API(Backend 항목 참고)를 호출하여 얻을 수 있습니다.	없음	O
onInit	Function(MoneytreeController _controller) ⇒ void	- MoneytreeController가 초기화될 때 호출되는 콜백 함수입니다. - MoneytreeController를 이용해서 결제 확인(confirmPayment), 결제 실패 함수(failedPayment)를 호출할 수 있습니다.		O
onEventReceived	Function(MoneytreeEvent event) ⇒ void	- Moneytree 플랫폼에서 발생하는 이벤트를 수신하기 위한 콜백 함수입니다.		O
mode	MoneytreeMode	1. Moneytree.prod (default): 돈나무 운영 서비스를 이용합니다. 2. Moneytree.test: 돈나무 개발(환경) 서비스를 이용합니다(실거래 방지를 위해 개발 환경에서는 반드시 이 모드를 사용해주시기 바랍니다).	MoneytreeMode.prod	X
onPressedBackInMain	Function() ⇒ void	메인 화면에서 뒤로 가기 버튼(Android)이 눌렸을 때 호출되는 콜백 함수입니다.		X

이벤트

이벤트(Event)란, 유저의 행동에 의해 돈나무 웹사이트로부터 요청받은 행위를 말하며, onEventReceived 를 통해 이벤트를 받을 수 있습니다.

  onEventReceived: (event) {}
Dart
복사

또한, event 객체는 다음과 같은 값이 있습니다. event.type에 따라 data 타입이 달라질 수 있습니다.

enum MoneytreeEventType {
  payment,
}

class MoneytreeEvent {
  final MoneytreeEventType type;
  final dynamic data;

  MoneytreeEvent({required this.type, required this.data});
} 
Dart
복사

Name	Type	Description
type	MoneytreeEventType	이벤트의 종류를 나타냅니다.
data	dynamic	이벤트 요청을 받았을 때 오는 데이터를 의미합니다.

결제 이벤트

결제 이벤트의 event.data에는 다음과 같은 값이 있습니다. 총 주문 금액에서 사용된 포인트를 뺀 값이 결제 금액입니다.

Name	Type	Description	Required
orderId	String	돈나무 주문 ID	O
totalAmount	int	총 주문 금액	O
usedPoint	int	사용된 포인트	O
paidAmount	int	결제된 금액	O
expirationTime	DateTime	결제 만료시간 결제 만료시간이 지난 결제 완료 건은 처리되지 않습니다.	O
createdAt	String	주문 생성일시	O

사용자의 결제 프로세스 중 PG사의 결제 승인 API를 호출 하기 전 돈나무 Backend 결제 완료 API를 호출해야 합니다(Backend에서 요청하시는 것을 권장드립니다). 그 다음 PG사의 결제 승인 API를 호출하여 모든 결제 프로세스를 완료합니다(돈나무 결제 완료 API는 해당 주문 건을 검증하고 최종 결제 완료 처리 후 상품 생성 및 지급합니다).

curl -X POST "https://api.moneytree.bz/v1/order/complete" \
		 -H "Content-Type: application/json" \
		 -H "x-api-key: YOUR_API_KEY"
     -d '{"orderId": 돈나무 Order Id}'
Shell
복사

결제 프로세스가 성공적으로 완료되었을 경우에는 orderId를 담아 confirmPayment를 호출해야 합니다. 단, 결제 프로세스 실패가 일어났을 경우에는 failedPayment를 호출해야 합니다.

ConfirmPayment

결제 프로세스가 성공적으로 완료되었을 경우 orderId를 담아 호출합니다. 단, 주문 생성 후 만료시간(5분)이 지났을 경우, 결제 실패 페이지로 이동하게 됩니다.

void confirmPayment(String orderId) {}
Dart
복사

Name	Type	Description	Required
orderId	String	돈나무 주문 ID	O

예시코드

MoneytreeWebview(
  mode: MoneytreeMode.test,
  jwtToken: jwtToken,
  onInit: (newController) {
    controller = newController;
  },
  onEventReceived: (event) {
    switch (event.type) {
      case MoneytreeEventType.payment:
        String orderId = event.data['orderId'];
        controller.confirmPayment(orderId);
        break;
    }
  },
);
Dart
복사

FailedPayment

결제 프로세스가 실패했을 경우, message를 선택적으로 담아서 호출합니다. 단, 이 함수를 호출하게되면 결제 실패 페이지로 이동하게 됩니다.

void failedPayment([String message = '']) {}
Dart
복사

Name	Type	Description	Required
message	String	에러 메세지	X

예제코드

MoneytreeWebview(
  mode: MoneytreeMode.test,
  jwtToken: jwtToken,
  onInit: (newController) {
    controller = newController;
  },
  onEventReceived: (event) {
    switch (event.type) {
      case MoneytreeEventType.payment:
        controller.failedPayment(); // (1) 기본 메세지: 결제 중에 알 수 없는 에러가 발생하였습니다.
        controller.failedPayment('구매 불가 상품입니다.'); // (2)
        break;
    }
  },
);
Dart
복사