Frequently Asked Questions on Terminal Commerce Application development

General Questions | Marketplace Questions | App Development Questions

General Questions

What type of applications can I develop and publish?
Commerce Platform supports HTML and Android applications. We call these as Terminal Commerce Applications and Android Commerce Applications.
Android applications can be run on the Carbon family devices. HTML apps can be run on all Commerce Platform compatible devices.

Are there any limitations on developing the apps?
Android apps support all standard Android APIs with addition of Verifone provided APIs. HTML apps do have limitations due to security requirements as these apps are run in the payment terminal. As an example we do not allow downloading JS scripts from internet and executing them on a device.
All apps must be published in the Verifone Marketplace.

Marketplace Questions

Can I monetize applications?
Yes, applications can be monetized.

What are the billing models available?
Developer can define app to be free, have one time fee or recurring monthly fee. For free applications Verifone charges negotiable placement fee.

How is billing managed?
Verifone takes care of billing and pays generated revenue to the developer at monthly basis. 
What is the revenue sharing model?

Verifone guarantees that developer gets 70% of the revenue paid applications generate. 

App Development Questions

Can I develop without having a Test terminal?
Applications can be tested in the simulator included in the Commerce Applications SDK. One can develop and test the applications without a test terminal. However to verify interaction with the payment application it is recommended to verify application also in a test terminal.

Where to find sample apps?
Commerce Applications SDK includes few sample applications. Look at the Verifone menu item.
Applications can be downloaded also via links provided in the developer guide

Can my app connect with my cloud based app/service?
Yes. HTML applications needs to be whitelisted to access cloud, see details at the  developer guide. Android applications do not require whitelisting.

How do I install apps on my test terminal?
Android apps are installed by using adb commands.
HTML apps can be side loaded into the Carbon device directly from the Commerce Applications SDK by using a USB cable. 
On all other devices HTML apps can be downloaded via a browser application in the PC,  payment terminal connected in a WiFi at HTTP download mode. See details at the developer guide.

Can my app have access to NFC APIs?
Payment application supports NFC for payment transactions. However platform does not support NFC for add-on services.

How to register Terminal Commerce app to launch at a specific trigger point?​
In the Storyboard or Manifest file view define the trigger to be used, and the html page that will be executed first.

How to identify merchant or terminal?
Trigger payload Transaction Context includes the Merchant ID and Terminal ID values (MID and TID).

Why the Trigger specification includes three different MID parameters and how to use them?
The three MID parameters in question are cp_merchantId, Acquirer_Merchant_Id and Gateway_Merchant_Id. Depending on the device type, payment application and deployment one or two of the se MID parameters include a value.
cp_merchantId is linked to the the merchant account at the Verifone Connect solution. Acquirer_Merchant_Id is set by the payment acquirer. Gateway_Merchant_Id is used if the solution includes a payment gateway between the payment terminal and the acquirer.   
Application should always check first availability of  cp_merchantId and use it. If the parameter is not set, next in priority order to be used is the Acquirer_Merchant_Id.

Can I use 3rd party JavaScript libraries?
Although Terminal Commerce application projects cannot include .js files, one can utilize the application project folder "modules" to include JS functions. More info about the use of JS functions is here. 
One needs to notice that due to Terminal Commerce app security reuirements all JS code is preprocessed before executing the HTML code. Thus in JS one cannot get or read any of the html elements. This may limit the use third party JS library components which typically allow getting access to the HTML DOM element and then perform operations which is not allowed in our case.

How app can notify Runtime about completion of the app execution?
One simply exits the app, and the Runtime gives control back to the payment app. Example in JS: exit("return 0").

Can applications have access to payment transaction data?
3rd party apps do not have access to core payment transaction data like PAN.
Selected data that is not in PCI scope is available to 3rd party apps,  Amount, Merchant ID and Terminal ID as examples are available via trigger payload data.
I notice the terminal key pad supports numbers.  Will it be possible for a user to manually enter their email address?
One can use the keypad to enter text, for example email address. It is a bit cumbersome as each letter requires multiple keypresses

Is there a way to notify the system that alternative payment failed?
One can return zero payment to the Payment app as approved alternative in case your alt payment failed. Payment app will treat this as split payment, and will ask the consumer to pay the rest. 

What are the implications on the connection due to passing through the Entitlement Services?
As application developer you do not know the CG is in between. However before testing your app in the test terminal the CG needs to be configured to allow your app to create connection to your backend. In the Developer Central you need to whitelisting used external connections.
Can I connect my cell phone app via NFC or BT to a Terminal Commerce App?
Unfortunately NFC or BT are not supported for Commerce Applications.
You can connect your iOS app to your Commerce App via your cloud services

Are the ARGV values carried between the trigger events?
ARGV vector is not saved over multiple sessions of the Commerce App. When you divide your app’s functionality over multiple trigger points, you are actually running your app multiple times. You exit at the previous trigger point and at the next trigger point you launch your app again, from a different html page.
You need to use the session data  to store parameter values over multiple invocations of your app. This is done by using the RGV data that is prefixed with "ctx_" 
  ARGV.ctx_data ="this data will live over multiple trigger points";
  ARGV.data="this data is available only at current trigger point";

How to access environmental variables ?

/* Example on how to access ADK populated environmental variables */
var appid = ARGV.cp_appId;

/* Example on how to access payment app populated environmental variables */
var env = JSON.parse(ARGV.cp_envData);
var locale = env.locale;

How to configure simulator for HTTPS  connections?
  • Download and install stunnel installer.exe file at https://www.stunnel.org/downloads.html
  • Insert your .pem file into folder C:\Program Files (x86)\stunnel\config. You must have a .pem –file for the used https connections, simulator does not accept any other certificate file formats
  • Include the used https url into the confApp.json –file. SDK is using this file to check if external connections are used
  • Refer to the url in the confApp.json correctly in your app, see example below
                              http = new XMLHTTPRequest();
                              http.open("POST", conf.exchangeEndpoint, false);
  • Start the simulator with a Run command
  • Before the simulator is started SDK prompts following window:
  • Verify the path to the stunnel.exe is correct. If not, fix it
  • Click Add Connection
  • Add the url name. Note, you must add the domain name, not the API name. 
  • Add the .pem certificate file

Anti-Virus SW gave a warning/error, is my computer infected?
Some Anti-Virus SW's may warn about creating the .zip files while packaging applications. If this happens, you may need to whitelist the Commerce Applications SDK to allow it creating .zip files. 

I accidentally edited the IP address at the Package Upload service settings in the Carbon device. What is the original IP address?
Verify that the Package Upload service shows IP address
This is the address of the payment terminal that the Package Upload service is using while installing the Terminal Commerce apps on the payment terminal.

Is there limit how much data or large content can be transferred through Entitlement Services?
Entitlement Services limits the size of single response to 750KB. This is with device memory and storage space into account.

Which JS version is supported?
ECMAScript5.1 specification is fully supported. Related JS functionality is documented at http://www.ecma-international.org/ecma-262/5.1/