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.
Download the latest DPSAUTHSSL COM Object (v 188.8.131.52) kit and run the Setup program.
Figure 1 DPSAUTHSSL SETUP
Indicates the directory where DPSAUTHSSL files will be installed.
To install DPSAUTHSSL, Press the Install Button.
|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.
To uninstall DPSAUTHSSL from a computer, use the Settings/Control Panel/ Add/Remove programs utility. Select DPSAuthSSL and press "Add/Remove".
Load appropriate COM properties (Amount, TxnType etc) and then call method DoAuthorize to perform a transaction.
Load appropriate COM properties (Amount, TxnType etc) and then call method DoAuthorize to perform a transaction.
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.
|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.
|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.|
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.
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 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
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.
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.
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.
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
|Ivr||IVR (Interactive Voice response)|
|Vend||Vending device or kiosk.|
|Internet||Internet (WebServer etc)|
|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:
|GBP||United Kingdom Pound|
|HKD||Hong Kong Dollar|
|NZD||New Zealand Dollar|
|USD||United States Dollar|
|SBD||Solomon Islands Dollar|
|PGK||Papua New Guinea Kina|
|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.
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.
|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|
|JH||AddBillCard failed for transaction|
|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:
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 ".
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.
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.
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 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)
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.
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
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.