PXCL ActiveX Component

PXCL.DLL is an ActiveX Component designed for easy integration with Microsoft Windows applications running on NT4.0 or better. PXCL has been tested under Windows 2000. PXCL is a COM object that encapsulates the interface to a Payment Express Server. For Customers using Websites or Microsoft Site Server software, please refer to separate software component DPSAUTH, DPSAUTSSL and for Site Server DPSAUTHP.

Technical Specifications/Features:

  • 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
  • Ideal for integration into existing custom in-house applications

Requirements/Downloads:

Installation Instructions

Download the latest PXCL ActiveX Object kit and run the PXCL_XXX.EXE

Figure 1 PXCL Installation Dialog

Installation Directory

Indicates the directory where PXCL ActiveX files will be installed.

Install

To install PXCL, Press the Install Button.

Files Installed/Updated

Filename Description

PXCL.DLL ActiveX COM Component

RPXCL.EXE Removes (uninstalls) from system.

Only PXCL.DLL is required for operation.

Uninstalling PXCL

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

Using PXCL.DLL

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

A sample Visual Basic application including source that demonstrates the useof PXCL is available by sending Email to support@paymentexpress.com

Methods

PXCL.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, CardHolderName, CardNumber, DateExpiry and TxnType properties must be loaded before calling DoAuthorize. Output properties are set when the corresponding AuthorizeEvent Event fires to indicate completion of the authorization request.

Operation

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

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
CardHolderName No Card Holder Name as on Card.
CardNumber No1 Credit Card Number. Left justified no embedded spaces or other delimiters.
ClientInfo No Browser IP Address or NT Username for information purposes.
ClientType Yes1 Indicates transaction source (Web vending machine etc)
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.
IssuerName No Issuer of card
ReceiptEmailAddress No Address to email a receipt to. Not currently implemented
TxnType Yes P=Purchase R=Refund A=Auth C=Completion
Password No Password (for sites with multiple accounts)
Username No Username (for sites with multiple accounts)

Note 1: The CardNumber, ClientType and DateExpiry are not required for Completion transactions. The AuthCode is required as input for a Completion transaction.

Note 2: The AuthCode is required as input for Completion transactions. It is ignored for other transaction types.

Output Properties

These properties are set when the DoAuthorize method returns.

Input Properties

Parameter Description
Authorized True if transaction successful False if declined or unsuccessful
AuthCode Authorisation Code (up to 64 character alphanumeric)
CardName Card used (Visa MasterCard Bankcard etc)
DateSettlement Date transaction will be settled to Merchant Bank Account in YYYYMMDD format
ReCo 2 character response code
MerchantResponseText Response Text associated with ResponseCode
MerchantResponseDescription Additional information for merchant.
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 transaction completes.
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

Input Properties

Parameter Required Description
ServerAddress Yes Set to Address of Payment Express Server
ServerPort Yes Do not set unless altering from default setting of 3004

Properties

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

Address1 (input) Datatype: String Max 32 Bytes

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

Address2 (input) Datatype: String Max 32 Bytes

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

Address3 (input) Datatype: String Max 32 Bytes

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

Amount (input) Datatype: String Max 13 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 Data type to allow for easy integration with Web applications. Maximum value allowable is $99,999.99. Note that acquirer or card limits may be lower than this amount.

AuthCode (output/input) Datatype: String 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 AuthCode prior to the subsequent Completion transaction.

CardHolderName (input) Datatype: String Max 64 bytes

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

CardNumber (input) Datatype: String Max 20 bytes

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

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.

CardName (output) Datatype: String 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.

Input Properties

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

Properties

ClientInfo (input) Datatype: String Max 64 bytes

Internet Address of the browser or the NT Username of the workstation. Free-form text that will appear on certain Merchant reports alongside the transaction.

ClientType (input) Datatype: String Max 1 byte

Type of client transaction - Choose from the following values

Input Properties

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

Input Properties

Value Meaning
Purchase Purchase - Funds are transferred immediately.
Refund Refund - Funds transferred immediately. Must be enabled as a special option.
Auth Authorise - amount is authorised no funds transferred. Requires AuthCode from original transaction as input.
Complete Completes a previous authorisation - funds are transferred.

Username (input) Datatype: BSTR Max 32 bytes

Payment Express username. A Username/Password pair is required to perform transactions.

VersionMajor (output) Datatype:numeric

Control Major version number. Indicates the version number of the PXCL.

VersionMinor (output) Datatype: numeric

Control Minor version number. Indicates the version number of the PXCL.

VersionRevision (output) Datatype: numeric

Control Revision number. Indicates the version number of the PXCL.

Events

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

AuthorizeEvent

Signals completion of a transaction started by DoAuthorize method

StatusChangedEvent

Signals a change in the status of the link to Payment Express server or Payment Express Host. A Client Application could use this event to change the user interface to update the visual cue according to the values of ServerOk and LinkOk

Registry Settings

Debugging Trace Log

PXCL can produce a log of transactions transmitted and received if the property "EnableTrace is set to 1. The filename is PXCL_yyyymmddddmmss.LOG

Auth/Completion

1) Authorization

Call DoAuthorize with TxnType set to "Auth" for for the amount to be authorized. The Auth response contains an AuthCode of up to 64 alphanumeric characters. The funds are not transferred from the cardholder account, but the AuthCode may be used up to 7 days later to Complete the transaction and cause funds transfer.

2) Completion

After a successful Authorization transaction, but within 7 days maximum, a "completion" (TxnType="Complete") transaction must be sent containing the "authorisation code" returned by the "auth" transaction response in the PreAuthNumber property.