PX Pay Interface for the Hosted Payments Package

PX Pay is designed to allow merchants to send transactions to Payment Express® via https posts, which links to a 128-Bit SSL secure payments page at https://www.paymentexpress.com/pxpay/pxaccess.aspx. The cardholder is automatically prompted to enter their details and a response is displayed. The result is automatically communicated back to the original site the transaction came from.
The product is platform independent as the host interface handles XML, which can be generated with any language on the client side.

A redundant post of the response is given back to the merchant site. No session variables will be included in this response as it is independent of the merchants web server.

Technical Specifications/Features:
  • No DPS software needed
  • No SSL Certificate Required
  • Fail-proof result notification
  • Multiple Account Selection
  • Unsecured web sites can link to different customized secure payment pages depending on which merchant account the transaction should be charged to.
  • Optional reference fields are available to hold information that will appear on transaction reports.
  • Multi-Currency Support
  • Demonstration site at www.pos.co.nz

Requirements/ Downloads:

Using PX Pay

How it works -

  1. Send XML transaction request (GenerateRequest) to PaymentExpress
  2. Receive XML response (Request) with the URI element (encrypted URL), which you use to redirect the user to PaymentExpress so they can enter their card details
  3. Cardholder enters their details and transaction is sent to your bank for authorisation. The response is given and they are redirected back to your site with the response
  4. You take the "Request" parameter (encrypted URL response) in the URL string and use this in the "Response" element, to send the response request (ProcessResponse) to PaymentExpress to decrypt and receive the XML response back.
  5. Receive XML response (Response) with the authorised result of the transaction.

Transaction Request

The following is a description of the inputs and outputs of the transaction request.

GenerateRequest (Input XML Document)

Input Element Required Description

PxPayUserId

Yes

Your account's UserId

PxPayKey

Yes

Your account's 64 character key

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 DPS when adding a card for recurring billing. Needed for rebilling transactions when you do not use your own BillingId.

DpsTxnRef

No

DPS transaction reference. Sent back to DPS for refund and complete transactions.

EmailAddress

No

Optional Email Address

EnableAddBillCard No Needed for recurring billing transactions when adding a card to the DPS 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

Auth, Complete, Purchase, Refund (DPS recomend completeing refunds through other API's)

TxnId No Contains a unique, COM or merchant application generated value that uniquely identifies the transaction

UrlFail

Yes

Url of customer site transaction failure page

UrlSuccess

Yes

Url of customer site transaction success page



<GenerateRequest>
<PxPayUserId>TestAccount</PxPayUserId>
<PxPayKey>dc339b3126c8fbadf4b30b498ded6a62a17b5f831e3111116bd8 e332c730bbc8</PxPayKey>
<AmountInput>2.06</AmountInput>
<CurrencyInput>NZD</CurrencyInput>
<MerchantReference>Test Transaction</MerchantReference>
<EmailAddress></EmailAddress>
<TxnData1>28 Grange Rd</TxnData1>
<TxnData2>Auckland</TxnData2>
<TxnData3>NZ</TxnData3>
<TxnType>Purchase</TxnType>
<TxnId>P777575CA3DDA78C</TxnId>
<BillingId></BillingId>
<EnableAddBillCard>0</EnableAddBillCard>
<UrlSuccess>http://www.mycompany.com/success.cfm</UrlSuccess>
<UrlFail>http://www.mycompany.com/fail.cfm</UrlFail>
</GenerateRequest>

Request (Output XML Document)

Output Element Description

Valid [Attribute]

Whether the request was valid. "1" for valid and "0" for an invalid request

URI

URL including Encrypted Transaction Request that you will need to redirect the customer to.



<Request Valid="1">
<URI>https://www.paymentexpress.com/pxpay/pxpay.aspx?userid=TestAccount
&request=e88cd9f2f6f301c712ae2106ab2b6137d86e954d2163d1042f73cce130b2c 88c06daaa226629644dc741b16deb77ca14ce4c59db84929eb0280837b92bd2ffec 2fae0b9173c066dab48a0b6d2c0f1006d4d26a8c75269196cc540451030958d257c1 86f587ad92cfa7472b101ef72e45cda3bf905862c2bf58fc214870292d6646f7c4ad 02a75e42fc64839fc50cea8c17f65c6a9b83b9c124e2f20844b63538e13a8cff17ec d8f165aee525632fd3661b591626f5fb77725ade21648fed94553f43bfa69acf3557 0ff8fdcbaf8a13a3fa7deb244017e41749e652a3549a5dbe20c6c3a7a66aa5901e3f 87150f7fc</URI>
</Request>

Transaction Response

The following is used to decode the result of the transaction after it has been submitted and get the XML response back.

ProcessResponse (Input XML Document)

Input Element Required Description

PxPayUserId

Yes

Your account's UserId

PxPayKey

Yes

Your account's 64 character key

Response

Yes

The encrypted URL response from DPS, which you can get from "Result" parameter in the URL string that is returned to your response page.



<ProcessResponse>
<PxPayUserId>TestAccount</PxPayUserId>
<PxPayKey>dc339b3126c8fbadf4b30b498ded6a62a17b5f831e3111116bd8 e332c730bbc8</PxPayKey>
<Response>df6cc75b4f9e23b66c0a84955a7b1ab663f27dba0d710ac4ee911c7 48d98f8432872b2b64380e3ae39aaa0c0ba5d093c6bd8b9141a74232ca1632bf1 1f8e4ad5f5c5399d659d44b0307ffb2f44a998dd75d3c9a06c56a3672b6c1ae13 f135e8f7023c75c03401cf3334ac9021c8fa5d1be2056a35035c0dfb024d5305 9371d262bf1680fa2b6a3a8c608066e7dcf8221eb9ed6193452d09dbb6f377ea 8bfe5116fe19ef625adbc84bc3b6af9e35a0dde9fd003302da1039ff6</Response>
</ProcessResponse>

Response (Output XML Document)

Output Element Description
Valid [Attribute] Whether the request was valid. "1" for valid and "0" for an invalid request.

AmountSettlement

The Amount of the transaction

AuthCode Authorisation code from the bank
CardName Card used (Visa,MasterCard,Bankcard etc)
CardNumber The card number used for the transaction in truncated form.
DateExpiry The expiry date of the card used in the transaction.

DpsTxnRef

DPS transaction reference. Sent back to DPS for refund and complete transactions.

Success

Non-zero if transaction successful, 0 if declined or unsuccessful

ResponseText

Response Text associated with the result of the transaction

DpsBillingId

Contains the billing ID generated by DPS when adding a card for recurring billing.

CardHolderName

The Card Holder Name used for the transaction

CurrencySettlement

The Currency of the transaction

TxnData1

Optional Free Text

TxnData2

Optional Free Text

TxnData3

Optional Free Text



<Response valid="1">
<Success>1</Success>
<TxnType>Purchase</TxnType>
<CurrencyInput>NZD</CurrencyInput>
<MerchantReference>Test Transaction</MerchantReference>
<TxnData1>28 Grange Rd</TxnData1>
<TxnData2>Auckland</TxnData2>
<TxnData3>NZ</TxnData3>
<AuthCode>053646</AuthCode>
<CardName>Visa</CardName>
<CurrencyName>NZD</CurrencyName>
<TxnId>P777575CA3DDA78C</TxnId>
<EmailAddress></EmailAddress>
<DpsTxnRef>000000040119429b</DpsTxnRef>
<BillingId></BillingId>
<DpsBillingId></DpsBillingId>
<CardHolderName>TEST</CardHolderName>
<AmountSettlement>2.06</AmountSettlement>
<CurrencySettlement>NZD</CurrencySettlement>
<ResponseText>APPROVED</ResponseText>
</Response>

Well Formed XML

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


<GenerateRequest>
<TxnData1>Bill & Son</TxnData1>
<MerchantReference>Abc >> 123</MerchantReference>
</GenerateRequest>

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".

The above example should be formatted as follows:


<GenerateRequest>
<TxnData1>Bill &amp; Son</TxnData1>
<MerchantReference>Abc &gt;&gt; 123</MerchantReference>
</GenerateRequest>

Element Properties

AmountInput (input) Datatype: BSTR Max 13 characters
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. The currently Maximum value allowable is $99,999.99. Note that acquirer or card limits may be lower than this amount.

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.

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

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

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
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
PNG 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.

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. Assigned on Account Setup by Payment Express support team.

PxPayUserId (input) Datatype: BSTR  Max 32 bytes
Unique username to identify customer. Assigned on Account Setup by Payment Express support team.

Response (input) Datatype: BSTR
The encrypted URL response from DPS, 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
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.

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.

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
Url of page to redirect to if transaction failed. No parameters (&, ?) are permitted.

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

Fail Proof Result Notification

It is highly recommended that Fail Proof result notification is configured by Payment Express. This setting (EnablePost Response) set at Payment Express host, ensures that the following process occurs for every transaction:

Transaction is performed via hosted payment page. As soon as the transaction is complete, but prior to the results being displayed for the user, a background process issues a HTTP GET to the merchant specified payment page response (UrlSuccess or UrlFail). If the merchant web site is unreachable or returns a response other than "200 OK", the GET is retried every minute for 30 minutes, thereafter every 15 minutes until a preset limit is exhausted. Merchant sites should therefore allow for the possibility that their application could receive more than one notification for the same transaction. The merchant application can distinguish which transaction the response is for by checking the TxnId value.

The Merchant application can optionally indicate a transient application failure by inserting the string <!-- Dps_ReCo=xx -->. If "xx" is any value other than "00", Payment Express will keep retrying the HTTP Request until either retries are exhausted or until the page contains <!-- Dps_ReCo=00 -->. This could be used to handle a temporary database issue at the customer site preventing successful transaction update for example.

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 or DpsBillingId, a MerchantReference, and the amount to be charged. 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.


Copyright 2007 Direct Payment Solutions Ltd. All rights reserved. | Legal Notice | Privacy Policy