DPSAUTH 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 DPSAuth COM object, we recommend that you integrate for PxPost or WebService.

DPSAuth is a COM object that encapsulates the XML interface to a Payment Express Server. DPSAuthSSL COM object can be used instead with a similar component reference, but sending https posts to the Payment Express Host directly, without the need for the PX Application Server. For customers using Microsoft Site Server software, please see DPSAuthP for a separate software component.

Technical Specifications/Features:

  • Risk Management

    This is an optional tag that allows transactions be checked against a Hot Card list before being processed.

  • Multiple Product Selection

    Transactions can be flagged with a product code to allow for transaction categorization on reports.

  • Multiple Account Selection

    Transactions can be redirected to different merchant accounts depending on the Account code that is specified with each transaction.

  • Reference fields for reconciliation

    Optional reference fields are available to hold information that will appear on transaction reports.

  • Multi-Currency Support

    Charge cuurrency can be explicitly specified on a per transaction basis or implicitly via product or account selection.

Installation Instructions

Download the latest DPSAUTH COM Object kit and run the DPSAUTH_XXX.EXE (XXX is software version).

Figure 1 DPSAUTH SETUP

DPSAUTH SETUP

Installation Directory

Indicates the directory where DPSAUTH files will be installed.

Payment Express Server TCP/IP Address

If the DPSAUTH COM Object is to be installed on the same machine as the Payment Express Server, the Local System check box should be checked as shown in Figure 1. If the Payment Express Service is installed on a remote system, remove the check from the "Local System" box and enter the TCP/IP address or hostname of the NT System running Payment Express in the entry field adjacent.

It is also possible for the application using DPSAuth control to set the ServerAddress andServerPort value prior to calling the DoAuthorize method. This is determined by the customer application at runtime.

Install

To install DPSAUTH, Press the Install Button.

Input Properties

Filename Description
DPSAUTH.DLL COM Component
DPSRAUTH.EXE Removes (uninstalls) from system.
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".

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

Parameter Required Description
Address1 No Cardholder Billing Address Line 1 (From Statement)
Address2 No Cardholder Billing Address Line 2 (From Statement)
Address3 No Cardholder Billing Address Line 3 (From Statement)
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 No1 Credit Card Number. Left justified no embedded spaces or other delimitors.
Cavv No The merchant and acquirer will need to include the CAVV in the transaction details in order to demonstrate that authentication occurred. Used for 3D secure transactions only.
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.
IssuerName Yes1 Name of bank that issued the card.
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.
PaReq No The merchant and acquirer will need to include the PaReq in the transaction details in order to demonstrate that authentication occurred. Used for 3D secure transactions only.
PaRes No The merchant and acquirer will need to include the PaRes in the transaction details in order to demonstrate that authentication occurred. Used for 3D secure transactions only.
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.
PreAuthNumber No4 Used as input for a Completion Transaction
ReceiptEmailAddress No Address to email a receipt to. Not currently implemented
TxnType Yes P=Purchase R=Refund A=Auth C=Completion BillAddCard
ServerAddress No Adress of the Payment Express application server
ServerPort No Internal port that the Payment Express server listens on. Default is 3004 if not set.
Xid No The merchant and acquirer will need to include the Xid in the transaction details in order to demonstrate that authentication occurred. Used for 3D secure transactions only.

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

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

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

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

Parameter Description
AuthCode Authorisation Code (up to 64 character alphanumeric)
CardName Card used (Visa MasterCard Bankcard etc)
ClientId This value is set immediately after control is created. it uniquely identifies the control instance and is a hashed value based on hostname and process ID.
DateSettlement Date transaction will be settled to Merchant Bank Account in YYYYMMDD format
DpsTxnRef Unique transaction identifier returned for every transaction. Reuqired input for refund transactions.
HostDate Date Transaction Processed YYYYMMDD format
HostTime Time transaction processed (HHMMSS format)
PreAuthNumber Only set by Auth transaction response
ResponseCode 2 character response code
ResponseText Response Text associated with ResponseCode
Retry If true retry transaction if false do not retry.
Success True if transaction successful False if declined or unsuccessful
TxnRef Set to uniquely identify transaction. This is an internal reference maintained by the ActiveX control and is set when the transaction is started and is available for storage by the client application when the
VersionMajor Set to the control Version 1-9
VersionMinor Set to the Control Version Minor 1-9
VersionRevision Set to the control version revision level 1-99

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.

  • Client Application loads DPSAuth object properties.,
  • Client Application calls DoAuthorize,
  • DPSAuth establishes connection with Payment Express Client,
  • DPSAuth sends transaction,
  • Link between Payment Express client and Payment Express Server is interrupted,
  • DPSAuth 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

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

Address1 (input) Datatype: BSTR Max 32 Bytes

Cardholder Billing Address Line1 - may be used by Payment Express Host for additional verification purposes. Not currently implemented.

Address2 (input) Datatype: BSTR Max 32 Bytes

Cardholder Billing Address Line2 - may be used by Payment Express Host for additional verification purposes. Not currently implemented.

Address3 (input) Datatype: BSTR Max 32 Bytes

Cardholder Billing Address Line3 - may be used by Payment Express Host for additional verification purposes. Not currently implemented.

Amount (input) Datatype: BSTR Max 12 bytes

Total Purchase, Refund, Auth or Completion 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.

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. For Auth/Completion operation, store this value after an Auth transaction and use the contents as input to the PreAuthNumber prior to the subsequent Completion transaction.

AllowClientStandIn (input) Boolean true/false

Default false. If set to true, allows Payment Express Client to "Stand In" for the Payment Express Server if communications or other temporary problems prevent online authorisation. This functionality is not implemented in the current Payment Express Server and this property is reserved for future use.

AllowServerStandIn (input) Boolean true/false

Default false. If set to true, allows Payment Express Server to "Stand In" for the Bank Host if communications or other temporary problems prevent online authorisation. This functionality is not implemented in the current Payment Express Server and this property is reserved for future use.

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

CardHolderResponseText (output) Data type: String Max 32 bytes

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

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.

CardNumber (input) Datatype: BSTR Max 20 bytes

The card number. No leading or embedded blanks are permitted. Must contain a numeric value.

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. This field is returned only for Purchase, Refund and Auth transactions. It is not returned for Completion transactions, because a completion transaction assumes a matching, successful Auth transaction.

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

Cavv (input) Datatype: BSTR Max 28 bytes

Set the CAVV (Cardholder authentication Verification Value) when a transaction has been authenticated through 3D authentication. CAVV contains a 20 byte value that has been Base64 encoded to 28 bytes result. The merchant and acquirer will need to include the CAVV in the authorization in order to demonstrate that authentication occurred.

ClientId (output) Datatype: BSTR Max 8 bytes

Uniquely identifies a client accessing DPSAUTH. This value is set by DPSAuth COM object upon object instantiation. Not usually used.

ClientInfo (input) Datatype: BSTR Max 64 bytes

Internet Address of the browser. Not usually used.

ClientType (input) Datatype: BSTR Max 1 byte

Type of client transaction - Choose from the following values

Value Meaning
I IVR (Interactive Voice response)
N Customer Not Present (generic)
V Vending device or kiosk.
W Internet (WebServer etc)
M Mail Order Transaction
T Telephone Order Transaction
C Card Swipe And Attendant Present
S Card Swipe and no attendant present

Properties

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.

Currency (output) Datatype: BSTR Max 4 bytes

Indicates currency used for this transaction. Currency will be determined by the bank account used which is selected using the Account property. E.g.: NZD or AUD or USD.

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

Cvc2 (input) Datatype: BSTR Max 4 bytes

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.

DateExpiry (input) Datatype: BSTR Max 4 bytes

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

DateSettlement (output) Datatype: BSTR Max 8 bytes

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.

DpsBillingId (input/output) Datatype: BSTR Max 16 bytes

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 DpsBillingIdwhen rebilling a transaction.

DpsTxnRef (input/output) Datatype: BSTR Max 16 bytes

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.

HostDate (output) Datatype: BSTR Max 8 bytes

Indicates Date of transaction as recorded by Bank Host in YYYYMMDD format. This field may be blank if the transaction was rejected locally or otherwise not processed by the bank host.

HostTime (output) Datatype: BSTR Max 6 bytes

Indicates Time of transaction as recorded by Bank Host in HHMMSS format. This field may be blank if the transaction was rejected locally or otherwise not processed by the bank host.

IssuerName (input) Datatype: BSTR Max 32 bytes

Name of bank that issued the credit card. Eg: ANZ, Westpac etc.

MerchantReference (input) Datatype: BSTR Max 64 bytes

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

PaReq (input) Datatype: BSTR

Set PAReq (Payer Authentication Request) message that was used when a transaction has been authenticated through 3D authentication. The merchant and acquirer will need to include the CAVV in the authorization in order to demonstrate that authentication occurred.

PaRes (input) Datatype: BSTR

Set the PARes (Payer Authentication Response) message that was received from the ACS server, when a transaction has been authenticated through 3D authentication. The merchant and acquirer will need to include the CAVV in the authorization in order to demonstrate that authentication occurred.

EnablePaxInfo (input) Data type: Boolean True/False

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.

PaxDateDepart (input) Data type: String Max 8 bytes

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

PaxName (input) Data type: String Max 20 bytes

Used for Airline Reservation Systems. Passenger Name. Alphanumeric.

PaxLeg1 (input) Data type: String Max 3 bytes

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

PaxLeg2 (input) Data type: String Max 3 bytes

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

PaxLeg3 (input) Data type: String Max 3 bytes

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

PaxLeg4 (input) Data type: String Max 3 bytes

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

PaxOrigin (input) Data type: String Max 3 bytes

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

PaxTicketNumber (input) Data type: String Max 14 bytes

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.

PaxCarrier (input) Data type: String Max 2 bytes

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

PaxTravelAgentInfo (input) Data type: String Max 25 bytes

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

Retry (output) Datatype: Boolean True/False

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.

PreAuthNumber (input) Datatype: BSTR Max 64 bytes

PreAuth Number - only used for Completion of Auth/Completion transactions. This is the value returned by a successful Auth transaction in AuthCode.

Password (input) Data type: String Max 32 bytes

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.

ResponseCode (output) Datatype: BSTR Max 2 bytes

Response Code generated by Payment Express 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 DPSAUTH 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 DPSAUTH control.

ReceiptEmailAddress (input) Data type: String Max 64 bytes

Email address to send a transaction receipt. If not blank, this must be a valid email address in the form user@x.y.z. Not currently implemented.

ServerAddress (input) Data type: String Max 32 bytes

Address of Payment Express Server in either "255.255.255.255" numeric format or alphanumeric "hostname" format. If blank, defaults to local host address. This value is written by the DPSAuth control to the system registry - it is preserved and will be used for subsequent connects until changed by a new value set in ServerAddress.

ServerPort (input) Datatype: long

Listener port of Payment Express Server. Default is 3007. Leave this value as blank unless the system administrator has reassigned the listener port. This value is written by the DPSAuth control to the system registry - it is preserved and will be used for subsequent connects until changed by a new value set in ServerPort.

StatusNeeded (output) Datatype: Boolean True/False

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 undetermined and error - recovery is required. See DoStatus method for further information.

Success (output) Datatype: Boolean true/false

Indicates success or failure of a method call.

TestMode (output) Datatype: Boolean true/false

If true, indicates the transaction was performed to a Test account, not a live merchant account. A Test account will never result in funds transfer even if a valid card is used.

TxnRef (output) Datatype: BSTR Max 6 bytes

Reference number for the transaction. Maximum 6 alphanumeric characters. Combined withClientId value to form a unique transaction reference. This is generated and maintained by DPSAuth for each transaction and returned on output. Used as input for DoStatus transactions.

TxnType (input) Datatype: BSTR 1 byte

Value Meaning
P Purchase - Funds are transferred immediately.
R Refund - Funds transferred immediately. Must be enabled as a special option.
A Authorise - amount is authorised no funds transferred.
C Completes a previous authorisation - funds are transferred.

BillAddCard Stores a BillingId against a card.

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.

VersionMajor (output) Data type: BSTR Max 20 bytes

Control Major version number. Reserved for future use.

VersionMinor (output) Datatype: BSTR Max 16 bytes

Control Minor version number. Reserved for future use.

VersionRevision (output) Datatype: BSTR Max 16 bytes

Control Revision number. Reserved for future use.

Xid (input) Datatype: BSTR Max 28 bytes

Set the Xid (Transaction Identifier) for transactions processed via 3D secure authentication. The merchant and acquirer will need to include the CAVV in the authorization in order to demonstrate that authentication occurred.

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 orDoStatus. The following table provides assistance in troubleshooting these errors.

Input Properties

Error Code Explanation
S1 DPSAuth cannot connect to the Payment Express Server. Check that the Payment Express Service is running. Is the Payment Express Service installed on the same computer as the DPSAuth component? Try "pinging" the Payment Express Server computer.
S2 DPSAuth cannot connect with the Payment Express Server within 5 seconds. Troubleshoot per "S1" error.
S3 Payment Express Server Socket was closed by the Payment Express Server or by the network.
S4 Link to Payment Express Server is OK but upstream Payment Express host signaled link down. Contact support@paymentexpress.com for assistance. 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 theStatusNeeded 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 ofCardHolderResponseText. 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 ".

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

ADDRESS String The TCP/IP address of the Payment Express NT Service. Defaults to the local computer IP address.

PORT DWORD The Port number exposed by the Payment Express NT Service.

TIMEOUT DWORD The maximum time the DPSAuth object will wait for a response from the Payment Express service. Defaults to 30 seconds.

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@paymentexpress.com 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. Payment Express 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)

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 theDpsTxnRef 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 theEnablePaxInfo 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: