CreditLine DLL API Integration
This article is part of the Payment Processing Software Library |
|
Get it... | |
Install it... | |
Connect to it... | |
Set it up... | |
Learn to use it... | |
→ Manual & User Guide | |
Fix it... | |
→ Errors & Troubleshooting | |
Get Help... | |
More Info ... | |
See also... | |
CreditLine Payment Processing Software Integration. This site can also be reached at http://docs.911software.com
→ Looking for better rates? Get a Free Credit Card Processing Cost Comparison!
Contents
- 1 Inventory
- 2 Important Programming Rules
- 3 Language Specific Instructions
- 4 Diagnostic API
- 5 Server Control
- 6 Call Sequences
- 6.1 On Startup
- 6.2 On Shutdown
- 6.3 On Start Dial
- 6.4 On Regular Authorization
- 6.5 On Regular Force
- 6.6 On Regular Credit
- 6.7 On Add Tip
- 6.8 Edit Transaction
- 6.9 On Void Transaction
- 6.10 On Batch
- 6.11 On Gift Card Transaction
- 6.12 Hotel Specific
- 6.13 Find Transactions
- 6.14 Credit Card Storage
- 6.15 Debit Card and Pin Pad
- 7 API Examples
- 8 Sample Code
- 9 Advanced Setup
- 10 Troubleshooting
- 11 Advanced Setup
- 12 Troubleshooting
This guide is for developers using the DLL
Inventory
To begin with, you will need the following:
1) The interface header file CLCAPIW.h located in 911\BIN directory. This header contains the ENTIRE listing of available API.
2) The library file CLCAPIW2.DLLlocated in 911\DATA directory.
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.
Language Specific Instructions
Visual Basic
- In VB you need to declare all the parameters using the ByVal prefix instead of ByRef. This includes the strings.
- If you would like to use an OCX instead for Visual Basic, you can use CLClient.ocx in the same directory. Another alternative is File Based Communication.
Public Declare Function clcInit Lib "CLCAPIW2.dll" (ByVal ClientName As String, ByVal ServerName As String As Integer)
C++/C#
- The Header file is the regular WIN32 header file. The data type LONG is 32 bit.
- Keep in mind that in C# and any .NET environment for instance, LONG is 64 bit so you have to use int or Integer not LONG ot Long in your definitions.
- In C, the path has to be of format "C:\\911\\DATA", because back-slash is the escape char
DllImport("CLCAPIW2.dll", EntryPoint="clcInit", SetLastError=true, ExactSpelling=true, CallingConvention=CallingConvention.StdCall)
public static extern int clcInit(string ClientName, string ServerName);
Diagnostic API
- clcIsServerOnline → Recommended! Returns false if server is down
- clcShowInfo → After calling any set functions (e.g. clcSetAccountNumber), and before calling any transaction functions (e.g. clcSale), call this function to dump all the information that DLL has so far into the client side log file (911\data\ccv_log.txt). A good way to determine if the parameters are correct.
- clcTest → call for testing the function declarations if the POS is not in C
Server Control
clcSetTimeout → Timeout in milliseconds between the POS and the credit card server.
Call Sequences
On Startup
- clcInit → Set the client name and server name for communications
- clcSetJournalDir → Set the directory where the credit card journal is, e.g. 911\DATA
- clcSetMessageDir → Set the directory where the file communications occur, e.g. C:\911\MESSAGES
NOTE: the directories are actual directories on the server (where the dll is installed)
- clcSetStationId → Set a unique number for the terminal
On Shutdown
- clcTerm Release the resources
On Start Dial
- clcSetMerchantIndex → Optional, use a different merchant than the default
- clcSetAccountNum → Set the card account number (for manual entry)
- clcSetTrackData → Set the scanned track data (for magnetic swipe)
- clcDial → Start to dial the processor, connect before sending the transaction
Note: do not call clcSetAccountNum after clcSetTrackData or the transaction will go through as type manual not scanned
On Regular Authorization
- clcSetMerchantIndex → Optional, use a different merchant than the default
- clcSetInvoiceId → Set the invoice number
- clcSetOperatorId → Set the operator number
- clcSetTableNum → Set the table number
- clcSetGuestCount → Set the guest count
- clcSetAccountNum → Set the card account number (for manual entry)
- clcSetExpDate → (format: MMYY). Set the expiration date (for manual entry)
- clcSetTrackData → Set the scanned track data (for magnetic swipe)
- clcSetAmount → Set the authorization amount ($20.01 is entered as 2001 )
- clcSetCVCNumber → Set the CVC Number
- clcSetAVSData → Set the AVS Data (e.g. Zip)
- clcAuth → Do the authorization, returns the Transaction Id if successful. Auths cannot be settled until Tip is added
- clcSale → Do the sale, returns the Transaction Id if successful
- clcGetAuthCode → Get the authorization code if successful
- clcGetErrText → Get the error text if failed
Note: do not call clcSetAccountNum after clcSetTrackData or the transaction will go through as type manual not scanned
On Regular Force
- clcSetMerchantIndex → Optional, use a different merchant than the default
- clcSetInvoiceId → Set the invoice number
- clcSetOperatorId → Set the operator number
- clcSetTableNum → Set the table number
- clcSetGuestCount → Set the guest count
- clcSetAccountNum → Set the card account number (for manual entry)
- clcSetExpDate → (format: MMYY). Set the expiration date (for manual entry)
- clcSetTrackData → Set the scanned track data (for magnetic swipe)
- clcSetAmount → Set the authorization amount
- clcSetAuthCode → Set the force auth code (acquired from the call center)
- clcSetCVCNumber → Set the CVC Number
- clcSetAVSData → Set the AVS Data (e.g. Zip)
- clcForce → Actual do the force, returns the Transaction Id if successful
On Regular Credit
- clcSetMerchantIndex → Optional, use a different merchant than the default
- clcSetInvoiceId → Set the invoice number
- clcSetOperatorId → Set the operator number
- clcSetTableNum → Set the table number
- clcSetGuestCount → Set the guest count
- clcSetAccountNum → Set the card account number (for manual entry)
- clcSetExpDate → Set the expiration date (for manual entry)
- clcSetTrackData → Set the scanned track data (for magnetic swipe)
- clcSetAmount → Set the authorization amount
- clcSetCVCNumber → Set the CVC Number
- clcSetAVSData → Set the AVS Data (e.g. Zip)
- clcSetAuthCode → Set the force auth code (acquired from the call center)
- clcCredit → Do the credit, returns the Transaction Id if successful
On Add Tip
- clcSetMerchantIndex → Optional, use a different merchant than the default
- clcAddTip → Add actual tip to the transaction, need the Transaction Id
Edit Transaction
- clcSetMerchantIndex → Optional, use a different merchant than the default
- clcEdit → Edit the transaction, need the Transaction Id. Will not finalize the transaction unless EditForceAuthToSale=YES in CreditLine Advanced Setup file. In case of upward amount adjustment an incremental auth may be sent to the processor (if supported).
On Void Transaction
- clcSetMerchantIndex → Optional, use a different merchant than the default
- clcVoid → Void the transaction, need the Transaction Id
On Batch
- clcSetMerchantIndex → Optional, use a different merchant than the default
- clcBatch → Batch
Batch Selected Transactions
- clcFindTransIdByInvoiceId → used to find the trans id by invoice id
- clcMarkSelected → mark transaction as selected or not
- clcBatch2 → batch selected transactions only (if bSelectedOnly set to true). The card type is the card type index present in the settlement configuration (see numbers in the left column under Index - e.g VISA = 0, AMEX = 2, if present, etc).
On Gift Card Transaction
- clcActivate → Optional, activate gift card
- clcDeactivate → Optional, deactivate gift card
- clcInquire → Optional, returns the balance on the gift card
- clcSale → Do the sale, returns the Transaction Id if successful.
- clcAuth → Do the auth, returns the Transaction Id if successful.
- clcAddTip → Do add tip/finalize, returns the Transaction Id if successful.
- clcCredit → Do the credit, returns the Transaction Id if successful
- clcVoid → Void the transaction, returns the Transaction Id if successful. Note: use voidTransaction for CLC COM interface
- clcGetAmount → Get actual amount approved - to be called after every action that affects the balance.
- clcGetTip → Get actual tip approved - to be called after every action that affects the balance
- clcGetBalanceAmount → Get remaining card balance
→ After every call, the client should use clcGetAmount() clcGetTip() to determine the true amount the gift card approves, e.g. for partial redemption. Also after every call, the balance of the card can be obtained by calling clcGetBalanceAmount().
Hotel Specific
- clcSetCheckInDate → Sets checkin date
- clcSetCheckOutDate → Sets checkout date
- clcSetRoomRate → Sets room rate
- clcSetCustomerLastName → Sets customer last name
- clcSetCustomerFirstName → Sets customer first name
- clcSetPaymentType → Disney room charges only
- clcSetGuestCount → Disney room charges only
Find Transactions
- clcFindTransIdByInvoiceId → used to find the trans id by invoice id
Credit Card Storage
Storing Info
- clcSetAccountNum → Sets account number for storage (call before clcStoreCard).
- clcSetExpDate → Sets (format: MMYY). Set the expiration date for storage before calling clcStoreCard.
- clcSesSetValue → Use with CLCKEY_CUSTOMERNAME, CLCKEY_CUSTOMERNUMBER, CLCKEY_CUSTOMERZIPCODE to set the customer info for storage before calling clcStoreCard.
- clcStoreCard → Stores card info in storage. Sets a tag to be pased extracted by clcGetTag() and passed to clcLoadCard for retrieval. Leave the second parameter as "" unless you want to set a custom tag.
- clcGetTag → Retrieves the tag set by clcStoreCard
Loading Info
- clcLoadCard → Loads card info from storage. Accepts the tag returned by clcGetTag and set by clcStoreCard.
- clcGetAccountNum → Gets account number from storage (call after clcLoadCard).
- clcGetExpDate → (format: MMYY). Get the expiration date from storage (call after clcLoadCard).
- clcSesGetValue → Use with CLCKEY_CUSTOMERNAME, CLCKEY_CUSTOMERNUMBER, CLCKEY_CUSTOMERZIPCODE to get customer info from storage after calling clcLoadCard.
Deleting Info
- clcDeleteCard → Deletes card info from storage. Accepts the tag returned by clcGetTag and set by clcStoreCard.
Debit Card and Pin Pad
- Call pinpadRequestEntry
- Call pinpadGetPINBlock, pinpadGetDUKPTValue, pinpadGetKeyPointer.
- Pass the above values back to the automation object with card info and transaction info for the server to process.
→ See Sample Code for more info
- clcSetAccountType → for debit cards only. See definition in the clcapiw.h header file.
- pinpadRequestEntry
- pinpadGetPINBlock
- pinpadGetDUKPTValue
- pinpadGetKeyPointer
API Examples
→ see Sample Code for more info
Dim hCC As Integer;
Dim nResult As Integer;
Dim nTransNum As Integer;
Dim nBalance As Integer;
'On Startup
' NOTE: client name has to be unique for every terminal
hCC = clcInit("TERM001", "CCVSVR1");
' NOTE: the directories are actual directories on the server
' (where the dll is installed). These are required.
clcSetJournalDir(hCC, "c:\911\data");
clcSetMessageDir(hCC, "c:\911\messages");
clcSetStationId(hCC, 1);
'On Shutdown
clcTerm(hCC);
'On Start Dial
clcSetMerchantIndex(hCC, 1); 'default is 0
clcSetAccountNum(hCC, "4111111111111111");
clcDial(hCC);
'On Regular Authorization
clcSetMerchantIndex(hCC, 1); 'default is 0
clcSetInvoiceId(hCC, 123);
clcSetOperatorId(hCC, 1);
clcSetTableNum(hCC, 10);
clcSetAccountNum(hCC, "4111111111111111");
clcSetExpDate2(hCC, 02, 12);
clcSetAmount(hCC, 100); '$1.00
' sales can be batched right away but auths need tip to be added to them before batching
nResult = clcAuth(hCC); ' or nResult = clcSale(hCC);
if (nResult > 0)
- nTransNum = clcGetTransId(hCC);
- clcCopyAuthCode(hCC, strAuthCode);
else
- clcCopyErrText(hCC, strErrText);
On Regular Force
clcSetMerchantIndex(hCC, 1); 'default is 0
clcSetInvoiceId(hCC, 123);
clcSetOperatorId(hCC, 1);
clcSetTableNum(hCC, 10);
clcSetAccountNum(hCC, "4111111111111111");
clcSetExpDate2(hCC, 02, 12);
clcSetAmount(hCC, 100); '$1.00
clcSetAuthCode(hCC, "123456");
nResult = clcForce(hCC);
if (nResult > 0)
- nTransNum = clcGetTransId(hCC);
- clcCopyAuthCode(hCC, strAuthCode);
else
- clcCopyErrText(hCC, strErrText);
'On Regular Credit
clcSetMerchantIndex(hCC, 1); 'default is 0
clcSetInvoiceId(hCC, 123);
clcSetOperatorId(hCC, 1);
clcSetTableNum(hCC, 10);
clcSetAccountNum(hCC, "4111111111111111");
clcSetExpDate2(hCC, 02, 12);
clcSetAmount(hCC, 100); '$1.00
clcSetAuthCode(hCC, "CREDIT");
nResult = clcCredit(hCC);
if (nResult > 0)
- nTransNum = clcGetTransId(hCC);
- clcCopyAuthCode(hCC, strAuthCode);
else
- clcCopyErrText(hCC, strErrText);
'On Add Tip
clcSetMerchantIndex(hCC, 1); 'default is 0
clcAddTip(hCC, nTransNum, 100); 'Add $1.00 Tip
'On Void Transaction
clcSetMerchantIndex(hCC, 1); 'default is 0
clcVoid(hCC, nTransNum);
'On Gift Card transaction
' sale & credit are the same as a regular credit card
clcActivate(hCC, "4111111111111111");
clcDeactivate(hCC, "4111111111111111");
nBalance = clcInquire(hCC, "4111111111111111");
'On Batch
clcSetMerchantIndex(hCC, 1); 'default is 0
nResult = clcBatch(hCC);
Credit Card Storage
///* // Test Card Store
char szTag[256] = "";
{ // Store
clcSetAccountNum(hObj, "4111111111111111");
clcSetExpDate2(hObj, 2005, 12);
clcSesSetValue(hObj, CLCKEY_CUSTOMERNAME, "Test");
clcSesSetValue(hObj, CLCKEY_CUSTOMERNUMBER, "123");
clcSesSetValue(hObj, CLCKEY_CUSTOMERADDRESS, "PO BOX 888");
clcSesSetValue(hObj, CLCKEY_CUSTOMERZIPCODE, "33481");
clcStoreCard(hObj, "");
strcpy(szTag, clcGetTag());
cout << _T("Store Tag: ") << szTag << "\n";
} // Store
{ // Load
clcLoadCard(hObj, szTag);
char szValue[128] = "";
cout << _T("Account Number: ") << clcGetAccountNum(hObj) << "\n";
cout << _T("ExpDate: ") << clcGetExpDate(hObj) << "\n";
clcSesGetValue(hObj, CLCKEY_CUSTOMERNAME, szValue);
cout << _T("Name: ") << szValue << "\n";
clcSesGetValue(hObj, CLCKEY_CUSTOMERNUMBER, szValue);
cout << _T("Number: ") << szValue << "\n";
clcSesGetValue(hObj, CLCKEY_CUSTOMERADDRESS, szValue);
cout << _T("Address: ") << szValue << "\n";
clcSesGetValue(hObj, CLCKEY_CUSTOMERZIPCODE, szValue);
cout << _T("ZipCode: ") << szValue << "\n";
} // Load
{ // Delete
clcDeleteCard(hObj, szTag);
}} // Delete
Sample Code
Visual Basic
Advanced Setup
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.
Troubleshooting
Advanced Setup
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.