iOS and Android integration

The following documentation is designed to help a mobile POS developer quickly and easily integrate in the Gravity Payments mobile application.Please contact your Gravity Payments representative for setup instructions. The CIP mobile is a native iOS and Android application that allows a Mobile POS to process credit, refund and void transactions.

Mobile workflow

A basic transaction from the mobile POS will follow this flow:

  1. The POS sends a POST request to our Transaction Service Layer (TSL).
    a. In the POST request’s headers, the POS defines the following:
KeyValue
Content-Type application/json
Content-Length
api-key
  1. In the POST request’s JSON body, the POS defines the following:
KeyJSON TypeDescriptionValid ValuesRequired for Transaction Type
ConfigurationIdStringAn ID, unique to the device making the transaction-All
CashierStringThe name of the cashier making the transaction-All
TransactionTypeStringThe type of transaction that will be processedCreditSale
CreditReturn
GenericVoid
RequestSignature		All
AmountStringThe amount of the sale or return-CreditSale
CreditReturn
RefNumStringUsed to reference a previous transaction in order to process a GenericVoid-GenericVoid
  1. The response from the POST request will include, among other information, the MobileTransactionId​. This ID should be passed to Gravity Payments Mobile, which handles the rest of the transaction.
  1. Once Gravity Payments Mobile has been launched, it reads the passed ­in MobileTransactionId,queries the TSL for all information regarding the transaction, and will prompt the user for further input, depending on the TransactionType.
  2. Gravity Payments Mobile uses an encrypted IDTech’s Shuttle (Two­Track Secure MobileMagStripe Reader) on both Android and iOS. If Gravity Payments Mobile is running on an Android device, there will also be an option to use IDTech’s BTMag (Three­Track Secure BluetoothMobile MagStripe Reader). Manual entry of the customer’s credit­ card information is available on both platforms.
  3. Gravity Payments Mobile will handle communication with the payment processor and will receive the results of the transaction.
  4. Gravity Payments Mobile will handle communication with the TSL regarding the results from the payment processor, ultimately passing control back to the calling mobile POS.
  5. The mobile POS can now communicate with the TSL to query for the results of the previous transaction.

Download the Gravity Payments mobile app

The Gravity Payments Mobile App must be installed on user’s devices.

Google Play Store
Apple iTunes

To login to standalone mobile app

Running the Gravity Payments Mobile App in stand-alone mode is different than from running it in integrated mode where it’s activated from your app. The credentials for the 2 modes are different.

These are shared test credentials for a test merchant called “Gravity Payments Shared External Dev Test Account”. Please contact your integration specialist for private test credentials.

Shared Stand-alone LoginPassword
MobileTestUsermyTestA23

Login to Merchant Portal

The Merchant Portal is where users get their reports. Once logged in, go to Filter then check the Mobile option.

URLhttps://mp.chargeitpro.com/
LoginMobileTestUser
PasswordmyTestA23

Demo POS apps

Demo Point of Sale Mobile App

Test credit card account numbers

The test app has a builtin swiper emulator. If you test credit card account numbers they can be found here.

Notes:

  • All HTTP requests will require an apikey​header in order to be authorized access to our REST Web Service Endpoints. We will provide this key.
    • Every device will need a ConfigurationId ​and each ConfigurationId is unique. This will allow an administrator for the merchant to disable specific IDs as well as run reports against specific users and the transactions performed by the users.
    • Prior to using the mobile POS with Gravity Payments Mobile, the user will need to activate the POS with a ConfigurationId
    • The user will need an Activation Code in order to gain the Configuration ID; The activation code is a one-­time-use twelve digit number.

Activating and configuring Gravity Payments from your app

The user will start the Activation Process from within your app by entering an Activation Key. This will generate a Configuration ID. Your app must save the Configuration ID to use on all subsequent transactions.

The activation process is normally done once. If the merchant needs to switch to a different account, they’ll need to go through the activation process again which will then generate a new Configuration ID

To Activate your app

The merchant may get an activation code by either requesting one from Gravity Payments customer service or by logging into the Merchant Portal and creating a new mobile user.

You can only activate a Mobile Configuration one time. Upon successful activation, save the ConfigurationId locally and use it on subsequent requests to the TSL to start new transactions.

The Activation Key can be found in mp.chargeitpro.com -> Users -> Mobile User Settings.

Test account

These are shared test credentials for a test merchant called “Gravity Payments Shared External Dev Test Account”. Please contact your integration specialist for private test credentials.

Activation Key425580140902
API Keyb70ed097256d4fbd9253e8371fc13ce1

Metadata

GET/Mobile/Activate/HTTP/1.1
Host:api.chargeitpro.com
apikey:
{
"ConfigurationId":"",
"ActivationKey":"",
"SourceKey":null,
"SourceKeyValueEncrypted":null,
"SourceKeyId":,
"PIN":null,
"CompanyName":null,
"Address":null,
"City":null,
"State":null,
"Zip":null,
"Phone":null,
"EMail":null,
"IsEnabled":true,
"UseSandbox":false,
"FriendlyName":null,
"Notes":null,
"UserName":null,
"Password":null,
"UserId":"",
"LocationId":null,
"CreatedOn":"/Date()/",
"ModifiedOn":"/Date()/",
"ActivatedOn":null
}

Processing a transaction

Processing a transaction is a 4 step process:

Step 1 - Generate a unique TransactionId

POST a new mobile transaction with the ConfigurationId to generate a unique TransactionId that will be used to bind all disparate service calls together.

Metadata

 

POST/Mobile/TransactionHTTP/1.1
Host:api.chargeitpro.com
apikey:
Content-Type:application/json
Content-Length:
{
"ConfigurationId":"”,
"Cashier":"",
"TransactionType":"",
"Amount":""
}
{
"Success":true,
"Status":"Created",
"StatusCode":201,
"Result":{
"MobileTransactionId":"",
"ConfigurationId":"",
"Cashier":"",
"RefNum":null,
"TransactionType":"",
"Amount":,
"DisplayEmailReceiptDialog":true,
"CreatedOn":"/Date()/",
"CompletedOn":null
},
"Error":null
}

Request Body Examples by TransactionType

{"ConfigurationId":"ab29f1908e164beaa133ca3fadbfa59","Cashier":"TestCashier","TransactionType":"CreditSale","Amount":"299.01"}
{"ConfigurationId":"ab29f1908e164beaa133ca3fadbfa59","Cashier":"TestCashier","TransactionType":"CreditReturn","Amount":"299.01"}
{"ConfigurationId":"ab29f1908e164beaa133ca3fadbfa59","Cashier":"TestCashier","TransactionType":"GenericVoid","RefNum":"121212ABCD"}
{"ConfigurationId":"ab29f1908e164beaa133ca3fadbfa59","Cashier":"TestCashier","TransactionType":"RequestSignature"}

Step 2 - Pass Control to the Gravity Payments Mobile App

Once the mobile POS has created a new transaction on the TSL and received a MobileTransactionId, it must pass the MobileTransactionId and control to Gravity Payments Mobile. Use the following example URL in order to launch Gravity Payments Mobile on either Android or iOS:
chargeitproapp:// mobileTransactionId={REPLACE­WITH­MOBILE­TRANSACTION­ID}&appUrl={REPLACE­WITH­MOBILE­POS­APP­URL}

Refer to the Android or iOS demo POS code to see exactly how to launch ChargeItPro Mobile using Java or Objective­C.

There are two parameters that are passed to Gravity Payments Mobile via query­ string parameters.

Parameter NameDescription
mobileTransactionIdTransaction ID for Gravity Payments Mobile to process.
appUrlThe URL of the calling app which Gravity Payments Mobile will call once the transaction has been processed.

Note - iOS 9+ Updates

There is a new way that iOS handles inter-app communication as of iOS 9. Apps used to be able to call any other app via custom URLs and schemes – in iOS 9 and newer, the app is now required to white-list the apps and schemes they might be calling.

In order to call Gravity Payments Mobile, the mobile POS must white-list our app’s scheme: chargeITProApp

Since Gravity Payments Mobile tries to call the original app after the transaction has completed, it needs to know the scheme that the app will respond to so it can be white-listed.

The way Gravity Payments Mobile is handling this currently is that it expects the calling app to respond to the scheme: chargeItProPOSApp

The calling app will also have to pass in this value as the appUrl when calling Gravity Payments Mobile.

New security requirements introduced in iOS 9 require that all URLs that an application will call to be added to the application’s info.plist file.

Inside of the “info.plist” file create the following hierarchy:

[-] URL types
    [-] Item 0
        [+] URL identifier
        [+] URL Schemes
            * Item 0

The value of URL types -> Item 0 -> URL Schemes -> Item 0 should be chargeItProPOSApp

Reference

Step 3 - Retrieve Transaction Results

When Gravity Payments Mobile has completed a transaction, it will send the results to the TSL. The POS must query for the results from the TSL using one of two methods:

  1. recommended – Once Gravity Payments Mobile has completed a transaction, it will return to the calling app using the supplied appUrl​. Once control has been given back to the mobile POS, make a request to the TSL to get the results of the transaction.
  2. Poll the TSL every few seconds until the mobile POS receives the results for the given transaction.

Metadata

GET/Mobile/Transactionresult/
{replace-with-mobile-transaction-id}HTTP/1.1
Host:api.chargeitpro.com
apikey:{replace-with-merchant-api-key}
{"Success":true,"Status":"OK","StatusCode":200,"Result":{"MobileTransactionId":"","ResultStatus":"true","ResultMessage":"","TransactionType":"","ApprovalNumberResult":null,"BatchNumber":"","BillingName":null,"AvsResponseCode":null,"AvsResponseText":"","CvvResponseCode":null,"CvvResponseText":"","AmountBalance":null,"AmountProcessed":null,"AccountCardType":null,"AccountExpiryDate":null,"MaskedAccount":null,"UniqueTransId":"","AccountEntryMethod":null,"Version":null,"OS":null,"Email":null,"CreatedOn":"\/Date()\/","AdjustmentTypeId":null,"SignatureId":null},"Error":null}

Receipt Examples

Step 4 - Generate/Send Receipt

AccountCardType
AmountTotal
AmountBalance
ApprovalNumberResult
BillingName
MaskedAccount
TransactionType
Signature (if supporting signature capture)
Space for customer to sign
Agreement Blurb:
I AGREE TO PAY THE ABOVE
TOTAL AMOUNT ACCORDING
TO CARD ISSUER AGREEMENT

Receipt Requirement Examples

Send a Receipt Email

CC and BCC fields are optional.

Metadata

POST/json/oneway/EMailRequestHTTP/1.1
Host:api.chargeitpro.com
apikey:{replace-with-merchant-api-key>}

{
"MobileTransactionId":"<{replace-with-mobile-transaction-id}",
"To":"",
"CC":"",
"BCC":""
}
{"Success":true,"Status":"OK","StatusCode":200,"Result":true,"Error":null}