Getting Started with the Flutter Plugin for In-App Payments SDK

April 5, 2023 · View on GitHub

This guide walks you through the process of setting up a new Flutter project with In-App Payments SDK. See the Flutter In-App Payments SDK Technical Reference for more detailed information about the methods available.

Before you start

  • You will need a Square account enabled for payment processing. If you have not enabled payment processing on your account (or you are not sure), visit squareup.com/activate.
  • Follow the Install instructions in the Flutter Getting Started guide to set up your Flutter development environment.

Process overview

Step 1: Create a Flutter project

The basic command is:

flutter create in_app_payments_flutter_app

See the Create the app step of the Test Drive section in Flutter's getting started guide for more detailed instructions.

Step 2: Update your iOS project

To use the In-App Payments plugin on iOS devices, install In-App Payments SDK for iOS to make it an available resource for the Flutter library.

  1. Open your iOS project Runner.xcodeproj with Xcode.
  2. Set the iOS Deployment Target to 12.0 or above.
  3. Add an In-App Payments SDK build phase:
    1. Open Runner.xcworkspace in Xcode.
    2. In the Build Phases tab for your application target, click the + button at the top of the pane.
    3. Select New Run Script Phase.
    4. Paste the following into the editor panel of the new run script: 
      FRAMEWORKS="${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}"
"${FRAMEWORKS}/SquareInAppPaymentsSDK.framework/setup"

Step 3: Configure the In-App Payments SDK dependency

Edit the pubspec.yaml file in your flutter directory to define the In-App Payments SDK dependency:

dependencies:

  ...

  square_in_app_payments: ^1.7.1

Step 4: Get Square Application ID

  1. Open the Square Application Dashboard.
  2. Create a new Square application.
  3. Click on the new application to bring up the Square application settings pages.
  4. You will need the Application ID from the Credentials page to configure In-App Payments SDK in the next steps.

Step 5: Initialize the In-App Payments SDK

  1. Add code that initialize the In-App Payments SDK.

    import 'package:square_in_app_payments/models.dart';
import 'package:square_in_app_payments/in_app_payments.dart';

class _MyAppState {
  ...
  Future<void> _initSquarePayment() async {
    await InAppPayments.setSquareApplicationId('APPLICATION_ID');
  }
  ...
}

  2. Replace APPLICATION_ID with the application ID from the application dashboard.

Step 6: Customize card entry appearance

The Android and iOS platforms allow customization of the card entry screen but provide different customization mechanisms. For more information, read about customizing the payment entry form in the Square developer documentation.

Android

You can customize the payment form UI by overriding the sqip.Theme.CardEntry theme resource. The SDK honors customization of system style attributes and provides 3 custom style attributes.

Custom Style attribute Styled UI element
sqipErrorColor The color of invalid text input
sqipSaveButtonText The text of the button the customer clicks to submit their card information
sqipActivityTitle The title of the payment form displayed in the action bar.

Change the appearance of the save button and the card information form to match the styles in the app's theme. This will entirely override the style for these elements, giving the application full control over their appearance.

  1. Open {YOUR_PROJECT}/android/app/src/main/res/values/themes.xml
  2. Add an item with the name="editTextStyle" and the value set to your desired style.
  <style name="sqip.Theme.CardEntry" parent="sqip.Theme.BaseCardEntryAppTheme">
    …
     <item name="editTextStyle">@style/CustomEditText</item>
  </style>

  <style name="CustomEditText" parent="@style/Widget.AppCompat.EditText">
    <item name="android:textColor">@color/blue</item>
  </style>
  1. Add an item with the name="buttonStyle" and the value set to your desired style.
  <style name="sqip.Theme.CardEntry" parent="sqip.Theme.BaseCardEntryAppTheme">
    …
     <item name="buttonStyle">@style/CustomButton</item>
  </style>

  <style name="CustomButton" parent="Widget.AppCompat.Button.Colored">
    <item name="android:textAllCaps">false</item>
    <item name="android:textSize">18sp</item>
  </style>

iOS

For iOS devices, set the card entry error text and background color, keyboard appearance and message color.

  1. Add code that creates a card entry theme and sets it in the plugin.

    Future _setIOSCardEntryTheme() async {
  var themeConfiguationBuilder = IOSThemeBuilder();
  themeConfiguationBuilder.saveButtonTitle = 'Pay';
  themeConfiguationBuilder.errorColor = RGBAColorBuilder()
    ..r = 255
    ..g = 0
    ..b = 0;
  themeConfiguationBuilder.tintColor = RGBAColorBuilder()
    ..r = 36
    ..g = 152
    ..b = 141;
  themeConfiguationBuilder.keyboardAppearance = KeyboardAppearance.light;
  themeConfiguationBuilder.messageColor = RGBAColorBuilder()
    ..r = 114
    ..g = 114
    ..b = 114;

  await InAppPayments.setIOSCardEntryTheme(themeConfiguationBuilder.build());
}

  2. Call the _setIOSCardEntryTheme method.

    if (Platform.isIOS) {
   await _setIOSCardEntryTheme();
}

Step 7: Implement the Payment flow

Add code to the _MyAppState_ class that starts the payment flow and handles the response.

Note: You cannot start the payment flow from a modal screen. To start the payment flow, you must close the modal screen before calling startCardEntryFlow.

import 'package:square_in_app_payments/models.dart';
import 'package:square_in_app_payments/in_app_payments.dart';
class _MyAppState extends State<MyApp> {
...
  /** 
  * An event listener to start card entry flow
  */
  Future<void> _onStartCardEntryFlow() async {
    await InAppPayments.startCardEntryFlow(
        onCardNonceRequestSuccess: _onCardEntryCardNonceRequestSuccess,
        onCardEntryCancel: _onCancelCardEntryFlow);
  }

  /**
  * Callback when card entry is cancelled and UI is closed
  */
  void _onCancelCardEntryFlow() {
    // Handle the cancel callback
  }

  /**
  * Callback when successfully get the card nonce details for processig
  * card entry is still open and waiting for processing card nonce details
  */
  void _onCardEntryCardNonceRequestSuccess(CardDetails result) async {
    try {
      // take payment with the card nonce details
      // you can take a charge
      // await chargeCard(result);

      // payment finished successfully
      // you must call this method to close card entry
      // this ONLY apply to startCardEntryFlow, please don't call this method when use startCardEntryFlowWithBuyerVerification
      InAppPayments.completeCardEntry(
          onCardEntryComplete: _onCardEntryComplete);
    } on Exception catch (ex) {
      // payment failed to complete due to error
      // notify card entry to show processing error
      InAppPayments.showCardNonceProcessingError(ex.message);
    }
  }

  /**
  * Callback when the card entry is closed after call 'completeCardEntry'
  */
  void _onCardEntryComplete() {
    // Update UI to notify user that the payment flow is finished successfully
  }
  ...
}

Note: To start the payment flow with Strong Customer Authentication, you should call startCardEntryFlowWithBuyerVerification. InAppPayments.completeCardEntry is NOT needed for this call.

Note: To start Strong Customer Authentication for card-on-file, you should call startBuyerVerificationFlow. InAppPayments.completeCardEntry is NOT needed for this call.

Note: The chargeCard method in this example shows a typical REST request on a backend process that uses the Payments API to take a payment with the supplied nonce. See BackendQuickStart Sample to learn about building an app that processes payment nonces on a server.

Note: To start Secure Remote Commerce (Mastercard Click-to-pay), you should call startSecureRemoteCommerce.