Introduction to Easy Integrator (EI Server)

The purpose of EasyIntegrator is to make integrating ChargeItPro quick and easy while relieving our partners of the burden of securing credit card data, integrating new hardware devices, and the worry over ever-changing regulations.

The EasyIntegrator API is available in two versions to choose from:

  1. Win32 ActiveX OCX library – cipwin32.ocx
  2. x86 .NET DLL library – cipeinet.dll

Both APIs support the same properties, methods, and functionality. Which API is chosen will be based on the requirements of the programming environment or personal preference.

API program code examples

Throughout this guide are code examples written in Visual Basic. The examples can be used with either API. To run a code example the instantiation statement must be updated with the name of the API chosen for use.

For example, consider the following line in the code examples:
Dim easyIntegrator1 As New EasyIntegrator

  • For use with the OCX, it would become:
    Dim easyIntegrator1 As New cipwin32.EasyIntegrator
  • For use with the DLL, it would become:
    Dim easyIntegrator1 As New cipeinet.EasyIntegrator

Setup

Step 1: Call Setup() function and enter merchant settings

ChargeItPro is designed to handle applications that support merchants with multiple merchant accounts and hardware configurations.

To accomplish this, ChargeItPro needs your application to store a setup string per computer. That setup string must then be handed back to ChargeItPro prior to each transaction with the LoadSetup(string) call.

In your application's workstation specific setup area, add a button called ChargeItPro Setup that makes the following call:

SaveInYourDB = easyIntegrator1.Setup(SaveInYourDB)

Test account

This will bring up the ChargeItPro Setup Screen.

For testing purposes, click the Quick Setup button. Next enter the Config Key, testabc123, and click Download Settings then click Save.

Sample transactions

For the complete list of available transaction parameters see Trans Fields documentation

Note on Sample Transactions

The examples below are dependent on your application using the saved Setup string from Step 1.

CreditSale

Performs a standard credit card sale.

easyIntegrator1.LoadSetup(SaveInYourDB)
easyIntegrator1.Clear
easyIntegrator1.ConfigFields.AllowPartialApprovals = True 
easyIntegrator1.TransFields.AmountTotal = 20.00 'unsigned with decimals
easyIntegrator1.TransFields.Cashier = "Phil"
easyIntegrator1.TransFields.TransactionReference = "Inv123456"
If easyIntegrator1.CreditSale() Then
  'transaction was approved
  'save easyIntegrator1.ResultsFields.UniqueTransID for 
  '  tokenized transactions such as voids, returns and additional charges 

CreditReturn

Performs a standard return of funds.

easyIntegrator1.LoadSetup(SaveInYourDB)
easyIntegrator1.Clear
easyIntegrator1.TransFields.AmountTotal = 20.00 'unsigned with decimals
easyIntegrator1.TransFields.Cashier = "Phil"
easyIntegrator1.TransFields.TransactionReference = "Inv123456"
If easyIntegrator1.CreditReturn() Then
  'transaction was approved 
  'save easyIntegrator1.ResultsFields.UniqueTransID for
  '  tokenized transactions such as voids, returns and additional charges 

DebitSale

Performs a standard pin debit sale transaction.

easyIntegrator1.LoadSetup(SaveInYourDB)
easyIntegrator1.Clear
easyIntegrator1.TransFields.AmountTotal = 20.00 'unsigned with decimals
easyIntegrator1.TransFields.Cashier = "Phil"
easyIntegrator1.TransFields.TransactionReference = "Inv123456"
If easyIntegrator1.DebitSale() Then
  'transaction was approved 
  'save easyIntegrator1.ResultsFields.UniqueTransID for voids

DebitReturn

This transaction returns funds to the cardholder’s account.

Notes on DebitReturn

  1. Due to processor limitations, ChargeItPro automatically converts all pin debit returns to a CreditReturn
  2. Debit transactions cannot be voided. When a user attempts to void a debit transaction, ChargeItPro will create an offsetting Credit transaction. If the original transaction was a DebitSale then a CreditReturn is processed.
easyIntegrator1.LoadSetup(SaveInYourDB)
easyIntegrator1.Clear
easyIntegrator1.TransFields.AmountTotal = 20.00 'unsigned with decimals
easyIntegrator1.TransFields.Cashier = "Phil"
easyIntegrator1.TransFields.TransactionReference = "Inv123456"
If easyIntegrator1.DebitReturn() Then
  'transaction was approved 
  'save easyIntegrator1.ResultsFields.UniqueTransID for voids

CreditSaveCard

This transaction generates a token to be used later.

easyIntegrator1.LoadSetup(SaveInYourDB)
easyIntegrator1.Clear
easyIntegrator1.TransFields.Cashier = "Phil"
easyIntegrator1.TransFields.TransactionReference = "Inv123456"
If easyIntegrator1.CreditSaveCard() Then
  'transaction was approved
  'save easyIntegrator1.ResultsFields.UniqueTransID for tokenized transactions such as voids, returns and additional charges

GenericVoid

Notes on GenericVoid

  • Every transaction returns a ResultsFields.UniqueTransID.
    • TransFields.UniqueTransRef must be populated with this ID to identify which transaction to void.
  • GenericVoid can be used for all transactions. ChargeItPro 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 ChargeItPro will transform the void into a CreditReturn to negate the sale.
  • AmountTotal is not needed and cannot be specified
  • Only the 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.
easyIntegrator1.LoadSetup(SaveInYourDB)
easyIntegrator1.Clear
'use the previously saved easyIntegrator1.ResultsFields.UniqueTransID to identify which transaction to void
easyIntegrator1.TransFields.UniqueTransRef = UniqueTransIDFromPreviousTransaction
easyIntegrator1.TransFields.Cashier = "Phil"
easyIntegrator1.TransFields.TransactionReference = "Inv123456"
If easyIntegrator1.GenericVoid() Then
  'transaction was approved

Tokens

CreditSale using a token

This will charge the card identified by the token without prompting for user interaction.

easyIntegrator1.LoadSetup(SaveInYourDB)
easyIntegrator1.Clear
'use the previously saved easyIntegrator1.ResultsFields.UniqueTransID to identify which card to charge
easyIntegrator1.TransFields.UniqueTransRef = UniqueTransIDFromPreviousTransaction
easyIntegrator1.ConfigFields.AllowPartialApprovals = True 
easyIntegrator1.TransFields.AmountTotal = 20.00 'unsigned with decimals
easyIntegrator1.TransFields.Cashier = "Phil"
easyIntegrator1.TransFields.TransactionReference = "Inv123456"
If easyIntegrator1.CreditSale() Then
  'transaction was approved
  'save easyIntegrator1.ResultsFields.UniqueTransID for tokenized transactions such as voids, returns and additional charges 

CreditReturn using a token

This will refund the card identified by the token without prompting for user interaction.

easyIntegrator1.LoadSetup(SaveInYourDB)
easyIntegrator1.Clear
'use the previously saved easyIntegrator1.ResultsFields.UniqueTransID to identify which card to refund
easyIntegrator1.TransFields.UniqueTransRef = UniqueTransIDFromPreviousTransaction
easyIntegrator1.TransFields.AmountTotal = 20.00 'unsigned with decimals
easyIntegrator1.TransFields.Cashier = "Phil"
easyIntegrator1.TransFields.TransactionReference = "Inv123456"
If easyIntegrator1.CreditReturn() Then
  'transaction was approved
  'save easyIntegrator1.ResultsFields.UniqueTransID for tokenized transactions such as voids, returns and additional charges

Gift transactions

GiftAddValue

This will add value to a gift card.

easyIntegrator1.LoadSetup(SaveInYourDB)
easyIntegrator1.Clear
easyIntegrator1.TransFields.AmountTotal = 20.00 'unsigned with decimals
easyIntegrator1.TransFields.Cashier = "Phil"
easyIntegrator1.TransFields.TransactionReference = "Inv123456"
If easyIntegrator1.GiftAddValue() Then
  'transaction was approved 
  'save easyIntegrator1.ResultsFields.UniqueTransID for voids

GiftRedeem

This will deduct value from a gift card

easyIntegrator1.LoadSetup(SaveInYourDB)
easyIntegrator1.Clear
easyIntegrator1.TransFields.AmountTotal = 20.00 'unsigned with decimals
easyIntegrator1.TransFields.Cashier = "Phil"
easyIntegrator1.TransFields.TransactionReference = "Inv123456"
If easyIntegrator1.GiftRedeem() Then
  'transaction was approved 
  'save easyIntegrator1.ResultsFields.UniqueTransID for voids

GiftBalance

This is used to check the current balance of a card.

easyIntegrator1.LoadSetup(SaveInYourDB)
easyIntegrator1.Clear
easyIntegrator1.TransFields.AmountTotal = 20.00 'unsigned with decimals
easyIntegrator1.TransFields.Cashier = "Phil"
easyIntegrator1.TransFields.TransactionReference = "Inv123456"
If easyIntegrator1.GiftBalance() Then
  'transaction was approved    

Read results and print receipt

When a transaction comes back as True, your application should read, save and print the following fields:

  1. TransFields.AmountTotal – returns actual amount processed if using the AllowPartialApproval flag
  2. ResultsFields. AccountCardType - ie VS, MC, AX etc
  3. ResultsFields.AmountBalance - current balance of Gift Card
  4. ResultsFields.ApprovalNumberResult - Approval Number
  5. ResultsFields.BillingName - Name of Card Holder
  6. ResultsFields.MaskedAccount - Masked Credit Card Number
  7. ResultsFields.Signature - Customer signature
  8. ResultsFields. TransactionType - type of transaction
  9. ResultsFields.UniqueTransID - used to void transaction

Results fields

For a complete list of Results Fields and Transaction Types please see the Appendix Guide documentation

Signature samples

Receipt samples

Overview


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.