Payment Express Hosted - PxPay 2.0

The PX Pay 2.0 interface is a platform independent Hosted Payments Page (HPP) solution provided by Payment Express. The HPP provides a solution for the capturing credit card information securely without exposing the merchant to the sensitive data.

This is achieved by allowing the card holder to enter their card details into a page which is hosted by Payment Express rather than the merchants own website. The major advantage of this approach is that the merchant does not see, and is not aware of, the card number at any point in the process. This is beneficial from a PCI DSS standpoint because the scope of PCI DSS requirements is likely to be reduced.

PCI DSS (Payment Card Industry Data Security Standard) is a set of comprehensive requirements created by card issuers American Express, Discover Financial Services, JCB International, MasterCard and Visa to ensure the security of credit card data online. All merchants, whether small or large, need to be PCI compliant. Payment Express is registered as a PCI DSS compliant service provider; therefore a payment page solution hosted by Payment Express meets all PCI DSS requirements.

PxPay 2.0 platform can support the following transaction types:

  • Purchase Transaction
  • Auth Transaction
  • Token billing Transaction
  • Re-bill Token Transaction

Download Documentation:

Payment Express PxPay 2.0 Integration Documentation (PDF): Click here to download

A demonstration of PxPay 2.0 can be found online at http://demo.paymentexpress.com

A sample of PxPay 2.0 CSS file can be downloaded here

Sample code to assist integration is available to download in the following languages:

Mobile Device Integration:

The PxPay 2.0 interface can be integrated on a native mobile application as a payment method. The mobile application may utilise a webpage component to view the hosted payment page over HTTPs. The mobile platform being integrated with PxPay 2.0 should support HTTPS posts and XML data exchange.

The PxPay 2.0 payment automatically switches to a mobile format for mobile devices by default. If the PxPay 2.0 payment page is not responsive to the mobile device's screen as expected, please ensure the user agent string that the device's web browser is reporting is mobile specific within the first 255 characters of the string.

If the hosted payment page is still not responsive on the mobile device screen, please note the following:

Please email devsupport@paymentexpress.com and quote the exact user agent string of the relevant mobile device(s) used to send the transaction request.

Also if a mobile web browser is used to redirect to the hosted payment page, please specify the exact mobile web browser and the version.

How it works:

To process a transaction, PX Pay 2.0 allows merchants to send XML requests to Payment Express via HTTPS posts to https://sec.paymentexpress.com/pxaccess/pxpay.aspx.

PxPay Username & PxPay Key is required too.

For testing PxPay 2.0 on the UAT enviornment - please send XML requests to https://uat.paymentexpress.com/pxaccess/pxpay.aspx.

Payment Express responds with a unique URI (encrypted URL) for an SSL secure payments page. Please refer to Request Response Codes in case the URI is not returned.

The merchant shopping cart uses the returned URI to redirect the customer to the secure Payment Express hosted payments page.

The customer will be prompted to enter their credit card details and complete the transaction. The transaction is then sent to the merchant bank for authorisation. The result is displayed and the user is automatically redirected back to the merchant's website (success or fail page); i.e https://www.dpsdemo.com/SandboxSuccess.aspx?result=0000840000185376f1519ff80a5ccd54&userid= SamplePXPayUser

You take the "result" parameter value in the URL string i.e. 0000840000185376f1519ff80a5ccd54 along with the PX Pay username and PX Pay key; to send the response request (ProcessResponse) to Payment Express and receive the XML response back.

The transaction results and other transaction details are decrypted and sent back to the merchant as a standard XML response.

PxPay 2.0 Process Flow

Transaction Request:

GenerateRequest XML Document - To initiate a transaction the merchant posts the GenerateRequest to https://sec.paymentexpress.com/pxaccess/pxpay.aspx

Generate Request

A full description of all available elements can be found on the integration guide.

Request XML Document - Once the GenerateRequest has been processed a Request will be returned. The URI returned can then be used to redirect the customer to the Payment Express Hosted Payments Page. Please refer to Request Response Codes in case the URI is not returned.

Generate Request

A full description of all available elements can be found on the integration guide.

Transaction Response:

ProcessResponse XML Document - Once the user has submitted their credit card information and the transaction has been processed, the merchant now needs to obtain the transaction outcome and details.

To extract the transaction details from the encrypted URI string, the merchant sends the encrypted string with their PXPayUsername and PXPaykey in the ProcessResponse (Input XML Document).

Generate Response

A full description of all available elements can be found on the integration guide.

Response XML Document - The Response will return the decrypted transaction results for the merchant to interpret.

Generate Response

A full description of all available elements can be found on the integration guide.

Element Properties

AmountInput (input) Datatype: BSTR Max 13 characters

The AmountInput field specifies the 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 "999999.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 the Japanese Yen (JPY), the AmountInput must be in an appropriate format e.g. "1000" for 1000 Yen. If "1000.00" is submitted in AmountInput with CurrencyInput set to JPY, an error will occur and response code "IU" will be returned.

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 from the acquirer.

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 supplied 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 16 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) depending on masking pattern set.

ClientType (input) Datatype: BSTR

Allows the Client type to be passed through at transaction time. Please note the feature may need to be enabled for the PxPay 2.0 user. Recommended values for PxPay 2.0:

  • Internet = I
  • Recurring = R (if supported by your MID at your merchant bank expiry date will not be validated)

Please note the single letter input is case-sensitive.

Please submit the full word or a single letter.

CurrencyInput (input) Datatype: BSTR Max 4 characters

Used to specify the currency to be used: AUD, USD, NZD etc.

Currency Country
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

CardNumber2 (output) Datatype: BSTR Max 16 characters

A token generated by Payment Express when adding a card for recurring billing. CardNumber2 is a 16 digit number which conforms to a Luhn 'mod 10' algorithm and has a 1-to-1 relationship with the actual card number used. Please contact Payment Express support if you would like to use this value.

CurrencySettlement (output) Datatype: BSTR Max 4 characters

Used to specify the currency that was used for the transaction: AUD, USD, NZD etc.

CVC2ResultCode (output) Datatype: BSTR 1 character

The result of CVC validation. The CVC result code indicate the following:

Response Code

RESPONSE CODE DEFINITION DEFINITION
M CVC matched. You will want to proceed with transactions for which you have received an authorisation approval. A CVC match indicates the values provided matches the Issuing Banks details
N CVC did not match. You may want to follow up with the cardholder to verify the CVC value before completing the transaction even if you have received an authorisation approval. The CVC details provided by the Cardholder do not match their Issuing Banks details
P CVC request not processed. Issuing Bank is unable to process CVC at this time
S CVC should be on the card but merchant has sent code indicating there was no CVC. You may want to follow up with the cardholder to verify that the customer checked the correct location for the CVC. If the transaction is Approved you may also wish to consider not fulfilling the transaction
U Issuer does not support CVC. The card Issuing bank does not support CVC process

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. The EmailAddress field can be used to store a customer's email address and will be returned in the transaction response. The response data along with the email address can then be used by the merchant to generate a notification/receipt email for the customer.

EnableAddBillCard (input) Datatype: BSTR Max 1 character

The EnableAddbillCard field is used if subsequent billing is required. Setting this field to "1" will cause DPS to store the credit card details for future billing purposes. A DpsBillingId (DPS generated) or BillingId (merchant generated) is used to reference the card.

MerchantReference (input) Datatype: BSTR Max 64 bytes

Free text to appear on transaction reports. The merchant reference allows users to easily find and identify the transaction in Payline transaction query and DPS reports. The merchant reference is returned in the transaction response, which can be used interpreted by the merchant website. Common uses for the merchant reference field are invoice and order numbers. This is an optional field.

Opt (input) Datatype: BSTR Max 64 bytes

Optional parameter most commonly used to specifiy a timeout timestamp in Coordinated Universal Time (UTC) after which the payment page will no longer allow a payment to be taken. The value must be in the format "TO=yymmddHHmm" e.g. TO=0901142221.

PxPayKey (input) Datatype: BSTR Max 64 bytes

Unique key to identify customer and used to encrypt the transaction request with 3DES to protect the transaction information. This key will be setup by our Payment Express Activations team and issued with your development account.

PxPayUserId (input) Datatype: BSTR Max 32 bytes

Unique username to identify customer account. This username will be setup by our Payment Express Activations team and issued with your development account. The standard format used for Dev PxPayUserId is 'merchantname_dev' e.g. dps_dev.

ReCo (output) Datatype: String Max 2 characters

Response Code generated by Payment ExpressServer (for locally declined transactions) or by the Card Acquirer (for host originated responses). The ReCo should not be checked by the client application, as these values differ based on the acquirer. Use the Success property to determine the result of a transaction.

Response (input) Datatype: BSTR

The encrypted URL response from Payment Express, which you can get from "Result" parameter in the URL string that is returned to your response page. You send this back to PaymentExpress to decrypt, to which you will receive the response in XML.

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 (each field)

The TxnData fields are free text fields that can be used to store information (from origin site) against a transaction. This can be used to store information such as customer name, address, phone number etc. This data is then returned in the transaction response and can also be retrieved from DPS reports. This is an optional field.

Note: storing large strings of information in the TxnData fields can cause the URI returned in the Request (Response) to exceed the max URL length for some browsers.

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, the transaction is not retried, but an "approved" message is displayed and the merchant site is informed of the result. Ensure that the value is always unique per transaction request.

Payment Express will generate a TxnRef/TxnID for each PxPay transaction if merchant application doesn't generate one.

TxnType (input) Datatype: BSTR Max 8 characters

Either "Purchase" or "Auth". A purchase transaction type processes a financial transaction immediately and funds are transferred at next settlement cut-off. For information on the authorisation transaction type please see here.

URI (output) Datatype: BSTR

URL to https://www.paymentexpress.com with encrypted transaction parameters. The browser should simply redirect to this URL.

UrlFail (input) Datatype: BSTR Max 255 bytes

Url of page to redirect to if transaction failed. Please ensure the URL starts with the protocol, for example: "https:..." or "http:...".

Query string characters are permitted. However percent-encoding the URL is not permitted.

UrlSuccess (input) Datatype: BSTR Max 255 bytes

Url of page to redirect to if transaction failed. Please ensure the URL starts with the protocol, for example: "https:..." or "http:...".

Query string characters are permitted. However percent-encoding the URL is not permitted.

Well Formed XML

Character data sent via PX Pay must be well formed XML. For example, the following is invalid XML:

Payment Express will be unable to read this XML and will return an error. If there is a possibility that a value will contain invalid characters (such as '&' in the cardholder name), please format the value using "HtmlEncoding".

However please make sure the return URL set for success and failure redirection is not encoded as Percent-encoding.

The above example should be formatted as follows:

Request Response Codes

During development if the URI is not received after a transaction request you may receive a Request XML document (response data) with children elements Reco and ResponseText from Payment Express. The Reco (Response code) and ResponseText provides an indication of the error (see an example of the XML below). Common error codes and the potential cause for the error are listed in the integration guide. To debug a possible request issue, please ensure your integration is logging the response data after a GenerateRequest is sent to Payment Express.

Please note these error codes are related to the functionality of PxPay 2.0 interface itself and are different to the ReCo related to the host, bank or acquirer that you receive in the final transaction response XML document.

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 Express hosted 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 Auth transaction, but within 7 days maximum, a Complete transaction must be sent containing the DpsTxnRef returned by the Auth transaction. This should be done using either PxPost, AUTH SSL, Web Service or Payline/Payment manager (manual option).

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 or leave it blank and use the ID returned in

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 PxPost, DPS 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.

PxPay 2.0 Sample Pages:

PxPay 2.0

PxPay 2.0

The PX Pay 2.0 interface is a platform independent Hosted Payments Page (HPP) solution provided by Payment Express. The HPP provides a solution for the capturing credit card information securely without exposing the merchant to the sensitive data.