Adding Payment Service to Cordova App with Square
Payment service either by credit card or cash is a very important feature for all types of business apps. There are many payment services available out there. However, we are going to use Square service in this article. You will learn how to add a payment service into a Cordova app and make a payment using Square service and Monaca Cloud IDE.
What is Square?
Square is a service that provides businesses with a portable Point-of-Sales (PoS) card reader for smartphones and tablets.
This gives businesses an easy-to-use and cost-efficient solution for providing customers the ability to purchase with credit cards. The cost for using Square is only a settlement fee. You can find various shops such as cafes and general merchandise stores already using this service.
What is Monaca?
Monaca is a Cross-platform hybrid mobile app development platform which has various cloud services and tools such as Cloud IDE (browser-based IDE), Localkit and CLI.
Monaca is a very simple development tool for Cordova apps. Even for people with less experience in app development can start using Monaca right away. Monaca has a flexible development environment. You can either develop on the cloud or locally. Without any installation, you can build your app and include any Cordova plugins easily within a few clicks.
Monaca also comes with Monaca Debugger app which is used to test your app on the fly in real-time without building it every time.
Creating Sample Application
In this section, a step-by-step guide on how to integrate Square service into Monaca app will be demonstrated. At the time of creating this tutorial, Square service can’t be integrated with Cordova Android platform. For this reason, we will only show how to integrate the service for Cordova iOS platform.
Tested Environments: iOS 11.0.2
Prerequisites
Before we can start using Square, we need to install the “Square Point of Sale (POS)” app on your iOS device. Then, create an account within the app.
If you want to charge with a credit card, we first must obtain a card reader then plug it into the earphone jack of your smartphone or tablet.
Step 1: Square Configuration
- If you do not already have a Square account, you will need to register for one. Information such as a bank account will be mandatory to handle transactions.
2. After completing the registration process, log in and navigate to the developer’s portal.
3. From the developer portal we can create and manage applications that require the use of the Square API. Lets create a new application.
4. Click on the newly created application. Then, you will find a generated Application ID under the Credentials section and it will be used in a later step.
5. Next, go to Point of Sale API tab and enter the following information:
- iOS App Bundle IDs:
io.monaca.square(if you are using the imported sample project) or input your own iOS app bundle ID - iOS App URL Schemes:
squaresample(if you are using the imported sample project) or input your own custom URL scheme. This will be our application’s custom URL scheme that will be create and configured from Monaca Cloud IDE. More details about this custom URL will be explained in Step 4 section.
Step 2: Importing Square Demo Project into Monaca Cloud IDE
Click on the link below to directly import the Square Demo project into your Monaca account. If you don’t have a Monaca account, please register here.
Step 3: Entering the Square’s Application ID
- Open the import project in Monaca Cloud IDE.
- Open
js/app.jsfile and replace the Square’s Application ID (you found in Step 1) in theclient_idvalue as follows:
// Square API's Application ID'
var client_id = 'REPLACE_YOUR_SQUARE_APPLICATION_ID_HERE';3. Save the change.
Step 4: Plugins Configuration
There are two plugins required in this sample application such as:
- Custom-URL-scheme
When developing an application that needs to communicate with and external app or to allow external apps to communicate with your app, custom URL schemes are used.
In this case, the “Square Point of Sale (POS)” application had created a custom URL scheme of square-commerce-v1:// to allow external apps to communicate with the Square app. By applying this URL scheme to a location.href function, we can invoke the “Square Point of Sale (POS)” app from within our app.
In addition, we will need a custom URL scheme of our own for allowing POS application to communicate with our app after it has completed processing a settlement. To achieve this, we need to use the Cordova plugin called Custom-URL-scheme.
Please note that the “Square Point of Sale (POS)” app does not communicate with the sandbox environment.
Custom-URL-scheme plugin is used to implement the URL scheme within Monaca apps. After adding the plugin, input URL_SCHEME=squaresample within its configuration dialog. With this configuration, you can now call Monaca app (Square API Demo) from outside (in this case, “Square Point of Sale (POS)” application) by using squaresample://.
2. cordova-plugin-queries-schemes
cordova-plugin-queries-schemes plugin is used to specify a custom URL scheme from Monaca application. For security reason, iOS restricts the use of custom URL scheme. For this reason, this plugin is used to whitelist the custom URL scheme.
After adding the plugin, add the following configuration within config.xmlfile:
With this configuration, you can call POS application from Monaca application by using square-commerce-v1://.
Step 5: Building & Installing the App
In order to test the application, build the application and install it on your device:
- From Monaca Cloud IDE, build the project for iOS debug build. You may want to refer to Building Monaca Apps for iOS
2. Install it on your device.
Step 6: Testing the App
In this section, we will demonstrate how to actually make a 100 yen payment within Monaca app. The app itself is very simple. When you press “Pay 100 Yen” button, the “Square Point of Sale (POS)” application will be launched and will return to the same page when the settlement is completed.
Please make sure to login in the POS app; otherwise, the app won’t be lunched.
- Once you run the app, you will see the following screen. Touch the Pay 100 Yen button to switch to the POS application.
2. The following screen should appear if POS app is successfully opened. There are various payment method you can choose from. However, since we don’t have the card reader, we will choose Cash option.
3. Input the amount to be settled and click Tender button.
4. Next, choose how you would like to receive the receipt.
5. When settlement is over, processing returns to the Monaca app. Then, settlement information is also passed to Monaca app.
Understanding the Application
In this section, we will explain how the application is actually implemented.
UI Components
This is a very simple single-page app using Onsen UI v2 and JavaScript. The page itself is created by using <ons-page> component which contains other components such as <ons-toolbar>, <ons-button> and <ons-list> for showing the transaction information after the settlement is completed.
JavaScript Implementation
All JavaScript implementation is in js/app.js file. The following event is triggered when the “Pay 100 Yen” button is clicked. Within this function, there are 3 important things such as:
- configuring transaction parameters
- creating URL to trigger the POS app based on the transaction parameter
- opening the URL or launching the POS app
Transaction Parameters Configuration
Configure the necessary parameters to be passed to the POS app. Please refer to the comments of each parameter for further understanding.
In addition to the above setting for supported_tender_types, the settlement type can also be SQUARE_GIFT_CARD(gift card) or CARD_ON_FILE(subscription card).
URL Configuration to Launch POS App
Encode the above setting as a JSON string and pass it to square-commerce-v1://payment/create as data parameter as follows:
var url = “square-commerce-v1://payment/create?data=” + encodeURIComponent(JSON.stringify(dataParameter));Launching the POS App
Now that everything is ready, we can open the URL to launch the POS app with following function:
location.href = url;Callback after Settlement
When the settlement is completed, the callback will return to the specified URL scheme (squaresample://). Then, handleOpenURL function is called.
At this time, if you start the implementation immediately after the callback, it may not work. Therefore, let’s wrap it with setTimeout() function.
A JSON object will be sent to the data parameter similar to when opening the POS app earlier. Decode it and use JSON.parse()function to get the result. For iOS, the following three information will be passed.
If the settlement is successfully completed, the status will be “ok”. transaction_id is the transaction ID recorded in the POS app. client_transaction_id is the transaction ID on the client side and will be used for offline payment (including cash).
That’s it!
Please note that this application uses third-party Cordova plugins, so you need to have a valid Monaca subscription plan.
Moreover, since the POS app can’t launch in sandbox environment, please build iOS debug build to test this sample project.
This sample project is based on a blog post found on Monaca Press.
