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.

 

CIPCMD workflow

  1. The application calls CIPCMD.exe with parameters for the following:
    1. Amount
    2. Name and path for a settings file
    3. Name and path of an output file
  2. Gravity Payments takes control and processes transaction
  3. CIPCMD.exe writes the output file
  4. CIPCMD.exe returns an Exit Code
  5. The application reads output file to determine the result of transaction
  6. The application stores the values it needs to reprint receipts
  7. The application adds the credit card section to its existing receipt
  8. The application prints the receipt(s)

Settings file

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.

Test account

On setup screen:

  1. Click on Quick Setup, enter `testabc123` in the Config Key field
  2. Click `Download Settings`
  3. Click `Save`

Available parameters

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:

  1. `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.
  2. `TAB` is a tab delimited file format. The order of the fields follows the TXT format.
  3. `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

Results

Review our results fields documentation.

User signatures

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

Receipts

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,

Exit Code

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.

ResultStatus field

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

Setup

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.

CreditSale

Transaction type differences

The only things that change between the examples are the Transaction Types -ab: and the Output File-ac:

"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

CreditReturn

Return amount

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

GiftAddValue

GiftAddValue tips

  • 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

GiftRedeem

"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

GiftRedeemMax tips

  • `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

GiftBalance

GiftBalance tips

  • 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

ShowForm

"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

GenericVoid tips

  • `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

Card Nickname tips

  • Card Nickname allows the user to enter a nickname when saving card data

CreditSaveCard

"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

Troubleshooting

Installation Issues

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:

  1. `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`
  2. .Net Framework 3.5 isn’t installed

Common errors

  1. Extra or missing spaces
  2. Improperly quoted values
  3. 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 [1] * ========== NEW TRANSACTION REQUEST ==========
2014-09-01 17:31:39.970 [1] * 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 [1] * Checking for location text file
2014-09-01 17:31:39.971 [1] * location already in file: C:\ChargeItPro\CIPCMD\CIPCMDLocation.txt
2014-09-01 17:31:40.631 [1] * ChargeItPro EasyIntegrator Version 4.1(Build-5.550) STANDARD MODE
2014-09-01 17:31:40.635 [1] * Initiate SignatureSaveAs Function as part of: SAVESIGNATUREASJPG
2014-09-01 17:31:40.636 [1] * No signature found in signature string file: C:\ChargeItPro\CIPCMD\Signature-BBB1.txt
2014-09-01 17:31:40.636 [1] * 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:

“`
xcopy^
file1.txt^
file2.txt
“`

References: