Implementing Square Reader SDK in person payments in Flutter/ Dart for IOS


We are trying to implement Square Reader in-person payments in our mobile app developed in Flutter/ Dart.
we followed below link to get going:

We have setup two applications in square portal, one for staging environment and another for prod environment. We have also enabled repository credentials for both apps.

My application details:
Mobile app in Flutter/ dart
Embedded Square reader sdk xc framework in Xcode using staging app credentials as listed in step:
Download and configure the latest version of SquareReaderSDK.xcframework in your project root by replacing YOUR_SQUARE_READER_APP_ID and YOUR_SQUARE_READER_REPOSITORY_PASSWORD with your Reader SDK credentials.
The command below will download the framework into the current directory. The framework must be in either the ios directory or the ios/Frameworks directory of your Flutter project.
ruby <(curl install
Square reader sdk works okay on my mobile app in IOS emulator but crashes on actual physical device (Ipad).

I have the following questions:
1: How to apply prod repository credentials? The confusion is when installing the framework we are supplying staging credentials. so do I need to un-install the framework and re-install it with prod repo credentials?
2: On the physical device (Ipad), where the user will be using a Square Reader device, do we need to install any additional software from Square? Will initiating the checkout flow automatically open the Square reader UI?

  1. The answer to this is probably no, but still asking, do we have to pass in test credit cards and check the general functionality of the app before moving it to production.

Any help is much appreciated.


If you want to change environments from staging to production you’ll need to un-install and reinstall the framework of the environment you want to target.

When you initialize the checkout flow on the device Square UI will be used for the checkout. All other Screens can be specific to your app. :slightly_smiling_face:

Thank you for your reply.
Could you please answer the following:

1: Please confirm the Square UI is still coming from the SDK not a separate UI that we will have to build correct?

2: What is proper way to uninstall the framework?

For installing we used

ruby <(curl install

Really appreciate your time and reply.

Thank you once again.

Yes, Square controls the checkout UI for processing payments any other UI is your custom UI for the app.

As for deleting the framework you’ll need to manually go into the project to remove it. There isn’t a command line prompt to remove the framework like there is to install it. :slightly_smiling_face:

Thank you Bryan. I will give it a shot and get back to you with updates, may be by Next Wednesday.

Appreciate your help.

On last thing, No need to install any additional software on the IPad device to use the Square Reader, correct?
Basically deploy the mobile app which has embedded reader sdk framework, grab the square reader plug it into the lightning port to begin accepting payments and that will be it right?

You’ll still need to build the other underlining functionality of the app that you integrate the SDK into. Only our Quickstart apps will work right out of the box. :slightly_smiling_face:

Thank you Bryan.

Here is my checkout method which works great when run on ios simulator on my MacOS.
In my earlier attempt deploying this on Ipad, crashed the entire app, I am going to retry this and see how it goes.

void onCheckout() async {
// Check requried permissions
await _checkStatus();
var builder = CheckoutParametersBuilder();
builder.amountMoney = MoneyBuilder()
…amount = widget.amountToCharge
…currencyCode = ‘USD’;

builder.skipReceipt = false;
builder.collectSignature = true;
builder.allowSplitTender = false;
builder.delayCapture = false;
builder.note =  "refid";

builder.additionalPaymentTypes = ListBuilder([,
// builder.tipSettings = TipSettingsBuilder()
//   ..showCustomTipField = true
//   ..showSeparateTipScreen = false
//   ..tipPercentages = ListBuilder([15, 20, 30]);

CheckoutParameters checkoutParameters =;

String _authCode = await PaymentManager().getAuthorizationCode();

bool _isAuthorized = await ReaderSdk.isAuthorized;

if(! _isAuthorized)
 await ReaderSdk.authorize(_authCode); 

// all un-successful Checkout result ends in an exception
// inclding user cancelling the transactin
await ReaderSdk.startCheckout(checkoutParameters);

// If it reaches this point the transaction was successful
setState(() {
   widget.resultMessage = "Successful";

} on ReaderSdkException catch (e) {
switch (e.code) {
case ErrorCode.checkoutErrorCanceled:
// Handle canceled transaction here
setState(() {
widget.resultMessage = “transaction canceled.”;
debugPrint(‘transaction canceled.’);
case ErrorCode.checkoutErrorSdkNotAuthorized:
setState(() {
widget.resultMessage = “Handle sdk not authorized”;
// Handle sdk not authorized
// Navigator.pushReplacementNamed(context, ‘/’);
var errorMessage = e.message!;
setState(() {
widget.resultMessage = errorMessage;



Hi Bryan, Hope things are going good with you.

I am unable to make this Square reader SDK work.
When I run my code on Mac with ios simulator with VS code, the transactions are going thru okay, but when I deploy it onto an IPAD, after I enable the microphone, location and blue tooth and I hit the checkout button I see a white screen and the app crashes( in the sense it gets minimized into an icon) and I keep clicking the icon all I see is a white screen. nothing is happening.

Please suggest what could be wrong, I am not sure how to see the logs on the IPAD for more details strangely this does not happen in the development PC on VS code, so I need your help to look into this.

Thank you for your time.


When this happens do you still have the device connected to your computer? If so are there any terminal logs with errors that will help you debug? :slightly_smiling_face:

Thank you for your reply.
Yes the device is still connected and the white screen too. This works fine on my PC where I could see the logs, but on IPAD I only see a white screen, not sure how to look at the log information on IPAD.

Well after googling a bit, I found a way to look into the device logs, and I am surprised for crash reason: missing NSBluetoothAlwaysUsageDescription. I followed the instruction on the link:
(reader-sdk-flutter-plugin/ at master · square/reader-sdk-flutter-plugin · GitHub) which only had NSBluetoothPeripheralUsageDescription
I think it will help people like me if someone from Square team would update these instructions.
Let me give another try with the changes. Thank you!

Hmm, okay! I’ll be sure to pass this along. :slightly_smiling_face:

After enabling both blue tooth settings in info.plist, as soon as I start the app on IPAD, it now says “Developer Mode Required”
For using Square reader do we need to turn on Developer Mode?

I enabled the developer mode and successfully tested the credit card transaction with real card.
I recommend the following:
DO NOT bind installations with user credentials.
Use standard channel such as pub dev package that should have the necessary methods to make the calls with credentials etc.
Provide the ability for the consumer to configure environments such as Dev, Beta, Prod , and apply restriction (such as no test credit card) to only prod, this way from the developer perspective it will become lot easier to implement.

I think its not a good idea to release a product with lots of restrictions.

Glad to hear that you got it working. We’re constantly working to improve our features based on feedback like this, so I’ll be sure to share your request to the API product team. :slightly_smiling_face:

Bryan, Thank you for all your help.
Could you please confirm if we must enable Developer Mode to use Square Reader SDK for in-person payments.
I just want re-confirm so that we can inform the client the reason why they should enable it on all devices used.
Based on what I could see so far is that if I include Blue tooth in info plist, the application is prompting for Developer Mode Required and if I don’t include Blue tooth the application is crashing reporting missing blue tooth. I upgraded the ios to 16.1 on the ipad for this test.

It appears this is a bug in ios
iOS 16 bug requires Developer Mode to run TestFlight apps - 9to5Mac

Good morning Bryan,
Did you get a chance to confirm that Square Reader SDK is prompting for Developer Mode on Ios 16.2 versions.
If not please do so, we are at a point where we must provide a reason for not upgrading to Ios 16.2.

Once again, thank you for all your help.

Developer Mode isn’t required with Reader SDK. When it crashes is there any additional detail of what’s missing other then missing bluetooth? :slightly_smiling_face: