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.
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
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.
Responses are received by the client application nt Express Server on TCP port 3004.
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.
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).
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.
Purpose
Initiates a request to perform a financial transaction to the Payment Express Server.
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.
| 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.
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 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
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
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:
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
| 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
| 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. |
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.
| 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 |
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.
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.
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..
