Command Line Interface
Command Line Interface wraps the ChargeItPro OCX API into an easy to use executable that can be called from virtually any application. CIPCMD.exe allows applications that may find calling an OCX or .NET DLL difficult, to easily integrate ChargeItPro.
- The application calls CIPCMD.exe with parameters for the following:
- Name and path for a settings file
- Name and path of an output file
- Gravity Payments takes control and processes transaction
- CIPCMD.exe writes the output file
- CIPCMD.exe returns an Exit Code
- The application reads output file to determine the result of transaction
- The application stores the values it needs to reprint receipts
- The application adds the credit card section to its existing receipt
- The application prints the receipt(s)
CIPCMD.exe is designed to handle applications that support multiple merchant locations. To accomplish this, CIPCMD.exe needs your application to help create the file.
In your application’s computer specific setup area, add a button called ChargeItPro Setup that makes the following call:
C:\ChargeItPro\CIPCMD\CIPCMD.exe -aa:"C:\ChargeItPro\CIPCMD\CIPSetup.xml" -ab:setup
This will bring up the ChargeItPro Setup where the merchant enters their account information as well as configure any hardware devices they have.
On setup screen:
- Click on Quick Setup, enter ‘testabc123’ in the Config Key field
- Click ‘Download Settings’
- Click ‘Save’
The information below can also be retrieved by running: C:\ChargeItPro\CIPCMD\CIPCMD.exe -?
-? Display this help screen -aa:ChargeItPro setup file, location & Name -ab:ChargeItPro transaction type ACHSale ACHReturn CreditAddTip CreditSale CreditReturn CreditForce CreditAuth CreditSaveCard DebitSale DebitReturn GenericVoid GiftAddValue GiftRedeem GiftRedeemMax GiftBalance CloseBatch RequestSignature ResetPinpad ReturnFocus -ac:Output file, location & Name [optional] (default=cipout.csv) -ad:Output file format: TXT, TAB or CSV [optional] (default=CSV) -af:Note1, returned in output file. [optional] -ag:Note2, returned in output file. [optional] -ap:ProcessId * returns focus to specified ProcessId. Can be used with any transaction type. * To return focus without running a transaction, use ReturnFocus as the transaction type. -v Verbose mode, creates debug log; ..\log\CIPCMD.log (optional) (default=True, NOTE: to disable logging, create file:C:\ChargeItPro\CIPCMD\DisableCIPCMDlog.txt)
-ba:AccountData(deprecated) -bb:ExpirationDate(deprecated) -bc:AmountFee -bd:AmountTip -be:AmountTotal -bf:ApprovalNumber -bg:BillingStreetAddress -bh:BillingZip -bi:CashBack -bj:Cashier -bk: CVVNumber -bl:Level2CustomerCode -bm:Level2OrderNumber -bn:Level2Tax -bo:PinpadBlock -bp:PinpadNumber -bq:SMID -br:TransactionReference -bs:UniqueTransRef
-ga:HealthCareAmount -gb:RxAmount -gc:ClinicalAmount -gd:DentalAmount -ge:VisionAmount -gf:CopayAmount
-da:DateTimeStart, format="YYYY-MM-DD HH:MM" (default=Today) -db:DateTimeEnd, format="YYYY-MM-DD HH:MM" (default=Today) -dc:ReportFileName, location & Name [optional] (default=rptout.csv)
-eb:SignatureReduction, percentage 1-99 [optional] (default=60) -ec:SaveSignatureAsBMP, output graphic file location & Name -ed:SaveSignatureAsJPG, output graphic file location & Name -ee:SaveSignatureAsPCL, output graphic file location & Name -ef:DisplayText, Text to Display on device screen (Ingenico only) -eg:SignatureString, input text file location & Name
-fa:AllowPartialApprovals, <(default=False) -fb:ScreenNumber, 0-1 [optional] (default=value from setup) -fc:AllowModifyTip (default=false)
-ha:FormTitle -hb:FormMessageFileLocation -hc:FormButton1Text -hd:FormButton2Text -he:FormButton3Text -hf:FormButton4Text
What is the Output file?
The Output file contains the results of the transaction. Your application will read this file to obtain the results.
Output file format
There are 3 formats available for the Output file:
- `TXT` is a name\value pair format where each line of file contains a name and value. This is a fixed format where if there’s no value available, the name will still be in the file. Any new fields will be added to the end of the file to maintain backwards compatibility. The order of the fields will also be maintained from version to version.
- `TAB` is a tab delimited file format. The order of the fields follows the TXT format.
- `CSV` is comma separated value file format. The order of the fields follows the TXT format.
Select an Output file format
Use the `-ad:` parameter to select the format. For example:
C:\ChargeItPro\CIPCMD\CIPCMD.exe -ad:TXT C:\ChargeItPro\CIPCMD\CIPCMD.exe -ad:TAB C:\ChargeItPro\CIPCMD\CIPCMD.exe -ad:CSV
Review our results fields documentation.
Review our documentation on storing user signatures.
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
Review our receipt requirement examples.
Output format examples
- Note1: - Note2: - TransactionReference: INV001234 - Cashier: SalesPerson - AmountTotal: 75.23 - CustomerRef: - PaymentID: - AccountCardType: VS - AccountHash: - AmountBalance: 0 - AmountBill: 0 - AmountFee: 0 - ApprovalNumberResult: 000037 - AVSResponseCode: - AVSResponseText: - BillingName: - CVVResponseCode: - CVVResponseText: - MaskedAccount: 401912******9016 - ResultMessage: AUTH/TKT 000037 - ResultStatus: True - Signature: - TransactionType: CreditSale - UniqueTransID: 01c4f262e19746c087c3c5c447893208 - AccountEntryMethod: Keyed - AccountExpiryDate: 1215 - CardNickname: John Q's Visa
INV001234 SalesPerson 0 VS 0 0 0 003571 Y Match of Address and 5-Digit ZIP Code FirstName LastName P Not Processed ************9016 Y003571 True CreditAuth 61581516 Keyed 0421 This is my card's nickname
,,INV001234,SalesPerson,0,,,VS,,0,0,0,003569,Y,Match of Address and 5-Digit ZIP Code,FirstName LastName,P,Not Processed,************9016,Y003569,True,,CreditAuth,61581512,Keyed,0421,This is my card's nickname,
The Exit Code (also known as an Exit Status or Return Code) is a signed integer the child process(CIPCMD.exe) returns to the parent process(your application) when CIPCMD.exe finishes it’s task. This allows your app to wait for CIPCMD.exe to finish before looking for the output file.
Do not use the Exit Code to determine the result of a transaction, you must read the
ResultStatus field in the output file to see if the transaction was approved or not.
-1 Output file successfully created 0 CIP Transaction failed (declined or user cancelled) 1 Required option missing: Setup File Name (-aa) 2 Required option missing: Transaction Type (-ab) 3 Exception encountered during Batch Close processing 4 Problem encountered with an amount value 5 Exception encountered during Transaction processing 6 Loading EasyIntegrator fields failed 7 Bitmap processing failed (-co) 8 Required option missing during DisplayText request (-ef) 66 Internal CIPCMD Error 76 Location File Error 77 Output File Error 78 Input File Error 79 Debug Log File Error 88 CIP Setup Error 99 Help Screen Displayed: requested by user or required option(s) missing
Sample transaction tips
- All samples use the Text Output file format
- Setup file names should be unique per store
- Output file names should be unique per transaction
- Output files should be deleted by your app
- Strings should be quoted to avoid problems with spaces
- An Output file is always created even if the cashier clicks Cancel
You generally only run this once:
“C:\ChargeItPro\CIPCMD\CIPCMD.exe” -aa:”C:\ChargeItPro\CIPCMD\CIPSetup.xml” -ab:setup
Unless the merchant needs to change the settings for their device or other preferences.
Transaction type differences
The only things that change between the examples are the Transaction Types
-ab: and the Output File
"C:\ChargeItPro\CIPCMD\CIPCMD.exe"^ -be:75.23^ -aa:"C:\ChargeItPro\CIPCMD\CIPSetup.xml"^ -ab:CreditSale^ -ac:"C:\ChargeItPro\CIPCMD\cipout-AAA1.txt"^ -bj:"CashierName"^ -br:"yourINV001234"^ -ad:txt
The amount should always be unsigned.
"C:\ChargeItPro\CIPCMD\CIPCMD.exe"^ -be:75.23^ -aa:"C:\ChargeItPro\CIPCMD\CIPSetup.xml"^ -ab:CreditReturn^ -ac:"C:\ChargeItPro\CIPCMD\cipoutAAA2.txt"^ -bj:"CashierName"^ -br:"yourINV001234"^ -ad:txt
- Gift Cards here refer to internal store branded gift cards.
- Visa / Mastercard / Discover / Amex gift cards are processed as regular credit cards.
- All Gift Cards start with a zero balance.
- There is no need for a separate activation step
- This same command is used to both issue a new card as well as to reload a card
"C:\ChargeItPro\CIPCMD\CIPCMD.exe"^ -be:25.00^ -aa:"C:\ChargeItPro\CIPCMD\CIPSetup.xml"^ -ab:GiftAddValue^ -ac:"C:\ChargeItPro\CIPCMD\cipout-AAA5.txt"^ -bj:"CashierName"^ -br:"yourINV001234"^ -ad:txt
"C:\ChargeItPro\CIPCMD\CIPCMD.exe"^ -be:10.00^ -aa:"C:\ChargeItPro\CIPCMD\CIPSetup.xml"^ -ab:GiftRedeem^ -ac:"C:\ChargeItPro\CIPCMD\cipout-AAA6.txt"^ -bj:"CashierName"^ -br:"yourINV001234"^ -ad:txt
- `GiftRedeemMax` differs from `GiftRedeem` in that this will partially approve the transaction for up to the balance on the card.
- For example if the gift card has a balance of $25.00, the transaction below will process for $25.00 instead of $30.00.
- This makes for a much smoother experience for the cashier since `GiftRedeem` would have declined the transaction.
- Reports will show a `GiftBalance` transaction and a `GiftRedeem` transaction when using this
"C:\ChargeItPro\CIPCMD\CIPCMD.exe"^ -be:30.00^ -aa:"C:\ChargeItPro\CIPCMD\CIPSetup.xml"^ -ab:GiftRedeemMax^ -ac:"C:\ChargeItPro\CIPCMD\cipout-AAA7.txt"^ -bj:"CashierName"^ -br:"yourINV001234"^ -ad:txt
- This returns the current balance on the gift card
- Notice that this transaction type does not have an amount `-be:`
"C:\ChargeItPro\CIPCMD\CIPCMD.exe"^ -aa:"C:\ChargeItPro\CIPCMD\CIPSetup.xml"^ -ab:GiftBalance^ -ac:"C:\ChargeItPro\CIPCMD\cipout-AAA8.txt"^ -bj:"CashierName"^ -br:"yourINV001234"^ -ad:txt
"C:\ChargeItPro\CIPCMD\CIPCMD.exe"^ -aa:"C:\ChargeItPro\CIPCMD\CIPSetup.xml"^ -ab:ShowForm^ -ha:ShowForm^ -hb:test.txt^ -hc:Yes^ -hd:No^ -ac:"C:\ChargeItPro\CIPCMD\output.txt"^ -ad:txt
- `GenericVoid` can be used for all transactions. Gravity Payments will translate the void in cases where the original transaction doesn’t support voids. For example `DebitSale` transactions do not support voids. In this case Gravity Payments will transform the void into a `CreditReturn` to negate the sale.
- Amount `-be:` is not needed and cannot be specified
- Only entire transactions can be voided. If you need to cancel a portion of a transaction, use a return transaction (or a sale if the original transaction was a return)
- Only transactions in the open batch can be voided. Batches are typically closed at the end of the business day by the merchant.
"C:\ChargeItPro\CIPCMD\CIPCMD.exe"^ -aa:"C:\ChargeItPro\CIPCMD\CIPSetup.xml"^ -ab:GenericVoid^ -bs:4c2f8fb2c3dc43a19e736aae5660e933^ -ac:"C:\ChargeItPro\CIPCMD\cipout-AAA9.txt"^ -bj:"CashierName"^ -br:"yourINV001234"^ -ad:txt
Card Nickname tips
- Card Nickname allows the user to enter a nickname when saving card data
"C:\ChargeItPro\CIPCMD\CIPCMD.exe"^ -be:75.23^ -aa:"C:\ChargeItPro\CIPCMD\CIPSetup.xml"^ -ab:CreditSaveCard^ -ac:"C:\ChargeItPro\test\CipCMD\cipout.txt"^ -bj:SalesPerson^ -br:INV001234^ -ad:TXT
Double-click on `CIPCMD.exe`. If the Help screen comes up then it’s been installed properly.
Help screen not showing?
If the Help doesn’t appear, the 2 most common causes are:
- `CIPWIN32.ocx` hasn’t been registered properly. `CIPWIN32.OCX` can usually be found in `C:\ChargeItPro`. To register it, start Window’s command prompt as an Administrator and run: `regsvr32 C:\ChargeItPro\cipwin32.ocx`
- .Net Framework 3.5 isn’t installed
- Extra or missing spaces
- Improperly quoted values
- Quotes being included within the Cashier `-bj:` or TransactionReference `-br:` fields
Using the Log
All transactions are logged to `C:\ChargeItPro\CIPCMD\Log`. This is an example of an error due to Signature-BBB1.txt being blank.
2014-09-01 17:31:39.969  * ========== NEW TRANSACTION REQUEST ========== 2014-09-01 17:31:39.970  * Command Line = -aa:C:\ChargeItPro\CIPCMD\CIPSetup.xml -ab:SaveSignatureAsJPG -eg:C:\ChargeItPro\CIPCMD\Signature-BBB1.txt -ed:C:\ChargeItPro\CIPCMD\sig-BBB1.jpg -bj:CashierName -br:yourINV001234 -ad:txt 2014-09-01 17:31:39.970  * Checking for location text file 2014-09-01 17:31:39.971  * location already in file: C:\ChargeItPro\CIPCMD\CIPCMDLocation.txt 2014-09-01 17:31:40.631  * ChargeItPro EasyIntegrator Version 4.1(Build-5.550) STANDARD MODE 2014-09-01 17:31:40.635  * Initiate SignatureSaveAs Function as part of: SAVESIGNATUREASJPG 2014-09-01 17:31:40.636  * No signature found in signature string file: C:\ChargeItPro\CIPCMD\Signature-BBB1.txt 2014-09-01 17:31:40.636  * Program returned ErrorLevel = 78
What does the ^ symbol do in the examples on this page?
Note that the `^` (caret) symbol is an escape character within `cmd.exe`. Using it here allows us to span a single command with parameters across multiple lines, making our documentation easier to read.
For example, `xcopy file1.txt file2.txt`
…can be written as: