FDMSHealthCare Class

Properties   Methods   Events   Config Settings   Errors  

The FDMSHealthCare class is an advanced tool used to authorize FSA cards for healthcare transactions in either a retail or e-commerce/moto environment. This class makes authorizing these types of transactions very easy. Supported Industry Types include retail stores, direct marketing (e-commerce and mail order/phone order) and grocery or food stores.

Syntax

dpaymentssdk.Fdmshealthcare

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 FDMSHealthCare class makes authorizing healthcare and FSA card transactions very easy by adding an additional layer of abstraction between the programmer and the protocol. There is no need to deal with raw sockets, TLS/SSL handshakes, or data packet formatting. The steps to setting up the class and authorizing a transaction are outlined below:

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.

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

Then set the Card fields with the customer's cardholder data. Most card readers are capable of reading both Track1 and Track2 data off of a credit card. If both are present and correctly read, you should default to sending Track1 data. If your card reader cannot read the card at all, you may manually enter the credit card number and expiration date. If your IndustryType is set to hitDirectMarketing, you may only use manual entry. Do not forget to set the EntryDataSource field, as it is used by the class during authorization to create the proper type of payload. FDMSHealthCare.Card.MagneticStripe = "B4662060000000005^FDCS TEST CARD^120410123456789" FDMSHealthCare.Card.EntryDataSource = edsTrack1

Next, set properties that contain details about the transaction. The TransactionNumber should be incremented for every transaction you authorize. The TotalMedicalAmount and TransactionAmount must now be set, along with any optional amounts such as PrescriptionAmount, VisionAmount, DentalAmount, or ClinicAmount. Please note that the TotalMedicalAmount need not equal the TransactionAmount, but it CANNOT be greater than the TransactionAmount. All amounts are set with an implied decimal point (ie: $1.00 is "100"). The IndustryType should also be set at this time, as it will indicate whether this transaction is made for a Retail store, e-commerce, or a grocery store.

FDMSHealthCare.TransactionNumber = 1 FDMSHealthCare.PrescriptionAmount = "6000" FDMSHealthCare.TotalMedicalAmount = "8000" FDMSHealthCare.TransactionAmount = "20200" FDMSHealthCare.IndustryType = hitRetail

Finally, submit the transaction via the Authorize method.

FDMSHealthCare.Authorize() When the class receives a response, the result of the authorization will be available in several Response properties. The DatawireStatus and DatawireReturnCode indicate whether any errors occurred while passing the transaction through the Datawire VXN system. These two properties alone do not indicate a successful transaction, they only tell whether or not there were any problems transporting the authorization request and response through the Datawire system. If the transaction was successfully authorized by FDMS, then the CaptureFlag will be True, and the ApprovalCode will contain an approval code that beings with "AP". (or "AL" for classs that support partially-approved/split-tender transactions).

Once an authorization request is approved, the money in the customer's account is blocked and tagged for the merchant. This transaction must go through the Batch Settlement process in order for the blocked money to be transferred to the merchant account. This is done by passing the XML aggregate returned from the GetDetailAggregate method to the FDMSSettle class. Usually, a Batch Settlement of all authorized transactions is done at the end of each business day.

Note that FSA cards may be only partially approved. If the card is authorized for less than the full amount, the ApprovalCode field will begin with "AL" instead of "AP", and the AuthorizedAmount will contain the amount that was actually removed from the card. The customer must then pay the remainder via another means. If the customer cannot pay the remainder or wishes to cancel the transaction, use the ReversePartialAuth method to reverse the authorization.

A fully authorized transaction may also be reversed by using the ReverseFullAuth method. Reversals are used instead of voids for FSA cards because the block on the customer's FSA card is immediately released and funds are quickly made available for use. The customer does not have to wait for the block to expire before he can use his FSA card again.

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.

ApplicationId Property (FDMSHealthCare Class)

Identifies the merchant application to the Datawire System.

Syntax

public String getApplicationId();


public void setApplicationId(String applicationId);

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.

Card Property (FDMSHealthCare Class)

Contains the customer's credit card information.

Syntax

public CCCard getCard();


public void setCard(CCCard card);

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.

ClinicAmount Property (FDMSHealthCare Class)

Total amount of Clinic or Other qualified medical items for Healthcare auto-substantiation.

Syntax

public String getClinicAmount();


public void setClinicAmount(String clinicAmount);

Default Value

""

Remarks

The sum of all auto-substantiation items cannot be more than the TotalMedicalAmount, which must be equal to or less than the TransactionAmount.

This amount is to be presented with an implied decimal point. For example, US $10.00 must be represented as 1000, and $0.10 is likewise simply 10. The allowable number of significant digits as well as the positioning of any implied decimal point is dictated by the designated CurrencyCode configuration setting. In the United States (default), the number of allowable significant digits is seven. Thus the maximum TransactionAmount is "9999999", yielding a US dollar amount of $99,999.99. This field may not contain a negative number.

CustomerAddress Property (FDMSHealthCare Class)

The customer's billing address.

Syntax

public String getCustomerAddress();


public void setCustomerAddress(String customerAddress);

Default Value

""

Remarks

This field is used as part of the Address Verification Service (AVS) and contains the customer's street address as it appears on their monthly statement. Only the street number, street name, and apartment number are required in this field. City and state are not included, and the zip code is set in the CustomerZip property.

The maximum length of this property is 20 characters.

If the customer's address is much greater than the length of this field, it is admissible to include only the street number in this field.

CustomerZip Property (FDMSHealthCare Class)

Customer's zip code (or postal code if outside of the USA).

Syntax

public String getCustomerZip();


public void setCustomerZip(String customerZip);

Default Value

""

Remarks

This field is used as part of the Address Verification Service (AVS). If the customer resides within the United States, this field should contain the five or nine digit zip code as it appears on the customer's monthly statement. If the customer's billing address is outside of the United States, this field should contain the customer's postal code.

The maximum length of this property is 10 characters.

DatawireId Property (FDMSHealthCare Class)

Identifies the merchant to the Datawire System.

Syntax

public String getDatawireId();


public void setDatawireId(String datawireId);

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.

DentalAmount Property (FDMSHealthCare Class)

Total amount of Dental items for Healthcare auto-substantiation.

Syntax

public String getDentalAmount();


public void setDentalAmount(String dentalAmount);

Default Value

""

Remarks

The sum of all auto-substantiation items cannot be more than the TotalMedicalAmount, which must be equal to or less than the TransactionAmount.

This amount is to be presented with an implied decimal point. For example, US $10.00 must be represented as 1000, and $0.10 is likewise simply 10. The allowable number of significant digits as well as the positioning of any implied decimal point is dictated by the designated CurrencyCode configuration setting. In the United States (default), the number of allowable significant digits is seven. Thus the maximum TransactionAmount is "9999999", yielding a US dollar amount of $99,999.99. This field may not contain a negative number.

FDMSPlatform Property (FDMSHealthCare Class)

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

Syntax

public int getFDMSPlatform();


public void setFDMSPlatform(int FDMSPlatform);


Enumerated values:
  public final static int fpNorth = 0;
  public final static int fpNashville = 1;

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.

IndustryType Property (FDMSHealthCare Class)

Code which indicates the industry the merchant is engaged in.

Syntax

public int getIndustryType();


public void setIndustryType(int industryType);


Enumerated values:
  public final static int hitUnknown = 0;
  public final static int hitRetail = 1;
  public final static int hitDirectMarketing = 4;

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.

MerchantNumber Property (FDMSHealthCare Class)

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

Syntax

public String getMerchantNumber();


public void setMerchantNumber(String merchantNumber);

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.

MerchantTerminalNumber Property (FDMSHealthCare Class)

Used to identify a unique terminal within a merchant location.

Syntax

public String getMerchantTerminalNumber();


public void setMerchantTerminalNumber(String merchantTerminalNumber);

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.

PrescriptionAmount Property (FDMSHealthCare Class)

Total amount of Prescription/Rx items for Healthcare auto-substantiation.

Syntax

public String getPrescriptionAmount();


public void setPrescriptionAmount(String prescriptionAmount);

Default Value

""

Remarks

The sum of all auto-substantiation items cannot be more than the TotalMedicalAmount, which must be equal to or less than the TransactionAmount.

This amount is to be presented with an implied decimal point. For example, US $10.00 must be represented as 1000, and $0.10 is likewise simply 10. The allowable number of significant digits as well as the positioning of any implied decimal point is dictated by the designated CurrencyCode configuration setting. In the United States (default), the number of allowable significant digits is seven. Thus the maximum TransactionAmount is "9999999", yielding a US dollar amount of $99,999.99. This field may not contain a negative number.

Proxy Property (FDMSHealthCare Class)

This property includes a set of properties related to proxy access.

Syntax

public Proxy getProxy();


public void setProxy(Proxy proxy);

Remarks

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

Response Property (FDMSHealthCare Class)

Contains the response to an authorization request.

Syntax

public FDMSResponse getResponse();

Remarks

This property will contain the response returned from the FDMS server. It should be inspected (and logged) after an authorization to determine if the transaction was approved. The FDMSResponse type contains the following fields:

This property is read-only.

SSLAcceptServerCert Property (FDMSHealthCare Class)

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

Syntax

public Certificate getSSLAcceptServerCert();


public void setSSLAcceptServerCert(Certificate SSLAcceptServerCert);

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.

Please note that this functionality is provided only for cases where 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.

SSLCert Property (FDMSHealthCare Class)

The certificate to be used during SSL negotiation.

Syntax

public Certificate getSSLCert();


public void setSSLCert(Certificate SSLCert);

Remarks

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.

SSLProvider Property (FDMSHealthCare Class)

This specifies the SSL/TLS implementation to use.

Syntax

public int getSSLProvider();


public void setSSLProvider(int SSLProvider);


Enumerated values:
  public final static int sslpAutomatic = 0;
  public final static int sslpPlatform = 1;
  public final static int sslpInternal = 2;

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 the platform implementation is used by default. When TLS 1.3 is enabled via SSLEnabledProtocols the internal implementation is used.

SSLServerCert Property (FDMSHealthCare Class)

The server certificate for the last established connection.

Syntax

public Certificate getSSLServerCert();

Remarks

SSLServerCert contains the server certificate for the last established connection.

SSLServerCert is reset every time a new connection is attempted.

This property is read-only.

Timeout Property (FDMSHealthCare Class)

A timeout for the class.

Syntax

public int getTimeout();


public void setTimeout(int timeout);

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

TotalMedicalAmount Property (FDMSHealthCare Class)

Sum total of all medical item amounts.

Syntax

public String getTotalMedicalAmount();


public void setTotalMedicalAmount(String totalMedicalAmount);

Default Value

""

Remarks

This property is required when submitting a Healthcare Auto-substantiation transaction, and should indicate the sum total of all VisionAmounts, PrescriptionAmounts, ClinicAmounts, and DentalAmounts, plus any additional healthcare-related charges that do not fall under those categories. The category-specific amounts are optional, but at the minimum the TotalMedicalAmount must be present for Healthcare auto-substantiation (it may be "0", but it may not be left blank). If other amounts are present, the TotalMedicalAmount must be greater than or equal to the total of all other amounts.

If the transaction is only for healthcare related costs, the TotalMedicalAmount should be equal to the TransactionAmount However, it is possible to authorize a transaction that includes non-healthcare items, where the TransactionAmount is higher than the TotalMedicalAmount. if the TotalMedicalAmount exceeds the TransactionAmount the class will throws an exception.

This amount is to be presented with an implied decimal point. For example, US $10.00 must be represented as 1000, and $0.10 is likewise simply 10. The allowable number of significant digits as well as the positioning of any implied decimal point is dictated by the designated CurrencyCode configuration setting. In the United States (default), the number of allowable significant digits is seven. Thus the maximum TransactionAmount is "9999999", yielding a US dollar amount of $99,999.99. This field may not contain a negative number.

TPPID Property (FDMSHealthCare Class)

Third Party Processor Identifier assigned by FDMS.

Syntax

public String getTPPID();


public void setTPPID(String TPPID);

Default Value

"V4D001"

Remarks

The Third Party Processor Identifier (TPPID. Also sometimes referred to as a "Vendor Id") is assigned by FDMS to each third party who is processing transactions. Each merchant will receive his own TPPID from FDMS. If there are multiple third parties involved in the transaction flow, additional TPPID's are required. These may be added by setting the TPPID property with a comma-delimited list. The first entry should always be the servicer that sends the transaction to FDMS. Each subsequent servicer should be identified where they are in the chain. There can be a maximum of three entries in this list.

The default value for 4D Payments, Inc. on the North and Nashville platforms is "V4D001".

Note: This value will be reset to the default value when FDMSPlatform is set.

A VisaIdentifier is also required for Visa transactions.

TransactionAmount Property (FDMSHealthCare Class)

Purchase amount to be authorized.

Syntax

public String getTransactionAmount();


public void setTransactionAmount(String transactionAmount);

Default Value

""

Remarks

This property contains the transaction amount to be authorized.

This amount is to be presented with an implied decimal point. For example, US $10.00 must be represented as 1000, and $0.10 is likewise simply 10. The allowable number of significant digits as well as the positioning of any implied decimal point is dictated by the designated CurrencyCode configuration setting. In the United States (default), the number of allowable significant digits is seven. Thus the maximum TransactionAmount is "9999999", yielding a US dollar amount of $99,999.99. This field may not contain a negative number.

TransactionNumber Property (FDMSHealthCare Class)

Uniquely identifies the transaction.

Syntax

public String getTransactionNumber();


public void setTransactionNumber(String transactionNumber);

Default Value

""

Remarks

The TransactionNumber (otherwise known as the Client Reference Number, or ClientRef) uniquely identifies the packet sent by the application to the Datawire system. This parameter stores some unique token of information, and is used to match the response to the initial request sent. For example, the client application could use a static counter that is increased with the each executed request.

For all classs except FDMSGiftCard the maximum length of this property is 14 alphanumeric characters.

The FDMS recommended format is "tttttttVnnnnrrr" where ttttttt is a 7 digit transaction id, V is a constant, and nnn is a 3 digit version number and rrr is a 3 digit revision number. The 6 digit version number is typically static but unique for an application (Example: Version 2.5 = tttttttV002500).

For the Rapid Connect platform, the 6 character version number should be your Project/TPPID value. The entire TransactionNumber must be unique within a 24 hour time period.

The FDMSGiftCard also passes this value to the FDMS Closed Loop Gift Card system as a transaction id, and therefore the following restrictions are enforced: The maximum length is 7 characters. If the first character is an 'X', the remaining characters must be in the range '0' through 'F', indicating a hexadecimal number. Otherwise the FDMS Closed Loop Gift Card system only allows digits in this property.

URL Property (FDMSHealthCare Class)

Location of the Datawire server to which transactions are sent.

Syntax

public String getURL();


public void setURL(String URL);

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.

VisaIdentifier Property (FDMSHealthCare Class)

Additional merchant identification field used when authorizing Visa transactions.

Syntax

public String getVisaIdentifier();


public void setVisaIdentifier(String visaIdentifier);

Default Value

""

Remarks

In conjunction with Visa regulatory change(s), First Data will require the Agent Identification Service from all Third Party Servicers (TPS) or Merchant Servicers (MS). Each 19-byte Visa Agent Identifier in the chain is composed of the following pieces:

A VisaIdentifier (Agent Identification Service - AUAR) is required for Visa transactions. A VisaIdentifier value is assigned by Visa as part of their Trusted Agent Program (TAP). Therefore it is suggested that you contact your FDMS certification analyst as they should be able to provide you with further information and put you in contact with the required party at Visa. Unfortunately more specific information on this matter cannot be provided as we do not handle live customer data and thus are not required to register in this particular program. However below is some additional information in regards to the requirements of a Visa Identifier.

Any merchant that transmits, processes, or stores cardholder data on server(s) that you own, manage, or operate on behalf of your clients (who are other merchant account holders) must meet the PCI Data Security Standard and follow additional steps to register as a service provider. Applicable services commonly include webhosting, software as a service, or collecting payment on behalf of a client. Any company providing these services must register with Visa's Third Party Agent (TAP) program.

You can register for the Visa Third Party Agent Program at http://usa.visa.com/merchants/risk_management/third-party-registration.html

If you find that you are not required to register with this program you can send the following value for VisaIdentifier: 0B 000000000000

VisionAmount Property (FDMSHealthCare Class)

Total amount of Vision or Optical items for Healthcare auto-substantiation.

Syntax

public String getVisionAmount();


public void setVisionAmount(String visionAmount);

Default Value

""

Remarks

The sum of all auto-substantiation items cannot be more than the TotalMedicalAmount, which must be equal to or less than the TransactionAmount.

This amount is to be presented with an implied decimal point. For example, US $10.00 must be represented as 1000, and $0.10 is likewise simply 10. The allowable number of significant digits as well as the positioning of any implied decimal point is dictated by the designated CurrencyCode configuration setting. In the United States (default), the number of allowable significant digits is seven. Thus the maximum TransactionAmount is "9999999", yielding a US dollar amount of $99,999.99. This field may not contain a negative number.

Authorize Method (Fdmshealthcare Class)

Authorizes an FSA card for a Healthcare transaction.

Syntax

public void authorize();

Remarks

This method sends an authorization request through Datawire to the FDMS transaction processor. The credit card is specified through the Card property . Whether the card is manually entered, track1 swiped, or track 2 swiped is specified by the EntryDataSource field.

An authorization blocks funds on the customer's credit card, but does not actually transfer funds. In order for funds to be transferred and the transaction completed, you must settle the transaction. To do this, you must pass an XML aggregate containing the results of the transaction to the Settlement class. For example:

FDMSHealthCare1.URL = "https://staging1.datawire.net/sd/"; FDMSHealthCare1.IndustryType = itRetail; FDMSHealthCare1.DatawireId = "YOURDATAWIREID"; FDMSHealthCare1.MerchantNumber = "000000925990"; FDMSHealthCare1.MerchantTerminalNumber = "573138"; FDMSHealthCare1.TPPID = "VNT001"; FDMSHealthCare1.VisaIdentifier = "0B34567890123456789"; FDMSHealthCare1.ClinicAmount = ""; FDMSHealthCare1.DentalAmount = ""; FDMSHealthCare1.VisionAmount = ""; FDMSHealthCare1.PrescriptionAmount = "6000"; FDMSHealthCare1.TotalMedicalAmount = "8000"; FDMSHealthCare1.TransactionAmount = "20200" ; FDMSHealthCare1.Card.MagneticStripe = "B4662060000000005^FDCS TEST CARD^120410123456789"; FDMSHealthCare1.Card.EntryDataSource = edsTrack1; FDMSHealthCare1.TransactionNumber = 1; FDMSHealthCare1.Authorize(); if (FDMSHealthCare1.ResponseCaptureFlag) { FDMSSettle.DetailRecords.Add(new FDMSRecordType(FDMSHealthCare1.GetDetailAggregate())); }

Note that FSA cards may be only partially approved. If the card is authorized for less than the full amount, the ApprovalCode field will begin with "AL" instead of "AP", and the AuthorizedAmount will contain the amount that was actually removed from the card. The customer must then pay the remainder via another means. If the customer cannot pay the remainder or wishes to cancel the transaction, use the ReversePartialAuth method to reverse the authorization.

Important Note: You must ping your list of service provider URLs and update the URL property to the service provider with the shortest response time every 100 transactions, as well as when your application initially starts. This is not a normal ICMP ping - to determine the fastest transaction URL you must use the special Ping method inside the FDMSRegister class. (You may update your list of service provider URLs with the FDMSRegister class's ServiceDiscovery method).

AVSAndCVVOnly Method (Fdmshealthcare Class)

Performs an AVS/CVV only check using the specified Card data.

Syntax

public void AVSAndCVVOnly();

Remarks

This methods allows you to perform an AVS/CVV only request for verification purposes using the specified Card data. This does not authorize any funds on the card and only performs an AVS and CVV check. The TransactionAmount must be 0 for this transaction.

Note: For Retail transactions the EntryDataSource must be set to a manual entry value for this transaction.

FDMSHealthCare.Card.EntryDataSource = EntryDataSources.edsManualEntryTrack1Capable; FDMSHealthCare.Card.Number = "4444333322221111"; FDMSHealthCare.Card.ExpMonth = 9; FDMSHealthCare.Card.ExpYear = 2015; FDMSHealthCare.Card.CVVData = "999"; FDMSHealthCare.CustomerAddress = "123 Nowhere Ln"; FDMSHealthCare.CustomerZip = "90210"; FDMSHealthCare.TransactionAmount = "0"; FDMSHealthCare.AVSAndCVVOnly();

BalanceInquiry Method (Fdmshealthcare Class)

Performs a Balance Inquiry Request using the specified Card data.

Syntax

public void balanceInquiry();

Remarks

This methods allows you to perform a Balance Inquiry Request using the specified Card data. The balance amount will be returned via Balance. Note that Balance Inquiries do not place a hold on a cardholder's funds and are not captured.

FDMSHealthCare.Card.MagneticStripe = "B4444333322221111^SMITH/JOHN M ^031210100000033301000000008000000"; FDMSHealthCare.Card.EntryDataSource = edsTrack1; FDMSHealthCare.BalanceInquiry(); Industry regulations do not allow merchants or processors to store track data in any form of persistent storage. Failure to abide by this regulation can result in significant fines and other penalties.

Config Method (Fdmshealthcare Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

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.

GetDetailAggregate Method (Fdmshealthcare Class)

Returns an aggregate containing details of this transaction, which is then used for settlement.

Syntax

public String getDetailAggregate();

Remarks

This method returns an aggregate containing all of the required data to send a transaction to settlement. This aggregate must be passed to the FDMSSettle class's DetailAggregate array property in order to settle the transaction. If you wish to view or change any part of the aggregate (such as adding a gratuity or additional info for an Installment payment), you may use the FDMSDetailRecord class to do so.

Note: This method may only be called after a successful authorization. If the authorization was not successful (and the CaptureFlag is false) the method throws an exception.

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

FDMSRetail.AuthorizeTrack1() if (FDMSRetail.ResponseCaptureFlag) { FDMSSettle.DetailRecords.Add(new FDMSRecordType(FDMSRetail.GetDetailAggregate())); }

Interrupt Method (Fdmshealthcare Class)

Interrupts the current action.

Syntax

public void interrupt();

Remarks

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

Reset Method (Fdmshealthcare Class)

Clears all properties to their default values.

Syntax

public void reset();

Remarks

This method clears all properties to their default values.

ReverseFullAuth Method (Fdmshealthcare Class)

This performs a reversal of a fully-authorized transaction.

Syntax

public void reverseFullAuth(String transactionId, String validationCode, String approvalCode);

Remarks

If you wish to reverse a transaction that was authorized for an amount less than the TransactionAmount, you must use the ReversePartialAuth method. The ReverseFullAuth method can only be used to reverse fully authorized transactions. This means that the AuthorizedAmount field from the original transaction Response was empty. You do not have to reverse the full TransactionAmount from the original transaction, you may reverse only part of that TransactionAmount if you so desire.

To reverse a transaction, simply set the TransactionAmount property to a value equal to or less than the original TransactionAmount, and call the ReverseFullAuth method with the TransactionId, ValidationCode, and ApprovalCode fields from the original transaction Response. For instance:

FDMSHealthCare1.TransactionAmount = "20000"; // $200.00 FDMSHealthCare1.Authorize(); FDMSHealthCare1.TransactionNumber++; FDMSHealthCare1.TransactionAmount = "20000"; FDMSHealthCare1.ReverseFullAuth(FDMSHealthCare1.Response.TransactionId, FDMSHealthCare1.Response.ValidationCode, FDMSHealthCare1.Response.ApprovalCode);

If you reverse a transaction for less than original TransactionAmount, you must update the Detail Record for the associated transaction to reflect the new settlement amount. If you reverse the entire amount the original transaction MUST NOT be sent in the settlement.

Please note that the ReversePartialAuth method is only applicable to healthcare (FSA card) transactions, and may not be used for regular credit card transactions.

ReversePartialAuth Method (Fdmshealthcare Class)

This performs a reversal of a partially-authorized transaction.

Syntax

public void reversePartialAuth(String transactionId, String validationCode, String approvalCode);

Remarks

If an FSA card is authorized for an amount less than the TransactionAmount, the customer must use another form of payment for the remainder. If the customer does not have any other funds, the transaction that was just authorized may be reversed and the funds returned to the FSA card. To reverse a transaction, you need to set the TransactionAmount property with the AuthorizedAmount from the partially-authorized transaction, and then pass the TransactionId, ValidationCode, and ApprovalCode to this method. The following example shows how to reverse immediately after receiving a partial authorization.

FDMSHealthCare1.TransactionNumber++; FDMSHealthCare1.TransactionAmount = FDMSHealthCare1.Response.AuthorizedAmount; FDMSHealthCare1.ReversePartialAuth(FDMSHealthCare1.Response.TransactionId, FDMSHealthCare1.Response.ValidationCode, FDMSHealthCare1.Response.ApprovalCode);

A transaction that has been reversed in this manner MUST NOT be sent in the settlement.

Please note that the ReversePartialAuth method is only applicable to healthcare (FSA card) transactions, and may not be used for regular credit card transactions.

Connected Event (Fdmshealthcare Class)

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

Syntax

public class DefaultFdmshealthcareEventListener implements FdmshealthcareEventListener {
  ...
  public void connected(FdmshealthcareConnectedEvent e) {}
  ...
}

public class FdmshealthcareConnectedEvent {
  public int statusCode;
  public String description;
}

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 (Fdmshealthcare Class)

Fired when receiving a data packet from the transaction server.

Syntax

public class DefaultFdmshealthcareEventListener implements FdmshealthcareEventListener {
  ...
  public void dataPacketIn(FdmshealthcareDataPacketInEvent e) {}
  ...
}

public class FdmshealthcareDataPacketInEvent {
  public byte[] dataPacket;
}

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 (Fdmshealthcare Class)

Fired when sending a data packet to the transaction server.

Syntax

public class DefaultFdmshealthcareEventListener implements FdmshealthcareEventListener {
  ...
  public void dataPacketOut(FdmshealthcareDataPacketOutEvent e) {}
  ...
}

public class FdmshealthcareDataPacketOutEvent {
  public byte[] dataPacket;
}

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 (Fdmshealthcare Class)

This event is fired when a connection is closed.

Syntax

public class DefaultFdmshealthcareEventListener implements FdmshealthcareEventListener {
  ...
  public void disconnected(FdmshealthcareDisconnectedEvent e) {}
  ...
}

public class FdmshealthcareDisconnectedEvent {
  public int statusCode;
  public String description;
}

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 (Fdmshealthcare Class)

Information about errors during data delivery.

Syntax

public class DefaultFdmshealthcareEventListener implements FdmshealthcareEventListener {
  ...
  public void error(FdmshealthcareErrorEvent e) {}
  ...
}

public class FdmshealthcareErrorEvent {
  public int errorCode;
  public String description;
}

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the class throws an exception.

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 (Fdmshealthcare Class)

Fired after the server presents its certificate to the client.

Syntax

public class DefaultFdmshealthcareEventListener implements FdmshealthcareEventListener {
  ...
  public void SSLServerAuthentication(FdmshealthcareSSLServerAuthenticationEvent e) {}
  ...
}

public class FdmshealthcareSSLServerAuthenticationEvent {
  public byte[] certEncoded;
  public String certSubject;
  public String certIssuer;
  public String status;
  public boolean accept;
}

Remarks

This event is where the client can decide whether to continue with the connection process or not. 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 to continue or not.

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 (Fdmshealthcare Class)

Shows the progress of the secure connection.

Syntax

public class DefaultFdmshealthcareEventListener implements FdmshealthcareEventListener {
  ...
  public void SSLStatus(FdmshealthcareSSLStatusEvent e) {}
  ...
}

public class FdmshealthcareSSLStatusEvent {
  public String message;
}

Remarks

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

Status Event (Fdmshealthcare Class)

Shows the progress of the FDMS/Datawire connection.

Syntax

public class DefaultFdmshealthcareEventListener implements FdmshealthcareEventListener {
  ...
  public void status(FdmshealthcareStatusEvent e) {}
  ...
}

public class FdmshealthcareStatusEvent {
  public String message;
}

Remarks

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

CCCard Type

Contains the customer's credit card information.

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 throws an exception because none is present.

Fields

Constructors

public CCCard();

public CCCard( number,  expMonth,  expYear);

public CCCard( magneticStripe,  entryDataSource);

Certificate Type

This is the digital certificate being used.

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.

Fields

Constructors

public Certificate();

Creates a Certificate instance whose properties can be set. This is useful for use with CERTMGR when generating new certificates.

public Certificate( certificateFile);

Opens CertificateFile and reads out the contents as an X509 public key.

public Certificate( certificateData);

Parses CertificateData as an X509 public key.

public Certificate( certStoreType,  store,  storePassword,  subject);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

public Certificate( certStoreType,  store,  storePassword,  subject,  configurationString);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. ConfigurationString is a newline separated list of name-value pairs that may be used to modify the default behavior. Possible values include "PersistPFXKey", which shows whether or not the PFX key is persisted after performing operations with the private key. This correlates to the PKCS12_NO_PERSIST_KEY CyrptoAPI option. The default value is True (the key is persisted). "Thumbprint" - a MD5, SHA1, or SHA256 thumbprint of the certificate to load. When specified, this value is used to select the certificate in the store. This is applicable to cstUser, cstMachine, cstPublicKeyFile, and cstPFXFile store types. "UseInternalSecurityAPI" shows whether the platform (default) or the internal security API is used when performing certificate-related operations. After the store has been successfully opened, the class will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

public Certificate( certStoreType,  store,  storePassword,  encoded);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will load Encoded as an X509 certificate and search the opened store for a corresponding private key.

public Certificate( certStoreType,  storeBlob,  storePassword,  subject);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. StoreBlob is a string (binary- or base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

public Certificate( certStoreType,  storeBlob,  storePassword,  subject,  configurationString);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. StoreBlob is a string (binary- or base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

public Certificate( certStoreType,  storeBlob,  storePassword,  encoded);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a string (binary- or base64-encoded) containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will load Encoded as an X509 certificate and search the opened store for a corresponding private key.

FDMSResponse Type

Contains the response to the authorization.

Remarks

This type contains the results of a transaction made with the FDMSECommerce or FDMSRetail class. The fields contained by this type are listed below.

Fields

Constructors

public FDMSResponse();

Proxy Type

This is the proxy the class will connect to.

Remarks

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

Fields

Constructors

public Proxy();

public Proxy( server,  port);

public Proxy( server,  port,  user,  password);

Config Settings (Fdmshealthcare Class)

FDMSHealthcare 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 (Fdmshealthcare Class)

FDMSHealthCare Errors

HTTP Errors

TCPClient Errors

SSL Errors

TCP/IP Errors