PxAccess Interface for the Hosted Payments Package

The PxAccess interface allows merchants with websites running in a Windows environment to accept credit card details using the Payment Express® SSL-secured payments page. The merchant's website communicates transaction details to a COM object (PXACCESS.DLL) and the object returns a URL at which the card details can be accepted. Once the user has completed the transaction they are directed back to the merchant's website. The merchant website is able to identify the transaction and any other pertinent details by extracting a query string value and supplying this to the COM object.

To ensure that the merchant website is always able to recognise that a transaction has taken place an HTTP GET is made to the merchant website independently of the user. Note that, as this request is made by Payment Expressdirectly, the merchant website will not be able recognize sessions maintained using cookies or query string values for this request however the session can be identified by populating one of a number of free text properties of the COM Object with a session ID or similar identifier.

If you intend to run PX Access on a 64-bit server please mention this to our technical support team at the time of setup so that they can provide you with a compatible version of the COM object.

Websites running on platforms other than Microsoft Windows should use the PX Pay interface to access and present the Payment Express® SSL-secured payments page. The PxPay interface is language and platform independent as it does not require any specific proprietary software to be installed on the server.

Technical Specifications/Features

  • Multiple Account Selection
  • Unsecured web sites can link to different customised secure payment pages depending on which merchant account the transaction should be charged to.
  • No SSL certificate required
  • Optional reference fields are available to hold information that will appear on transaction reports.
  • Multi–Currency Support
  • Customisable styling of the Payments Page through a wizard
 

Installation Instructions

Download the PXACCESS._xxx.EXE installation kit and run.

Enter your 64 character encryption key and UserId provided by PaymentExpress and click "Set". If you do not have an encryption key and or userid, email support@paymentexpress.com to obtain.    
 

Filename Description
PXACCESS.DLL COM Component
 

Registry Settings


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

HKEY_LOCAL_MACHINE\SOFTWARE\DirectPaymentSolutions\PXACCESS\KEYS
 
<Customer Userid> String 64 Character Key for 3DES and MAC Encryption

The following path is the URL of the Hosted Payments Page for the response redirect call. This should only be changed when talking in conjunction with Payment Express support.
 
URL String Current Address of the Hosted Payment Page

Function Calls

 

DoGenerateRequest(Request)

DoGenerateRequest is used to initiate a PXACCESS transaction from a remote PXACCESS Client.
 
Assign variables to PXACCESS.DLL then call DoGenerateRequest. This returns an encrypted Url which you then redirect your web site to.

Input Properties
Parameter Required Description
AmountInput Yes Amount value in d.cc format.
BillingId No Needs to be generated to add a card for recurring billing and sent again when rebilling transactions.
CurrencyInput Yes Currency of AmountInput
DpsBillingId No The BillingId generated by Payment Express when adding a card for recurring billing. Needed for rebilling transactions when you do not use your own BillingId.
DpsTxnRef No Payment Express transaction reference. Sent back to Payment Expressfor refund and complete transactions.
EmailAddress No Optional Email Address
EnableAddBillCard No Needed for recurring billing transactions when adding a card to the Payment Express system. Set element to 1 for true and 0 for false
MerchantReference Yes Reference field to appear on transaction reports
TxnData1 No Optional Free Text
TxnData2 No Optional Free Text
TxnData3 No Optional Free Text
TxnType Yes Purchase or Auth
TxnId No Contains a unique, COM or merchant application generated value that uniquely identifies the transaction
UserId Yes UserId of Payment Access User 
UrlFail Yes Url of customer site transaction failure page

 

Output Properties

Parameter Description
Request URL including Encrypted Transaction Request

DoProcessResponse (Response)


DoProcessResponse is used to decode the result of the transaction after it has been submitted.

 

Input Properties

Parameter Required Description
UserId Yes UserId of Payment Access User
Response Yes The encrypted URL response from Payment Express

 

Output Properties

Parameter Description
AmountSettlement The Amount of the transaction
AuthCode Authorisation code from the bank
CardName Card used (Visa,MasterCard,Bankcard etc)
CardNumber Version 1.38 and above. The card number used for the transaction in truncated form.
CurrencySettlement The Currency of the transaction
DateExpiry Version 1.39 and above. The expiry date of the card used in the transaction.
DpsBillingId Contains the billing ID generated by Payment Express when adding a card for recurring billing.
DpsTxnRef Payment Express transaction reference. Sent back to Payment Express for refund and complete transactions.
CardHolderName The Card Holder Name used for the transaction
EmailAddress Optional Email Address
ResponseText Response Text associated with the result of the transaction
Success Non-zero if transaction successful, 0 if declined or unsuccessful
MerchantReference Reference field to appear on transaction reports
TxnData1 Optional Free Text
TxnData2 Optional Free Text
TxnData3 Optional Free Text
 

COM Object Properties


AmountInput (input) Datatype: BSTR Max 13 characters
Total Purchase or Auth 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. The maximum value allowable is $99,999.99 however acquirer or card limits may be lower than this amount. When submitting transactions for currencies with no decimal division of units such as JPY the

AmountSettlement (output) Datatype: BSTR Max 13 characters
Total Purchase, Refund, Auth or Completion amount that was settled with your bank.

AuthCode (output) Datatype: BSTR Max 22 characters
Authorisation code returned for approved transactions.

BillingId (input) Datatype: BSTR Max 32 characters
If a token based billing transaction is to be created, a BillingId may be supplied. This is an identifier generated by the merchant application that is used to identify a customer or billing entry and can be used as input  instead of card number and date expiry for subsequent billing transactions.

CardHolderName (output)Datatype: BSTR Max 64 bytes
The cardholder name as it appears on customer card.

CardName (output)Datatype: BSTR Max 16 bytes
The card type used for the transaction.

CardNumber (output) Datatype: BSTR Max 20 bytes
The card number used for the transaction. The full credit card number isn't shown, however the bin range is given (first 6 characters).

CurrencyInput (input) Datatype: BSTR Max 4 characters
Used to specify the currency to be used: AUD, USD, NZD etc.
 
CAD Canadian Dollar
CHF Swiss Franc
DKK Danish Krone
EUR Euro
FRF French Franc
GBP United Kingdom Pound
HKD Hong Kong Dollar
JPY Japanese Yen
NZD New Zealand Dollar
SGD Singapore Dollar
THB Thai Baht
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

CurrencySettlement (output) Datatype: BSTR Max 4 characters
Used to specify the currency that was used for the transaction: AUD, USD, NZD etc.

DpsBillingId (input) Datatype: BSTR Max 16 characters
When output, contains the Payment Express generated BillingId. Only returned for transactions that are requested by the application with the EnableAddBillCard value is set to true indicating a token billing entry should be created.

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 specify a transaction for refund without supplying the original card number and expiry date.

EmailAddress (input) Datatype: BSTR Max 255 bytes
Optional Email Address field. Will be returned to origin site for emailing of receipts etc.

EnableAddBillCard (input) Datatype: Long
To automatically add a card for subsequent billing purposes, set this to 1. When generating a Billing Transaction for a previously loaded BillingId or DpsBillingId, EnableAddBillCard must be 0.

MerchantReference (input) Datatype: BSTR Max 64 bytes*
Free text to appear on transaction reports.

*For Pago transactions the MerchantReference is restricted to 50 characters.

Request (output) Datatype: BSTR
URL to https://www.paymentexpress.com with encrypted transaction parameters. The browser should simply redirect to this URL.

ResponseText (output) Datatype: BSTR Max 32 bytes
Response Text associated with the response code of the transaction

Success (output) Datatype: Long
Indicates success or failure of the transaction. A value of 0 indicates the transaction was declined or there was an error. A value of 1 indicates the transaction was approved.

TxnData1, TxnData2, TxnData3 (input) Datatype: BSTR Max 255 bytes
Optional free text fields. Usually assigned at origin web site.

TxnId (input/output) Datatype: BSTR Max 16 bytes
Contains a unique, merchant application generated value that uniquely identifies the transaction. Used by Payment Express to check for a duplicate transaction generated from Merchant web site. If a duplicate is detected (same transaction id used for an approved transaction within the previous 48 hours), the transaction is not retried, but an "approved" message is displayed and the merchant site is informed of the result. If the merchant does not supply a value for TxnId, PXACCESS.DLL generates a merchant unique value. Where possible it is recommended that the merchant application sets this value.

TxnType  (input) Datatype: BSTR 
 
Value Meaning
Auth Authorises a transaction. Must be completed within 7 days using the "Complete" TxnType.
Complete  Completes (settles) a pre-approved Auth Transaction. The DpsTxnRef value returned by the original approved Auth transaction must be supplied.
Purchase Purchase - Funds are transferred immediately.
Refund Refund - Funds transferred immediately. The DpsTxnRef value returned by the original approved Purchase/Complete transaction must be supplied. (Not Currently implemented)

UrlFail  (input) Datatype: BSTR Max 255 bytes
Url of page to redirect to if transaction failed. No parameters (&, ?) are permitted.

UrlSuccess  (input) Datatype: BSTR Max 255 bytes
Url of page to redirect to if transaction successful. No parameters (&, ?) are permitted.

UserId (input) Datatype: BSTR  Max 32 bytes

Unique username to identify customer. Assigned on Account Setup by Payment Express support team.
 

Fail-proof Result Notification


Fail-proof result notification (FPRN) is a service that provides additional assurance that the merchant website will receive notification regarding the outcome of transactions completed via the  Payment Expresshosted payment page.

FPRN helps cater for the possibility that a user may not successfully navigate to the nominated success or failure URL enabling the merchant web application to acknowledge the outcome of the transaction. The user could close their browser or otherwise navigate away from the Payment Express hosted payment page once they have been informed of the transaction outcome. The merchant's web server may be temporarily unavailable as the transaction is completed and therefore unable to recognise that a transaction has taken place. Using the FPRN service the merchant website is virtually guaranteed to receive notification of the each and every transaction.

FPRN is highly recommended by Payment Express and is enabled on all new accounts by default. The service ensures that the following processes occur for every transaction performed via hosted payment page:
As soon as the transaction is completed, a background process at Payment Express makes an HTTP GET request to the merchant-nominated success or failure URL. If the merchant web site is unreachable or returns any HTTP status code other than 200 or 404 the HTTP GET is retried up to a maximum of six times. It will give up immediately on receiving a 404 HTTP status code (page not found). A 500 HTTP status code, indicating a temporary problem at the client site, will cause a retry.

In order to ensure that the web application is in the best position to acknowledge the outcome of each and every transaction certain guidelines should be followed.

The merchant web application should not;
 
  • Filter or base any conditional logic upon the originating IP address (this can vary)
  • Depend upon receiving one and only one request for the success/fail URL from the Payment Express FPRN system (multiple requests may be sent)

The merchant web application should;
 
  • Decrypt the query string for all requests for a success/fail page requests where the requested URL contains a 'result' parameter containing the encrypted transaction outcome details
  • Determine if a database operation or some form of communication such as generating an order record or sending an email is required. Generally this will mean that the application needs to be aware if these actions have been taken previously for the particular transaction or not (TxnId should be used for this purpose).

N.B. The URL at which the merchant website will process FPRN requests must be exposed via standard internet ports i.e. port 80 or port 443 for SSL/TLS traffic. When specifying UrlSuccess and UrlFail values do not specify a non-standard port number within the URL.
 

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) Authorisation

Set TxnType to "Auth" 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 Authorisation transaction, but within 7 days maximum, a "completion"  (TxnType="Complete") 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 a 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 expiry date, only the BillingId originally associated during the Setup Phase

1) Setup Phase

The setup phase consists of loading a card into Payment Express with a transaction. The transaction can be an online $1.00 Auth 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.

To add a card for future rebilling, send a transaction request (Auth or Purchase) including the following properties:

EnableAddBillCard (Set to 1 when adding a card)
BillingId (optional)

You can supply your own billing ID in BillingId or leave it blank and use the ID returned in DpsBillingId
determined by Payment Express)

2) Rebill Phase

The merchant application or Batch processor requests a new transaction and supplies the appropriate BillingId, DpsBillingId or CardNumber2, a MerchantReference (which appears on reports) and the amount to be charged using either PxPostDPS AUTHSSL or Web Service. EnableAddBillCard value will be set to "False" (or 0) for the rebill phase.
 
Payment Express® retrieves the credit card number and expiry date stored in the Setup Phase and a purchase transaction is formatted and processed to the card acquirer.