Note: This has been deprecated in favour of PxPay2 API. Support for existing integrator is still available. If you are still using original PxPay interface, we recommend that you integrate for PxPay2 API.
PxPay allows merchants to send transactions to Payment Express via HTTPS posts to https://sec.paymentexpress.com/pxpay/pxaccess.aspx. Payment Express responds with a unique URL for an SSL secure payments page at which the user will be prompted to enter their credit card details and complete the transaction. The result is displayed and the user is automatically directed back to the merchant's website. The result and other transaction details can then be extracted by the merchant. PX Pay is platform independent as transaction requests and responses are made using XML which can be generated and read in any programming language.
| No Payment Express software required |
|---|
| 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.dpsdemo.com |
| 1stWebDesign | ASPDotNetStoreFront | Big Commerce |
| Bloom Tools | BusinessCatalyst | CactusLab |
| CityXpress | Civicrm | Comersus |
| Contegro | CS-Cart | DotNetNuke |
| Dremus | Early Impact | Eazyshop |
| GetPaidGoldbar | OneInterspire | MagentoMalsMix |
| MyPaymentForm | NetIDNow | NetMerchant |
| Oceanic | OnPix | OpenCart |
| OPMC | osCommerce | OZCart |
| PrestaShop | ProductCart | Rad3 |
| Reserve Group | Rocket Cart | SalesCart |
| Shopify | StockboxPhoto | StoresOnline |
| Supermodel | Ubercart | UltraCart |
| VirtueMart | VPAsp | WHMCS |
| Wicked Eye | X-Cart | YourMembership |
| Zen Cart | Storbie | CoreCommerce |
| GPOS | WooCommerce | ShopFactory |
| Do Webs | WP EasyCart | Rocketspark |
| Website Builder | Vend | SmithCart |
The following is a description of the inputs and outputs of the transaction request.
| Input Element | Required | Description |
|---|---|---|
| PxPayUserId | Yes | Your account's user ID |
| PxPayKey | Yes | Your account's 64 character key |
| AmountInput | Yes | Amount value in d.cc format |
| BillingId | No | Optional identifier when adding a card for recurring billing |
| CurrencyInput | Yes | Currency of AmountInput |
| EmailAddress | No | Optional email address |
| EnableAddBillCard | No | Required when adding a card to the Payment Express system for recurring billing. Set element to "1" for true |
| MerchantReference | No | 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" or "Purchase" |
| TxnId | No | A value that uniquely identifies the transaction |
| UrlFail | Yes | URL of the merchant transaction failure page. No parameters ("&" or "?") are permitted. |
| UrlSuccess | Yes | URL of the merchant transaction success page. No parameters ("&" or "?") are permitted. |
| Opt | No | Optional additional parameter |
| 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 user to. |
The following is used to decode the result of the transaction after it has been submitted and get the XML response back.
| Input Element | Required | Description |
|---|---|---|
| PxPayUserId | Yes | Your account's User ID |
| PxPayKey | Yes | Your account's 64 character key |
| Response | Yes | The encrypted URL response from Payment Express which you can obtain from "result" parameter in the URL string that is returned to your response page. |
| 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 acquirer |
| CardName | Card used (Visa MasterCard Amex Diners etc.) |
| CardNumber | The card number used for the transaction in truncated form |
| DateExpiry | The expiry date of the card used in the transaction |
| DpsTxnRef | Payment Express transaction reference. Can be stored and later used to process complete or refund 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 Payment Express 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 |
| TxnType | "Auth" or "Purchase" as submitted in the GenerateRequest |
| CurrencyInput | Currency as submitted in the GenerateRequest |
| MerchantReference | MerchantReference as submitted in the GenerateRequest |
| ClientInfo | The IP address of the user who processed the transaction |
| TxnId | The TxnId supplied in the GenerateRequest |
| EmailAddress | The EmailAddress supplied in the GenerateRequest |
| BillingId | The BillingId as supplied in the GenerateRequest |
| TxnMac | Indication of the uniqueness of a card number |
| CardNumber2 | Contains a token generated by Payment Express when adding a card for recurring billing |
| Cvc2ResultCode | CVC / CVV2 Result Code associated with the result of the CVC validation |
| ReCo | 2 character response code |
AmountInput (input) must be in an appropriate format e.g. "10".
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 characters
The cardholder name as it appears on customer card.
CardName (output)Datatype: BSTR Max 16 characters
The card type used for the transaction.
CardNumber (output) Datatype: BSTR Max 20 characters
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 |
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 CVC result code indicate the following:
| 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 characters
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 characters
Optional email address field. Will be returned to origin site for emailing of receipts etc.
EnableAddBillCard (input) Datatype: BSTR 1 characters
To have Payment Express store card details for subsequent billing purposes set this to "1".
MerchantReference (input) Datatype: BSTR Max 64 characters*
Free text to appear on transaction reports.
*For pago transactinos the max length of the Merchantreference field is reduced to 50 characters
Opt (input) Datatype: BSTR Max 64 characters
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 characters
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 characters
Unique username to identify customer account. Assigned on account setup by Payment Express support team.
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 Succes 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 characters
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 32 characters
Optional free text fields. Usually assigned at origin web site.
TxnId (input/output) Datatype: BSTR Max 16 characters
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
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 characters
Url of page to redirect to if transaction failed. No parameters (&, ?) are permitted.
UrlSuccess (input) Datatype: BSTR Max 255 characters
Url of page to redirect to if transaction successful. No parameters (&, ?) are permitted.
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".
The above example should be formatted as follows:
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;
The merchant web application should;
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.
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.
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 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:
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.
