Retail Class

Properties   Methods   Events   Config Settings   Errors  

The Retail class is used to authorize credit card transactions with any of the supported Internet Payment Gateways.

Syntax

Retail

Remarks

The Retail class allows you to use multiple Internet Payment Gateways through one interface and one class. This allows for easy migration from one gateway to another, as well as quick integration into applications or web services.

The Retail class allows your website to securely perform credit card transactions without the need to redirect to a third-party site. All transactions are accomplished through a secure HTTPS Post to any supported gateway. The secure response is received and then stored in the class's response properties. Any web site on a standard HTTP server or any stand-alone application can process transactions without the need for a secure server or third-party intervention.

The first thing you must do is select one of the many gateways supported by the Retail class, and set up an account with that gateway vendor. Once you have an account set up with a valid (or test) login Id and password, you can use the Retail class.

To begin, set the Gateway property to the gateway you wish to use. If this gateway supports an alternate URL to send test transactions to, set the GatewayURL at this time.

Next, set the MerchantLogin (and for some gateways the MerchantPassword). These are supplied by your gateway vendor when you set up an account.

Now you are ready to process transactions. For each transaction, you can set the Card and TransactionAmount properties. For swiped card transactions you can set MagneticStripe or for manually entered transactions you can set Number, ExpMonth, ExpYear. Most gateways will also require additional properties, such as Address, FirstName, LastName, InvoiceNumber, etc. Any additional required properties are listed in the Gateway property description.

Once these properties are set, you may run validity checks on the card data with the AVSOnly method, or simply authorize the transaction with the Sale method. If your Gateway supports them, you may also perform a wide variety of transaction types such as VoidTransaction, Refund, Credit, or Force. Please review the method pages for further details about these methods and their designed functionality.

The following gateways are supported by the Retail class:

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.

AuthCode Property (Retail Class)

Authorization code from a previous transaction.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetAuthCode();
int SetAuthCode(const char* lpszAuthCode);

Unicode (Windows)
LPWSTR GetAuthCode();
INT SetAuthCode(LPCWSTR lpszAuthCode);

char* inpay_retail_getauthcode(void* lpObj);
int inpay_retail_setauthcode(void* lpObj, const char* lpszAuthCode);

QString GetAuthCode();
int SetAuthCode(QString qsAuthCode);

Default Value

""

Remarks

Some gateways require the merchant to include the ApprovalCode from the original transaction in Credit, VoidTransaction, and Capture transactions. You may send the original approval code in this AuthCode property. The gateways which require this are listed below:

• gwIntellipay (3)
• gwBankOfAmerica (13)
• gwInnovative (14)
• gwACHPAyments (35)
• gwForte (36)
• gwSagePay (50)
• gwDataCash (77)
• gwFirstDataE4 (80)

Data Type

String

Card Property (Retail Class)

Contains the customer's credit card information.

Syntax

• C++
• C
• Qt

InPayCCCard* GetCard();
int SetCard(InPayCCCard* val);

int inpay_retail_getcardtype(void* lpObj);
int inpay_retail_setcardtype(void* lpObj, int iCardType);

char* inpay_retail_getcardcvvdata(void* lpObj);
int inpay_retail_setcardcvvdata(void* lpObj, const char* lpszCardCVVData);

int inpay_retail_getcardcvvpresence(void* lpObj);
int inpay_retail_setcardcvvpresence(void* lpObj, int iCardCVVPresence);

int inpay_retail_getcardentrydatasource(void* lpObj);
int inpay_retail_setcardentrydatasource(void* lpObj, int iCardEntryDataSource);

int inpay_retail_getcardexpmonth(void* lpObj);
int inpay_retail_setcardexpmonth(void* lpObj, int iCardExpMonth);

int inpay_retail_getcardexpyear(void* lpObj);
int inpay_retail_setcardexpyear(void* lpObj, int iCardExpYear);

int inpay_retail_getcardisencrypted(void* lpObj);
int inpay_retail_setcardisencrypted(void* lpObj, int bCardIsEncrypted);

char* inpay_retail_getcardmagneticstripe(void* lpObj);
int inpay_retail_setcardmagneticstripe(void* lpObj, const char* lpszCardMagneticStripe);

char* inpay_retail_getcardnumber(void* lpObj);
int inpay_retail_setcardnumber(void* lpObj, const char* lpszCardNumber);

int GetCardType();
int SetCardType(int iCardType);

QString GetCardCVVData();
int SetCardCVVData(QString qsCardCVVData);

int GetCardCVVPresence();
int SetCardCVVPresence(int iCardCVVPresence);

int GetCardEntryDataSource();
int SetCardEntryDataSource(int iCardEntryDataSource);

int GetCardExpMonth();
int SetCardExpMonth(int iCardExpMonth);

int GetCardExpYear();
int SetCardExpYear(int iCardExpYear);

bool GetCardIsEncrypted();
int SetCardIsEncrypted(bool bCardIsEncrypted);

QString GetCardMagneticStripe();
int SetCardMagneticStripe(QString qsCardMagneticStripe);

QString GetCardNumber();
int SetCardNumber(QString qsCardNumber);

Remarks

This must be set to an instance of the CCCard type, which will contain information about the credit card to be charged. This may include a MagneticStripe for swiped cards, or a Number, ExpMonth, and ExpYear for manually entered cards. (EntryDataSource indicates which set of properties will be used). See the CCCard type for more information.

This property is not available at design time.

Data Type

InPayCCCard

Customer Property (Retail Class)

Contains the customer's name, address, and other identifying information.

Syntax

• C++
• C
• Qt

InPayEPCustomer* GetCustomer();
int SetCustomer(InPayEPCustomer* val);

char* inpay_retail_getcustomeraddress(void* lpObj);
int inpay_retail_setcustomeraddress(void* lpObj, const char* lpszCustomerAddress);

char* inpay_retail_getcustomeraddress2(void* lpObj);
int inpay_retail_setcustomeraddress2(void* lpObj, const char* lpszCustomerAddress2);

char* inpay_retail_getcustomeraggregate(void* lpObj);
int inpay_retail_setcustomeraggregate(void* lpObj, const char* lpszCustomerAggregate);

char* inpay_retail_getcustomercity(void* lpObj);
int inpay_retail_setcustomercity(void* lpObj, const char* lpszCustomerCity);

char* inpay_retail_getcustomercountry(void* lpObj);
int inpay_retail_setcustomercountry(void* lpObj, const char* lpszCustomerCountry);

char* inpay_retail_getcustomeremail(void* lpObj);
int inpay_retail_setcustomeremail(void* lpObj, const char* lpszCustomerEmail);

char* inpay_retail_getcustomerfax(void* lpObj);
int inpay_retail_setcustomerfax(void* lpObj, const char* lpszCustomerFax);

char* inpay_retail_getcustomerfirstname(void* lpObj);
int inpay_retail_setcustomerfirstname(void* lpObj, const char* lpszCustomerFirstName);

char* inpay_retail_getcustomerfullname(void* lpObj);
int inpay_retail_setcustomerfullname(void* lpObj, const char* lpszCustomerFullName);

char* inpay_retail_getcustomerid(void* lpObj);
int inpay_retail_setcustomerid(void* lpObj, const char* lpszCustomerId);

char* inpay_retail_getcustomerlastname(void* lpObj);
int inpay_retail_setcustomerlastname(void* lpObj, const char* lpszCustomerLastName);

char* inpay_retail_getcustomerphone(void* lpObj);
int inpay_retail_setcustomerphone(void* lpObj, const char* lpszCustomerPhone);

char* inpay_retail_getcustomerstate(void* lpObj);
int inpay_retail_setcustomerstate(void* lpObj, const char* lpszCustomerState);

char* inpay_retail_getcustomerzip(void* lpObj);
int inpay_retail_setcustomerzip(void* lpObj, const char* lpszCustomerZip);

QString GetCustomerAddress();
int SetCustomerAddress(QString qsCustomerAddress);

QString GetCustomerAddress2();
int SetCustomerAddress2(QString qsCustomerAddress2);

QString GetCustomerAggregate();
int SetCustomerAggregate(QString qsCustomerAggregate);

QString GetCustomerCity();
int SetCustomerCity(QString qsCustomerCity);

QString GetCustomerCountry();
int SetCustomerCountry(QString qsCustomerCountry);

QString GetCustomerEmail();
int SetCustomerEmail(QString qsCustomerEmail);

QString GetCustomerFax();
int SetCustomerFax(QString qsCustomerFax);

QString GetCustomerFirstName();
int SetCustomerFirstName(QString qsCustomerFirstName);

QString GetCustomerFullName();
int SetCustomerFullName(QString qsCustomerFullName);

QString GetCustomerId();
int SetCustomerId(QString qsCustomerId);

QString GetCustomerLastName();
int SetCustomerLastName(QString qsCustomerLastName);

QString GetCustomerPhone();
int SetCustomerPhone(QString qsCustomerPhone);

QString GetCustomerState();
int SetCustomerState(QString qsCustomerState);

QString GetCustomerZip();
int SetCustomerZip(QString qsCustomerZip);

Remarks

This property must be set to an instance of the EPCustomer type, which will contain information that identifies the customer. This information will be used by the Gateway for fraud checking purposes. See the EPCustomer type for more information.

All gateways require at the minimum the FirstName, LastName, FullName (the customer's name as it appears on the card), Address, City, State, and Zip. The following table shows which gateways require which additional Customer properties:

This property is not available at design time.

Data Type

InPayEPCustomer

Gateway Property (Retail Class)

Gateway to process transactions with.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetGateway();
int SetGateway(int iGateway);

Unicode (Windows)
INT GetGateway();
INT SetGateway(INT iGateway);

RGW_NO_GATEWAY(0), 
RGW_AUTHORIZE_NET(1), 
RGW_EPROCESSING(2), 
RGW_ITRANSACT(4), 
RGW_NET_BILLING(5), 
RGW_PAY_FLOW_PRO(6), 
RGW_USAE_PAY(7), 
RGW_PLUG_NPAY(8), 
RGW_PLANET_PAYMENT(9), 
RGW_MPCS(10), 
RGW_RTWARE(11), 
RGW_ECX(12), 
RGW_BANK_OF_AMERICA(13), 
RGW_MERCHANT_ANYWHERE(15), 
RGW_SKIPJACK(16), 
RGW_TRUST_COMMERCE(19), 
RGW_PAY_FUSE(21), 
RGW_LINK_POINT(24), 
RGW_FAST_TRANSACT(27), 
RGW_NETWORK_MERCHANTS(28), 
RGW_PRIGATE(30), 
RGW_MERCHANT_PARTNERS(31), 
RGW_FIRST_DATA(33), 
RGW_YOUR_PAY(34), 
RGW_ACHPAYMENTS(35), 
RGW_FORTE(36), 
RGW_CYBER_SOURCE(37), 
RGW_GO_EMERCHANT(39), 
RGW_CHASE(41), 
RGW_NEX_COMMERCE(42), 
RGW_TRANSACTION_CENTRAL(44), 
RGW_STERLING(45), 
RGW_PAY_JUNCTION(46), 
RGW_MY_VIRTUAL_MERCHANT(49), 
RGW_VERIFI(54), 
RGW_MERCHANT_ESOLUTIONS(56), 
RGW_PAY_LEAP(57), 
RGW_WORLD_PAY_XML(59), 
RGW_PRO_PAY(60), 
RGW_QBMS(61), 
RGW_HEARTLAND(62), 
RGW_LITLE(63), 
RGW_BRAIN_TREE(64), 
RGW_JET_PAY(65), 
RGW_HSBC(66), 
RGW_BLUE_PAY(67), 
RGW_PAY_TRACE(70), 
RGW_TRANS_NATIONAL_BANKCARD(74), 
RGW_FIRST_DATA_E4(80), 
RGW_BLUEFIN(82), 
RGW_PAYSCAPE(83), 
RGW_PAY_DIRECT(84), 
RGW_WORLD_PAY_LINK(87), 
RGW_PAYMENT_WORK_SUITE(88), 
RGW_FIRST_DATA_PAY_POINT(90), 
RGW_PAYEEZY(94), 
RGW_AUTHORIZE_NET_XML(96), 
RGW_PHOENI_XGATE(97), 
RGW_REPAY(98), 
RGW_BASYS(106), 
RGW_QBPAYMENTS(113), 
RGW_SHIFT_4(114), 
RGW_HEARTLAND_PORTICO(116), 
RGW_PAY_TRACE_JSON(117)

int inpay_retail_getgateway(void* lpObj);
int inpay_retail_setgateway(void* lpObj, int iGateway);

int GetGateway();
int SetGateway(int iGateway);

Default Value

0

Remarks

This property is used to select the gateway with which transactions will be processed. Setting the Gateway property will also fill the GatewayURL, Name, and Value properties with default data for the selected gateway. The following table shows the currently supported gateways, as well as the corporate home page for each.

Data Type

Integer

GatewayURL Property (Retail Class)

Default URL for a specific Gateway .

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetGatewayURL();
int SetGatewayURL(const char* lpszGatewayURL);

Unicode (Windows)
LPWSTR GetGatewayURL();
INT SetGatewayURL(LPCWSTR lpszGatewayURL);

char* inpay_retail_getgatewayurl(void* lpObj);
int inpay_retail_setgatewayurl(void* lpObj, const char* lpszGatewayURL);

QString GetGatewayURL();
int SetGatewayURL(QString qsGatewayURL);

Default Value

""

Remarks

This property is used to change the default URL for a specific Gateway. This is useful for specifying a different URL for testing purposes, or to support additional gateway processors that share a protocol format (such as additional Authorize.net compatible gateways). Please note that the proper "http://" or "https://" formatting must be observed. See "Testing Information" in the Table of Contents for a list of test URLs.

Data Type

String

InvoiceNumber Property (Retail Class)

Merchant-generated invoice number.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetInvoiceNumber();
int SetInvoiceNumber(const char* lpszInvoiceNumber);

Unicode (Windows)
LPWSTR GetInvoiceNumber();
INT SetInvoiceNumber(LPCWSTR lpszInvoiceNumber);

char* inpay_retail_getinvoicenumber(void* lpObj);
int inpay_retail_setinvoicenumber(void* lpObj, const char* lpszInvoiceNumber);

QString GetInvoiceNumber();
int SetInvoiceNumber(QString qsInvoiceNumber);

Default Value

""

Remarks

This field contains a merchant-generated invoice number. This number should be unique for each transaction. This property is optional for most gateways, but it is recommended that the merchant use an invoice number to keep track of transactions. See the Gateway property to determine if this is a required or optional field for the gateway you are using.

Data Type

String

Level2Aggregate Property (Retail Class)

The level 2 aggregate containing the data to be sent in the request.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetLevel2Aggregate();
int SetLevel2Aggregate(const char* lpszLevel2Aggregate);

Unicode (Windows)
LPWSTR GetLevel2Aggregate();
INT SetLevel2Aggregate(LPCWSTR lpszLevel2Aggregate);

char* inpay_retail_getlevel2aggregate(void* lpObj);
int inpay_retail_setlevel2aggregate(void* lpObj, const char* lpszLevel2Aggregate);

QString GetLevel2Aggregate();
int SetLevel2Aggregate(QString qsLevel2Aggregate);

Default Value

""

Remarks

This property is used to specify the level 2 aggregate obtained from Level2 class. When specified, the class will parse the aggregate and send the specified values within the transaction request to process the transaction as a level 2 transaction.

Data Type

String

Level3Aggregate Property (Retail Class)

The level 3 aggregate containing the data to be sent in the request.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetLevel3Aggregate();
int SetLevel3Aggregate(const char* lpszLevel3Aggregate);

Unicode (Windows)
LPWSTR GetLevel3Aggregate();
INT SetLevel3Aggregate(LPCWSTR lpszLevel3Aggregate);

char* inpay_retail_getlevel3aggregate(void* lpObj);
int inpay_retail_setlevel3aggregate(void* lpObj, const char* lpszLevel3Aggregate);

QString GetLevel3Aggregate();
int SetLevel3Aggregate(QString qsLevel3Aggregate);

Default Value

""

Remarks

This property is used to specify the level 3 aggregate obtained from Level3 class. When specified, the class will parse the aggregate and send the specified values within the transaction request to process the transaction as a level 3 transaction.

Data Type

String

MerchantLogin Property (Retail Class)

Merchant's Gateway login.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetMerchantLogin();
int SetMerchantLogin(const char* lpszMerchantLogin);

Unicode (Windows)
LPWSTR GetMerchantLogin();
INT SetMerchantLogin(LPCWSTR lpszMerchantLogin);

char* inpay_retail_getmerchantlogin(void* lpObj);
int inpay_retail_setmerchantlogin(void* lpObj, const char* lpszMerchantLogin);

QString GetMerchantLogin();
int SetMerchantLogin(QString qsMerchantLogin);

Default Value

""

Remarks

This is the login Id supplied by the Gateway you signed up with to process credit card transactions.

Data Type

String

MerchantPassword Property (Retail Class)

Merchant's Gateway password.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetMerchantPassword();
int SetMerchantPassword(const char* lpszMerchantPassword);

Unicode (Windows)
LPWSTR GetMerchantPassword();
INT SetMerchantPassword(LPCWSTR lpszMerchantPassword);

char* inpay_retail_getmerchantpassword(void* lpObj);
int inpay_retail_setmerchantpassword(void* lpObj, const char* lpszMerchantPassword);

QString GetMerchantPassword();
int SetMerchantPassword(QString qsMerchantPassword);

Default Value

""

Remarks

This is the password supplied by the Gateway you signed up with to process credit card transactions. Some gateways require passwords only for Credit or Void transactions, some require it for all transactions, and some do not require this field at all.

Data Type

String

Proxy Property (Retail Class)

A set of properties related to proxy access.

Syntax

• C++
• C
• Qt

InPayProxy* GetProxy();
int SetProxy(InPayProxy* val);

int inpay_retail_getproxyauthscheme(void* lpObj);
int inpay_retail_setproxyauthscheme(void* lpObj, int iProxyAuthScheme);

int inpay_retail_getproxyautodetect(void* lpObj);
int inpay_retail_setproxyautodetect(void* lpObj, int bProxyAutoDetect);

char* inpay_retail_getproxypassword(void* lpObj);
int inpay_retail_setproxypassword(void* lpObj, const char* lpszProxyPassword);

int inpay_retail_getproxyport(void* lpObj);
int inpay_retail_setproxyport(void* lpObj, int iProxyPort);

char* inpay_retail_getproxyserver(void* lpObj);
int inpay_retail_setproxyserver(void* lpObj, const char* lpszProxyServer);

int inpay_retail_getproxyssl(void* lpObj);
int inpay_retail_setproxyssl(void* lpObj, int iProxySSL);

char* inpay_retail_getproxyuser(void* lpObj);
int inpay_retail_setproxyuser(void* lpObj, const char* lpszProxyUser);

int GetProxyAuthScheme();
int SetProxyAuthScheme(int iProxyAuthScheme);

bool GetProxyAutoDetect();
int SetProxyAutoDetect(bool bProxyAutoDetect);

QString GetProxyPassword();
int SetProxyPassword(QString qsProxyPassword);

int GetProxyPort();
int SetProxyPort(int iProxyPort);

QString GetProxyServer();
int SetProxyServer(QString qsProxyServer);

int GetProxySSL();
int SetProxySSL(int iProxySSL);

QString GetProxyUser();
int SetProxyUser(QString qsProxyUser);

Remarks

This property contains fields describing the proxy through which the class will attempt to connect.

Data Type

InPayProxy

Response Property (Retail Class)

Contains the response to the authorization.

Syntax

• C++
• C
• Qt

InPayEPResponse* GetResponse();

char* inpay_retail_getresponseapprovalcode(void* lpObj);

int inpay_retail_getresponseapproved(void* lpObj);

char* inpay_retail_getresponseapprovedamount(void* lpObj);

char* inpay_retail_getresponseavsresult(void* lpObj);

char* inpay_retail_getresponsecode(void* lpObj);

char* inpay_retail_getresponsecvvresult(void* lpObj);

char* inpay_retail_getresponsedata(void* lpObj);

char* inpay_retail_getresponseerrorcode(void* lpObj);

char* inpay_retail_getresponseerrortext(void* lpObj);

char* inpay_retail_getresponseinvoicenumber(void* lpObj);

char* inpay_retail_getresponseprocessorcode(void* lpObj);

char* inpay_retail_getresponsetext(void* lpObj);

char* inpay_retail_getresponsetransactionid(void* lpObj);

QString GetResponseApprovalCode();

bool GetResponseApproved();

QString GetResponseApprovedAmount();

QString GetResponseAVSResult();

QString GetResponseCode();

QString GetResponseCVVResult();

QString GetResponseData();

QString GetResponseErrorCode();

QString GetResponseErrorText();

QString GetResponseInvoiceNumber();

QString GetResponseProcessorCode();

QString GetResponseText();

QString GetResponseTransactionId();

Remarks

This property will contain the response returned from the Gateway server. It should be inspected (and logged) after a call to AuthOnly, Sale, Capture, Credit, Force, or VoidTransaction. The EPResponse type contains the following fields:

Note that many gateways do not return values in all of these fields. Any field in the Data which has not been parsed into these Response fields may be retrieved with the GetResponseVar method.

This property is read-only and not available at design time.

Data Type

InPayEPResponse

ShippingInfo Property (Retail Class)

Contains the customer's shipping name, address, and other identifying information.

Syntax

• C++
• C
• Qt

InPayEPShipInfo* GetShippingInfo();
int SetShippingInfo(InPayEPShipInfo* val);

char* inpay_retail_getshippingaddress(void* lpObj);
int inpay_retail_setshippingaddress(void* lpObj, const char* lpszShippingAddress);

char* inpay_retail_getshippingaddress2(void* lpObj);
int inpay_retail_setshippingaddress2(void* lpObj, const char* lpszShippingAddress2);

char* inpay_retail_getshippingcity(void* lpObj);
int inpay_retail_setshippingcity(void* lpObj, const char* lpszShippingCity);

char* inpay_retail_getshippingcountry(void* lpObj);
int inpay_retail_setshippingcountry(void* lpObj, const char* lpszShippingCountry);

char* inpay_retail_getshippingemail(void* lpObj);
int inpay_retail_setshippingemail(void* lpObj, const char* lpszShippingEmail);

char* inpay_retail_getshippingfirstname(void* lpObj);
int inpay_retail_setshippingfirstname(void* lpObj, const char* lpszShippingFirstName);

char* inpay_retail_getshippinglastname(void* lpObj);
int inpay_retail_setshippinglastname(void* lpObj, const char* lpszShippingLastName);

char* inpay_retail_getshippingphone(void* lpObj);
int inpay_retail_setshippingphone(void* lpObj, const char* lpszShippingPhone);

char* inpay_retail_getshippingstate(void* lpObj);
int inpay_retail_setshippingstate(void* lpObj, const char* lpszShippingState);

char* inpay_retail_getshippingzip(void* lpObj);
int inpay_retail_setshippingzip(void* lpObj, const char* lpszShippingZip);

QString GetShippingAddress();
int SetShippingAddress(QString qsShippingAddress);

QString GetShippingAddress2();
int SetShippingAddress2(QString qsShippingAddress2);

QString GetShippingCity();
int SetShippingCity(QString qsShippingCity);

QString GetShippingCountry();
int SetShippingCountry(QString qsShippingCountry);

QString GetShippingEmail();
int SetShippingEmail(QString qsShippingEmail);

QString GetShippingFirstName();
int SetShippingFirstName(QString qsShippingFirstName);

QString GetShippingLastName();
int SetShippingLastName(QString qsShippingLastName);

QString GetShippingPhone();
int SetShippingPhone(QString qsShippingPhone);

QString GetShippingState();
int SetShippingState(QString qsShippingState);

QString GetShippingZip();
int SetShippingZip(QString qsShippingZip);

Remarks

This property must be set to an instance of the EPShipInfo type, which will contain information that specifies the shipping information for the order. See the EPShipInfo type for more information.

This property is not available at design time.

Data Type

InPayEPShipInfo

SpecialFields Property (Retail 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_retail_getspecialfieldcount(void* lpObj);
int inpay_retail_setspecialfieldcount(void* lpObj, int iSpecialFieldCount);

char* inpay_retail_getspecialfieldname(void* lpObj, int fieldindex);
int inpay_retail_setspecialfieldname(void* lpObj, int fieldindex, const char* lpszSpecialFieldName);

char* inpay_retail_getspecialfieldvalue(void* lpObj, int fieldindex);
int inpay_retail_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

SSLAcceptServerCert Property (Retail Class)

Instructs the class to unconditionally accept the server certificate that matches the supplied certificate.

Syntax

• C++
• C
• Qt

InPayCertificate* GetSSLAcceptServerCert();
int SetSSLAcceptServerCert(InPayCertificate* val);

char* inpay_retail_getsslacceptservercerteffectivedate(void* lpObj);

char* inpay_retail_getsslacceptservercertexpirationdate(void* lpObj);

char* inpay_retail_getsslacceptservercertextendedkeyusage(void* lpObj);

char* inpay_retail_getsslacceptservercertfingerprint(void* lpObj);

char* inpay_retail_getsslacceptservercertfingerprintsha1(void* lpObj);

char* inpay_retail_getsslacceptservercertfingerprintsha256(void* lpObj);

char* inpay_retail_getsslacceptservercertissuer(void* lpObj);

char* inpay_retail_getsslacceptservercertprivatekey(void* lpObj);

int inpay_retail_getsslacceptservercertprivatekeyavailable(void* lpObj);

char* inpay_retail_getsslacceptservercertprivatekeycontainer(void* lpObj);

char* inpay_retail_getsslacceptservercertpublickey(void* lpObj);

char* inpay_retail_getsslacceptservercertpublickeyalgorithm(void* lpObj);

int inpay_retail_getsslacceptservercertpublickeylength(void* lpObj);

char* inpay_retail_getsslacceptservercertserialnumber(void* lpObj);

char* inpay_retail_getsslacceptservercertsignaturealgorithm(void* lpObj);

int inpay_retail_getsslacceptservercertstore(void* lpObj, char** lpSSLAcceptServerCertStore, int* lenSSLAcceptServerCertStore);
int inpay_retail_setsslacceptservercertstore(void* lpObj, const char* lpSSLAcceptServerCertStore, int lenSSLAcceptServerCertStore);

char* inpay_retail_getsslacceptservercertstorepassword(void* lpObj);
int inpay_retail_setsslacceptservercertstorepassword(void* lpObj, const char* lpszSSLAcceptServerCertStorePassword);

int inpay_retail_getsslacceptservercertstoretype(void* lpObj);
int inpay_retail_setsslacceptservercertstoretype(void* lpObj, int iSSLAcceptServerCertStoreType);

char* inpay_retail_getsslacceptservercertsubjectaltnames(void* lpObj);

char* inpay_retail_getsslacceptservercertthumbprintmd5(void* lpObj);

char* inpay_retail_getsslacceptservercertthumbprintsha1(void* lpObj);

char* inpay_retail_getsslacceptservercertthumbprintsha256(void* lpObj);

char* inpay_retail_getsslacceptservercertusage(void* lpObj);

int inpay_retail_getsslacceptservercertusageflags(void* lpObj);

char* inpay_retail_getsslacceptservercertversion(void* lpObj);

char* inpay_retail_getsslacceptservercertsubject(void* lpObj);
int inpay_retail_setsslacceptservercertsubject(void* lpObj, const char* lpszSSLAcceptServerCertSubject);

int inpay_retail_getsslacceptservercertencoded(void* lpObj, char** lpSSLAcceptServerCertEncoded, int* lenSSLAcceptServerCertEncoded);
int inpay_retail_setsslacceptservercertencoded(void* lpObj, const char* lpSSLAcceptServerCertEncoded, int lenSSLAcceptServerCertEncoded);

QString GetSSLAcceptServerCertEffectiveDate();

QString GetSSLAcceptServerCertExpirationDate();

QString GetSSLAcceptServerCertExtendedKeyUsage();

QString GetSSLAcceptServerCertFingerprint();

QString GetSSLAcceptServerCertFingerprintSHA1();

QString GetSSLAcceptServerCertFingerprintSHA256();

QString GetSSLAcceptServerCertIssuer();

QString GetSSLAcceptServerCertPrivateKey();

bool GetSSLAcceptServerCertPrivateKeyAvailable();

QString GetSSLAcceptServerCertPrivateKeyContainer();

QString GetSSLAcceptServerCertPublicKey();

QString GetSSLAcceptServerCertPublicKeyAlgorithm();

int GetSSLAcceptServerCertPublicKeyLength();

QString GetSSLAcceptServerCertSerialNumber();

QString GetSSLAcceptServerCertSignatureAlgorithm();

QByteArray GetSSLAcceptServerCertStore();
int SetSSLAcceptServerCertStore(QByteArray qbaSSLAcceptServerCertStore);

QString GetSSLAcceptServerCertStorePassword();
int SetSSLAcceptServerCertStorePassword(QString qsSSLAcceptServerCertStorePassword);

int GetSSLAcceptServerCertStoreType();
int SetSSLAcceptServerCertStoreType(int iSSLAcceptServerCertStoreType);

QString GetSSLAcceptServerCertSubjectAltNames();

QString GetSSLAcceptServerCertThumbprintMD5();

QString GetSSLAcceptServerCertThumbprintSHA1();

QString GetSSLAcceptServerCertThumbprintSHA256();

QString GetSSLAcceptServerCertUsage();

int GetSSLAcceptServerCertUsageFlags();

QString GetSSLAcceptServerCertVersion();

QString GetSSLAcceptServerCertSubject();
int SetSSLAcceptServerCertSubject(QString qsSSLAcceptServerCertSubject);

QByteArray GetSSLAcceptServerCertEncoded();
int SetSSLAcceptServerCertEncoded(QByteArray qbaSSLAcceptServerCertEncoded);

Remarks

If it finds any issues with the certificate presented by the server, the class will normally terminate the connection with an error.

You may override this behavior by supplying a value for SSLAcceptServerCert. If the certificate supplied in SSLAcceptServerCert is the same as the certificate presented by the server, then the server certificate is accepted unconditionally, and the connection will continue normally.

Note: This functionality is provided only for cases in which you otherwise know that you are communicating with the right server. If used improperly, this property may create a security breach. Use it at your own risk.

Data Type

InPayCertificate

SSLCert Property (Retail Class)

The certificate to be used during Secure Sockets Layer (SSL) negotiation.

Syntax

• C++
• C
• Qt

InPayCertificate* GetSSLCert();
int SetSSLCert(InPayCertificate* val);

char* inpay_retail_getsslcerteffectivedate(void* lpObj);

char* inpay_retail_getsslcertexpirationdate(void* lpObj);

char* inpay_retail_getsslcertextendedkeyusage(void* lpObj);

char* inpay_retail_getsslcertfingerprint(void* lpObj);

char* inpay_retail_getsslcertfingerprintsha1(void* lpObj);

char* inpay_retail_getsslcertfingerprintsha256(void* lpObj);

char* inpay_retail_getsslcertissuer(void* lpObj);

char* inpay_retail_getsslcertprivatekey(void* lpObj);

int inpay_retail_getsslcertprivatekeyavailable(void* lpObj);

char* inpay_retail_getsslcertprivatekeycontainer(void* lpObj);

char* inpay_retail_getsslcertpublickey(void* lpObj);

char* inpay_retail_getsslcertpublickeyalgorithm(void* lpObj);

int inpay_retail_getsslcertpublickeylength(void* lpObj);

char* inpay_retail_getsslcertserialnumber(void* lpObj);

char* inpay_retail_getsslcertsignaturealgorithm(void* lpObj);

int inpay_retail_getsslcertstore(void* lpObj, char** lpSSLCertStore, int* lenSSLCertStore);
int inpay_retail_setsslcertstore(void* lpObj, const char* lpSSLCertStore, int lenSSLCertStore);

char* inpay_retail_getsslcertstorepassword(void* lpObj);
int inpay_retail_setsslcertstorepassword(void* lpObj, const char* lpszSSLCertStorePassword);

int inpay_retail_getsslcertstoretype(void* lpObj);
int inpay_retail_setsslcertstoretype(void* lpObj, int iSSLCertStoreType);

char* inpay_retail_getsslcertsubjectaltnames(void* lpObj);

char* inpay_retail_getsslcertthumbprintmd5(void* lpObj);

char* inpay_retail_getsslcertthumbprintsha1(void* lpObj);

char* inpay_retail_getsslcertthumbprintsha256(void* lpObj);

char* inpay_retail_getsslcertusage(void* lpObj);

int inpay_retail_getsslcertusageflags(void* lpObj);

char* inpay_retail_getsslcertversion(void* lpObj);

char* inpay_retail_getsslcertsubject(void* lpObj);
int inpay_retail_setsslcertsubject(void* lpObj, const char* lpszSSLCertSubject);

int inpay_retail_getsslcertencoded(void* lpObj, char** lpSSLCertEncoded, int* lenSSLCertEncoded);
int inpay_retail_setsslcertencoded(void* lpObj, const char* lpSSLCertEncoded, int lenSSLCertEncoded);

QString GetSSLCertEffectiveDate();

QString GetSSLCertExpirationDate();

QString GetSSLCertExtendedKeyUsage();

QString GetSSLCertFingerprint();

QString GetSSLCertFingerprintSHA1();

QString GetSSLCertFingerprintSHA256();

QString GetSSLCertIssuer();

QString GetSSLCertPrivateKey();

bool GetSSLCertPrivateKeyAvailable();

QString GetSSLCertPrivateKeyContainer();

QString GetSSLCertPublicKey();

QString GetSSLCertPublicKeyAlgorithm();

int GetSSLCertPublicKeyLength();

QString GetSSLCertSerialNumber();

QString GetSSLCertSignatureAlgorithm();

QByteArray GetSSLCertStore();
int SetSSLCertStore(QByteArray qbaSSLCertStore);

QString GetSSLCertStorePassword();
int SetSSLCertStorePassword(QString qsSSLCertStorePassword);

int GetSSLCertStoreType();
int SetSSLCertStoreType(int iSSLCertStoreType);

QString GetSSLCertSubjectAltNames();

QString GetSSLCertThumbprintMD5();

QString GetSSLCertThumbprintSHA1();

QString GetSSLCertThumbprintSHA256();

QString GetSSLCertUsage();

int GetSSLCertUsageFlags();

QString GetSSLCertVersion();

QString GetSSLCertSubject();
int SetSSLCertSubject(QString qsSSLCertSubject);

QByteArray GetSSLCertEncoded();
int SetSSLCertEncoded(QByteArray qbaSSLCertEncoded);

Remarks

This property includes the digital certificate that the class will use during SSL negotiation. Set this property to a valid certificate before starting SSL negotiation. To set a certificate, you may set the Encoded field to the encoded certificate. To select a certificate, use the store and subject fields.

Data Type

InPayCertificate

SSLProvider Property (Retail Class)

The Secure Sockets Layer/Transport Layer Security (SSL/TLS) implementation to use.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSSLProvider();
int SetSSLProvider(int iSSLProvider);

Unicode (Windows)
INT GetSSLProvider();
INT SetSSLProvider(INT iSSLProvider);

SSLP_AUTOMATIC(0), 
SSLP_PLATFORM(1), 
SSLP_INTERNAL(2)

int inpay_retail_getsslprovider(void* lpObj);
int inpay_retail_setsslprovider(void* lpObj, int iSSLProvider);

int GetSSLProvider();
int SetSSLProvider(int iSSLProvider);

Default Value

0

Remarks

This property specifies the SSL/TLS implementation to use. In most cases the default value of 0 (Automatic) is recommended and should not be changed. When set to 0 (Automatic), the class will select whether to use the platform implementation or the internal implementation depending on the operating system as well as the TLS version being used.

Possible values are as follows:

In most cases using the default value (Automatic) is recommended. The class will select a provider depending on the current platform.

When Automatic is selected, on Windows, the class will use the platform implementation. On Linux/macOS, the class will use the internal implementation. When TLS 1.3 is enabled via SSLEnabledProtocols, the internal implementation is used on all platforms.

Data Type

Integer

SSLServerCert Property (Retail Class)

The server certificate for the last established connection.

Syntax

• C++
• C
• Qt

InPayCertificate* GetSSLServerCert();

char* inpay_retail_getsslservercerteffectivedate(void* lpObj);

char* inpay_retail_getsslservercertexpirationdate(void* lpObj);

char* inpay_retail_getsslservercertextendedkeyusage(void* lpObj);

char* inpay_retail_getsslservercertfingerprint(void* lpObj);

char* inpay_retail_getsslservercertfingerprintsha1(void* lpObj);

char* inpay_retail_getsslservercertfingerprintsha256(void* lpObj);

char* inpay_retail_getsslservercertissuer(void* lpObj);

char* inpay_retail_getsslservercertprivatekey(void* lpObj);

int inpay_retail_getsslservercertprivatekeyavailable(void* lpObj);

char* inpay_retail_getsslservercertprivatekeycontainer(void* lpObj);

char* inpay_retail_getsslservercertpublickey(void* lpObj);

char* inpay_retail_getsslservercertpublickeyalgorithm(void* lpObj);

int inpay_retail_getsslservercertpublickeylength(void* lpObj);

char* inpay_retail_getsslservercertserialnumber(void* lpObj);

char* inpay_retail_getsslservercertsignaturealgorithm(void* lpObj);

int inpay_retail_getsslservercertstore(void* lpObj, char** lpSSLServerCertStore, int* lenSSLServerCertStore);

char* inpay_retail_getsslservercertstorepassword(void* lpObj);

int inpay_retail_getsslservercertstoretype(void* lpObj);

char* inpay_retail_getsslservercertsubjectaltnames(void* lpObj);

char* inpay_retail_getsslservercertthumbprintmd5(void* lpObj);

char* inpay_retail_getsslservercertthumbprintsha1(void* lpObj);

char* inpay_retail_getsslservercertthumbprintsha256(void* lpObj);

char* inpay_retail_getsslservercertusage(void* lpObj);

int inpay_retail_getsslservercertusageflags(void* lpObj);

char* inpay_retail_getsslservercertversion(void* lpObj);

char* inpay_retail_getsslservercertsubject(void* lpObj);

int inpay_retail_getsslservercertencoded(void* lpObj, char** lpSSLServerCertEncoded, int* lenSSLServerCertEncoded);

QString GetSSLServerCertEffectiveDate();

QString GetSSLServerCertExpirationDate();

QString GetSSLServerCertExtendedKeyUsage();

QString GetSSLServerCertFingerprint();

QString GetSSLServerCertFingerprintSHA1();

QString GetSSLServerCertFingerprintSHA256();

QString GetSSLServerCertIssuer();

QString GetSSLServerCertPrivateKey();

bool GetSSLServerCertPrivateKeyAvailable();

QString GetSSLServerCertPrivateKeyContainer();

QString GetSSLServerCertPublicKey();

QString GetSSLServerCertPublicKeyAlgorithm();

int GetSSLServerCertPublicKeyLength();

QString GetSSLServerCertSerialNumber();

QString GetSSLServerCertSignatureAlgorithm();

QByteArray GetSSLServerCertStore();

QString GetSSLServerCertStorePassword();

int GetSSLServerCertStoreType();

QString GetSSLServerCertSubjectAltNames();

QString GetSSLServerCertThumbprintMD5();

QString GetSSLServerCertThumbprintSHA1();

QString GetSSLServerCertThumbprintSHA256();

QString GetSSLServerCertUsage();

int GetSSLServerCertUsageFlags();

QString GetSSLServerCertVersion();

QString GetSSLServerCertSubject();

QByteArray GetSSLServerCertEncoded();

Remarks

This property contains the server certificate for the last established connection.

SSLServerCert is reset every time a new connection is attempted.

This property is read-only.

Data Type

InPayCertificate

TestMode Property (Retail Class)

Turns test mode on and off for transactions sent to the current Gateway .

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetTestMode();
int SetTestMode(int bTestMode);

Unicode (Windows)
BOOL GetTestMode();
INT SetTestMode(BOOL bTestMode);

int inpay_retail_gettestmode(void* lpObj);
int inpay_retail_settestmode(void* lpObj, int bTestMode);

bool GetTestMode();
int SetTestMode(bool bTestMode);

Default Value

FALSE

Remarks

You can use this property to set a test mode flag that will be sent in an authorization request. Not all Gateways support test modes. If you set the TestMode property to True and the current Gateway does not support it, the class will fails with an error.

Data Type

Boolean

Timeout Property (Retail Class)

A timeout for the class.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetTimeout();
int SetTimeout(int iTimeout);

Unicode (Windows)
INT GetTimeout();
INT SetTimeout(INT iTimeout);

int inpay_retail_gettimeout(void* lpObj);
int inpay_retail_settimeout(void* lpObj, int iTimeout);

int GetTimeout();
int SetTimeout(int iTimeout);

Default Value

30

Remarks

If Timeout is set to a positive value, and an operation cannot be completed immediately, the class will retry the operation for a maximum of Timeout seconds.

The default value for Timeout is 30 (seconds).

Data Type

Integer

TransactionAmount Property (Retail Class)

Purchase amount for an authorization transaction.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetTransactionAmount();
int SetTransactionAmount(const char* lpszTransactionAmount);

Unicode (Windows)
LPWSTR GetTransactionAmount();
INT SetTransactionAmount(LPCWSTR lpszTransactionAmount);

char* inpay_retail_gettransactionamount(void* lpObj);
int inpay_retail_settransactionamount(void* lpObj, const char* lpszTransactionAmount);

QString GetTransactionAmount();
int SetTransactionAmount(QString qsTransactionAmount);

Default Value

""

Remarks

This field contains the transaction amount to be authorized. Gateways may have differing requirements for how the TransactionAmount should be formatted, so refer to the ICharge Gateway Setup page for details on the gateway you are using.

Data Type

String

TransactionDesc Property (Retail Class)

Description of goods purchased.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetTransactionDesc();
int SetTransactionDesc(const char* lpszTransactionDesc);

Unicode (Windows)
LPWSTR GetTransactionDesc();
INT SetTransactionDesc(LPCWSTR lpszTransactionDesc);

char* inpay_retail_gettransactiondesc(void* lpObj);
int inpay_retail_settransactiondesc(void* lpObj, const char* lpszTransactionDesc);

QString GetTransactionDesc();
int SetTransactionDesc(QString qsTransactionDesc);

Default Value

""

Remarks

This field contains a description of the goods or services being purchased. Please see the "ICharge Gateway Setup and Required Properties" page to determine if this is a required or optional field for the gateway you are using.

Data Type

String

TransactionId Property (Retail Class)

Merchant-generated transaction Id used for all transactions.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetTransactionId();
int SetTransactionId(const char* lpszTransactionId);

Unicode (Windows)
LPWSTR GetTransactionId();
INT SetTransactionId(LPCWSTR lpszTransactionId);

char* inpay_retail_gettransactionid(void* lpObj);
int inpay_retail_settransactionid(void* lpObj, const char* lpszTransactionId);

QString GetTransactionId();
int SetTransactionId(QString qsTransactionId);

Default Value

""

Remarks

This property is used to send a merchant-generated transaction id to the Gateway, if the gateway supports that feature.

Data Type

String

AddSpecialField Method (Retail 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_retail_addspecialfield(void* lpObj, const char* lpszName, const char* lpszValue);

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

Remarks

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.)

AuthOnly Method (Retail Class)

Initiates an authorization-only request transaction.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int AuthOnly();

Unicode (Windows)
INT AuthOnly();

int inpay_retail_authonly(void* lpObj);

int AuthOnly();

Remarks

This method sends an authorization-only request to the specified Gateway. This transaction is not added to the current open batch, and must be completed later with the Capture method (you may use the Sale method if you wish to authorize and capture in one step).

Note: If the Gateway does not support this method, the class will fails with an error.

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.)

AVSOnly Method (Retail Class)

Used to check the validity of the card without authorizing funds.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int AVSOnly();

Unicode (Windows)
INT AVSOnly();

int inpay_retail_avsonly(void* lpObj);

int AVSOnly();

Remarks

This method can be used if you wish to perform fraud (AVS and CVV) checks on a card, but don't actually wish to charge the customer. This is useful for pre-ordering an item that has not yet been released or is currently back- ordered. The card information is validated by the merchant, and when the item is later in stock and ships to the customer, an Sale transaction can be performed.

Note: If the Gateway does not support this method, the class will fails with an error.

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.)

Capture Method (Retail Class)

Captures a previously authorized transaction.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Capture(const char* lpszTransactionId, const char* lpszCaptureAmount);

Unicode (Windows)
INT Capture(LPCWSTR lpszTransactionId, LPCWSTR lpszCaptureAmount);

int inpay_retail_capture(void* lpObj, const char* lpszTransactionId, const char* lpszCaptureAmount);

int Capture(const QString& qsTransactionId, const QString& qsCaptureAmount);

Remarks

This method captures a transaction that has been previously authorized with the AuthOnly method. The TransactionId parameter indicates to the Gateway which transaction is to be captured, and should contain the TransactionId from the original transaction. The CaptureAmount parameter is the value to be captured from the customer's credit card, and can be different from the authorized amount.

Please see the gateway information in the table of contents to determine if your gateway supports Capture transactions.

The LinkPoint and PSIGateXML gateways require you send the InvoiceNumber rather than the TransactionId.

The SecurePay gateway does not require the TransactionId for captures. Instead, you must send the ApprovalCode returned from the original response in the AuthCode property.

The MyVirtualMerchant and Converge gateways do not require the TransactionId for captures. Instead, you must send the ApprovalCode returned from the original response in the AuthCode property. Note that there is a new capture transaction type available for these gateways. To use the new transaction type, set the MyVirtualMerchantTransactionType to "CCCOMPLETE" and call Capture like normal. When using this transaction type, TransactionId is required and ApprovalCode is not applicable.

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 (Retail 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_retail_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.

Credit Method (Retail Class)

Credits a customer's card.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Credit();

Unicode (Windows)
INT Credit();

int inpay_retail_credit(void* lpObj);

int Credit();

Remarks

This method credits a customer's card specified via Card. This type of transaction is NOT based on previous transaction. Some gateways refer to these as "Open" or "Blind" Credits.

TransactionAmount is used to specify the amount you wish to return to the customer's card.

Please see the gateway information in the table of contents to determine if your gateway supports Credit transactions.

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.)

DoEvents Method (Retail Class)

This method processes events from the internal message queue.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DoEvents();

Unicode (Windows)
INT DoEvents();

int inpay_retail_doevents(void* lpObj);

int DoEvents();

Remarks

When DoEvents is called, the class processes any available events. If no events are available, it waits for a preset period of time, and then returns.

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.)

Force Method (Retail Class)

Used when authorization cannot be obtained online.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Force(const char* lpszVoiceAuthCode);

Unicode (Windows)
INT Force(LPCWSTR lpszVoiceAuthCode);

int inpay_retail_force(void* lpObj, const char* lpszVoiceAuthCode);

int Force(const QString& qsVoiceAuthCode);

Remarks

This method is used when the response to a Sale or AuthOnly request indicates that voice authorization is required. The merchant then telephones the call center and receives a voice authorization code. Calling the Force method with this code in the VoiceAuthCode parameter will complete the transaction.

Note: If the Gateway does not support this method, the class will fails with an error.

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.)

GetResponseVar Method (Retail Class)

Parses additional information out of the response.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetResponseVar(const char* lpszName);

Unicode (Windows)
LPWSTR GetResponseVar(LPCWSTR lpszName);

char* inpay_retail_getresponsevar(void* lpObj, const char* lpszName);

QString GetResponseVar(const QString& qsName);

Remarks

Due to the fact that this class supports so many gateways, only the most commonly used response variables are parsed into the Response fields. Any additional response information contained within the Data may be retrieved with this GetResponseVar method. There are three formats for the Data returned by the gateways this class supports: Name/value pairs, delimited list, or XML. The value you pass in the Name parameter changes based on these formats, as detailed below:

If the Data field contains name/value pairs, pass the name in the Name parameter and this method will return the value. For instance, if Data contains "ResponseCode=00&FraudScore=53&ApprovalCode=123456&...", calling GetResponseVar("FraudScore") will return "53".

However, if Data contains a delimited list, pass the index of the field you wish to receive. For instance, if Data contains "00|53|123456|...", calling GetResponseVar("1") will return "53".

Finally, if Data contains XML, pass the xpath to the value you wish to receive. For instance, if Data contains "<Response><Code>00</Code><FraudScore>53</FraudScore><ApprovalCode>123456</ApprovalCode></Response>", calling GetResponseVar("/Response/FraudScore") will return "53".

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.

Interrupt Method (Retail Class)

Interrupts the current action.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Interrupt();

Unicode (Windows)
INT Interrupt();

int inpay_retail_interrupt(void* lpObj);

int Interrupt();

Remarks

This method interrupts any processing that the class is currently executing.

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.)

Refund Method (Retail Class)

Refunds a previously captured transaction.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Refund(const char* lpszTransactionId, const char* lpszRefundAmount);

Unicode (Windows)
INT Refund(LPCWSTR lpszTransactionId, LPCWSTR lpszRefundAmount);

int inpay_retail_refund(void* lpObj, const char* lpszTransactionId, const char* lpszRefundAmount);

int Refund(const QString& qsTransactionId, const QString& qsRefundAmount);

Remarks

This method refunds a transaction that has already been captured, or settled. If the transaction is still outstanding use the VoidTransaction method instead. The TransactionId parameter indicates to the Gateway which transaction is to be refunded, and should contain the TransactionId from the original transaction. The RefundAmount parameter is the value to be refunded back to the customer, and can be all or part of the original TransactionAmount

Please see the gateway information in the table of contents to determine if your gateway supports Refund transactions.

The gw3DSI gateway requires the following additional fields for Refund transactions:

class.AddSpecialField "UserId", "my 3DSI-assigned UserId" '(Different than MerchantLogin) class.MerchantPassword = "my 3DSI-assigned Pwd"

The LinkPoint and PSIGateXML gateways require you send the InvoiceNumber rather than the TransactionId.

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.)

Reset Method (Retail Class)

Clears all properties to their default values.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Reset();

Unicode (Windows)
INT Reset();

int inpay_retail_reset(void* lpObj);

int Reset();

Remarks

This method clears all properties to their default values and returns the component to its default state.

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.)

ResetSpecialFields Method (Retail Class)

Resets all special fields to the default settings.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ResetSpecialFields();

Unicode (Windows)
INT ResetSpecialFields();

int inpay_retail_resetspecialfields(void* lpObj);

int ResetSpecialFields();

Remarks

This function resets all special gateway configuration fields to the default settings for the specified Gateway.

Please refer to the Name and Value properties 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.)

Sale Method (Retail Class)

Initiates an Sale transaction (authorization and capture).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Sale();

Unicode (Windows)
INT Sale();

int inpay_retail_sale(void* lpObj);

int Sale();

Remarks

Sends a basic sale transaction to the Gateway. This transaction decrements the cardholder's open-to-buy funds for the TransactionAmount, and the transaction is automatically added to the current open batch.

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.)

VoidTransaction Method (Retail Class)

Voids a previously authorized transaction.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int VoidTransaction(const char* lpszTransactionId);

Unicode (Windows)
INT VoidTransaction(LPCWSTR lpszTransactionId);

int inpay_retail_voidtransaction(void* lpObj, const char* lpszTransactionId);

int VoidTransaction(const QString& qsTransactionId);

Remarks

This method voids a transaction that has been previously authorized, but which has not yet gone to settlement, or been "captured". The TransactionId parameter indicates to the Gateway which transaction is to be voided, and should contain the TransactionId from the original transaction.

Please see the gateway information in the table of contents to determine if your gateway supports Void transactions.

To cancel a transaction which has already been captured, use the Credit method.

The LinkPoint gateway requires you send the InvoiceNumber rather than the TransactionId.

For the PSIGateXML gateway, send the TransactionId as normal.

For the Heartland gateway, a reversal transaction will be sent when a TransactionAmount is specified. Otherwise a void transaction will be sent.

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.)

Error Event (Retail Class)

Information about errors during data delivery.

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_RETAIL_ERROR 1

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

class RetailErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

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

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

// Or, subclass Retail and override this emitter function.
virtual int FireError(RetailErrorEventParams *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.

SSLServerAuthentication Event (Retail Class)

Fired after the server presents its certificate to the client.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireSSLServerAuthentication(RetailSSLServerAuthenticationEventParams *e);

typedef struct {
  const char *CertEncoded;
  int lenCertEncoded;
  const char *CertSubject;
  const char *CertIssuer;
  const char *Status;
  int Accept;
  int reserved;
} RetailSSLServerAuthenticationEventParams;


Unicode (Windows)
virtual INT FireSSLServerAuthentication(RetailSSLServerAuthenticationEventParams *e);

typedef struct {
  LPCSTR CertEncoded;
  INT lenCertEncoded;
  LPCWSTR CertSubject;
  LPCWSTR CertIssuer;
  LPCWSTR Status;
  BOOL Accept;
  INT reserved;
} RetailSSLServerAuthenticationEventParams;

#define EID_RETAIL_SSLSERVERAUTHENTICATION 2

virtual INT INPAY_CALL FireSSLServerAuthentication(LPSTR &lpCertEncoded, INT &lenCertEncoded, LPSTR &lpszCertSubject, LPSTR &lpszCertIssuer, LPSTR &lpszStatus, BOOL &bAccept);

class RetailSSLServerAuthenticationEventParams {
public:
  const QByteArray &CertEncoded();

  const QString &CertSubject();

  const QString &CertIssuer();

  const QString &Status();

  bool Accept();
  void SetAccept(bool bAccept);

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

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

// Or, subclass Retail and override this emitter function.
virtual int FireSSLServerAuthentication(RetailSSLServerAuthenticationEventParams *e) {...}

Remarks

During this event, the client can decide whether or not to continue with the connection process. The Accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether or not to continue.

When Accept is False, Status shows why the verification failed (otherwise, Status contains the string OK). If it is decided to continue, you can override and accept the certificate by setting the Accept parameter to True.

SSLStatus Event (Retail Class)

Fired when secure connection progress messages are available.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireSSLStatus(RetailSSLStatusEventParams *e);

typedef struct {
  const char *Message;
  int reserved;
} RetailSSLStatusEventParams;


Unicode (Windows)
virtual INT FireSSLStatus(RetailSSLStatusEventParams *e);

typedef struct {
  LPCWSTR Message;
  INT reserved;
} RetailSSLStatusEventParams;

#define EID_RETAIL_SSLSTATUS 3

virtual INT INPAY_CALL FireSSLStatus(LPSTR &lpszMessage);

class RetailSSLStatusEventParams {
public:
  const QString &Message();

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

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

// Or, subclass Retail and override this emitter function.
virtual int FireSSLStatus(RetailSSLStatusEventParams *e) {...}

Remarks

The event is fired for informational and logging purposes only. This event tracks the progress of the connection.

CCCard Type

Contains the customer's credit card information.

Syntax

InPayCCCard (declared in inpay.h)

Remarks

This type contains the customer's credit card information. If you are processing transactions where the customer and his credit card are physically present, set the MagneticStripe field with the data read from the card reader. You may set either Track1 or Track2 data (but not both). You must also set the EntryDataSource to indicate which track is stored in the MagneticStripe field.

Example: Setting the Fields CCCard card = new CCCard(); card.MagneticStripe = "B4012000033330026^FDMS TEST CARD /VISA^090410054321000000000000000 150 A"; card.EntryDataSource = edsTrack1; Example: Using a Constructor CCCard card = new CCCard("B4012000033330026^FDMS TEST CARD /VISA^090410054321000000000000000 150 A", edsTrack1);

If you are processing a transaction where the credit card is not physically present (eCommerce, mail/order, etc) or if the magstripe on the back of the card cannot be read by the card reader, you must set the Number, ExpMonth, and ExpYear fields, and EntryDataSource must be set to one of the manually entered enumerations.

Example: Setting the Fields CCCard card = new CCCard(); card.Number = "4788250000028291"; card.ExpMonth = 12; card.ExpYear = 2010; card.EntryDataSource = edsManualEntryNoCardReader; Example: Using a Constructor CCCard card = new CCCard("4012000033330026", 04, 2009); Note that the constructor in the previous example automatically sets the EntryDataSource to edsManualEntryNoCardReader. If you wish to set any other value for the EntryDataSource, you must set it yourself before authorizing the transaction.

When authorizing a transaction, the fields used by the class are solely dependant on the value of EntryDataSource. If you set the Number, ExpMonth, and ExpYear fields, but EntryDataSource is set to edsTrack2, the class will look for MagneticStripe data when authorizing the transaction, and will fails with an error because none is present.

• CardType
• CVVData
• CVVPresence
• EntryDataSource
• ExpMonth
• ExpYear
• IsEncrypted
• MagneticStripe
• Number

Fields

Constructors

CCCard()

CCCard(const char* lpszNumber, int iExpMonth, int iExpYear)

CCCard(const char* lpszMagneticStripe, int iEntryDataSource)

Certificate Type

This is the digital certificate being used.

Syntax

InPayCertificate (declared in inpay.h)

Remarks

This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.

• EffectiveDate
• ExpirationDate
• ExtendedKeyUsage
• Fingerprint
• FingerprintSHA1
• FingerprintSHA256
• Issuer
• PrivateKey
• PrivateKeyAvailable
• PrivateKeyContainer
• PublicKey
• PublicKeyAlgorithm
• PublicKeyLength
• SerialNumber
• SignatureAlgorithm
• Store
• StorePassword
• StoreType
• SubjectAltNames
• ThumbprintMD5
• ThumbprintSHA1
• ThumbprintSHA256
• Usage
• UsageFlags
• Version
• Subject
• Encoded

Fields

Constructors

Certificate()

Certificate(const char* lpEncoded, int lenEncoded)

Certificate(int iStoreType, const char* lpStore, int lenStore, const char* lpszStorePassword, const char* lpszSubject)

EPCustomer Type

Contains customer information.

Syntax

InPayEPCustomer (declared in inpay.h)

Remarks

This type contains information about the customer which the merchant has collected. At the minimum, this should include the customer's name and address. You may also optionally include a merchant-generated customer Id, the customer's Email address, Phone number, and Fax number. This type is used by both the ICharge and ECheck classs.

Example: EPCustomer cust = new EPCustomer(); cust.FirstName = "John" cust.LastName = "Smith" cust.FullName = "John M. Smith" cust.Address = "123 Nowhere Ln." cust.City = "Beverly Hills" cust.State = "CA" cust.Zip = "90210" cust.Country = "USA" cust.Phone = "555-555-5555" cust.Email = "jsmith@fake.com" cust.Id = "123456" ICharge1.Customer = cust;

• Address
• Address2
• Aggregate
• City
• Country
• Email
• Fax
• FirstName
• FullName
• Id
• LastName
• Phone
• State
• Zip

Fields

Constructors

EPCustomer()

EPResponse Type

Contains the response to the authorization.

Syntax

InPayEPResponse (declared in inpay.h)

Remarks

This type contains the results of a transaction made with the ICharge, Retail, and ECheck classs. The fields contained by this type are listed below.

• ApprovalCode
• Approved
• ApprovedAmount
• AVSResult
• Code
• CVVResult
• Data
• ErrorCode
• ErrorText
• InvoiceNumber
• ProcessorCode
• Text
• TransactionId

Fields

Constructors

EPResponse()

EPShipInfo Type

Contains shipping information.

Syntax

InPayEPShipInfo (declared in inpay.h)

Remarks

This type contains the shipping information which the merchant has collected. Shipping information is typically optional data. This type is used by the ICharge classs.

Example: EPShipInfo shipInfo = new EPShipInfo(); shipInfo.FirstName = "John" shipInfo.LastName = "Smith" shipInfo.Address = "123 Nowhere Ln." shipInfo.City = "Beverly Hills" shipInfo.State = "CA" shipInfo.Zip = "90210" shipInfo.Country = "USA" shipInfo.Phone = "555-555-5555" ICharge1.ShippingInfo = shipInfo;

• Address
• Address2
• City
• Country
• Email
• FirstName
• LastName
• Phone
• State
• Zip

Fields

Constructors

EPShipInfo()

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)

Proxy Type

The proxy the component will connect to.

Syntax

InPayProxy (declared in inpay.h)

Remarks

When connecting through a proxy, this type is used to specify different properties of the proxy, such as the Server and the AuthScheme.

• AuthScheme
• AutoDetect
• Password
• Port
• Server
• SSL
• User

Fields

Constructors

Proxy()

Proxy(const char* lpszServer, int iPort)

Proxy(const char* lpszServer, int iPort, const char* lpszUser, const char* lpszPassword)

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 Retail class.

int GetCount() {}

int SetCount(int count) {}

T* Get(int index) {}

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

Config Settings (Retail Class)

Retail Config Settings