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.
This is an optional tag that allows transactions be checked against a Hot Card list before being processed.
Transactions can be flagged with a product code to allow for transaction categorization on reports.
Transactions can be redirected to different merchant accounts depending on the Account code that is specified with each transaction.
Optional reference fields are available to hold information that will appear on transaction reports.
Charge cuurrency can be explicitly specified on a per transaction basis or implicitly via product or account selection.
Download the latest DPSAUTH COM Object kit and run the DPSAUTH_XXX.EXE (XXX is software version).
Figure 1 DPSAUTH SETUP
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.
To install DPSAUTH, Press the Install Button.
| 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. |
To uninstall DPSAUTH from a computer, use the Settings/Control Panel/ Add/Remove programs utility. Select DPSAuth and press "Add/Remove".
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.
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.
| 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.
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 |
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.
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 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.
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.
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 |
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.
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.
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.
| 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: |
An accepted transaction is indicated by a Success property being set to true. In this case, display contents of CardHolderResponseText on the Browser.
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
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 ".
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
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.
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.
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:
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:
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.
