PX XML InterfacePayment 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 FormatCommands 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 transactionNot 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 FormatResponses are received by the client application nt Express Server on TCP port 3004.
Sample XML ResponseSee 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 CommandPurposeChecks 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 FormatThe 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 CommandPurposeInitiates a request to perform a financial transaction to the Payment Express Server. doTxnTransaction Command Format
doTxnTransaction Response Format
Data ElementsThis 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
Note 1 - Either GroupAccount OR a Username/Password combination is required. See documentation for these elements for further information. Output ElementsRequested 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
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 Response Format
Data ElementsNote. Optional Indicates that the element need not be supplied. AcquirerId (output) Data type: number
ID of Acquirer that processed the transaction.
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.
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.
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) 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 Host or 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 a doTxnTransaction,
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.
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 calling
doTxnTransaction 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
Username (input) Data type: string Max
32 characters
Used with Password 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.
VersionMajor (output) Data type:
string Max 16 bytes
Payment Express Server Software Major version number. Returned by doLinkConnect.
VersionMinor (output) Data type:
string Max 16 bytes
Payment Express Server Software Minor version number. Returned by doLinkConnect
VersionRevision (output) Datatype:
string Max 16 bytes
Payment express Server Software Revision number. Returned by doLinkConnect.
Response CodesThe 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 if doTxnStatus error recovery is needed. Payment Express Server Originated ResponsesThe 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.
Acquirer Response Codes And TextThe response codes and text values vary from acquirer to acquirer. Use of response codes for Web SitesIt is recommended that developers utilise the following approach to display of transaction results to the web browser: Accepted TransactionAn 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 #1This 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/ CompletionOverviewPayment 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. OperationSend 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..
|