FDMSSettle Class

Properties   Methods   Events   Config Settings   Errors  

The FDMSSettle class is used to do a Batch Settlement on all transactions that were successfully authorized with the FDMSECOMMERCE or FDMSRETAIL classes. This class may also send Level 2 and Level 3 Corporate Purchasing Card data for better interchange rates.

Syntax

FDMSSettle

Remarks

This class connects to the First Data Merchant Services (FDMS) processor, by way of the Datawire VXN transaction transport network. Transactions originating with these classs go through Datawire, to the FDMS processor where the transaction is authorized. The result is then returned back through Datawire and received by the class. This class can be integrated into web pages or stand-alone Point Of Sale applications. Because all SSL communications are handled inside the class, any application or web page can be deployed without the need for expensive dedicated SSL servers.

The FDMSSettle class is used to settle all transactions previously authorized by the FDMSECommerce or FDMSRetail class. When a transaction is authorized, money in the customer's account is blocked and tagged for the merchant. However, funds do not actually change hands at this point. When transactions are settled with the FDMSSettle class the funds are deducted from the customer's account and added to the merchant's. It is essential that the authorized transactions are properly recorded and resent later in a Batch Settlement.

Sending a Batch Settlement with this class is easy. First, you must register and activate your account with Datawire. Datawire will provide you with a MerchantNumber and MerchantTerminalNumber, but you'll need to use the FDMSRegister class to activate the merchant and receive a DatawireId. Once you acquire the DatawireId and receive your transaction URLs through Service Discovery, you may begin to authorize transactions.

To authorize a credit card, set the MerchantNumber and MerchantTerminalNumber with the values supplied by FDMS and Datawire, and the DatawireId with the value retrieved by the FDMSRegister class after activating your merchant account. Set the URL property with one of the URLs you retrieved during Service Discovery.

FDMSSettle.MerchantNumber = "000000999990" 'Supplied by FDMS/Datawire FDMSSettle.MerchantTerminalNumber = "555555" 'Supplied by FDMS/Datawire FDMSSettle.DatawireId = "0000B47FFFFFFFFFFFFF" 'Retrieved with the FDMSRegister class. FDMSSettle.URL = "https://staging1.datawire.net/sd/"; 'Retrieved with the FDMSRegister class.

Additionally, set the IndustryType and the BatchSequenceNumber.

FDMSSettle.IndustryType = fitDirectMarketing FDMSSettle.BatchSequenceNumber = "4127"

At this point, you are ready to add transactions to the batch settlement. Each transaction to be settled must be added to the DetailRecordAggregate array property. First set the DetailRecordCount to the total number of transactions you wish to settle. Each index in the DetailRecordAggregate array property must be set with the XML aggregate returned from the FDMSRetail, FDMSECommerce, or FDMSDetailRecord class's GetDetailAggregate method.

FDMSSettle.DetailRecordCount = 1 FDMSSettle.DetailRecordAggregate(0) = FDMSECommerce.GetDetailAggregate()

Finally, call the SendSettlement method.

FDMSSettle.SendSettlement()

If the settlement is successful, the ResponseBatchStatus will contain "OK" and the ResponseBatchNumber will contain a number which can be used to identify the batch in the future. If the batch was not successful the class fails with an error that indicates the problem. If any individual record in the batch fails, information concerning that record will appear in the Error event when the response to that particular record is received.

Up to 1000 detail records may be settled in the above manner, just by adding transactions to the DetailRecordAggregate property. However, it is recommended that Batch Settlements be kept relatively small - around 100 transactions or so - to decrease the number of records that must be resent in the event of an error.

To void a transaction that has been authorized but has not yet been settled, simply do not include it in the batch settlement. The block on the cardholder's account will clear automatically. If you wish to explicitly void the transaction, use the FDMSDetailRecord class to modify the transaction aggregate and set the TransactionType property to fttVoid. Credits and forced transactions may also be created using the FDMSDetailRecord class and settled in the same manner as regular transactions.

To add Level 2 and Level 3 data to the settled transactions, use the FDMSLevel2 and FDMSLevel3 classs to create addendum aggregates, and then add them to the DetailRecordAddendum for the corresponding transaction stored in DetailRecordAggregate.

Note that the IndustryType from the FDMSSettle class MUST match the detail record aggregate of EACH transaction that is added to the settlement. You cannot mix industry types in a batch - you must settle a separate batch for each industry type.

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.

ApiVersion Property (FDMSSettle Class)

Identifies the application version number.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetApiVersion();
int SetApiVersion(const char* lpszApiVersion);

Unicode (Windows)
LPWSTR GetApiVersion();
INT SetApiVersion(LPCWSTR lpszApiVersion);

char* dpaymentssdk_fdmssettle_getapiversion(void* lpObj);
int dpaymentssdk_fdmssettle_setapiversion(void* lpObj, const char* lpszApiVersion);

QString GetApiVersion();
int SetApiVersion(QString qsApiVersion);

Default Value

"016XX0"

Remarks

The ApiVersion includes the application's version number and revision number. This field should be 6 characters long and it cannot contain periods or spaces.

The default value of this property is "016XX0" indicating the current version number of 4D Payments SDK.

Data Type

String

ApplicationId Property (FDMSSettle Class)

Identifies the merchant application to the Datawire System.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetApplicationId();
int SetApplicationId(const char* lpszApplicationId);

Unicode (Windows)
LPWSTR GetApplicationId();
INT SetApplicationId(LPCWSTR lpszApplicationId);

char* dpaymentssdk_fdmssettle_getapplicationid(void* lpObj);
int dpaymentssdk_fdmssettle_setapplicationid(void* lpObj, const char* lpszApplicationId);

QString GetApplicationId();
int SetApplicationId(QString qsApplicationId);

Default Value

"NSOFTDIRECTPXML"

Remarks

The Application ID includes the Merchant's application name and version number. This property is used to identify the merchant application within the Datawire system, and may be validated along with the MerchantTerminalNumber and DatawireId as connection credentials.

The default value of this property is assigned to the 4D Payments FDMS Integrator, but you may be required to have a new ApplicationId assigned for the software you create with this class.

Data Type

String

BatchSequenceNumber Property (FDMSSettle Class)

Starting sequence number for the transactions in this batch.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetBatchSequenceNumber();
int SetBatchSequenceNumber(const char* lpszBatchSequenceNumber);

Unicode (Windows)
LPWSTR GetBatchSequenceNumber();
INT SetBatchSequenceNumber(LPCWSTR lpszBatchSequenceNumber);

char* dpaymentssdk_fdmssettle_getbatchsequencenumber(void* lpObj);
int dpaymentssdk_fdmssettle_setbatchsequencenumber(void* lpObj, const char* lpszBatchSequenceNumber);

QString GetBatchSequenceNumber();
int SetBatchSequenceNumber(QString qsBatchSequenceNumber);

Default Value

""

Remarks

A batch settlement is made up of many separate transaction packets. The class creates these packets and posts them one-by-one to the Datawire VXN, where they are then routed to the FDMS payment processor. Each of these packets sent to Datawire must contain a unique 7 digit transaction sequence identifier. This property should contain the beginning sequence number, which the class will increment for each individual data payload sent in the batch settlement. The component will pad the entered value with trailing zeros as needed and restart at 0 when the maximum transaction sequence identifier is reached.

To retrieve the last transaction sequence identifier used by the component in the batch settlement you need to read the value of BatchSequenceNumber after SendSettlement method is called. ... FDMSSettle.BatchSequenceNumber = "1234"; FDMSSettle.DetailRecords.Add(new FDMSRecordType(FDMSEcommerce.GetDetailAggregate())); FDMSSettle.SendSettlement(); // retrieve the last transaction sequence identifier used in batch settlement // increment it and use in the consecutive transaction to First Data String lastUsedTranNum = FDMSSettle.BatchSequenceNumber; 'this returns the last transaction sequence identifier used in batch settlement.

Data Type

String

DatawireId Property (FDMSSettle Class)

Identifies the merchant to the Datawire System.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetDatawireId();
int SetDatawireId(const char* lpszDatawireId);

Unicode (Windows)
LPWSTR GetDatawireId();
INT SetDatawireId(LPCWSTR lpszDatawireId);

char* dpaymentssdk_fdmssettle_getdatawireid(void* lpObj);
int dpaymentssdk_fdmssettle_setdatawireid(void* lpObj, const char* lpszDatawireId);

QString GetDatawireId();
int SetDatawireId(QString qsDatawireId);

Default Value

""

Remarks

The Datawire Id is a unique customer identifier generated by Datawire and returned to the client after successfully registering the merchant (using the FDMSRegister class). This Id (which is sent in all subsequent transactions) allows a transaction, to pass through the Datawire system and be correctly routed to the FDMS Payment processor.

The maximum length for this property is 32 characters.

Data Type

String

DetailRecordCount Property (FDMSSettle Class)

The number of records in the DetailRecord arrays.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetDetailRecordCount();
int SetDetailRecordCount(int iDetailRecordCount);

Unicode (Windows)
INT GetDetailRecordCount();
INT SetDetailRecordCount(INT iDetailRecordCount);

int dpaymentssdk_fdmssettle_getdetailrecordcount(void* lpObj);
int dpaymentssdk_fdmssettle_setdetailrecordcount(void* lpObj, int iDetailRecordCount);

int GetDetailRecordCount();
int SetDetailRecordCount(int iDetailRecordCount);

Default Value

0

Remarks

This property controls the size of the following arrays:

• DetailRecordAddendum
• DetailRecordAggregate

The array indices start at 0 and end at DetailRecordCount - 1.

This property is not available at design time.

Data Type

Integer

DetailRecordAddendum Property (FDMSSettle Class)

Optional Detail Record Addendum data (such as Level2 or Level3 data) The DetailAggregate property contains an xml aggregate of the transaction retrieved from the FDMSECOMMERCE , FDMSRETAIL , or FDMSDETAILRECORD class's GetDetailAggregate method.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetDetailRecordAddendum(int iDetailRecordIndex);
int SetDetailRecordAddendum(int iDetailRecordIndex, const char* lpszDetailRecordAddendum);

Unicode (Windows)
LPWSTR GetDetailRecordAddendum(INT iDetailRecordIndex);
INT SetDetailRecordAddendum(INT iDetailRecordIndex, LPCWSTR lpszDetailRecordAddendum);

char* dpaymentssdk_fdmssettle_getdetailrecordaddendum(void* lpObj, int detailrecordindex);
int dpaymentssdk_fdmssettle_setdetailrecordaddendum(void* lpObj, int detailrecordindex, const char* lpszDetailRecordAddendum);

QString GetDetailRecordAddendum(int iDetailRecordIndex);
int SetDetailRecordAddendum(int iDetailRecordIndex, QString qsDetailRecordAddendum);

Default Value

""

Remarks

Optional Detail Record Addendum data (such as Level2 or Level3 data)

The DetailRecordDetailAggregate property contains an xml aggregate of the transaction retrieved from the FDMSECommerce, FDMSRetail, or FDMSDetailRecord class's GetDetailAggregate method. If you wish to accept corporate purchasing cards you will also need to send Level2, and possibly Level3 addendum data along with the DetailRecordDetailAggregate. The DetailRecordAddendumAggregate property takes an xml aggregate containing either Level2 or Level2 plus Level3 addendum data, which will be added to the DetailRecordDetailAggregate when sending the settlement. The DetailRecordAddendumAggregate may be created with either the FDMSLevel2 or FDMSLevel3 classs, and then returned via those class's GetAddendum method.

For example:

'First, authorize the credit card FDMSECommerce.TransactionAmount = "2720" '$27.20 FDMSECommerce.Authorize() 'Then, put the result into the settlement component FDMSSettle.DetailRecordCount = 1 FDMSSettle.DetailRecordAggregate(0) = FDMSECommerce.GetDetailAggregate() 'Then build the Level 2 portion FDMSLevel2.CardType = fctVisa FDMSLevel2.CommercialCardType = FDMSECommerce.ResponseCommercialCard FDMSLevel2.OrderDate = "230928" 'September 28th, 2023 FDMSLevel2.FreightTaxAmount = "0" FDMSLevel2.FreightAmount = "600" '$6.00 FDMSLevel2.PurchaseIdentifier = "123456PURCHID" FDMSLevel2.ShippedToZip = "90210" FDMSLevel2.ShippedFromZip = "90210" FDMSLevel2.TaxAmount = "120" '$1.20 'Now build the Level 3 portion FDMSLevel3.CardType = fctVisa FDMSLevel3.LineItemCount = 2 FDMSLevel3.ItemCommodityCode(0) = "4900" ' Books and printed materials FDMSLevel3.ItemDescription(0) = "Reference manual" FDMSLevel3.ItemDiscountAmount(0) = "" ' No discount FDMSLevel3.ItemProductCode(0) = "ISBN123456" FDMSLevel3.ItemTaxAmount(0) = "60" '$0.60 FDMSLevel3.ItemTaxRate(0) = "600" '6.00 percent FDMSLevel3.ItemQuantity(0) = "2" FDMSLevel3.ItemUnitCost(0) = "500" '$5.00 FDMSLevel3.ItemTotal(0) = "1060" '$10.60 FDMSLevel3.ItemUnits(0) = "each" FDMSLevel3.ItemCommodityCode(1) = "4900" ' Books and printed materials FDMSLevel3.ItemDescription(1) = "Quick Start manual" FDMSLevel3.ItemDiscountAmount(1) = "" ' No discount FDMSLevel3.ItemProductCode(1) = "ISBN654321" FDMSLevel3.ItemTaxAmount(1) = "60" '$0.60 FDMSLevel3.ItemTaxRate(1) = "600" '6.00 percent FDMSLevel3.ItemQuantity(1) = "1" FDMSLevel3.ItemUnitCost(1) = "1000" '$10.00 FDMSLevel3.ItemTotal(1) = "1060" '$10.60 FDMSLevel3.ItemUnits(1) = "each" 'Finally, add the Level 2 and Level 3 addendum data to the settlement at the same index 'as the associated transaction. FDMSSettle.DetailRecordAddendum(0) = FDMSLevel2.GetAddendum() & FDMSLevel3.GetAddendum()

Note that you may mix corporate and non-corporate card transactions in the same settlement. It is not necessary that all DetailRecordDetailAggregates have a corresponding DetailRecordAddendumAggregate.

The DetailRecordIndex parameter specifies the index of the item in the array. The size of the array is controlled by the DetailRecordCount property.

This property is not available at design time.

Data Type

String

DetailRecordAggregate Property (FDMSSettle Class)

Set this property with xml aggregates of the transactions you wish to settle.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetDetailRecordAggregate(int iDetailRecordIndex);
int SetDetailRecordAggregate(int iDetailRecordIndex, const char* lpszDetailRecordAggregate);

Unicode (Windows)
LPWSTR GetDetailRecordAggregate(INT iDetailRecordIndex);
INT SetDetailRecordAggregate(INT iDetailRecordIndex, LPCWSTR lpszDetailRecordAggregate);

char* dpaymentssdk_fdmssettle_getdetailrecordaggregate(void* lpObj, int detailrecordindex);
int dpaymentssdk_fdmssettle_setdetailrecordaggregate(void* lpObj, int detailrecordindex, const char* lpszDetailRecordAggregate);

QString GetDetailRecordAggregate(int iDetailRecordIndex);
int SetDetailRecordAggregate(int iDetailRecordIndex, QString qsDetailRecordAggregate);

Default Value

""

Remarks

Set this property with xml aggregates of the transactions you wish to settle.

To settle previously authorized transactions, this property must be set with the xml aggregate returned from the FDMSECommerce, FDMSRetail, or FDMSDetailRecord class's GetDetailAggregate method. For instance:

FDMSSettle.DetailRecords.Add(new FDMSRecordtype(FDMSRetail1.GetDetailAggregate()));

On occasion, you may need to modify these aggregates before sending them to settlement. For instance, if you're running a restaurant you may need to add a gratuity to the charge. If you're accepting installment payments, you will need to add the installment info. To accomplish this, you may use the FDMSDetailRecord class.

For example, to add a gratuity to a charge:

FDMSDetailRecord.ParseAggregate(FDMSRetail.GetDetailAggregate()) FDMSDetailRecord.Gratuity = "500" FDMSDetailRecord.TransactionAmount = FDMSDetailRecord.TransactionAmount + FDMSDetailRecord.Gratuity FDMSSettle.DetailAggregate(0) = FDMSDetailRecord.GetDetailAggregate()

To settle a transaction authorized with the dmtInstallment TransactionType, you must use the FDMSDetailRecord class to add the number of this installment and the total count of all installments to be made. For instance, if the purchase was for "Three easy payments of $19.95", and this is the first payment, then the installment number will be 1, and the installment count 3. An example is included below:

FDMSECommerce.TransactionType = dmtInstallment FDMSECommerce.TransactionAmount = "1995" FDMSECommerce.Authorize() FDMSDetailRecord.ParseAggregate FDMSECommerce.GetDetailAggregate() FDMSDetailRecord.InstallmentCount = 3 FDMSDetailRecord.InstallmentNumber = 1 FDMSSettle.DetailRecordAggregate(5) = FDMSDetailRecord.GetDetailAggregate()

The DetailRecordIndex parameter specifies the index of the item in the array. The size of the array is controlled by the DetailRecordCount property.

This property is not available at design time.

Data Type

String

FDMSPlatform Property (FDMSSettle Class)

Specifies the FDMS platform that the transactions will be processed on.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetFDMSPlatform();
int SetFDMSPlatform(int iFDMSPlatform);

Unicode (Windows)
INT GetFDMSPlatform();
INT SetFDMSPlatform(INT iFDMSPlatform);

FP_NORTH(0), 
FP_NASHVILLE(1)

int dpaymentssdk_fdmssettle_getfdmsplatform(void* lpObj);
int dpaymentssdk_fdmssettle_setfdmsplatform(void* lpObj, int iFDMSPlatform);

int GetFDMSPlatform();
int SetFDMSPlatform(int iFDMSPlatform);

Default Value

0

Remarks

This property is used to identify the FDMS platform that the transactions will be sent to and processed on. The following table lists the platforms supported by this class.

Data Type

Integer

IndustryType Property (FDMSSettle Class)

Code which indicates the industry the merchant is engaged in.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetIndustryType();
int SetIndustryType(int iIndustryType);

Unicode (Windows)
INT GetIndustryType();
INT SetIndustryType(INT iIndustryType);

FIT_UNKNOWN(0), 
FIT_RETAIL(1), 
FIT_RESTAURANT(2), 
FIT_GROCERY_STORE(3), 
FIT_DIRECT_MARKETING(4), 
FIT_HOTEL(5)

int dpaymentssdk_fdmssettle_getindustrytype(void* lpObj);
int dpaymentssdk_fdmssettle_setindustrytype(void* lpObj, int iIndustryType);

int GetIndustryType();
int SetIndustryType(int iIndustryType);

Default Value

1

Remarks

This property is used to identify the industry type of the merchant submitting the authorization request. The following table lists the industry types supported by this class.

Data Type

Integer

MerchantNumber Property (FDMSSettle Class)

A unique number used to identify the merchant within the FDMS and Datawire systems.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetMerchantNumber();
int SetMerchantNumber(const char* lpszMerchantNumber);

Unicode (Windows)
LPWSTR GetMerchantNumber();
INT SetMerchantNumber(LPCWSTR lpszMerchantNumber);

char* dpaymentssdk_fdmssettle_getmerchantnumber(void* lpObj);
int dpaymentssdk_fdmssettle_setmerchantnumber(void* lpObj, const char* lpszMerchantNumber);

QString GetMerchantNumber();
int SetMerchantNumber(QString qsMerchantNumber);

Default Value

""

Remarks

This property contains a unique number (typically 12 digits) which is assigned by the signing merchant's bank or processor. This field is used to identify the merchant within the FDMS and Datawire systems, and is used along with the MerchantTerminalNumber and DatawireId as connection credentials.

Data Type

String

MerchantServiceNumber Property (FDMSSettle Class)

Merchant's customer service phone number.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetMerchantServiceNumber();
int SetMerchantServiceNumber(const char* lpszMerchantServiceNumber);

Unicode (Windows)
LPWSTR GetMerchantServiceNumber();
INT SetMerchantServiceNumber(LPCWSTR lpszMerchantServiceNumber);

char* dpaymentssdk_fdmssettle_getmerchantservicenumber(void* lpObj);
int dpaymentssdk_fdmssettle_setmerchantservicenumber(void* lpObj, const char* lpszMerchantServiceNumber);

QString GetMerchantServiceNumber();
int SetMerchantServiceNumber(QString qsMerchantServiceNumber);

Default Value

""

Remarks

This 10 character field contains the merchant customer service phone number without dashes or spaces. The initial "1" for long-distance or toll-free calls should be omitted. For instance, "8001234567" is acceptable, while "18001234567" or "1-800-123-4567" is not.

This property is only required when the IndustryType is set to fitDirectMarketing, and will otherwise not be sent.

Data Type

String

MerchantTerminalNumber Property (FDMSSettle Class)

Used to identify a unique terminal within a merchant location.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetMerchantTerminalNumber();
int SetMerchantTerminalNumber(const char* lpszMerchantTerminalNumber);

Unicode (Windows)
LPWSTR GetMerchantTerminalNumber();
INT SetMerchantTerminalNumber(LPCWSTR lpszMerchantTerminalNumber);

char* dpaymentssdk_fdmssettle_getmerchantterminalnumber(void* lpObj);
int dpaymentssdk_fdmssettle_setmerchantterminalnumber(void* lpObj, const char* lpszMerchantTerminalNumber);

QString GetMerchantTerminalNumber();
int SetMerchantTerminalNumber(QString qsMerchantTerminalNumber);

Default Value

""

Remarks

This property contains a number (typically 6 digits) assigned by FDMS to uniquely identify a terminal within a merchant location, and is used along with the MerchantNumber and DatawireId as connection credentials.

Data Type

String

ProxyAuthScheme Property (FDMSSettle Class)

This property is used to tell the class which type of authorization to perform when connecting to the proxy.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetProxyAuthScheme();
int SetProxyAuthScheme(int iProxyAuthScheme);

Unicode (Windows)
INT GetProxyAuthScheme();
INT SetProxyAuthScheme(INT iProxyAuthScheme);

AUTH_BASIC(0), 
AUTH_DIGEST(1), 
AUTH_PROPRIETARY(2), 
AUTH_NONE(3), 
AUTH_NTLM(4), 
AUTH_NEGOTIATE(5)

int dpaymentssdk_fdmssettle_getproxyauthscheme(void* lpObj);
int dpaymentssdk_fdmssettle_setproxyauthscheme(void* lpObj, int iProxyAuthScheme);

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

Default Value

0

Remarks

This property is used to tell the class which type of authorization to perform when connecting to the proxy. This is used only when the ProxyUser and ProxyPassword properties are set.

ProxyAuthScheme should be set to authNone (3) when no authentication is expected.

By default, ProxyAuthScheme is authBasic (0), and if the ProxyUser and ProxyPassword properties are set, the component will attempt basic authentication.

If ProxyAuthScheme is set to authDigest (1), digest authentication will be attempted instead.

If ProxyAuthScheme is set to authProprietary (2), then the authorization token will not be generated by the class. Look at the configuration file for the class being used to find more information about manually setting this token.

If ProxyAuthScheme is set to authNtlm (4), NTLM authentication will be used.

For security reasons, setting this property will clear the values of ProxyUser and ProxyPassword.

Data Type

Integer

ProxyAutoDetect Property (FDMSSettle Class)

This property tells the class whether or not to automatically detect and use proxy system settings, if available.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetProxyAutoDetect();
int SetProxyAutoDetect(int bProxyAutoDetect);

Unicode (Windows)
BOOL GetProxyAutoDetect();
INT SetProxyAutoDetect(BOOL bProxyAutoDetect);

int dpaymentssdk_fdmssettle_getproxyautodetect(void* lpObj);
int dpaymentssdk_fdmssettle_setproxyautodetect(void* lpObj, int bProxyAutoDetect);

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

Default Value

FALSE

Remarks

This property tells the class whether or not to automatically detect and use proxy system settings, if available. The default value is false.

Data Type

Boolean

ProxyPassword Property (FDMSSettle Class)

This property contains a password if authentication is to be used for the proxy.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetProxyPassword();
int SetProxyPassword(const char* lpszProxyPassword);

Unicode (Windows)
LPWSTR GetProxyPassword();
INT SetProxyPassword(LPCWSTR lpszProxyPassword);

char* dpaymentssdk_fdmssettle_getproxypassword(void* lpObj);
int dpaymentssdk_fdmssettle_setproxypassword(void* lpObj, const char* lpszProxyPassword);

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

Default Value

""

Remarks

This property contains a password if authentication is to be used for the proxy.

If ProxyAuthScheme is set to Basic Authentication, the ProxyUser and ProxyPassword are Base64 encoded and the proxy authentication token will be generated in the form Basic [encoded-user-password].

If ProxyAuthScheme is set to Digest Authentication, the ProxyUser and ProxyPassword properties are used to respond to the Digest Authentication challenge from the server.

If ProxyAuthScheme is set to NTLM Authentication, the ProxyUser and ProxyPassword properties are used to authenticate through NTLM negotiation.

Data Type

String

ProxyPort Property (FDMSSettle Class)

This property contains the Transmission Control Protocol (TCP) port for the proxy Server (default 80).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetProxyPort();
int SetProxyPort(int iProxyPort);

Unicode (Windows)
INT GetProxyPort();
INT SetProxyPort(INT iProxyPort);

int dpaymentssdk_fdmssettle_getproxyport(void* lpObj);
int dpaymentssdk_fdmssettle_setproxyport(void* lpObj, int iProxyPort);

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

Default Value

80

Remarks

This property contains the Transmission Control Protocol (TCP) port for the proxy ProxyServer (default 80). See the description of the ProxyServer property for details.

Data Type

Integer

ProxyServer Property (FDMSSettle Class)

If a proxy Server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetProxyServer();
int SetProxyServer(const char* lpszProxyServer);

Unicode (Windows)
LPWSTR GetProxyServer();
INT SetProxyServer(LPCWSTR lpszProxyServer);

char* dpaymentssdk_fdmssettle_getproxyserver(void* lpObj);
int dpaymentssdk_fdmssettle_setproxyserver(void* lpObj, const char* lpszProxyServer);

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

Default Value

""

Remarks

If a proxy ProxyServer is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.

If the ProxyServer property is set to a domain name, a DNS request is initiated. Upon successful termination of the request, the ProxyServer property is set to the corresponding address. If the search is not successful, an error is returned.

Data Type

String

ProxySSL Property (FDMSSettle Class)

This property determines when to use a Secure Sockets Layer (SSL) for the connection to the proxy.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetProxySSL();
int SetProxySSL(int iProxySSL);

Unicode (Windows)
INT GetProxySSL();
INT SetProxySSL(INT iProxySSL);

PS_AUTOMATIC(0), 
PS_ALWAYS(1), 
PS_NEVER(2), 
PS_TUNNEL(3)

int dpaymentssdk_fdmssettle_getproxyssl(void* lpObj);
int dpaymentssdk_fdmssettle_setproxyssl(void* lpObj, int iProxySSL);

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

Default Value

0

Remarks

This property determines when to use a Secure Sockets Layer (SSL) for the connection to the proxy. The applicable values are as follows:

Data Type

Integer

ProxyUser Property (FDMSSettle Class)

This property contains a username if authentication is to be used for the proxy.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetProxyUser();
int SetProxyUser(const char* lpszProxyUser);

Unicode (Windows)
LPWSTR GetProxyUser();
INT SetProxyUser(LPCWSTR lpszProxyUser);

char* dpaymentssdk_fdmssettle_getproxyuser(void* lpObj);
int dpaymentssdk_fdmssettle_setproxyuser(void* lpObj, const char* lpszProxyUser);

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

Default Value

""

Remarks

This property contains a username if authentication is to be used for the proxy.

If ProxyAuthScheme is set to Basic Authentication, the ProxyUser and ProxyPassword properties are Base64 encoded and the proxy authentication token will be generated in the form Basic [encoded-user-password].

If ProxyAuthScheme is set to Digest Authentication, the ProxyUser and ProxyPassword properties are used to respond to the Digest Authentication challenge from the server.

If ProxyAuthScheme is set to NTLM Authentication, the ProxyUser and ProxyPassword properties are used to authenticate through NTLM negotiation.

Data Type

String

ResponseBatchNumber Property (FDMSSettle Class)

FDMS-generated Id of the batch settlement.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetResponseBatchNumber();

Unicode (Windows)
LPWSTR GetResponseBatchNumber();

char* dpaymentssdk_fdmssettle_getresponsebatchnumber(void* lpObj);

QString GetResponseBatchNumber();

Default Value

"0"

Remarks

FDMS-generated Id of the batch settlement.

This property is filled after a successful batch settlement, and contains a unique number which identifies the settlement with the FDMS processor. This number should be logged in case you have any questions about the settlement in the future.

This property is read-only.

Data Type

String

ResponseBatchStatus Property (FDMSSettle Class)

Indicates success or failure of the entire settlement.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetResponseBatchStatus();

Unicode (Windows)
LPWSTR GetResponseBatchStatus();

char* dpaymentssdk_fdmssettle_getresponsebatchstatus(void* lpObj);

QString GetResponseBatchStatus();

Default Value

""

Remarks

Indicates success or failure of the entire settlement.

This property will be filled after calling the SendSettlement method. If it contains "OK", the batch settlement has succeeded. If it contains any other data, an error will be generated by the class. Possible responses include:

This property is read-only.

Data Type

String

ResponseDatawireReturnCode Property (FDMSSettle Class)

Contains an error code providing more details about the DatawireStatus received.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetResponseDatawireReturnCode();

Unicode (Windows)
LPWSTR GetResponseDatawireReturnCode();

char* dpaymentssdk_fdmssettle_getresponsedatawirereturncode(void* lpObj);

QString GetResponseDatawireReturnCode();

Default Value

""

Remarks

Contains an error code providing more details about the ResponseDatawireStatus received.

When a transaction is successfully passed from the application, through the Datawire system to the FDMS payment processor and back, the ResponseDatawireStatus will be "OK" and the ResponseDatawireReturnCode will be "000". These two properties have NO BEARING on the actual results of any transaction. Even though the transaction has successfully passed through the Datawire system, it can still fail to be processed successfully by FDMS. This property only indicates that the request reached FDMS, and that FDMS responded with some data.

The ResponseCaptureFlag and ResponseApprovalCode properties contain the actual transaction result that was returned by FDMS.

The following is a list of possible Datawire return codes:

This property is read-only.

Data Type

String

ResponseDatawireStatus Property (FDMSSettle Class)

Status of the communication with Datawire.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetResponseDatawireStatus();

Unicode (Windows)
LPWSTR GetResponseDatawireStatus();

char* dpaymentssdk_fdmssettle_getresponsedatawirestatus(void* lpObj);

QString GetResponseDatawireStatus();

Default Value

""

Remarks

Status of the communication with Datawire.

When a transaction is successfully passed from the application, through the Datawire system to the FDMS payment processor and back, the ResponseDatawireStatus will be "OK" and the ResponseDatawireReturnCode will be "000". These two properties have NO BEARING on the actual results of any transaction. Even though the transaction has successfully passed through the Datawire system, it can still fail to be processed successfully by FDMS. This property only indicates that the request reached FDMS, and that FDMS responded with some data.

The ResponseCaptureFlag and ResponseApprovalCode properties contains the actual FDMS Transaction Result that was returned.

The following is a list of possible Datawire response status codes:

This property is read-only.

Data Type

String

SSLAcceptServerCertEncoded Property (FDMSSettle Class)

This is the certificate (PEM/Base64 encoded).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSSLAcceptServerCertEncoded(char* &lpSSLAcceptServerCertEncoded, int &lenSSLAcceptServerCertEncoded);
int SetSSLAcceptServerCertEncoded(const char* lpSSLAcceptServerCertEncoded, int lenSSLAcceptServerCertEncoded);

Unicode (Windows)
INT GetSSLAcceptServerCertEncoded(LPSTR &lpSSLAcceptServerCertEncoded, INT &lenSSLAcceptServerCertEncoded);
INT SetSSLAcceptServerCertEncoded(LPCSTR lpSSLAcceptServerCertEncoded, INT lenSSLAcceptServerCertEncoded);

int dpaymentssdk_fdmssettle_getsslacceptservercertencoded(void* lpObj, char** lpSSLAcceptServerCertEncoded, int* lenSSLAcceptServerCertEncoded);
int dpaymentssdk_fdmssettle_setsslacceptservercertencoded(void* lpObj, const char* lpSSLAcceptServerCertEncoded, int lenSSLAcceptServerCertEncoded);

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

Default Value

""

Remarks

This is the certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The SSLAcceptServerCertStore and SSLAcceptServerCertSubject properties also may be used to specify a certificate.

When SSLAcceptServerCertEncoded is set, a search is initiated in the current SSLAcceptServerCertStore for the private key of the certificate. If the key is found, SSLAcceptServerCertSubject is updated to reflect the full subject of the selected certificate; otherwise, SSLAcceptServerCertSubject is set to an empty string.

This property is not available at design time.

Data Type

Binary String

SSLCertEncoded Property (FDMSSettle Class)

This is the certificate (PEM/Base64 encoded).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSSLCertEncoded(char* &lpSSLCertEncoded, int &lenSSLCertEncoded);
int SetSSLCertEncoded(const char* lpSSLCertEncoded, int lenSSLCertEncoded);

Unicode (Windows)
INT GetSSLCertEncoded(LPSTR &lpSSLCertEncoded, INT &lenSSLCertEncoded);
INT SetSSLCertEncoded(LPCSTR lpSSLCertEncoded, INT lenSSLCertEncoded);

int dpaymentssdk_fdmssettle_getsslcertencoded(void* lpObj, char** lpSSLCertEncoded, int* lenSSLCertEncoded);
int dpaymentssdk_fdmssettle_setsslcertencoded(void* lpObj, const char* lpSSLCertEncoded, int lenSSLCertEncoded);

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

Default Value

""

Remarks

This is the certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The SSLCertStore and SSLCertSubject properties also may be used to specify a certificate.

When SSLCertEncoded is set, a search is initiated in the current SSLCertStore for the private key of the certificate. If the key is found, SSLCertSubject is updated to reflect the full subject of the selected certificate; otherwise, SSLCertSubject is set to an empty string.

This property is not available at design time.

Data Type

Binary String

SSLCertStore Property (FDMSSettle Class)

This is the name of the certificate store for the client certificate.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSSLCertStore(char* &lpSSLCertStore, int &lenSSLCertStore);
int SetSSLCertStore(const char* lpSSLCertStore, int lenSSLCertStore);

Unicode (Windows)
INT GetSSLCertStore(LPSTR &lpSSLCertStore, INT &lenSSLCertStore);
INT SetSSLCertStore(LPCSTR lpSSLCertStore, INT lenSSLCertStore);

int dpaymentssdk_fdmssettle_getsslcertstore(void* lpObj, char** lpSSLCertStore, int* lenSSLCertStore);
int dpaymentssdk_fdmssettle_setsslcertstore(void* lpObj, const char* lpSSLCertStore, int lenSSLCertStore);

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

Default Value

"MY"

Remarks

This is the name of the certificate store for the client certificate.

The SSLCertStoreType property denotes the type of the certificate store specified by SSLCertStore. If the store is password protected, specify the password in SSLCertStorePassword.

SSLCertStore is used in conjunction with the SSLCertSubject property to specify client certificates. If SSLCertStore has a value, and SSLCertSubject or SSLCertEncoded is set, a search for a certificate is initiated. Please see the SSLCertSubject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

Data Type

Binary String

SSLCertStorePassword Property (FDMSSettle Class)

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetSSLCertStorePassword();
int SetSSLCertStorePassword(const char* lpszSSLCertStorePassword);

Unicode (Windows)
LPWSTR GetSSLCertStorePassword();
INT SetSSLCertStorePassword(LPCWSTR lpszSSLCertStorePassword);

char* dpaymentssdk_fdmssettle_getsslcertstorepassword(void* lpObj);
int dpaymentssdk_fdmssettle_setsslcertstorepassword(void* lpObj, const char* lpszSSLCertStorePassword);

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

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Data Type

String

SSLCertStoreType Property (FDMSSettle Class)

This is the type of certificate store for this certificate.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSSLCertStoreType();
int SetSSLCertStoreType(int iSSLCertStoreType);

Unicode (Windows)
INT GetSSLCertStoreType();
INT SetSSLCertStoreType(INT iSSLCertStoreType);

CST_USER(0), 
CST_MACHINE(1), 
CST_PFXFILE(2), 
CST_PFXBLOB(3), 
CST_JKSFILE(4), 
CST_JKSBLOB(5), 
CST_PEMKEY_FILE(6), 
CST_PEMKEY_BLOB(7), 
CST_PUBLIC_KEY_FILE(8), 
CST_PUBLIC_KEY_BLOB(9), 
CST_SSHPUBLIC_KEY_BLOB(10), 
CST_P7BFILE(11), 
CST_P7BBLOB(12), 
CST_SSHPUBLIC_KEY_FILE(13), 
CST_PPKFILE(14), 
CST_PPKBLOB(15), 
CST_XMLFILE(16), 
CST_XMLBLOB(17), 
CST_JWKFILE(18), 
CST_JWKBLOB(19), 
CST_SECURITY_KEY(20), 
CST_BCFKSFILE(21), 
CST_BCFKSBLOB(22), 
CST_PKCS11(23), 
CST_AUTO(99)

int dpaymentssdk_fdmssettle_getsslcertstoretype(void* lpObj);
int dpaymentssdk_fdmssettle_setsslcertstoretype(void* lpObj, int iSSLCertStoreType);

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

Default Value

0

Remarks

This is the type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

Data Type

Integer

SSLCertSubject Property (FDMSSettle Class)

This is the subject of the certificate used for client authentication.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetSSLCertSubject();
int SetSSLCertSubject(const char* lpszSSLCertSubject);

Unicode (Windows)
LPWSTR GetSSLCertSubject();
INT SetSSLCertSubject(LPCWSTR lpszSSLCertSubject);

char* dpaymentssdk_fdmssettle_getsslcertsubject(void* lpObj);
int dpaymentssdk_fdmssettle_setsslcertsubject(void* lpObj, const char* lpszSSLCertSubject);

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

Default Value

""

Remarks

This is the subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

Data Type

String

SSLProvider Property (FDMSSettle Class)

This specifies the 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 dpaymentssdk_fdmssettle_getsslprovider(void* lpObj);
int dpaymentssdk_fdmssettle_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:

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

SSLServerCertEncoded Property (FDMSSettle Class)

This is the certificate (PEM/Base64 encoded).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSSLServerCertEncoded(char* &lpSSLServerCertEncoded, int &lenSSLServerCertEncoded);

Unicode (Windows)
INT GetSSLServerCertEncoded(LPSTR &lpSSLServerCertEncoded, INT &lenSSLServerCertEncoded);

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

QByteArray GetSSLServerCertEncoded();

Default Value

""

Remarks

This is the certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The SSLServerCertStore and SSLServerCertSubject properties also may be used to specify a certificate.

When SSLServerCertEncoded is set, a search is initiated in the current SSLServerCertStore for the private key of the certificate. If the key is found, SSLServerCertSubject is updated to reflect the full subject of the selected certificate; otherwise, SSLServerCertSubject is set to an empty string.

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

Data Type

Binary String

Timeout Property (FDMSSettle 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 dpaymentssdk_fdmssettle_gettimeout(void* lpObj);
int dpaymentssdk_fdmssettle_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 return with an error after Timeout seconds.

The default value for Timeout is 30 (seconds).

Data Type

Integer

URL Property (FDMSSettle Class)

Location of the Datawire server to which transactions are sent.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetURL();
int SetURL(const char* lpszURL);

Unicode (Windows)
LPWSTR GetURL();
INT SetURL(LPCWSTR lpszURL);

char* dpaymentssdk_fdmssettle_geturl(void* lpObj);
int dpaymentssdk_fdmssettle_seturl(void* lpObj, const char* lpszURL);

QString GetURL();
int SetURL(QString qsURL);

Default Value

"https://staging1.datawire.net/sd/"

Remarks

This is the URL to which all authorization and settlement transactions are sent. This URL is acquired by using the FDMSRegister class. Once you Register and Activate the merchant using the FDMSRegister class, you may then do a Service Discovery. After sending a Service Discovery transaction, the Datawire system will return a list of transaction URLs. The URL from this list with the shortest round-trip transit time from a ping is the URL you should use here.

Note: By default, this property is populated with the Datawire Staging (test) server, and is not the correct URL to use in a production environment. In a production environment, this URL is supplied by the FDMSRegister class.

Data Type

String

Config Method (FDMSSettle 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* dpaymentssdk_fdmssettle_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.

Interrupt Method (FDMSSettle Class)

Interrupts the current action.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Interrupt();

Unicode (Windows)
INT Interrupt();

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

Reset Method (FDMSSettle Class)

Clears all properties to their default values.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Reset();

Unicode (Windows)
INT Reset();

int dpaymentssdk_fdmssettle_reset(void* lpObj);

int Reset();

Remarks

This method clears all properties to their default values.

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

SendSettlement Method (FDMSSettle Class)

Begins a Batch Settlement transaction with the transaction server.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SendSettlement();

Unicode (Windows)
INT SendSettlement();

int dpaymentssdk_fdmssettle_sendsettlement(void* lpObj);

int SendSettlement();

Remarks

This begins a Batch Settlement transaction. The class begins a session with the Datawire system, and then posts a header record, all the detail records, all the Level 2 and Level 3 addendum records (if any), and a trailer record in sequence. The session is then automatically terminated, and the ResponseBatchStatus property will indicate the result of the settlement as returned by the FDMS processor.

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

Connected Event (FDMSSettle Class)

This event is fired immediately after a connection completes (or fails).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireConnected(FDMSSettleConnectedEventParams *e);

typedef struct {
  int StatusCode;
  const char *Description;
  int reserved;
} FDMSSettleConnectedEventParams;


Unicode (Windows)
virtual INT FireConnected(FDMSSettleConnectedEventParams *e);

typedef struct {
  INT StatusCode;
  LPCWSTR Description;
  INT reserved;
} FDMSSettleConnectedEventParams;

#define EID_FDMSSETTLE_CONNECTED 1

virtual INT DPAYMENTSSDK_CALL FireConnected(INT &iStatusCode, LPSTR &lpszDescription);

class FDMSSettleConnectedEventParams {
public:
  int StatusCode();

  const QString &Description();

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

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

// Or, subclass FDMSSettle and override this emitter function.
virtual int FireConnected(FDMSSettleConnectedEventParams *e) {...}

Remarks

If the connection is made normally, StatusCode is 0 and Description is "OK".

If the connection fails, StatusCode has the error code returned by the Transmission Control Protocol (TCP)/IP stack. Description contains a description of this code. The value of StatusCode is equal to the value of the error.

Please refer to the Error Codes section for more information.

DataPacketIn Event (FDMSSettle Class)

Fired when receiving a data packet from the transaction server.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireDataPacketIn(FDMSSettleDataPacketInEventParams *e);

typedef struct {
  const char *DataPacket;
  int lenDataPacket;
  int reserved;
} FDMSSettleDataPacketInEventParams;


Unicode (Windows)
virtual INT FireDataPacketIn(FDMSSettleDataPacketInEventParams *e);

typedef struct {
  LPCSTR DataPacket;
  INT lenDataPacket;
  INT reserved;
} FDMSSettleDataPacketInEventParams;

#define EID_FDMSSETTLE_DATAPACKETIN 2

virtual INT DPAYMENTSSDK_CALL FireDataPacketIn(LPSTR &lpDataPacket, INT &lenDataPacket);

class FDMSSettleDataPacketInEventParams {
public:
  const QByteArray &DataPacket();

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

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

// Or, subclass FDMSSettle and override this emitter function.
virtual int FireDataPacketIn(FDMSSettleDataPacketInEventParams *e) {...}

Remarks

This event fires when a packet is received. The entire data packet (including all framing and error detection characters) is contained in the parameter "DataPacket". This parameter may be inspected for advanced troubleshooting, or to extract additional response properties beyond the scope of this class.

DataPacketOut Event (FDMSSettle Class)

Fired when sending a data packet to the transaction server.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireDataPacketOut(FDMSSettleDataPacketOutEventParams *e);

typedef struct {
  const char *DataPacket;
  int lenDataPacket;
  int reserved;
} FDMSSettleDataPacketOutEventParams;


Unicode (Windows)
virtual INT FireDataPacketOut(FDMSSettleDataPacketOutEventParams *e);

typedef struct {
  LPCSTR DataPacket;
  INT lenDataPacket;
  INT reserved;
} FDMSSettleDataPacketOutEventParams;

#define EID_FDMSSETTLE_DATAPACKETOUT 3

virtual INT DPAYMENTSSDK_CALL FireDataPacketOut(LPSTR &lpDataPacket, INT &lenDataPacket);

class FDMSSettleDataPacketOutEventParams {
public:
  const QByteArray &DataPacket();

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

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

// Or, subclass FDMSSettle and override this emitter function.
virtual int FireDataPacketOut(FDMSSettleDataPacketOutEventParams *e) {...}

Remarks

This event fires right before each data packet is sent. The entire data packet (including all framing and error detection characters) is contained in the parameter "DataPacket". This parameter may be inspected for advanced troubleshooting, or may be modified to support additional features beyond the scope of this class.

Disconnected Event (FDMSSettle Class)

This event is fired when a connection is closed.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireDisconnected(FDMSSettleDisconnectedEventParams *e);

typedef struct {
  int StatusCode;
  const char *Description;
  int reserved;
} FDMSSettleDisconnectedEventParams;


Unicode (Windows)
virtual INT FireDisconnected(FDMSSettleDisconnectedEventParams *e);

typedef struct {
  INT StatusCode;
  LPCWSTR Description;
  INT reserved;
} FDMSSettleDisconnectedEventParams;

#define EID_FDMSSETTLE_DISCONNECTED 4

virtual INT DPAYMENTSSDK_CALL FireDisconnected(INT &iStatusCode, LPSTR &lpszDescription);

class FDMSSettleDisconnectedEventParams {
public:
  int StatusCode();

  const QString &Description();

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

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

// Or, subclass FDMSSettle and override this emitter function.
virtual int FireDisconnected(FDMSSettleDisconnectedEventParams *e) {...}

Remarks

If the connection is broken normally, StatusCode is 0 and Description is "OK".

If the connection is broken for any other reason, StatusCode has the error code returned by the Transmission Control Protocol (TCP/IP) subsystem. Description contains a description of this code. The value of StatusCode is equal to the value of the TCP/IP error.

Please refer to the Error Codes section for more information.

Error Event (FDMSSettle Class)

Fired when information is available about errors during data delivery.

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_FDMSSETTLE_ERROR 5

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

class FDMSSettleErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

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

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

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

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the class fails with an error.

The ErrorCode parameter contains an error code, and the Description parameter 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 (FDMSSettle Class)

Fired after the server presents its certificate to the client.

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_FDMSSETTLE_SSLSERVERAUTHENTICATION 6

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

class FDMSSettleSSLServerAuthenticationEventParams {
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(FDMSSettleSSLServerAuthenticationEventParams *e);

// Or, subclass FDMSSettle and override this emitter function.
virtual int FireSSLServerAuthentication(FDMSSettleSSLServerAuthenticationEventParams *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 (FDMSSettle Class)

Fired when secure connection progress messages are available.

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_FDMSSETTLE_SSLSTATUS 7

virtual INT DPAYMENTSSDK_CALL FireSSLStatus(LPSTR &lpszMessage);

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

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

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

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

Remarks

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

Status Event (FDMSSettle Class)

Shows the progress of the FDMS/Datawire connection.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireStatus(FDMSSettleStatusEventParams *e);

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


Unicode (Windows)
virtual INT FireStatus(FDMSSettleStatusEventParams *e);

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

#define EID_FDMSSETTLE_STATUS 8

virtual INT DPAYMENTSSDK_CALL FireStatus(LPSTR &lpszMessage);

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

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

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

// Or, subclass FDMSSettle and override this emitter function.
virtual int FireStatus(FDMSSettleStatusEventParams *e) {...}

Remarks

The event is fired for informational and logging purposes only. Used to track the progress of the connection.

Config Settings (FDMSSettle Class)

FDMSSettle Config Settings

TCPClient Config Settings

SSL Config Settings

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
..
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
..
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

Socket Config Settings

Base Config Settings

Trappable Errors (FDMSSettle 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.

FDMSSettle Errors

The class may also return one of the following error codes, which are inherited from other classes.

HTTP Errors

The class may also return one of the following error codes, which are inherited from other classes.

TCPClient Errors

SSL Errors

TCP/IP Errors