DPSAuth SSL COM Object

DPS AuthSSL is a COM object that encapsulates the XML interface and connects directly to the Payment Express^® Host via HTTPS Posts.

• Installation Instructions
• Function Calls
• Exception Handling
• COM Object Properties
• Auth/Complete Transactions
• Token Billing
• Refund Transactions
• Migrating from the DPSAuth COM object
• Extended Airline Booking Data
  

Requirements/Downloads:

DPSAUTHS.DLL Sample Code ASP Cold Fusion Test account. Apply online at https://www.paymentexpress.com/pxmi/apply

Installation Instructions

Download the latest DPSAUTHSSL COM Object (v 1.8.0.9) kit and run the Setup program.

Figure 1 DPSAUTHSSL SETUP

Installation Directory

Indicates the directory where DPSAUTHSSL files will be installed.

Install

To install DPSAUTHSSL, Press the Install Button.

Files Installed/Updated 

Filename	Description
DPSAUTHS.DLL	COM Component
DPSRSATH.EXE	Removes (uninstalls) from system.

Only DPSAUTHS.DLL is required for operation. If automated removal (uninstall) is not required, DPSRSATH.EXE may be deleted after install.

Uninstalling DPSAUTHSSL

To uninstall DPSAUTHSSL from a computer, use the Settings/Control Panel/ Add/Remove programs utility. Select DPSAuthSSL and press "Add/Remove".

Using DPSAUTHS.DLL

Load appropriate COM properties (Amount, TxnType etc) and then call method DoAuthorize to perform a transaction.

Methods

DPSAUTHSSL.DLL control offers methods to initiate transactions and to retrieve results of previous transactions.

DoAuthorize Request Properties

Amount, CardNumber, ClientType, DateExpiry, Password, TxnType, Username  properties must be loaded before calling DoAuthorize. Output properties are set by DPSAUTHSSL before the return from the DoAuthorize method.

Input Properties

Parameter	Required	Description
Username	Yes	Combined with Password, selects account
Password	Yes	Combined with Username, selects account
Amount	Yes	Amount of Purchase or Refund in 1.23 format
BillingId	No	Specified for  token billing transactions
CardHolderName	No	Card Holder Name as on Card.
CardNumber	Yes1	Credit Card Number. Left justified, no embedded spaces or other delimitors.
ClientInfo	No2	Browser IP Address etc.
ClientType	Yes1	Indicates transaction source (Web, vending machine etc)
Currency	No	You will need to specify a currency here if you will be doing transactions in multiple currencies.
Cvc2	No	Card Verification number. This number is found on the back of a credit card in the signature panel - it is different from the embossed card number and provides an additional safety check.
DateExpiry	Yes1	Expiry date of card in 4 digit MMYY format. Note: do not include "/" or other delimitors.
DpsBillingId	No	The Billing Id generated by DPS when adding a card for recurring billing. Needed for rebilling transactions when you do not use your own BillingId.
DpsTxnRef	Yes3	Only required for Refund transactions or Complete.
EnableAddBillCard	No	Needed for recurring billing transactions when adding a card to the DPS system. Set element to 1 for true and 0 for false
MerchantReference	No	64 character free text field
EnablePaxInfo	No	Used for Airline Reservation Systems. Enable collection of extended booking data to go through to the acquirer if they support it.
PaxDateDepart	No	Used for Airline Reservation Systems. Date departing in DD/MM/YY format.
PaxName	No	Used for Airline Reservation Systems. Passenger Name.
PaxLeg1	No	Used for Airline Reservation Systems. Leg 1 flight information.
PaxLeg2	No	Used for Airline Reservation Systems. Leg 2 flight information
PaxLeg3	No	Used for Airline Reservation Systems. Leg 3 flight information
PaxLeg4	No	Used for Airline Reservation Systems. Leg 4 flight information
PaxTicketNumber	No	Used for Airline Reservation Systems. Passenger Ticket Number. Format: AAATTTTTTTTTTC
PaxCarrier	No	Used for Airline Reservation Systems. 2 character airline identifier.
PaxOrigin	No	Used for Airline Reservation Systems. Passenger Origin.
PaxTravelAgentInfo	No	Used for Airline Reservation Systems. Travel Agent description field.
EnableCpcData	No	Enable, if you wish to send CPC data for American Express extended data.
CpcData1	No	Corporate Purchase Card Data 1 field. Merchant Corp Ref.
CpcData2	No	Corporate Purchase Card Data 2 field. Card Holder Reference.
ReceiptEmailAddress	No	Address to email a receipt to. Not currently implemented
TxnData1	No	Optional Free Text
TxnData2	No	Optional Free Text
TxnData3	No	Optional Free Text
TxnRef	No	A unique identifier for the transaction. You can supply your own identifier. If you don't set this property then a unique identifier will be generated for you.
TxnType	Yes	P=Purchase, R=Refund, A=Auth, C=Complete, V=Validate

Note^1: CardNumber, ClientType,DateExpiry are not required for Complete transactions and are ignored if present.

Note^2: ClientInfo is required for internet transactions. It is used to record the address of the end user browser that initiated the transaction and is useful for recording country of origin of transactions.

Note^3: DpxTxnRef is required for a Refund transaction or Complete transaction only. Must contain the DpsTxnRef returned by the original Purchase or Authorisation transaction to be refunded or completed.

DoAuthorize Response Properties

These properties are set when the DoAuthorize method returns.

Parameter	Description
AcquirerReCo	2 character response code from the acquiring bank. Not always available.
AcquirerResponseText	Response text associated with ReCo from the acquiring bank. Not always available.
AuthCode	Authorisation Code (up to 64 character alphanumeric)
CardName	Card used (Visa,MasterCard,Bankcard etc)
DateSettlement	Date transaction will be settled to Bank Account in YYYYMMDD format. This is supported for most, but not all banks and card acquirers. If the DateSettlement is not available from the banking network, the DateSettlement will contain the current calendar date.
DpsBillingId	Contains the BillingId generated by DPS when adding a card for recurring billing.
DpsTxnRef	Unique transaction identifier returned for every transaction. Required input for Refund transactions or Complete transactions.
ResponseCode	2 character response code.
ResponseText	Response Text associated with ResponseCode
Retry	If true; retry transaction, if false do not retry.
StatusNeeded	True if transaction result is unknown.
Success	True if transaction successful, False if declined or unsuccessful
TraceData	This will contain a log of any errors in the event of a failure.
TxnRef	An identifier for the transaction. Will be the same value that was supplied as an input. If not supplied, a TxnRef value will be generated internally by DPSAuthSSL.

DoDelay

Suspends execution in a CPU-efficient manner for 5 seconds. A convenient delay for ASP or Visual Basic programmers to use between calls to DoStatus. 

DoGenerateTxnRef

Generates a unique value for the TxnRef property. You will only need to call this method if you want get the next TxnRef value before calling DoAuthorize. DoAuthorize will use the TxnRef generated by DoGenerateTxnRef. If you don't set TxnRef to your own value (or call DoGenerateTxnRef) then a new TxnRef value will be generated for you by DoAuthorize. Generating the TxnRef value before calling DoAuthorize gives you the opportunity to store it to non-volatile storage before calling DoAuthorize. If your application were to crash while a transaction was in progress then you could use the TxnRef value you stored to retrieve the result of the transaction with DoStatus.

DoStatus

DoStatus is used when a call to DoAuthorize fails and the StatusNeeded property of the DPSAuthSSL object is set to true. If DoAuthorize returns with the StatusNeeded value set to true, it indicates that the result of the transaction is unknown. The response from the Payment Express server was not received within a timeout period. The DoStatus method must be used to retrieve the actual transaction status. DoStatus uses the TxnRef value from the original transaction to lookup the transaction on the Payment Express server and return the results. Example:

Client Application instantiates DPSAuthSSL object.

1. Client Application loads DPSAuthSSL object properties.
2. Client Application calls DoAuthorize
3. DPSAuthSSL establishes connection with Payment Express Client
4. DPSAuthSSL sends transaction
5. Link between Payment Express client and Payment Express Server is interrupted
6. DPSAuthSSL returns failure (Success property set to false). StatusNeeded is set to true.
7. Client Application checks StatusNeeded property.
8. Client Application performs following error recovery: Pseudo Code:
   While StatusNeeded is true
       Client Application calls DoDelay
       Client Application calls DoStatus
   End While

Once the client application has confirmed the result of the transaction with the Payment Express server with the DoStatus call, normal processing of subsequent transactions using DoAuthorize method can resume.

TxnRef property must be loaded before calling DoStatus. Output properties are set before the return from the DoAuthorize method. This method is provided to retrieve information about a previous transaction started by DoAuthorize. This would not ordinarily be required, but should be performed automatically if the DoAuthorize method does not return a host-originated response. That is, if the StatusNeeded property is returned as True. DoStatus is called with the original transaction reference, as returned in TxnRef property after calling DoAuthorize. Ensure that this TxnRef value is loaded in TxnRef property before calling DoStatus. The Payment Express server maintains transaction results for at least 48 hours. Therefore, calls to DoStatus can rely on results being available for at least this period following transmission of the original transaction.

If a DoStatus method is made for a transaction that was successfully processed by Payment Express Host and was accepted by the bank, then the DoStatus method will result in the DPSAuthSSL properties being set exactly as they would have been for the original transaction result, regardless of whether the original transaction result was actually received by the DPSAuthSSL object.

Properties returned by DoStatus

Only the following properties are returned by a successful call to DoStatus method.

AcquirerReCo

AcquirerResponseText

AuthCode

BillingId

CardName

CardHolderResponseDescription

CardHolderHelpText

CardHolderResponseText

DateSettlement

DpsBillingId

DpsTxnRef

MerchantResponseDescription

MerchantHelpText

MerchantResponseText

ResponseCode

ResponseText

Retry

StatusNeeded

Success

TxnRef

Exception Handling

Refer to DoStatus method. The Payment Express architecture does not provide for customer applications to "reverse" or "back out" transactions once started. Exception conditions could arise when the link between the customer application (DPSAuthSSL COM Object interface) and the Payment Express host is interrupted before the Payment Express Host has transmitted a response to a transaction request. In this circumstance, the result of the transaction is indeterminate for the customer application because no response was received from the Payment Express server.
In this case the transaction can not be assumed to have "failed". In this case, the application must enter a "recovery" mode until the actual status of the transaction can be ascertained. The mechanism to perform this error recovery is easily accomplished using the procedure outlined in the DoStatus method documentation.

Properties Description

The following section provides a detailed description of each DPSAuthSSL property and indicates if the property is used as input or as output. If a property is marked as input, it is not updated or output when a call to DoAuthorize or DoStatus returns. This is important when a call is made to DoStatus for example, the original contents of Amount as input to the DoAuthorize call are not output by DoStatus.

Response code from the acquiring bank. Not provided by all acquirers.

Response text associated with the response code from the acquiring bank. May be useful for understanding why a transaction was declined. Not provided by all acquirers.

Total Purchase, Refund, Auth or Complete amount. Format is d.cc where d is dollar amount (no currency indicator) and cc is cents amount. for example, $1.80 (one dollar and eighty cents) is represented as "1.80", not "1.8". A string value is used rather than the conventional Currency Datatype to allow for easy integration with Web applications. Note that the original  value used as input to  DoAuthorize  is not returned by any subsequent DoStatus and must be stored by the application if required. Maximum value allowable is $99,999.99. Note that acquirer or card limits may be lower than this amount.

Authorisation code. A variable length string returned by Card Acquirer. For credit card transactions, contains the authorisation code.

BillingId generated by the customer system. This could be a customer number and is used as input to DoAuthorize to rebill an existing customer. If EnableAddBillCard

More detailed explanation of result. Intended for card holder.

More detailed explanation of result. Intended for card holder.

The cardholder name as it appears on customer card. Optional and may be left blank.

Brief (Max 32 character) response text intended for card holder.

The card number. No leading or embedded blanks are permitted. Must contain a numeric value. Not required for Complete or Refund TxnType.

The card type used for the transaction. Note that the list may be expanded as support for new cards is added. The CardName format is to capitalize the first letter with remaining letters in lowercase. 

CardName Value	Description
Amex	American Express
Bankcard	Bank Card
Diners	Diners Card
Jcb	JCB
Mastercard	Mastercard
Visa	Visa

Internet Address of the browser where credit card information was entered. required if available. 

Type of client transaction - Choose from the following values

Value	Meaning
Ivr	IVR (Interactive Voice response)
Vend	Vending device or kiosk.
Internet	Internet (WebServer etc)
MOTO	Mail/Telephone Order
Mail	Mail Order Transaction
Tel	Telephone Order Transaction
C	Card Swipe And Attendant Present

The ClientType property describes the origin of the transaction, for example; Vending machine or from a Web Server. 

Indicates currency used for this transaction. If blank, currency will be determined by the bank account used which is selected using the Username/Password details. Not all acquirers can support multiple currencies. Valid valus for Currency are:

CAD	Canadian Dollar
CHF	Swiss Franc
EUR	Euro
FRF	French Franc
GBP	United Kingdom Pound
HKD	Hong Kong Dollar
JPY	Japanese Yen
NZD	New Zealand Dollar
SGD	Singapore Dollar
USD	United States Dollar
ZAR	Rand
AUD	Australian Dollar
WST	Samoan Tala
VUV	Vanuatu Vatu
TOP	Tongan Pa'anga
SBD	Solomon Islands Dollar
PGK	Papua New Guinea Kina
MYR	Malaysian Ringgit
KWD	Kuwaiti Dinar
FJD	Fiji Dollar

Card Verification Code 2 number.  Some payment cards are issued with additional identifying information. These cards will have the account number printed on the signature panel of the card followed by a three or four digit value. This value is generated by the issuing bank and can be verified by the bank. Payment card brands have varying names for the value:

   American Express:  Four-digit batch code (4DBC)  
   MasterCard: Card Verification Code 2 (CVC2) 
   Visa: Card Verification Value 2 (CVV2)

Supplying this value provides an indication of that the person participating in a transaction had physical possession of the card at some point in time. This is not currently implemented by all acquirer and may not necessarily be checked

Indicates card expiry date. Format is MMYY where MM is month 01-12 and Year 00-99. do not insert "/" or other delimiter. Not required for Complete or Refund transactions.

Indicates Date of settlement (when money will be deposited in Merchant bank account)  if this is supported by the Acquirer, otherwise contains the date the transaction was processed in YYYYMMDD format.

Returned for a successful billing transaction if EnableAddBillCard is set. Supplied as input to rebill a transaction if BillingId is not used. It is not allowed to specify both a BillingId and a DpsBillingId when rebilling a transaction.

Returned for every transaction. If the transaction was approved, DpsTxnRef can be used as input to a Refund transaction. Used to specifiy a transaction for refund without supplying the original card number and expiry date.

If set to true on input to DoAuthorize, the details necessary to charge the same customer in the future are securely stored. A BillingId may optionally be attached on input. DpsBillingId is returned. See Token Billing section for details on using this feature. 

Free Text Field for use by merchant (could be order number, customer number etc.).

Used with Username to determine account for settlement. Payment Express clients can be set up with more than one bank account. Each transaction may be designated for a specific account if required. 

Used for Airline Reservation Systems. Enable collection of extended booking data to go through to the acquirer. Value will need to be true (1) if ticket information is included with the transaction.

Used for Airline Reservation Systems. Date departing in YYYYMMDD format. Numeric.

Used for Airline Reservation Systems. Passenger Name. Alphanumeric.

Used for Airline Reservation Systems. Leg 1 flight information. Alphanumeric.

Used for Airline Reservation Systems. Leg 2 flight information. Alphanumeric.

Used for Airline Reservation Systems. Leg 3 flight information. Alphanumeric.

Used for Airline Reservation Systems. Leg 4 flight information. Alphanumeric.

Used for Airline Reservation Systems. Passenger Origin of departure. Alphanumeric.

Used for Airline Reservation Systems. Passenger Ticket Number. Format: AAATTTTTTTTTTC. AAA is airline code, TTTTTTTTTT (10 chars) is actual ticket number and C is check digit. Numeric.

Used for Airline Reservation Systems. 2 character airline identifier. Alphanumeric.

Used for Airline Reservation Systems. Travel Agent description field. Also known as the Booking Reference on some of DPS screens. Alphanumeric free text field.

Response Code generated by DPS Server (for locally declined transactions) or by the Card Acquirer (for host originated responses).  The ResponseCode should not be checked by the client application using DPSAuthSSL as these  values differ according to acquirer. Use the Success property to check for successful completion of a transaction. Refer to section Response Codes for a list of valid response codes generated by acquirers and locally by the Payment Express Server or DPSAUTHSSL control.

Response Text associated with the response code of the transaction

If true, then the transaction should be resent - the transaction was declined due to a communication error or transmission error. If false, then the transaction should not be resent regardless of whether it was accepted or declined.

If false, indicates that the result was successfully retrieved from the Payment Express server, or that no message was sent to Payment Express because of a local error. No further action is required in this case. If true after a call to DoAuthorize, a message was sent to Payment Express, but a valid response was not received. In this, case, the result of the transaction is unknown and error recovery is required. See DoStatus method for further information.

Indicates success or failure of a method call.

Available from version 1.4. Displays error message tracing in the event of a failure. If successful the following type of message will be displayed - "csdTransact:www.paymentexpress.com SendRequest OK".

Optional free text fields. Usually assigned at origin website.

Reference number for the transaction. Maximum 16 alphanumeric characters. This is generated and maintained by DPSAuthSSL for each transaction and returned on output. Used as input for DoAuthorize and DoStatus transactions. If you set TxnRef to your own value than DPSAuthSSL will not overwrite it. It's important for TxnRef to be unique for each transaction or calls to DoStatus could return the details for the wrong transaction. May be generated by DoTxnGenerateTxnRef.

TxnType  (input) Datatype: BSTR 1 byte 

Value	Meaning
A	Authorize - amount is authorised, no funds transferred.
C	Complete a previous authorisation - funds are transferred.
P	Purchase - Funds are transferred immediately.
R	Refund - Funds transferred immediately. Must be enabled as a special option.
V	Validation Transaction. Effects a $1.00 Auth to validate card details including expiry date. Often utilised with the EnableAddBillCard property set to 1 to automatically add to Billing Database if the transaction is approved (validate).

Used with Password to determine account for settlement. Payment Express clients can be set up with more than one bank account. Each transaction may be designated for a specific account if required. 

Response Codes

The client application should not interpret the ResponseCode property contents - it is provided as information only. The Success property determines if the the transaction was successful or not and the StatusNeeded property determines if DoStatus error recovery is needed.

Troubleshooting DPSAuthSSL Connection Errors

A connection issue is indicated by the data in the ResponseCode result  after a call to DoAuthorize or DoStatus. The following table provides assistance in troubleshooting these errors.

Error Code	Explanation
99	DPSAuthSSL cannot connect to the Payment Express Host. This could be a number of things including proxy server, no internet connection. You can get the "TraceData" output property to help find the reason why there is a connection problem.
AQ	Amex Not Accepted
AR	Diners Not Accepted
AS	JCB not configured
AT	RFS/Farmers not configured
J1	Refund not matched
J3	Refund amount attempted greater than purchase amount
J4	Transaction Already Completed
J6	Transaction not forund for refund
J7	Refund not matched
JA	BillingID not Matched
JC	Invalid BillingId
JD	Invalid DpsBillingId
JH	AddBillCard failed for transaction
U9	Uplink Timeout
D2	No such user for PXPost. Please contact DPS to confirm your account information.
D3	Blank password for PX Post. Please contact DPS to confirm your account information.
D5	Invalid Password for PxPost. Please contact DPS to confirm your account information.

It is recommended that developers utilize the following approach to display transaction results to the web browser:

Accepted Transaction

An accepted transaction is indicated by a Success property being set to true. In this case, display contents of CardHolderResponseText on the Browser.

Declined or Rejected transaction Scenario #1

This result is conveniently indicated by the Success property being set to false and the StatusNeeded property being set to false. It is essential that the web application checks both properties. In this case the web application should display the contents of CardHolderResponseText. Additional information should ideally be displayed from CardHolderResponseDescription

For Display of cardholder response information, Display the contents of a more detailed description of the reason for declination is available  in the CardHolderResponseDescription property

Declined or Rejected transaction Scenario #2

WhenStatusNeeded is True the result of the transaction (accepted or otherwise) is not known for sure. This scenario is covered in the section of this document entitled "Exception Handling ".

Auth-Complete

Overview

Payment Express supports Auth/Complete. An "Auth" transaction verifies that funds are available for the requested card and amount and reserves the specified amount. A "Complete" transaction is sent at a later date to cause funds transfer for the previously authorised amount, or a smaller amount if the total original value is no longer required. This transaction set is useful when the merchant needs to ensure that funds up to a certain limit are available but the actual total amount is not yet known or goods or services have not yet been delivered.

Operation

1) Authorization

Call DoAuthorize with TxnType set to "A" for for the amount to be authorised. The Auth response contains a DpsTxnRef. The funds are not transferred from the cardholder account. 

2) Complete

After a successful Authorization transaction, but within 7 days maximum, a "Complete"  (TxnType="C") transaction must be sent containing the DpsTxnRef returned by the Auth transaction.

Token Billing

Overview

Token Billing allows for regular billing of a cardholder card, under the control of the merchant, without requiring the merchant to either store sensitive card data securely or to obtain credit card details every time a new payment is requested. This functionality is implemented by proving the ability for a merchant to request payment express to capture and store credit card number and expiry date and to link these stored details to a merchant supplied "BillingId". The BillingId is a 32 character field that contains a reference that is unique to the merchant's customer, that will be associated with the credit card information stored securely at Payment Express. This is undertaken during the Setup Phase. For subsequent charges to the card (Rebill Phase), the merchant does not need to supply the card number or exopiry date, only the BillingId originally associated during the Setup Phase

1) Setup Phase

A setup phase involves loading a card into Payment Express. Optionally the setup phase can include an online $1.00 authorisation (Validate) transaction which will determine that the card is valid and not on hot or stolen card lists and that it has the correct expiry date.

Customers will typically integrate directly into their call centre or web application for the setup phase.

To add a card for future rebilling, call the DoAuthorize method with the following properties -

TxnType property set to "P" (Purchase)
EnableAddBillCard property set to "1" (true).
CardHolderName (optional, strongly recommended)
MerchantReference
CardNumber
DateExpiry
BillingId (optional, as if none is given then a DpsBillingId determined by Payment Express will be returned to use)

2) Rebill Phase

The merchant application or Batch processor requests a new transaction and supplies the appropriate BillingId, or DpsBillingId a MerchantReference which appears on reports and the amount to be charged. EnableAddBillCard value will be set to 0 (False) for the rebill phase.
Payment Express retrieves the credit card number and expiry date stored in the Setup Phase and a purchase transaction is formatted and processed to the card acquirer.

Refunds

DPS AuthSSL is capable of handling refunds (credit) transactions, however you will need to match the original Purchase or Complete transaction for this to happen. The matching is done with the DpsTxnRef given from the response of a purchase or complete transaction. You are able to do multiple refund transactions to the maximum amount of the original matched transaction.
The TxnType will be R.

The Payment Manager is provided to merchants with all integrated solutions by DPS, so there is a ready built interface to handle refund transactions already. However, if you wish to integrate refunds into your own interfaces the following input properties need to be provided for a refund transaction:

TxnType = R
DpsTxnRef
MerchantReference
Amount

Migrating from the DPSAuth COM object

The first change is the instantiation of the COM object. You will need to change the name from DpsAuth.DpsAuthCtrl to DpsAuthSSL.DpsAuthSSLCtrl.

Most of the input paramaters are the same for both components. If you currently use Address1, Address2 and Address3 input properties, you can use TxnData1, TxnData2 and TxnData3 properties instead for DPSAuthSSL.

ServerAddress and ServerPort properties aren't needed anymore.

The last change is if you use recurring billing. Instead of using the TxnType as BillAddCard you will just use your standard TxnType (Auth, Purchase), but with a further input property EnableAddBillCard.

Extended Airline Booking Data

The COM object is capable of taking extended booking information, which is used to display on cardholders statements.

If you would like to add booking information to your transaction details you will need to set the EnablePaxInfo input property to true (1) and you will be able to use the following properties -
PaxDateDepart, PaxName, PaxLeg1, PaxLeg2, PaxLeg3, PaxLeg4, PaxOrigin, PaxTicketNumber, PaxCarrier and PaxTravelAgentInfo.

Sample data:

PaxDateDepart = "20081224"
PaxName = "Brian Smith"
PaxOrigin = "AKL"
PaxLeg1 = "SYD"
PaxLeg2 = "LAX"
PaxLeg3 = "LHR"
PaxLeg4 = "AKL"
PaxTicketNumber = "0030458343"
PaxCarrier = "QB"
PaxTravelAgentInfo = "BA1234567890"