CreditLine Integration Tutorial
| This article is part of the
Payment Processing Software Library
|Connect to it...|
|Set it up...|
|Learn to use it...|
|More Info ...|
→ Looking for better rates? Get a Free Credit Card Processing Cost Comparison!
- 1 Integration Basics
- 2 Important Programming Rules
- 3 Multiple Terminal Setup
- 4 PCI Tokenization and Encapsulation Functions
- 5 API Call Documentation
- 6 Platform Specific API Guides
- 7 Rush Approval Mode
- 8 Card Storage
- 9 Testing & Troubleshooting
- 10 Certification
- 11 Samples
- 12 Advanced Setup
- 13 Complete List of Functions
- 14 Also See
Your Point Of Sale will drive our CreditLine Server through the Application Programming Interface (API). The API can be made available to the application through one of the methods described below.
The basic operation is as follows:
- sets the local path to the server data directory here. Every client can actually use a different data path for advanced configurations (e.g. every client batches their own transactions separately).
Here you will set:
- Client Name, that has to be unique for every terminal
- Server Directories, which are actual directories on the server where the dll is installed). These two are required.
Fine Dining Restaurants (Tip Environment)
- 1) Auth
- Every card (Configuration->Authorization Configuration->Visa->Edit) has a field Tip Rate. By default it is set to 20%. When using Auth call, the server does an automatic authorization for the main amount plus 20% to account for a possible tip. This will make sure that the money is already reserved, so that when the server adds tip at the end of the day the card does not decline. If you do not use Tips in your environment or to disable, set Tip Rate to 0 for every card.
IMPORTANT: Auth transaction (a transaction created with Auth) will not Batch until it is Finalized. (see AddTip below).
- 2) AddTip
- will overwrite any previously set Tip value, including the one preset by Authorize. Pass the Tracking Id created by Authorize to this function. This call will Finalize the Auth transaction. This means that it will turn the Auth transaction into Sale transaction, which in turn will include it in the next Batch.
IMPORTANT: the Tracking Id returned by Auth must match the one supplied to AddTip, otherwise two transactions will be generated in the journal (one Auth transaction and one Sale transaction ). This will create Auth transactions in the journal that will not be batched. If you are generating your own Tracking Ids please make sure that they match on Finalization to avoid serious transaction problems.
Retail and QSR (No-Tip Environment)
- creates a sale transactions that is ready for batching. You can also include tip if desired in the sale if it is a one step process. Do not use Auth if you do not use tips in this environment!
Repeat the Transaction Processing step as necessary
- This call will instruct the processor to deposit the money (allocated by Authorize, Add Tip and/or Sale as described in Step 2. above) into the bank account. Only Finalized transactions will be included in the Batch. The rest of transactions will be left in the journal. Most merchants Batch daily.
Repeat Transaction Processing and Batch steps as necessary
- This call will shutdown and clean up the connection
Other calls include Void, Credit, Selective Batch, etc. Please Platform Specific API Guides below for complete listing.
Important Programming Rules
→ PLEASE, read every point below as those are the common points of failure in the integrations. Reviewing these pointers may save you significant amount of time in debugging.
- Compile for x86 / 32-bit. Do NOT compile for 64-bit even if the program will be used on a 64-bit OS.
- Each API object instance needs to call the initialization function (such as clcInit or Init) themselves and get a unique handle to themselves. This handle can not be shared across objects. However, SEE IMPORTANT WARNING BELOW about multiple object creation!
- Do NOT create a new object every time you call our API. This will create resource issues. The API object is meant to be created and shared by your application, unless you need to make multiple requests in parallel or creating multiple terminals to do the same - see below.
- Each instance can only make one request at a time, but one process can have multiple instances to make multiple requests.
- Each instance needs to have a unique client name or terminal name. For example, instance 1 gets TERM001, and instance 2 gets TERM002. The best way to configure this is by device. The length limit is 7. The server monitors the names for duplication and will do it's own name resolution in case of duplicate client names.
- The server name should match what's showing on the title bar of the credit server program.
- If using the CreditLine Multiple Merchant Account Setup, you must call clcSetMerchantIndex before every Auth, Edit, Sale, Batch and other transaction related calls. The merchant index is reset to 0 on every call completion.
- Some environments, such as VB.NET may lose the automation reference if the same API is called twice too quickly. Avoid calling the same API in tight loops - add a reasonable delay if needed.
- The dollar amounts have an implied decimal point. e.g. $2.00 should be submitted to our API as 200, not 2.00
- Since you will be calling a "black box" DLL, please avoid redundant and inefficient code. Obscure and hard to debug code may significantly extend your debugging efforts.
- Do take a look at our sample code.
The server name should match what's showing on the title bar of the credit server program. We had a NETBIOS interface before, so they must match. However, the file API is not that strict. However, it is a good practice to match them, in case we implement multi-servers that monitor the same message directory.
Multiple Terminal Setup
→ For more info, please see: CreditLine Networked Client-Server Installation
PCI Tokenization and Encapsulation Functions
There are three ways, in which CreditLine can help your application eliminate exposure to the payment info:
- Our application pops up a custom UI for accepting and processing credit cards, debit cards or gift cards, so that your application does not have to.
- Recurrent credit card data is accepted, stored and processed through our custom UI, as well.
- Tokenization UI API is used to reference credit card data that is stored and encrypted within CreditLine, instead of your POS.
This way your application can claim that no credit card data is being stored or processed.
- Important Notice: This program was called "PCI Exempt". We changed the name to reflect the new policies of the PCI Council. PCI Exempt used to be a convenient term that Point Of Sale developers use to refer to the practice of tokenization and external UI encapsulation. 911 Software does not have the authority to exempt any vendor from PCI requirements. Please, contact your independent PCI auditor for rules applicable to your situation.
For more info, please see PCI Friendly API.
API Call Documentation
→ Please see API Call Documentation
Platform Specific API Guides
DLL API (Preferred)
- API Guide for DLL Based Communication - Preferred Integration Method
Text Based (ICVerify compatible)
ATL COM for Visual Basic, .NET, ASP, web etc
OCX for Visual Basic
- OCX Integration Guide for Visual Basic - This is a legacy interface, please use ATL COM Integration Guide ABOVE.
Rush Approval Mode
Rush Approval Mode is an optional transparent offline mode that allows POS to continue taking credit cards without delays during connectivity failures. For more information see Rush Approval Mode article. Requires 3.03.14Alpha6+
PCI Friendly API also offers a comprehensive set of payment info storage API.
Testing & Troubleshooting
You can use the following scripts to test your POS integration with 911 Software:
- Certification Scripts (after opening the link, please use right click and Save Target As to avoid download delays)
Make sure to set the CreditLine into CreditLine Test Mode when using these test accounts:
→ Some samples include DLL's for your convenience. For the production work, please update the DLL's with the latest provided in your software install under \911\BIN directory.
CreditLine behavior can be fine tuned to match your operational requirements.
Please see the 911/data/911_CCV.INI and 911/DATA/CLCAPI.INI (for advanced API behavior) files for more information.
→ Upgrades do not overwrite the ini files because they may contain custom settings.
→ IMPORTANT! Make sure to browse through the CUSTOM POS SETTINGS section at the end of the 911/data/911_CCV.INI file for any settings that may be necessary for your specific POS installation.
- Note: for the key to take effect, do not forget to remove ';' in front of a key to uncomment it.
Complete List of Functions
Please see 911\bin\CLCAPIW.h
NOTE: OCX/COM/ATL objects simply wrap the standard API DLL, removing "clc" prefix from functions.