Level3 Class

Properties   Methods   Events   Config Settings   Errors  

The Level3 class is a tool used to create Level3 Corporate Purchasing Card aggregates, which can then be passed to the ICharge or Retail classes.

Syntax

Level3

Remarks

The available fields for each gateway supporting Level 3 data can be found below. Note: This list of fields does not designate what is required but rather only the fields made available by the gateway. For the required fields required to obtain the best rates, please consult your gateway for further information.

Property List

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

LineItems Property (Level3 Class)

A collection of line items to be included in the Level 3 addendum.

Syntax

• C++
• C
• Qt

InPayList<InPayEPLineItem>* GetLineItems();
int SetLineItems(InPayList<InPayEPLineItem>* val);

int inpay_level3_getlineitemcount(void* lpObj);
int inpay_level3_setlineitemcount(void* lpObj, int iLineItemCount);

char* inpay_level3_getitemcommoditycode(void* lpObj, int itemindex);
int inpay_level3_setitemcommoditycode(void* lpObj, int itemindex, const char* lpszItemCommodityCode);

char* inpay_level3_getitemdescription(void* lpObj, int itemindex);
int inpay_level3_setitemdescription(void* lpObj, int itemindex, const char* lpszItemDescription);

char* inpay_level3_getitemdiscountamount(void* lpObj, int itemindex);
int inpay_level3_setitemdiscountamount(void* lpObj, int itemindex, const char* lpszItemDiscountAmount);

char* inpay_level3_getitemdiscountrate(void* lpObj, int itemindex);
int inpay_level3_setitemdiscountrate(void* lpObj, int itemindex, const char* lpszItemDiscountRate);

char* inpay_level3_getitemname(void* lpObj, int itemindex);
int inpay_level3_setitemname(void* lpObj, int itemindex, const char* lpszItemName);

char* inpay_level3_getitemproductcode(void* lpObj, int itemindex);
int inpay_level3_setitemproductcode(void* lpObj, int itemindex, const char* lpszItemProductCode);

int inpay_level3_getitemquantity(void* lpObj, int itemindex);
int inpay_level3_setitemquantity(void* lpObj, int itemindex, int iItemQuantity);

int inpay_level3_getitemtaxable(void* lpObj, int itemindex);
int inpay_level3_setitemtaxable(void* lpObj, int itemindex, int bItemTaxable);

char* inpay_level3_getitemtaxamount(void* lpObj, int itemindex);
int inpay_level3_setitemtaxamount(void* lpObj, int itemindex, const char* lpszItemTaxAmount);

char* inpay_level3_getitemtaxrate(void* lpObj, int itemindex);
int inpay_level3_setitemtaxrate(void* lpObj, int itemindex, const char* lpszItemTaxRate);

char* inpay_level3_getitemtaxtype(void* lpObj, int itemindex);
int inpay_level3_setitemtaxtype(void* lpObj, int itemindex, const char* lpszItemTaxType);

char* inpay_level3_getitemtotal(void* lpObj, int itemindex);
int inpay_level3_setitemtotal(void* lpObj, int itemindex, const char* lpszItemTotal);

char* inpay_level3_getitemunitcost(void* lpObj, int itemindex);
int inpay_level3_setitemunitcost(void* lpObj, int itemindex, const char* lpszItemUnitCost);

char* inpay_level3_getitemunits(void* lpObj, int itemindex);
int inpay_level3_setitemunits(void* lpObj, int itemindex, const char* lpszItemUnits);

int GetLineItemCount();
int SetLineItemCount(int iLineItemCount);

QString GetItemCommodityCode(int iItemIndex);
int SetItemCommodityCode(int iItemIndex, QString qsItemCommodityCode);

QString GetItemDescription(int iItemIndex);
int SetItemDescription(int iItemIndex, QString qsItemDescription);

QString GetItemDiscountAmount(int iItemIndex);
int SetItemDiscountAmount(int iItemIndex, QString qsItemDiscountAmount);

QString GetItemDiscountRate(int iItemIndex);
int SetItemDiscountRate(int iItemIndex, QString qsItemDiscountRate);

QString GetItemName(int iItemIndex);
int SetItemName(int iItemIndex, QString qsItemName);

QString GetItemProductCode(int iItemIndex);
int SetItemProductCode(int iItemIndex, QString qsItemProductCode);

int GetItemQuantity(int iItemIndex);
int SetItemQuantity(int iItemIndex, int iItemQuantity);

bool GetItemTaxable(int iItemIndex);
int SetItemTaxable(int iItemIndex, bool bItemTaxable);

QString GetItemTaxAmount(int iItemIndex);
int SetItemTaxAmount(int iItemIndex, QString qsItemTaxAmount);

QString GetItemTaxRate(int iItemIndex);
int SetItemTaxRate(int iItemIndex, QString qsItemTaxRate);

QString GetItemTaxType(int iItemIndex);
int SetItemTaxType(int iItemIndex, QString qsItemTaxType);

QString GetItemTotal(int iItemIndex);
int SetItemTotal(int iItemIndex, QString qsItemTotal);

QString GetItemUnitCost(int iItemIndex);
int SetItemUnitCost(int iItemIndex, QString qsItemUnitCost);

QString GetItemUnits(int iItemIndex);
int SetItemUnits(int iItemIndex, QString qsItemUnits);

Remarks

This property contains a collection of line items to be included in the Level 3 addendum.

Please refer to Level3 to identify which LineItems are required for the gateway you are implementing.

An example of setting two line items for a Visa Corporate purchasing card follows:

Level3.LineItems.Add(new EPLineItem()); Level3.LineItems[0].CommodityCode = "4900"; // Books and printed materials Level3.LineItems[0].Description = "Reference manual"; Level3.LineItems[0].DiscountAmount = ""; // No discount Level3.LineItems[0].ProductCode = "ISBN123456"; Level3.LineItems[0].Quantity = "2"; Level3.LineItems[0].TaxAmount = "60"; Level3.LineItems[0].TaxRate = "600"; // 6.00 percent Level3.LineItems[0].Total = "1060"; Level3.LineItems[0].UnitCost = "500"; Level3.LineItems[0].Units = "each"; Level3.LineItems.Add(new EPLineItem()); Level3.LineItems[1].CommodityCode = "4900"; Level3.LineItems[1].Description = "Quick Start manual"; Level3.LineItems[1].DiscountAmount = ""; Level3.LineItems[1].ProductCode = "ISBN654321"; Level3.LineItems[1].Quantity = "1"; Level3.LineItems[1].TaxAmount = "60"; Level3.LineItems[1].TaxRate = "600"; // 6.00 percent Level3.LineItems[1].Total = "1060"; Level3.LineItems[1].UnitCost = "1000"; Level3.LineItems[1].Units = "each";

Data Type

InPayEPLineItem

SpecialFields Property (Level3 Class)

A list of additional fields to send in the request.

Syntax

• C++
• C
• Qt

InPayList<InPayEPSpecialField>* GetSpecialFields();
int SetSpecialFields(InPayList<InPayEPSpecialField>* val);

int inpay_level3_getspecialfieldcount(void* lpObj);
int inpay_level3_setspecialfieldcount(void* lpObj, int iSpecialFieldCount);

char* inpay_level3_getspecialfieldname(void* lpObj, int fieldindex);
int inpay_level3_setspecialfieldname(void* lpObj, int fieldindex, const char* lpszSpecialFieldName);

char* inpay_level3_getspecialfieldvalue(void* lpObj, int fieldindex);
int inpay_level3_setspecialfieldvalue(void* lpObj, int fieldindex, const char* lpszSpecialFieldValue);

int GetSpecialFieldCount();
int SetSpecialFieldCount(int iSpecialFieldCount);

QString GetSpecialFieldName(int iFieldIndex);
int SetSpecialFieldName(int iFieldIndex, QString qsSpecialFieldName);

QString GetSpecialFieldValue(int iFieldIndex);
int SetSpecialFieldValue(int iFieldIndex, QString qsSpecialFieldValue);

Remarks

This property contains a properties of EPSpecialField name/value pair objects. The Gateway may put some special configuration fields into this property which you can edit or add to. This allows you to extend the functionality of the class by adding fields for which there are not currently properties for.

This property is not available at design time.

Data Type

InPayEPSpecialField

AddSpecialField Method (Level3 Class)

Adds a special field name and the corresponding value.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int AddSpecialField(const char* lpszName, const char* lpszValue);

Unicode (Windows)
INT AddSpecialField(LPCWSTR lpszName, LPCWSTR lpszValue);

int inpay_level3_addspecialfield(void* lpObj, const char* lpszName, const char* lpszValue);

int AddSpecialField(const QString& qsName, const QString& qsValue);

Remarks

This method allows for specifying special fields for level 3 details at a transaction as well as a line item level. Typically level 3 details pertain to item details, however some gateways expose fields that are not item specific. This method allows you to specify these fields. Additionally you can specify item specific fields that aren't exposed via LineItems. Please consult the gateways specifications to obtain available fields and their format.

Gateways implemented using XML may require the elements to be split into their own line item elements. In such a case, the specified Name value can be specified in the form "[index]:[name]" (where 'index' is the LineItems index and 'name' is the name of the element you wish to add). The component will then parse the format and place line item data within the correct element in the request.

The following gateways are implemented using XML and support indexed special field values:

• gwBankOfAmerica (13)
• gwOrbital (23)
• gwSterling (45)
• gwLitle (63)
• gwPayTrace (70)
• gwDataCash (77)
• gwFirstDataE4 (80)

Please refer to the Name and Value fields for more information on form variables and how they are managed.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Config Method (Level3 Class)

Sets or retrieves a configuration setting.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* Config(const char* lpszConfigurationString);

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);

char* inpay_level3_config(void* lpObj, const char* lpszConfigurationString);

QString Config(const QString& qsConfigurationString);

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetAggregate Method (Level3 Class)

Returns an aggregate containing level 3 details for a transaction.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetAggregate();

Unicode (Windows)
LPWSTR GetAggregate();

char* inpay_level3_getaggregate(void* lpObj);

QString GetAggregate();

Remarks

This method returns an aggregate containing the level 3 data specified. This aggregate must be passed to the ICharge class's Level3Aggregate property in order for the level 3 data to be sent in the transaction. Each gateway has different requirements when processing level 3 transactions. Please refer to Level3 to identify which properties are required for the gateway you are implementing.

An example of how this method is used is shown below:

Level2.PONumber = "123456789" Level2.ShipToZip = "27713" Level2.TaxAmount = "1.23" Level2.IsTaxExempt = false ICharge.Level2Aggregate = Level2.GetAggregate() Level3.LineItemCount = 2 Level3.LineItems[0].CommodityCode = "4900" // Books and printed materials Level3.LineItems[0].Description = "Reference manual" Level3.LineItems[0].DiscountAmount = "" // No discount Level3.LineItems[0].ProductCode = "ISBN123456" Level3.LineItems[0].Quantity = "2" Level3.LineItems[0].TaxAmount = "60" Level3.LineItems[0].TaxRate = "600" // 6.00 percent Level3.LineItems[0].Total = "1060" Level3.LineItems[0].UnitCost = "500" Level3.LineItems[0].Units = "each" Level3.LineItems.Add(new EPLineItem()); Level3.LineItems[1].CommodityCode = "4900" Level3.LineItems[1].Description = "Quick Start manual" Level3.LineItems[1].DiscountAmount = "" Level3.LineItems[1].ProductCode = "ISBN654321" Level3.LineItems[1].Quantity = "1" Level3.LineItems[1].TaxAmount = "60" Level3.LineItems[1].TaxRate = "600" // 6.00 percent Level3.LineItems[1].Total = "1060" Level3.LineItems[1].UnitCost = "1000" Level3.LineItems[1].Units = "each"

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Error Event (Level3 Class)

Information about errors during data delivery.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireError(Level3ErrorEventParams *e);

typedef struct {
  int ErrorCode;
  const char *Description;
  int reserved;
} Level3ErrorEventParams;


Unicode (Windows)
virtual INT FireError(Level3ErrorEventParams *e);

typedef struct {
  INT ErrorCode;
  LPCWSTR Description;
  INT reserved;
} Level3ErrorEventParams;

#define EID_LEVEL3_ERROR 1

virtual INT INPAY_CALL FireError(INT &iErrorCode, LPSTR &lpszDescription);

class Level3ErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Error(Level3ErrorEventParams *e);

// Or, subclass Level3 and override this emitter function.
virtual int FireError(Level3ErrorEventParams *e) {...}

Remarks

The Error event is fired in case of exceptional conditions during message processing.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

EPLineItem Type

Contains a single Level 3 line item.

Syntax

InPayEPLineItem (declared in inpay.h)

Remarks

This type contains a single line item, used for Level 3 settlements. The fields contained by this type are listed below.

• CommodityCode
• Description
• DiscountAmount
• DiscountRate
• Name
• ProductCode
• Quantity
• Taxable
• TaxAmount
• TaxRate
• TaxType
• Total
• UnitCost
• Units

Fields

Constructors

EPLineItem()

EPSpecialField Type

Additional name/value pairs which can be added to a transaction.

Syntax

InPayEPSpecialField (declared in inpay.h)

Remarks

This type contains a Name and Value which may contain any additional information you wish to send to your gateway that this class does not currently send. You must know the field name in the gateway integration guide available from your gateway. For instance, the code below shows how to add a customer IP Address for the Authorize.Net gateway:

ICharge1.SpecialFields.add(new EPSpecialField("x_customer_ip", "255.123.456.78"));

• Name
• Value

Fields

Constructors

EPSpecialField()

EPSpecialField(const char* lpszName, const char* lpszValue)

InPayList Type

Syntax

InPayList<T> (declared in inpay.h)

Remarks

InPayList is a generic class that is used to hold a collection of objects of type T, where T is one of the custom types supported by the Level3 class.

int GetCount() {}

int SetCount(int count) {}

T* Get(int index) {}

T* Set(int index, T* value) {}

Config Settings (Level3 Class)

Level3 Config Settings

Base Config Settings

Trappable Errors (Level3 Class)

Error Handling (C++)

Call the GetLastErrorCode() method to obtain the last called method's result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. Known error codes are listed below. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Level3 Errors