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.
- 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.
- Step 1: Create a Flutter project
- Step 2: Add the In-App Payments SDK to your iOS project
- Step 3: Configure the In-App Payments SDK dependency
- Step 4: Get Square Application ID
- Step 5: Initialize the In-App Payments SDK
- Step 6: Customize card entry appearance
- Step 7: Implement the Payment flow
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.
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.
- Open your iOS project
Runner.xcodeproj
with Xcode. - Set the
iOS Deployment Target
to 12.0 or above. - Add an In-App Payments SDK build phase:
- Open
Runner.xcworkspace
in Xcode. - In the Build Phases tab for your application target, click the + button at the top of the pane.
- Select New Run Script Phase.
- Paste the following into the editor panel of the new run script:
FRAMEWORKS="${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}" "${FRAMEWORKS}/SquareInAppPaymentsSDK.framework/setup"
- Open
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
- Open the Square Application Dashboard.
- Create a new Square application.
- Click on the new application to bring up the Square application settings pages.
- You will need the Application ID from the Credentials page to configure In-App Payments SDK in the next steps.
-
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'); } ... }
-
Replace
APPLICATION_ID
with the application ID from the application dashboard.
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.
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.
- Open
{YOUR_PROJECT}/android/app/src/main/res/values/themes.xml
- 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>
- 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>
For iOS devices, set the card entry error text and background color, keyboard appearance and message color.
-
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()); }
-
Call the
_setIOSCardEntryTheme
method.if (Platform.isIOS) { await _setIOSCardEntryTheme(); }
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
.