API Call Documentation

From Payment Processing Software Library
Revision as of 19:13, 29 August 2016 by Admin (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
This article is part of the
Payment Processing Software Library

Categories

Get it...

Credit Card Software
Download

Install it...

Installation
Upgrade & Migration

Connect to it...

Point Of Sale Integration

Set it up...

Quick Start Guide
Setup
Processor Setup

Licensing

Learn to use it...

Manual & User Guide
Knowledge Base
Frequently Asked Questions
Compliance Guide
Merchant Account Rates
User Interface Guides

Fix it...

Errors & Troubleshooting
Knowledge Base
Corrupted Install Repair

Get Help...

Contact
Processor Support Contacts

More Info ...

Glossary
Articles

See also...

911 Software
Help

CreditLine Payment Processing Software API Calls. This site can also be reached at http://docs.911software.com

Not finding all the answers? Try Knowledge Base!

Call Sequences

List of Functions

The full list of functions is found in \911\BIN\CLCAPIW.H file.

Rush Approval Mode

To process Stored Transactions online:

  • clcGetRushApprovalTransIdString → returns a string containing all Rush Approval stored offline transaction IDs, stored under Rush Approval Mode, separated by commas. Call clcRealAuth for each one to process online (convert the id to integer)
  • clcRealAuth → process Rush Approval stored offline transaction online (convert the id to integer). Call clcGetRushApprovalTransIdString to get a list of Rush Approval stored offline transaction IDs.

On Startup

  • clcInit → Set the client name and server name for communications. See Important Programming Rules for more info.
  • 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

→ Note: batches longer than 400 will be broken up for reliability purpuses and sent automatically as sequential smaller batches of 400 or less. Call clcBatch BEFORE the batch to get the correct batch total. Otherwise, only the last segmented batch part total will be returned.

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 Debit Card Transaction

  1. Get track data from the MSR.
  2. Get the account number from the track data
  3. Use the account number and the amount to call pinpadRequestEntry
  4. Call pinpadGetPINBlock to get the PIN Block
  5. Call pinpadGetDUKPTValue to get the DUKPT Value
  6. Call pinpadGetKeyPointer to get the Key Pointer
  7. Call pinpadShowDone to show "Thank You" on the pinpad
  8. Call the normal functions for a transaction, such as setTrackData, setAmount (Do not call setAccountNumber since it is for manual keyed transactions and Debit does not support manual entry)
  9. Call setPINBlock again to pass the PIN Block to the transaction buffer
  10. Call setDUKPTValue to pass the DUKPT Value to the transaction buffer
  11. Call setKeyPointer to pass the Key Pointer to the transaction buffer
  12. Call setCashBackAmount, setSurchargeAmount if there are any.
  13. Call sale to perform the debit transaction.

→ Note: debit only supports sale, refund and inquiry transactions.

  • clcSetAccountType → for debit cards only. See definition in the clcapiw.h header file.

→ See Sample Code and Pin Pad Setup for more info

On Gift Card Transaction

To sell a Gift Card, the POS must first charge the client the Activation Amount by using another form of payment (such as credit card). Then activation is sent to the processor to record the sale of the gift card.
Use clcSetAccountNum and clcSetAmount to set the parameters.

→ Gift Card Vendors use various terminologies. See below for common mapping of terms.

  • clcActivate → Issue. Optional, activate gift card. Returns 1 or 0 (ok=1)
  • clcDeactivate → Cash out for both pre-valued and not pre-valued. Optional, deactivate gift card. Call 'clcGetAmount' for the amount to return to the customer. Returns 1 or 0 (ok=1)
  • clcInquire → Optional, returns the balance on the gift card
  • clcSale → Redemption. Do the gift card redemption, returns the Transaction Id if successful or 0 if not. You can use clcGetAuthCode to get an auth code.
  • clcAuth → Do the auth, returns the Transaction Id if successful, or 0 if not. You can use clcGetAuthCode to get an auth code.
  • clcAddTip → Do add tip/finalize, returns the Transaction Id if successful.
  • clcCredit → Reload. 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().

On Loyalty Card Transaction

  • clcSetAccountNum(strAccountNum); → Sets the account number
  • clcSetAccountType(ACCTTYPE_LOYALTY); → Sets the account type
  • cSetMoneyAmount(nTotalDollarAmount); → Sets the dollar amount
  • clcSetUnits(nQuantity); → Sets number of units
  • clcIssuance() → Adds points to the customer account based on the money spent.
  • clcRedemption() → Deducts the points from the account to pay for the check.
  • clcSetPromoCode(); → Optional. Used to issue points based on products. Promo code defined by the merchant affects the conversion of amount and units to points.
  • clcSetSKU(strSKUDetailInfo) → Optional. Used to issue points based on products.
    SKU Detail Info Format: SKU,price,quantity;SKU,price[,quantity] (quantity is set to 1, if omitted)
    Example: "19999,19.99,3;20000,4.99;19999,19.99" means 3 x "19999,19.99" and 1 x "20000,4.99" and one more "19999,19.99"
  • clcGetAmount() → Get points issued
  • clcGetBalanceAmount() → Get total points on the account

See API Samples for more info.

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

Multiple Merchant Setup Info

  • clcGetMerchantListCount → returns how many merchant accounts are setup, or 0 if none
  • clcGetMerchantListData → takes absolute index (range is 0 to total number, returned by clcGetMerchantListCount) and returns the merchant index handle. Used in clcGetMerchantInfo.
  • clcGetMerchantInfo → takes merchant index handle obtained from clcGetMerchantListData, and returns merchant name and industry

Advanced Programming Notes

Card Type ID

Card Type used in clcGetCardType API can be obtained by looking at the Index number in front of the Card Type in the Configuration → Authorization Configuration: http://911software.com/credit_card_processing_software/index.php?title=CreditLine_Authorization_Configuration#Selecting_Accepted_Cards

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 clcSetAccountNum(hCC, "4111111111111111");
clcSetAmount(hCC, 100); '$1.00
clcActivate(hCC);
nBalance = clcGetBalanceAmount(hCC);
clcDeactivate(hCC);

'On Loyalty Card Transaction

///////////////////////////////
// Amount Based Point Issuence Setup
///////////////////////////////
clcSetAccountNum(strAccountNum);
clcSetAccountType(ACCTTYPE_LOYALTY);
clcSetMoneyAmount(nTotalDollarAmount);
clcSetUnits(nQuantity);
///////////////////////////////
// END of Amount Based Point Issuence Setup
///////////////////////////////

//////////////////////////////////////////////////////////
// ALTERNATIVELY, you can use Product Based Point Issuence Setup
//////////////////////////////////////////////////////////

clcSetAccountNum(strAccountNum);
clcSetAccountType(ACCTTYPE_LOYALTY);
clcSetSKU(strSKUDetailInfo);
// SKU Detail Info Format: SKU,price,quantity;SKU,price[,quantity] (quantity is set to 1, if omitted)
// Example: "19999,19.99,3;20000,4.99;19999,19.99" means 3 x "19999,19.99" and 1 x "20000,4.99" and one more "19999,19.99"


// clcSetPromoCode(123); You can also use customer defined promo code


//////////////////////////////////////////////////////////
// END of Product Based Point Issuence Setup
//////////////////////////////////////////////////////////


// After setting up the parameters invoke the issuance command and queries
clcIssuance();
// .....
clcGetAmount(); // to get the points issued and
clcGetBalanceAmount(); // to get the total points on the account.

///////////////////////////////
// Redemption
///////////////////////////////

clcSetAccountNum(strAccountNum);
clcSetAccountType(ACCTTYPE_LOYALTY);
clcSetAmount(nChargeAmount);
clcRedemption();
clcGetBalanceAmount();// to get the total points on the account.

'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