DPSAuth SSL COM Object

Note: This has been deprecated in favour of PxPost or WebService API. Support for existing integrator is still available. If you are still using the DPSAuthSSL COM object, we recommend that you integrate for PxPost or WebService.

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

If you intend to install DPSAuthSSL on a 64-bit server, please mention this to our technical support team at the time of set up so that they can provide you with a compatible version of the COM object.

Installation Instructions

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

Figure 1 DPSAUTHSSL SETUP

DPS Auth

Installation Directory

Indicates the directory where DPSAUTHSSL files will be installed.

Install

To install DPSAUTHSSL, Press the Install Button.

Files Installed/Updated

Filename Descriptio
DPSAUTHS.DLLCOM 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.

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 Payment Express 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 Payment Express 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 YYYYMMDD 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

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

Note2: 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.

Note3: 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.

These properties are set when the DoAuthorize method returns.

DoAuthorize Response Properties

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 Payment Express 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.

Client Application loads DPSAuthSSL object properties.

Client Application calls DoAuthorize

DPSAuthSSL establishes connection with Payment Express Client

DPSAuthSSL sends transaction

Link between Payment Express client and Payment Express Server is interrupted

DPSAuthSSL returns failure (Success property set to false). StatusNeeded is set to true.

Client Application checks StatusNeeded property.

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

AcquirerReCo (output) Datatype: BSTR Max 2 bytes

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

AcquirerResponseText (output) Datatype: BSTR Max 32 bytes

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.

Amount (input) Datatype: BSTR Max 12 bytes

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. When submitting transactions for currencies with no decimal division of units such as JPY the AmountInput must be in an appropriate format e.g. "10".

AuthCode (output) Datatype: BSTR Max 64 bytes

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

BillingId (input/output) Datatype: BSTR Max 32 bytes

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

CardHolderResponseDescription (output) Data type: String Max 32 bytes

More detailed explanation of result. Intended for card holder.

CardHolderHelpText (output) Data type: String Max 32 bytes

More detailed explanation of result. Intended for card holder.

CardHolderName (input) Datatype: BSTR Max 64 bytes

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

CardHolderResponseText (output) Data type: String Max 32 bytes

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

CardNumber (input) Datatype: BSTR Max 19 bytes

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

CardName (output) Datatype: BSTR Max 16 bytes

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

ClientInfo (input) Datatype: BSTR Max 64 bytes

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

ClientType (input) Datatype: BSTR Max 1 byte

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.

Currency (output) Datatype: BSTR Max 4 bytes

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
DKK Danish Krone
EUR Euro
FRF French Franc
GBP United Kingdom Pound
HKD Hong Kong Dollar
JPY Japanese Yen
NZD New Zealand Dollar
SGD Singapore Dollar
THB Thai Baht
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
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). Note that the Validate transaction type is not enabled by default on live accounts. Please make a request to Payment Express Support if you would like to utilise this transaction type.

Username (input) Data type: String Max 32 bytes

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. TheSuccess property determines if the the transaction was successful or not and the StatusNeeded property determines ifDoStatus 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 Payment Express to confirm your account information.
D3 Blank password for PX Post. Please contact Payment Express to confirm your account information.
D5 Invalid Password for PxPost. Please contact Payment Express 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 ofCardHolderResponseText 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 fromCardHolderResponseDescription

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, orDpsBillingId 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 toDpsAuthSSL.DpsAuthSSLCtrl.

Most of the input paramaters are the same for both components. If you currently use Address1, Address2 and Address3input 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 standardTxnType (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 andPaxTravelAgentInfo.

Sample data:

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