Files Installed/Updated 

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

Uninstalling DPSAUTH

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

Using DPSAUTH.DLL

Load appropriate COM properties (Amount, TxnType etc) and then call method DoAuthorize to perform a transaction, either purchase, refund, authorisation or completion. 

Methods

DPSAUTH.DLL control offers a number of methods to initiate transactions, connect to the Payment Express Server and alter settings and retrieve information. This section details the available methods and their intended uses.

DoAuthorize

Amount, ClientId, CardHolderName, CardNumber, DateExpiry and TxnType properties must be loaded before calling DoAuthorize. Output properties are set before the return from the DoAuthorize method.

Input Properties

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

Note^2: ClientInfo is required for internet transactions. It is used to record the addressof the end user browser that initiated the transaction.

Note^3: DpxTxnRef is required for a Refund transaction only. Must contain the DpsTxnRef returned by the transaction to be refunded.

Note^4: The PreAuthNumber is required for Completion transactions. It is ignored for other transaction types.

Output Properties

These properties are set when the DoAuthorize method returns.

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. The delay is configurable from 1 second to 60 seconds for system wide users via a registry setting if desired.

DoGenerateTxnRef

Certain applications need to know what the TxnRef value is going to be prior to a transaction starting. This would cater for the situation where a program calling DpsAUth crashes while a transaction is in flight. The calling application can call DoGenerateTxnRef to generate a TxnRef which is returned in TxnRef property. This value may be stored by teh caller to hard disk or other non volatile storage and then DoAuthorize is called. DoAuthorize will use the TxnRef generated by DoGenerateTxnRef. Alternatively, the calling application can supply its own TxnRef as input to DoAuthorize (DoGenerateTxnref is not used).

DoStatus

DoStatus is used when a call to DoAuthorize fails and the StatusNeeded property of the DPSAuth object is set true. If DoAuthorize returns with the StatusNeeded value set to true, it indicates that DPSAuth has transmitted a transaction request to Payment Express Server, but a response was not received within a timeout period or the link to Payment Express Server or beyond failed while awaiting a response. In either of these circumstances, the result of the transaction is indeterminate. The DoStatus method should be used to retrieve the actual completion status. DoStatus uses the original ClientId and TxnRef values which uniquely identify the transaction to lookup the transaction at the Payment Express Host and return the results. Example:

Client Application instantiates DPSAuth object.

1. Client Application loads DPSAuth object properties.
2. Client Application calls DoAuthorize
3. DPSAuth establishes connection with Payment Express Client
4. DPSAuth sends transaction
5. Link between Payment Express client and Payment Express Server is interrupted
6. DPSAuth 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.

ClientId and 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. Payment Express Host 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 DPSAuth 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 DPSAuth object.

Properties returned upon DoStatus completion

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

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 arise when the link between the customer application (DPSAuth COM Object interface) and the Payment Express Server is interrupted the Payment Express Server 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.
i.e. 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

The following section provides a detailed description of each DPSAuth 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.

The ClientType property describes the origin of the transaction, for example; Vending machine or from a Web Server. It is also possible to capture magnetic stripe information (Track2 data) for Card Swipe transactions. (e.g.: a car park kiosk using a magnetic swipe to capture customer card information.

   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.

Response Codes

The client application should not interpret the ResponseCode property contents - it is provided as informational 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 DPSAuth Socket Errors

A socket error is indicated by S1-S5 in the ResponseCode result  after a call to DoAuthorize or DoStatus. The following table provides assistance in troubleshooting these errors.

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

Registry Settings

Several registry settings are read by DPSAUTH. All Subkeys are registered in the path:

HKEY_LOCAL_MACHINE\SOFTWARE\DirectPaymentSolutions
\DPSAUTH

For example, to specify a value for the ADDRESS option create a key of type REG_SZ in the following path:

HKEY_LOCAL_MACHINE\SOFTWARE\DirectPaymentSolutions
\DPSAUTH\SERVER

SERVER Subkey

Debugging/Trace Output

DPSAuth can produce a detailed log of its operation if the registry DWORD value 

HKEY_LOCAL_MACHINE\SOFTWARE\DirectPaymentSolutions
\DPSAUTH\TRACE\ENABLE

is set to 1. Output filename is DPSAUTH.LOG. This file will be created in the same directory as the DPSAUTH.DLL object resides. It is appended to (not created afresh after each instantiation of DPSAuth). Note: size of this file is limited to approximately 5 megabytes. If the file grows to this size, further trace info is discarded to prevent disk space issues.

Sample output for the log file:

11-02-2000 01:00:07 00000248/00000259 D_1B6F75>DPSAuth Init: ClientId=D_1B6F75
11-02-2000 01:00:07 00000248/00000259 D_1B6F75>Socket:Host Socket Connect

Each line consists of date, time, process ID, thread ID, ClientID followed by the trace/debug text.

Transaction Log

DPSAuth can produce a log of transactions transmitted and received if the registry DWORD value:

HKEY_LOCAL_MACHINE\SOFTWARE\DirectPaymentSolutions
\DPSAUTH\SERVER\TXNLOG

is set to 1. Output filename is DPSAUTH_TXNLOG.LOG. This file will be created in the same directory as the  DPSAUTH.DLL object resides. It is appended to (not created afresh after each instantiation of DPSAuth). Note: size of this file is limited to approximately 5 megabytes. If the file grows to this size, further trace info is discarded to prevent disk space issues.

Sample output for the log file:

14-05-2000 17:59:42 000000f9/00000071 D_230641>TX:AuthMsg: PreauthNum: TxnRef:00003eREF DATA Amt: Account:9997 Amt:000000000123 ClientType:W TxnInfo:TxnInfo Cvc2:1234 TxnType:P DaEx:0102 PAN:411111......1111 F48: CardHolderName:LastName Initials ReceiptEmail:expresstest@dps.co.nz ClientTypeEx: ClientVersion: SelectCaid: SelectCatid: HostDate: HostTime: LogonToken: ClientInfo:

14-05-2000 17:59:46 000000f9/00000071 D_230641>Rx:DPS AuthResponseMessage:AuthCode:075559F48: PreAuth: DateSettle:20000515 Stan:10 CardName:VISA TxnDate:14052000 TxnTime:175558 DaEx: Pan:...... TxnRef:00003eREF DATA ReCo:00 RespText:ACCEPTED Caid:10009053010 Catid:00905310 LogonToken: Currency: TestMode:1

Auth-Completion

Overview

Payment Express supports Auth/Completion. An "Auth" transaction verifies that funds are available for the requested card and amount and reserves the specified amount. A "Completion" 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) Completion

After a successful Authorization transaction, but within 7 days maximum, a "completion"  (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

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. DPS has numerous applications available for integrating with common merchant applications.

To add a card for future rebilling, call the DoAuthorize method with the TxnType property set to "BillAddCard". If the BillAddCard request is made, the following properties need to be loaded:

CardHolderName (optional, strongly recommended)
MerchantReference
CardNumber
DateExpiry
BillingId (optional, if customer supplied billing id is used, rather than DpsBillingId determined by Payment Express)

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

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"