Application Whitelisting and Submission
Terminal Commerce Application Whitelisting for a Test Terminal
| Application Publishing Process
Terminal Commerce Application Whitelisting for a Test Terminal
If you’re testing an application that uses external services, it’s required that you ‘whitelist’ it to allow the application to connect into any 3rd party service. ‘Whitelisting’ of an app takes place by documenting the URLs the application uses to connect to external services in the App Submission Form in the Developer Central. The Developer Central will use this information to configure the sandbox environment in the Entitlement Services to allow the application to access external services. Entitlement Services uses the app ID and version to map whitelisted URLs to the connection requests coming from the test terminals. Thus, it is important that you copy the developer portal generated app ID into the application manifest file in the SDK. It is also important that you align the app version in the submission form to the app version documented in the app manifest file.
Application Whitelisting takes place when the draft app submission form is saved in the Developer Central. New app submission form is created in the Apps view by pressing the Create Commerce Apps button.
At minimum the form must include the Application name, App ID, application version number, URL's of the used external connection and if HTTPS connections are used, also the certificate file must be included in the app submission form. Listed information is required before Dev Central can configure the CG to allow the app running on a test terminal to access external services via the CG sandbox environment.
After entering the application name into the app submission form, press the Generate -button to request Developer Central to create a unique application ID.
Add also the application version number.
Verify that the Application name is the same both in the app submission form in the Developer Central, as well in the application manifest file. You can edit the app manifest file with the Commerce Applications SDK, see the image below. Copy the Developer Central generated unique App ID in to the application manifest file. Verify that the application version number is the same both in the app submission form as well in the app manifest file.
After you have completed above steps, export the application test package to be installed on a test terminal.
On Carbon family devices the app installation takes place while starting the simulator. No need to export the test app packages.
Android and Android Commerce applications do not require whitelisting as those applications do not connect to external services via the Entitlement Services.
You don't need to repeat the whitelisting process for the payment terminals merchants use. Application whitelisting for the CG production environment takes automatically place when the application is published in the Marketplace.
Important points to note:
- Ensure App ID and version number are consistent across the submission form and the app manifest file
- You cannot change the app ID or version number at a later stage; if you do, you’ll have to start the ‘whitelisting’ process right from the beginning by starting a new app submission process
- Ensure only the external connections domain URL is copied to the app submission form, and not the entire path of the API the app uses. In the example below you would whitelist the url helloworlddomain.com, not the full path to the API the app is using.
Application Publishing Process
The a publishing process can be paused at any time; it doesn’t interfere with the development of the app. The app submission form is saved in draft mode until all the required information and final application package are available for Verifone's review.
The Marketplace stores all published apps as well the draft app versions the publisher adds. However, only one draft application version can be in the Marketplace at any given time. Every time a new draft is uploaded, it replaces the older one.
App Submission Form
After successfully logging into the Developer Central and opening the Apps view, you can either choose to initiate the process to create a new app or continue working on an app submission form saved in draft mode. You can also open a published app to make any modifications or to publish a new version of the app.
If you chose to submit a new app, or decide to work with app submission form saved in draft mode, you will be asked to fill the app submission form. You can save the draft form at any time and return to it at a later stage.
App submission form includes general application information, connection configuration to external services, the actual application package to be published, media files related to the application, pricing and distribution info, information on legal and support, and finally the summary page with the application submission button.
General Application Information
The very first step is to define an app name
and generate an app ID.
- Application name must be at least five characters long.
- Based on the given application name the Developer Central generates a unique Application ID.
- The Developer Admin must enter a description for the application that’ll be visible in the Marketplace. Description is limited to 2500 characters. Please use the description field to "sell" your app in the Marketplace. Description should also include adequate instructions to configure and use the app. At minimum it must include info from where to find more detailed instructions.
- App category must also be defined as applications are categorized accordingly in the Marketplace
- Custom Message field includes a message that will be sent to the merchants via email after they have purchased the application from the Marketplace. Message size is limited to 500 characters.
For Android and Android Commerce .apk files one does not need to fill the Connections -page.
All external connections the app uses must be declared in the app submission form. Verifone’s Entitlement Services will allow Terminal Commerce apps to access only the domains declared by the application publisher. Ensure only the external connections domain URL is copied to the app submission form, and not the entire path of the API the app uses. In the example below you would whitelist the url helloworlddomain.com, not the full path to the API the app is using.
If your application uses HTTPS connections, the corresponding SSL certificate (.pem file as an example) content must be copied into the ‘Connections’ section of the app submission form.
Timeout value for the CG should be given as well. This is the maximum time the CG tries to make connection to the defined 3rd party services.
In order to upload the application, select the application package exported by the Commerce Applications SDK.
During the upload, Developer Central verifies that the application includes the Publisher Certificate. If the Publisher Certificate is missing or if the used certificate is not owned by you, you’ll be asked to re-submit a correctly signed application package.
Certificate verification is followed by an automated sanity check for the application package. This includes verifying the app package format, file name format, file size and App ID.
If the application package fails during any of the sanity checks, a note will be sent to the you with details about the failure.
Terminal Commerce application packages are in the .zip file format, Android and Android Commerce applications in .apk file format.
Terminal Commerce application packages must be smaller than 5MB in size.
App Icon & Screenshots
Media assets required to publish an app to the Marketplace are:
Application Icon file. Recommended to be 100*100 pixels jpg or png file. Application icon will be used in the Marketplace to identify the app.
App Screenshots. Up to eight screenshots can be included.
Requirement for the image files:
- Minimum image resolution 320x320 pixels. Maximum image resolution 2280x2280 pixels (width x height)
- Mazimum image file size 16 MB
App Screenshots will be published in the Marketplace. Select the app screenshots which help the merchants to understand the app functionality and how to use it.
Price & Distribution
The publisher must define the application pricing model. The VeriFone Developer Central portal now enables developers to set the price of their applications while submitting the applications on the Developer Central Portal. The details process for how to submit a paid application is available here
Legal & Support
The Legal & Support form requires the publisher to document the use of cryptography and encryption in the app. The contact information for the app’s technical support also needs to be provided, as well app publisher's website from where one can find more information about the application and the publisher.
Support contact info will also be visible in the Marketplace.
Application developer is responsible for supporting merchants on technical and usage issues. Merchants will contact app developers directly, based on published contact info.
Summary & Submit
You can initiate the application submission process after you’ve completed the submission form
Before you submit your application for certification, please confirm that you've done the following:
- Adhered to the software development guidelines and prerequisites
- Completed required items in the application submission form
Developer Central will verify completeness of the App Submission form to guide you on completing it.
After submitting the App Submission Form, you'll be notified about sending the app for the Verifone certification review. At this stage, you can sign out from the Developer Central portal. The Developer Admin will also receive an email confirmation when the application is successfully uploaded along with instructions on next steps.
The complete application certification process may take multiple business days, perhaps up to two weeks. If you have a certain deadline to be met, contact Verifone Developer Support in advance to schedule a timely application review.