PX XML Interface

Payment Express provides a payment gateway interface to banking settlement systems via an independent host. Linux and NT Servers are available for Payment Express. Both Linux and NT versions expose an XML Interface that may be controlled by a client application.

XML Command Format

Commands are sent by the client application to the Payment Express Server via a TCP connection to port 3004. The command is always enclosed by a MifCommand tag and the tag contains an attribute named "action" that identifies the oprration to be performed. The format of the action attribute is typically doXxxYyy where Xxx is the class of command (e.g.: Txn, Link) and Yyy the operation (e.g.: Transaction, Status) The information payload is

Sample XML Command to initiate a transaction

Not all XML data elements are required. See Elements Description for detailed information about each data element. 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 Order1234. The TxnRef element supplied is generated by the application.

XML Response Format

Responses are received by the client application nt Express Server on TCP port 3004.

Sample XML Response

See Elements Description for detailed information about each data element. 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 Order1234.

doLinkStatus Command

Purpose

Checks connection to Payment Express Server and upstream connection status to Payment Express Host. ServerOk indicates Payment Express Server is functioning OK. LinkOk indicates upstream link is also Ok. (1 if of 0 if not OK).

Command Format

Response Format

The response indicates whether the server is online and ready for transactions via the "LinkOk" element. ServerOk indicates that the Payment Express Server is online and LinkOk indicates that the connection upstream to Payment Express Host is connected and available.

doTxnTransaction Command

Purpose

Initiates a request to perform a financial transaction to the Payment Express Server.

doTxnTransaction Command Format

doTxnTransaction Response Format

Data Elements

This sections describes each data element of the command and response pairs in detail. Some elements are present in both Command (input) and response (output) messages. Other elements are present in one type of message.

Input Elements

Element Required Notes
Amount Yes Amount of Transaction (dddddd.cc)
CardHolderName Yes Card Holders Name
CardNumber Yes Card Number
ClientInfo No
Cvc2 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.
DateExpiry Yes Expiry Date on Card
EnableDuplicateCheck No Defaults to 0 (false) if not specified
EnableRm No Defaults to 0 (false) if not specified.
GroupAccount No1 Note 1
InputCurrency No You will need to specify a currency here if you will be doing transactions in multiple currencies.
MerchantReference No Optional Reference to Appear on Transaction Reports Max 64 Characters
Password No1 Note 1
ReceiptEmail No Optional Email Address
TxnClass No
TxnRef Yes Obtained from doLinkConnect or LinkConnect or generated by application.
TxnType Yes 'Purchase' 'Auth' 'Complete' 'Refund' 'Validate'
Username No1 Note 1

Note 1 - Either GroupAccount OR a Username/Password combination is required. See documentation for these elements for further information.

Output Elements

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

doTxnStatus (Exception Handling)

doTxnStatus is used when a call to doTxnTransaction fails and the StatusRequired element is returned as 1. This indicates that Payment Express Server has transmitted a transaction request to Payment Express Host, but a response was not received within a timeout period or the link to Payment Express Host or beyond failed while awaiting a response. In either of these circumstances, the result of the transaction is indeterminate. The doTxnStatus command should be used to retrieve the actual completion status. DoStatus uses the original TxnRef values which uniquely identifies the transaction to lookup the transaction at the Payment Express Host and return the results. Example:

Client Application connects to Payment Express Server

  • Client Application sends doLinkConnect
  • Client application receives response from doLinkConnect providing the TxnRef.
  • Client Application sends doTxnTransaction tagged with TxnRef received in step 2.
  • Link between Payment Express Server and Payment Express Host is interrupted
  • Payment express returns doTxnTransaction response to client withStatusRequired element set to 1.
  • Client Application checks StatusRequired property.
  • Client Application performs following error recovery: Pseudo Code: While StatusRequired is true Client Application sleeps for 5 seconds Client Application calls doTxnStatus End While

Once the client application has confirmed the result of the transaction with the Payment Express Server with the doTxnStatus command, normal processing of subsequent transactions using doLinkConnect/doTxnTransaction can resume.

Sample doTxnStatus Command Format

Sample doTxnStatus Command Format

Sample doTxnStatus Response Format

Data Elements

Note. Optional Indicates that the element need not be supplied.

AcquirerId (output) Data type: number

ID of Acquirer that processed the transaction.

Name Acquirer Id
ANZ AU 5
ANZ NZ 2
BNZ 4
National Bank 3
RFS 6
St George 8
WestpacTrust 1
Test 9000

AcquirerName (output) Data type: string Max 32 characters

Name of Acquirer that processed the transaction. See table under AcquirerId for list of Acquirer Names.

AcquirerDate (output) Data type: string Max 8 characters

Indicates Date of transaction as recorded by Acquirer Host in YYYYMMDD format. This field may be blank if the transaction was rejected locally or otherwise not processed by the bank host.

AcquirerTime (output) Datatype: string Max 6 characters

Indicates Time of transaction as recorded by Acquirer Host in HHMMSS format. This field may be blank if the transaction was rejected locally or otherwise not processed by the bank host.

Address1 (input) Data type: string Max 32 characters

Optional. Cardholder Billing Address Line1 - may be used by Payment Express Host for additional verification purposes.

Address2 (input) Data type: string Max 32 characters

Optional. Cardholder Billing Address Line2 - may be used by Payment Express Host for additional verification purposes.

Address3 (input) Data type: string Max 32 characters

Cardholder Billing Address Line3 - may be used by Payment Express Host for additional verification purposes.

Amount (input/output) Data type: 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". Maximum value allowable at this time is 99999.99. Note that acquirer or card limits may be lower than this amount.

AuthCode (input/output) Data type: string Max 64 characters

Authorisation code. A variable length string returned by Card Acquirer. For credit card transactions, contains the bank authorisation code and additional acquirer specific information if required.

CardId (output) Data type: number

Id of card used for transaction.

CardName (output) Data type: string Max 16 characters

The card type used for the transaction. Note that the list may be expanded as support for new cards is added.

CardName CardId Description
Amex 6 American Express
Bankcard 5 Bank Card
Diners 7 Diners
Jcb 3 JCB
MasterCard 1 Mastercard
Rfs 4 Retail Finance Services (Farmers)
Visa 2 Visa

CardHolderName (input) Data type: string Max 64 bytes, optional

The cardholder name as it appears on customer card. Optional and may be left blank.

CardNumber (input/output) Data type: string Max 40 bytes

The card number. No blanks are permitted. Must contain a numeric value. The only exception is for transactions where the TxnClass is "CardRead" or "CardReadNoOperator" indicating a card swipe value. In this case, CardNumber contains the contents of the customer card Track2.

ClientInfo (input) Data type: string Max 64 characters

Optional. Internet Address of the browser or other information such as username.

CurrencyId (output) Data type: number

Id of Currency that transaction was settled in.

CurrencyName (output) Data type: string Max 32 characters

Name of Currency that the transaction was settled in.

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

Cvc2 (input) Data type: string Max 4 bytes

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. Currently acquirers do not validate this number and cardholders have not been educated as to its use so applications need not send this element.

DateExpiry (input) Data type: string Max 4 bytes

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) Data type: string Max 8 bytes

Indicates Date of settlement if this is supported by the Acquirer, otherwise contains the date the transaction was processed in YYYYMMDD format.

EnableDuplicateCheck (input) Data type: number (0 or 1)

If 1 indicates a check should be made for the last accepted transaction. If the last accepted transaction as the same card number and amount as the current transaction, it is failed "DU" duplicate. The client can then resend the transaction with EnableDuplicateCheck set to 0 if the transaction is really wanted. If not present, default is to not check for duplicate transactions.

EnableRm (input) Data type: number (0 or 1)

If 1 indicates if Risk Management should be enabled for the transaction. Risk Management provides for velocity checking and other anti-fraud measures. This field is optional. If not present, the system will default to no risk management checking.

GroupAccount (input) Data type: number (0 to 9999)

Indicates account to use for transaction. Customer defined number from 0-9989. Group Accounts 9990 to 9999 are reserved for testing purposes. For example, a customer may have account 1 for a certain kind of transaction that needs to be settled to a specific bank account and account 2 for another transaction and bank account. Another example is GroupAccount 1 setup to settle NZD bank account and GroupAccount 101 setup to settle in AUD.

MerchantReference (input) Data type: string Max 64 bytes

Client Application supplied reference string, e.g.: order reference. May be blank. May be used for reconciliation purposes.

Password (input) Data type: string Max 32 characters

Used with Username to select a specific GroupAccount as settlement destination for a transaction. Payment Express Host is configured to accept transactions tagged by either GroupAccount number OR by Username/Password combination. For ISPs and other resellers of Payment Express, the Username/Password approach is usually better as less possibility of mistakes.

ReCo (output) Data type: string Max 2 characters

Response Code generated by Payment Express Server (for locally declined transactions) or by the Card Acquirer (for host originated responses). The ResponseCode should not be checked by the client application using DPSAUTH as these values differ according to acquirer. Use the Authorized property to check for successful completion of a transaction. Refer to section Response Codes for a list of valid response codes generated by acquirers and locally by the Payment Express Server or DPSAUTH control.

ReceiptEmail (input) Data type: string Max 64 characters

Email address to send a transaction receipt. If not blank, this must be a valid email address in the form user@company.com. Note: Not currently implemented in Payment Express host.

ResponseText (output) Data type: string Max 32 bytes

Refer to section Response Codes for a listing of response text values.

Retry (output) Data type: boolean (0 or 1)

If true (1), indicates that the transaction was not processed due to a transient condition, such as no available port. When true, the applicationmay retry the transaction if required. This information is especially useful to batch processing applications.

StatusRequired (output) Data type:boolean (0 or 1)

If false (0) a response was successfully retrieved from the Payment Express Hostor that no message was sent to Payment Express Host because of a local error. No further action is required in this case. If true after a transmitting adoTxnTransaction, request a message was sent to Payment Express, but a valid response was not received. In this, case, the result of the transaction is undetermined and error - recovery is required. See doTxnStatus for further information.

ServerSoftware (output) Data type: string Max 32 characters

Describes server software. Currently Either "PXNT" for Payment Express servers running on NT or "PXLINUX" for servers running on Linux.

Success (output) Data type numeric (0,1)

Indicates success or failure of a method call.

TxnClass (input) Data type: string Max 32 byte

Class of transaction.

Value Meaning
Ivr IVR (Interactive Voice response)
CHNotPresent Card Holder Not Present (generic) Vending Vending device or kiosk.
WebServer Internet (WebServer etc)
MailOrder Mail Order Transaction
TelephoneOrder Telephone Order Transaction
CardReadOperator Card Swipe And Attendant Present
CardRead Card Swipe and no attendant present

The TxnClass property describes the origin of the transaction, for example; Vending machine or from a Web Server. In addition, information can be attached to describe frequency of the transaction: Installment, Recurring.

TestMode (output) Data type: numeric (0,1)

If 1, indicates the transaction was performed to a Test account, not a live merchant account. A Test account will never result in funds transfer even if a valid card is used. This would be the case if username test/password test was specified for a transaction.

TxnRef (input/output) Data type: string Max 6 characters

Payment Express Reference number for the transaction. Obtained prior to callingdoTxnTransaction by calling doLinkConnect. Alternatively, the application may maintain TxnRef as a counter that is incremented after each doTxnTransaction response.

TxnType (input/output) Data type: string Max 16 characters

Class of transaction.

Value Meaning
Purchase Purchase - Funds are transferred immediately.
Refund Refund - Funds transferred immediately. Must be enabled as a special option.
Auth Authorize - amount is authorized no funds transferred. Followed by a completion transaction within 7 days.
Complete Completes a previous authorisation - funds are transferred.

Response Codes

The client application should not interpret the ResponseCode property contents - it is provided as informational only. The Authorized property determines if the the transaction was successful or not and the Retry property determines ifdoTxnStatus error recovery is needed.

Payment Express Server Originated Responses

The following responses are generated by the Payment Express Client or Payment Express Server and indicate a server error condition or a problem with the transaction that caused it to be locally declined. This list is not exhaustive. Applications should not use these response codes or make decisions based upon the contents of ReCo, ResponseText.

Class of transaction.

Code Text Meaning
A8 INVALID AMOUNT Amount value is not of the form d.cc where d is dollars and cc is cents value.
A9 INVALID CARD NUMBER Card number not a valid credit card number.
SA INVALID ACCOUNT An incorrect account was selected.
AB INVALID EXPIRY Expiry not in MMYY format or Month not between "01" and "12".
AC CARD EXPIRED Local expiry check failed. Card is expired or local computer time is incorrect.
AD ACCOUNT ERROR An incorrect account was selected.
AE TIMEOUT Timeout awaiting bank response - transaction is declined.
AF TRANSMISSION ERROR Only possible for a DoStatus call. Indicates Payment Express Server has no record of the transaction and it can be treated as "failed" or may be safely retried.
B1 IVL REQ TYPE Invalid Transaction Type. See TxnType for legal values.
R0 INVALID CLIENT TYPE TxnClass not one of list described in TxnClass property.
X1 TIMEOUT Communications error

Acquirer Response Codes And Text

The response codes and text values vary from acquirer to acquirer.

Use of response codes for Web Sites

It is recommended that developers utilise the following approach to display of transaction results to the web browser:

Accepted Transaction

An accepted transaction is indicated by the Authorized Element being set to 1. In this case, display "Transaction Approved" for the card holder.

Declined or Rejected transaction Scenario #1

This result is conveniently indicated by the Authorized element being set to false and the StatusRequired element being set to false. It is essential that the web application checks both properties. In this case the web application should display the contents of CardHolderResponseText. Additional information should ideally be displayed from CardHolderResponseDescription

Declined or Rejected transaction Scenario #2

(StatusRequired isTrue) This scenario is covered in the section of this document entitled "Exception Handling". It occurs when the result of the transaction (accepted or otherwise) is not known for sure.

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 authorized 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

Send a "Auth" Transaction for the amount to be authorized. The Auth response contains an AuthCode of up to 64 alphanumeric characters. The funds are not transferred from the cardholder account. At a later time, but within 7 days maximum, a "completion" ("8") transaction must be sent containing the authorisation code returned by the "auth" transaction response. in the AuthCode element in order to transfer (settle) funds..