PX Post
PX POST is designed to handle transactions using a HTTPS Post Request. The XML is generated at the client site and sent to https://www.paymentexpress.com/pxpost.aspx.
There is no DPS software needed on the client side, which makes it platform and language independent. This allows for greater flexibility & interoperability.
| Technical Specifications/Features: | |
|
|
| Requirements/Downloads: | |
|
|
Transaction variables are posted to pxpost.aspx in xml form.
|
| Parameter | Required | Description |
Yes |
Amount of Transaction (dddddd.cc) |
|
No |
Card holder's name |
|
No |
Card Number |
|
No |
Needs to be generated to add a card for recurring billing and sent again when rebilling transactions. |
|
No |
Card Verification number. This number is found on the back of a credit card in the signature panel - it is different from the embossed card number and provides an additional safety check. |
|
No |
Expiry Date on Card |
|
| DpsBillingId | No | The BillingId generated by DPS when adding a card for recurring billing. Needed for rebilling transactions when you don't use your own BillingId. |
| DpsTxnRef | No | Output from an original transaction request. Is a required field to do second stage transactions like Refund and Complete. |
No |
Needed for recurring billing transactions when adding a card to the DPS system. Set element to 1 for true and 0 for false |
|
No |
You will need to specify a currency here if you will be doing transactions in multiple currencies. |
|
No |
Optional Reference to Appear on Transaction Reports Max 64 Characters |
|
Yes |
Username of Account (Supplied by Dps) |
|
Yes |
Password of Account (Supplied by Dps) |
|
Yes |
'Purchase', 'Auth', 'Complete', 'Refund', 'Validate' |
|
No |
Optional Free Text |
|
No |
Optional Free Text |
|
No |
Optional Free Text |
|
| TxnId | No | Used for checking the status of a transaction |
No |
Address Verification System property. Values are 1 (Enable Verification), 0 (Disable Verification). |
|
No |
Address Verification System property. Values are 0,1 & 2. |
|
No |
Address Verification System property. Post Code that is listed on the customer's bank statement |
|
No |
Address Verification System property. Address that is listed on the customer's bank statement. |
|
No |
The Issue date of the customer's credit card, if Issuer requires this field to be present. |
|
No |
The Issue Number of your credit card if Issuer requires this field to be present. |
|
| Track2 | No | Extracted from Track2 of credit card. |
The Response to the POST is in XML form. The status of a transaction is indicated by the Authorized element (0 = Declined, 1 = Accepted).
In the following example, a transaction for $1.23 is requested for cardholder A J CARDHOULD, card number is 4111111111111111, the origin of the transaction is a telephone order, Expiry date is Jan 2002, Merchant Reference for the transaction is "Test Transaction".
| <Txn> <Transaction success="1" reco="00" responsetext="APPROVED"> <Authorized>1</Authorized> <MerchantReference>Test Transaction</MerchantReference> <Cvc2></Cvc2> <CardName>Visa</CardName> <Retry>0</Retry> <StatusRequired>0</StatusRequired> <AuthCode>015921</AuthCode> <Amount>1.23</Amount> <InputCurrencyId>1</InputCurrencyId> <InputCurrencyName>NZD</InputCurrencyName> <Acquirer>WestpacTrust</Acquirer> <CurrencyId>1</CurrencyId> <CurrencyName>NZD</CurrencyName> <CurrencyRate>1.00</CurrencyRate> <Acquirer>WestpacTrust</Acquirer> <AcquirerDate>30102000</AcquirerDate> <AcquirerId>1</AcquirerId> <CardHolderName>DPS</CardHolderName> <DateSettlement>20050811</DateSettlement> <TxnType>Purchase</TxnType> <CardNumber>411111</CardNumber> <DateExpiry>0807</DateExpiry> <ProductId></ProductId> <AcquirerDate>20050811</AcquirerDate> <AcquirerTime>060039</AcquirerTime> <AcquirerId>9000</AcquirerId> <Acquirer>Test</Acquirer> <TestMode>1</TestMode> <CardId>2</CardId> <CardHolderResponseText>APPROVED</CardHolderResponseText> <CardHolderHelpText>The Transaction was approved</CardHolderHelpText> <CardHolderResponseDescription>The Transaction was approved</CardHolderResponseDescription> <MerchantResponseText>APPROVED</MerchantResponseText> <MerchantHelpText>The Transaction was approved</MerchantHelpText> <MerchantResponseDescription>The Transaction was approved</MerchantResponseDescription> <GroupAccount>9997</GroupAccount> <DpsTxnRef>00000004011a2478</DpsTxnRef> <AllowRetry>0</AllowRetry> <DpsBillingId></DpsBillingId> <BillingId></BillingId> <TransactionId>011a2478</TransactionId> </Transaction> <ReCo>00</ReCo> <ResponseText>APPROVED</ResponseText> <HelpText>The Transaction was approved</HelpText> <Success>1</Success> <TxnRef>00000004011a2478</TxnRef> </Txn> |
| Parameter | Description |
| AuthCode | Authorisation code given back from the bank for that transaction |
| Authorized | 1 if transaction successful - 0 if declined or unsuccessful |
| DateSettlement | Date transaction will be settled to Merchant Bank Account in YYYYMMDD format |
| DpsTxnRef | Required for refund and complete transactions. |
| DpsBillingId | Contains the BillingId generated by DPS when adding a card for recurring billing. |
| HelpText | A more detailed explanation of the response from the bank |
| ReCo | 2 character response code |
| ResponseText | Response Text associated with ResponseCode |
| StatusRequired | 1 if the result of the transaction could not be determined. See the Exception Handling section. |
| Success | 1 if transaction successful - 0 if declined or unsuccessful. Will be the same value as Authorized |
If you didn't receive a response to your Post, or if StatusRequired was set to 1 in the response, then you must send another Post to request the status of the transaction. For this function to work you will need to send up a TxnId with your origninal transaction. TxnId must be a unique value for each transaction. It can be up to 16 characters long.
XML Format of a transaction status Post:
|
or
|
Character data sent via PX Post must be well formatted 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:
|
Amount (input)Datatype: String 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.
AuthCode (input) Datatype: String Max 22 characters
Authorization code returned for approved transactions.
Authorized (output) Datatype: Boolean
Indicates if the transaction was authorized or not. Either False (0) or True (1)
BillingId (input) Datatype: String Max 32 characters
If a token based billing transaction is to be created, a BillingId has to 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. To add a BillingId in the transaction request
the EnableAddBillCard element needs to be present and set to 1 (true). Upon rebilling this will need to be set to 0
(false).
CardHolderName (input)Datatype: String Max 64 characters
The cardholder name as it appears on customer card. Optional and may be left blank.
CardNumber (input) Datatype:String Max 20 characters
The card number. No leading or embedded blanks are permitted. Must contain a numeric value.
Cvc2 (input) Datatype: String Max 4 characters
Card 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)
MasterCard: Card Verification Code 2 (CVC2)
Visa: Card Verification Value 2 (CVV2)
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: String Max 4 characters
Indicates 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 characters
Indicates 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.
DpsBillingId(input)Datatype: String 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 set to 1 (true) indicating a token billing entry should be created.
DpsTxnRef (input/output) Datatype: String Max 16 characters
Returned for every transaction. If the transaction was approved, DpsTxnRef can be used as input to a Refund transaction.
Used to specifiy a transaction for refund without supplying the original card number and expiry date. The DpsTxnRef value
returned by the original approved Auth transaction must be supplied also when doing a complete transaction.
EnableAddBillCard (input) Datatype: Boolean
To automatically add a card for subsequent billing purposes, set this to 1 (true). When generating a Billing Transaction
for a previously loaded BillingId or DpsBillingId, EnableAddBillCard must be 0 (false).
DateStart (input) Datatype: String Max 4 characters
The Issue date of the customer's credit card, if Issuer requires this field to be present.
Format is MMYY where MM is month 01-12 and Year 00-99. do not insert "/" or other delimiter.
Used for Maestro/Solo cards.
IssueNumber (input) Datatype: INT
The Issue Number of your credit card if Issuer requires this field to be present.
EnableAvsData (input) Datatype: INT
Address Verification System property. Values are 1 (Enable Verification), 0 (Disable Verification). Your bank may require
that you use AVS, in which case you will need to set to 1.
AvsPostCode (input) Datatype: String Max 20 characters
Address Verification System property. Post Code that is listed on the customer's bank statement.
AvsStreetAddress (input) Datatype: String Max 60 characters
Address Verification System property. Address that is listed on the customer's bank statement.
AvsAction (input) Datatype: INT
Address Verification System property. Values are 0, 1 & 2.
0 - Don't check AVS details with acquirer, but pass them through to Payment Express only.
1 - Attempt AVS check. If the acquirer doesn't support AVS or is unavailable, then transaction will proceed as normal. If AVS is supported it will check the transaction and give the result.
2 - The transactions needs to be checked by AVS, even if isn't available, otherwise the transaction will be blocked.
3 - AVS check will be attempted and any outcome will be recorded, but ignored i.e. transaction will not be declined if AVS fails or unavailable.
The value will most likely be 1 for most circumstances.
InputCurrency (input) Datatype: String Max 4 characters
Indicates currency used for this transaction. If blank, currency will be determined by the bank account used which is
selected using the Username/Password details. Not all acquirers can support multiple currencies. Please check here to see an updated list. All other banks can only transact in their home currency. Valid values for Currency are:
| 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 |
| PGK | Papua New Guinea Kina |
| MYR | Malaysian Ringgit |
| KWD | Kuwaiti Dinar |
| FJD | Fiji Dollar |
MerchantReference (input) Datatype: String Max 64 characters
Free text to appear on transaction reports.
TxnData1, TxnData2, TxnData3 (input) Datatype: String Max 255 characters
Optional free text fields. Usually assigned at origin website.
TxnId(input/output) Datatype: String Max 16 characters
Input: contains a unique, merchant application generated value that uniquely identifies the transaction. If TxnId is used, you can check the status of a transaction. Where possible it is recommended that the merchant application sets this value.
PostPassword (input) Datatype: String Max 32 characters
Used with PostUsername to determine account for settlement. Payment Express clients can be set up with more than one bank account. Each transaction may be designated for a specific account if required.
PostUsername (input) Data type: String Max 32 characters
Used with PostPassword to determine account for settlement. Payment Express clients can be set up with more than one bank account. Each transaction may be designated for a specific account if required.
ReCo (Response Code) (output) Datatype: String Max 2 characters
The client application should not interpret the Response Code property contents - it is provided as informational only. The Authorized property determines if the the transaction was successful or not.
StatusRequired (output) Datatype: Boolean
1 if transaction result is unknown - 0 if transaction result is in the response. See the Exception Handling section.
Success (output) Datatype: Boolean
1 if transaction successful - 0 if declined or unsuccessful. Will be the same value as Authorized
TxnType (input) Datatype: String
| Value | Meaning |
| Auth | Authorizes a transactions. 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. Must be enabled as a special option. |
| Validate | Validation Transaction. Effects a $1.00 Auth to validate card details including expiry date. Often utilised with the EnableAddBillCard property set to 1 to automatically add to Billing Database if the transaction is approved. |
Track 2 DataType: String Max 37 characters
Extracted from Track2 of credit card. Numeric with an equal sign.
Example:
4111111111111111=08101011179517320000
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.
Set TxnType to "Auth" for for the amount to be authorised. The Auth response contains a DpsTxnRef. The funds are not transferred from the cardholder account.
After a successful Authorization 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 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
A setup phase involves loading a card into Payment Express. Optionally the setup phase can include an online $1.00 authorisation (Validate) 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 new transaction request with the following properties:
CardHolderName (optional - strongly recommended)
MerchantReference
CardNumber
DateExpiry
Amount
EnableAddBillCard(Set to true when adding a card)
BillingId (optional - included when generating own billing id. Else, can use returned DpsBillingId determined by Payment Express)
The merchant application or Batch processor requests a new transaction and supplies the appropriate BillingId, or DpsBillingId a MerchantReference which appears on reports 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.
PX Post is capable of handling refunds (credit) transactions, however you will need to match the original Purchase or Complete transaction for this to happen. The matching is done with the DpsTxnRef given from the response of a purchase or complete transaction. You are able to do multiple refund transactions to the maximum amount of the original matched transaction.
The TxnType will be Refund.
The Payment Manager is provided to merchants with all integrated solutions by DPS, so there is a ready built interface to handle refund transactions already. However, if you wish to integrate refunds into your own interfaces the following input properties need to be provided for a refund transaction:
TxnType = Refund
DpsTxnRef
MerchantReference
Amount
|
The client application should not interpret the ReCo (Response Code) property contents - it is provided as information only. The Success property determines if the the transaction was successful or not.
The following table provides assistance in troubleshooting errors.
| Error Code | Explanation |
D2 |
No such user for PXPost. Please contact DPS to confirm your account information. |
D3 |
Blank password for PX Post. Please contact DPS to confirm your account information. |
D5 |
Invalid Password for PxPost. Please contact DPS to confirm your account information. |