PXCL ActiveX ComponentPXCL.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.
Installation InstructionsDownload the latest PXCL ActiveX Object kit and run the PXCL_XXX.EXE Figure 1 PXCL Installation Dialog
Installation DirectoryIndicates the directory where PXCL ActiveX files will be installed. InstallTo install PXCL, Press the Install Button. Files Installed/Updated
Only PXCL.DLL is required for operation. Uninstalling PXCLTo uninstall PXCL from a computer, use the Settings/Control Panel/ Add/Remove programs utility. Select PXCL and press "Add/Remove". Using PXCL.DLLLoad 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@dps.co.nz MethodsPXCL.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. DoAuthorizeAmount, 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. OperationThe 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
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 PropertiesThese properties are set when the DoAuthorize method returns.
DoConnectConnects to Payment Express Server. Input Properties
PropertiesThe 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 BytesCardholder Billing Address Line1 - may be used by Payment Express Host for additional verification purposes. Not currently implemented. Address2 (input) Datatype: String Max 32 BytesCardholder Billing Address Line2 - may be used by Payment Express Host for additional verification purposes. Not currently implemented. Address3 (input) Datatype: String Max 32 BytesCardholder Billing Address Line3 - may be used by Payment Express Host for additional verification purposes. Not currently implemented. Amount (input) Datatype: String Max 13 bytesTotal 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 bytesAuthorisation 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 bytesThe cardholder name as it appears on customer card. Optional and may be left blank. CardNumber (input) Datatype: String Max 20 bytesThe card number. No leading or embedded blanks are permitted. Must contain a numeric value. CardHolderResponseDescription (output) Data type: String Max 32 bytesMore detailed explanation of result. Intended for card holder. CardHolderHelpText (output) Data type: String Max 32 bytesMore detailed explanation of result. Intended for card holder. CardName (output) Datatype: String Max 16 bytesThe 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.
ClientInfo (input) Datatype: String Max 64 bytesInternet 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 byteType of client transaction - Choose from the following values
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. CurrencySettlement (output) Datatype: BSTR Max 4 bytesIndicates currency used for this transaction. Currency will be determined by the bank account used which is selected using the property. E.g.: NZD or AUD or USD. Cvc2 (input) Datatype: BSTR Max 4 bytesCard 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) 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 bytesIndicates 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: String Max 8 bytesIndicates 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. IssuerName (input) Datatype: BSTR Max 32 bytesName of bank that issued the credit card. Eg: ANZ, Westpac etc. LinkOk (output) Datatype: boolean true/falseIf true, indicates the link to Payment Express Host is online. See also ServerOk and StatusChangedEvent Password (input) Datatype: String Max 32 bytesPayment Express password. A Username/Password pair is required to perform transactions when multiple accounts are configured. ReCo (output) Datatype: String Max 2 bytesResponse Code generated by Payment Express (for locally declined transactions) or by the Card Acquirer (for host originated responses). The ReCo should not be checked by the client application using PXCL as these values differ according to acquirer. Use the Authorized property to check for successful completion of a transaction. The Retry property may be used to determine if the transaction should be retried. ReceiptEmailAddress (input) Datatype: String Max 255 bytesEmail 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. MerchantResponseText (output) Datatype: String Max 20 bytesResult of the transaction. MerchantResponseDescription (output) Datatype: String Max 255 bytesResult of the transaction in more detailed form. ServerAddress (input) Datatype: BSTR Max 255 bytesAddress of Payment Express Server in either "255.255.255.255" numeric format or alphanumeric "hostname" format. ServerPort (input) Datatype: longListener port of Payment Express Server. Default is 3004. Leave this value unchanged unless the system administrator has reassigned the listener port. ServerOk (output) Datatype: boolean true/falseIf true, indicates the Server (PX.EXE) link is OK. This is usually across a local LAN. See also LinkOk property and StatusChangedEvent. Success (output) Datatype: Boolean true/falseIndicates success or failure of a method call. TestMode (output) Datatype: BOOL true/falseIf 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: String Max 6 bytesReference number for the transaction. Maximum 16 alphanumeric characters. This is generated and maintained by PXCL for each transaction and returned on output. TxnType (input) Datatype: String Max 32 bytes
Username (input) Datatype: BSTR Max 32 bytesPayment Express username. A Username/Password pair is required to perform transactions. VersionMajor (output) Datatype:numericControl Major version number. Indicates the version number of the PXCL. VersionMinor (output) Datatype: numericControl Minor version number. Indicates the version number of the PXCL. VersionRevision (output) Datatype: numericControl Revision number. Indicates the version number of the PXCL. EventsThe 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. AuthorizeEventSignals completion of a transaction started by DoAuthorize method StatusChangedEventSignals 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 SettingsDebugging Trace LogPXCL can produce a log of transactions transmitted and received if the property "EnableTrace is set to 1. The filename is PXCL_yyyymmddddmmss.LOG Auth/Completion1) AuthorizationCall 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) CompletionAfter 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.
|
