WSDL

A web services descriptor language (WSDL) file is an XML document that describes the arguments accepted by a specific web service as well as the methods and properties supported by that service. The WSDL specification provides the grammar and syntax rules for WSDL files. For the WSDL schema please see https://www.paymentexpress.com/WS/PXWS.asmx?WSDL.

SOAP Operations

The WS control offers a number of methods to initiate transactions, connect to the Payment Express Server and alter settings and retrieve information. This section details the available SOAP operations and their uses.

• SubmitTransaction
• SubmitTransaction2
• GetStatus
• GetStatus2
• UpdateCard

SubmitTransaction

Add the appropriate inputs (Amount, TxnType etc) with the SubmitTransaction SOAP operation to perform a purchase, refund, authorisation or completion transaction.

Input Elements

Note1: dpsTxnRef is required for a Refund transaction or Complete transaction only. Must contain the DpsTxnRef returned by the original Purchase or Auth transaction to be refunded or completed.

Output Elements

These Elements are given when the SubmitTransaction method returns results.

SubmitTransaction2

This is used in the same way as SubmitTransaction call, however it also includes the Acquirer response in the result.

Additional Output Elements

GetStatus

GetStatus is used when the SubmitTransaction operation fails and the response was not received within a timeout period or the link to Payment Express Server or beyond failed while awaiting a response. In this circumstance, the result of the transaction is indeterminate. The GetStatus operation should be used to retrieve the actual result. GetStatus uses the original TxnRef values which uniquely identify the transaction to lookup the transaction at the Payment Express Host and return the results.

Input Elements

Output Elements

Example:

1. Client Application loads the Web Service Input Elements
2. Client Application uses the SubmitTransaction operation call and connects to the Web Service
3. Web Service sends transaction
4. Link between Web Service client application is interrupted
5. Client application returns indeterminate result after timeout period
6. Client Application calls the GetStatus operation
7. Client Application receives the result of the transaction

Once the client application has confirmed the result of the transaction with the Payment Express Server with the GetStatus call, normal processing of subsequent transactions using SubmitTransaction method can resume.

Ensure that this txnRef value is loaded in txnRef property before calling GetStatus. Payment Express Host maintains transaction results for at least 48 hours therefore calls to GetStatus can rely on results being available for at least this period following transmission of the original transaction.

If a GetStatus method is made for a transaction that was successfully processed by Payment Express Host and was accepted by the bank, then the GetStatus method will result in the Web Service properties being set exactly as they would have been for the original transaction result, regardless of whether the original transaction result was actually received by the client application.

Exception Handling

Refer to the GetStatus operation. The Payment Express architecture does not provide for customer applications to "reverse" or "back out" transactions once started. Exception conditions arise when the link between the customer application and the Payment Express Host is interrupted. A response to a transaction request is not received or the StatusRequired parameter in the response is true. In this circumstance, the result of the transaction is unknown.

The transaction must not be assumed to have failed. In this case, the application must enter a "recovery" mode until the result of the transaction can be ascertained. The mechanism to perform this error recovery is easily accomplished using the procedure outlined in the GetStatus method documentation.

GetStatus2

This is used in the same way as GetStatus call, however it also includes the Acquirer response in the result.

Additional Output Elements

UpdateCard

UpdateCard call is used to update the expiry date of a BillingId or DpsBillingId associated with a credit card. This is useful when a customers credit card has expired and they receive a new one from their bank with the same credit card number.

Input Elements

Output Elements

Request example:

<cardDetails>
<billingId>xxxxxxx</billingId>
<dpsBillingId>xxxxx</dpsBillingId>
<dateExpiry>0108</dateExpiry>
</cardDetails>

Output example:

<updateCardResult>
<updateSucceeded>1</updateSucceeded>
<reco>00</reco>
<responseText></responseText>
</updateCardResult>

Auth-Complete

Overview

Payment Express supports Authorisation and Complete transaction types. An Auth transaction verifies that funds are available for the requested card and amount, and reserves the specified amount. A Complete 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.

Operation

1) Authorization 

Use the SubmitTransaction operation with TxnType set to "Auth" for for the amount to be authorised. The Auth response contains a DpsTxnRef. The funds are not transferred from the cardholder account. 

2) Complete

After a successful Auth transaction, but within 7 days maximum, a Complete transaction must be sent containing the DpsTxnRef returned by the Auth transaction.

Token Billing

Overview

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

1) 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, call the SubmitTransaction web service method/operation with the following properties -

TxnType property set to "Purchase" or "Auth"
EnableAddBillCard property set to "1" (true)
CardHolderName (optional, strongly recommended)
MerchantReference
CardNumber
DateExpiry
BillingId (Optional. If none is supplied then a DpsBillingId determined by Payment Express will be returned for use)

2) Rebill Phase

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. EnableAddBillCard value will be set to 0 (False) 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.

Refunds

The Web Service 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 (Optional)
Amount

Extended Airline Booking Data

The Web Service is capable of taking extended booking information, which is used to display on cardholders statements.

If you would like to add booking information to your transaction details you will need to set the EnablePaxInfo input property to true (1) and you will be able to use the following properties -
PaxDateDepart, PaxName, PaxLeg1, PaxLeg2, PaxLeg3, PaxLeg4, PaxOrigin, PaxTicketNumber, PaxCarrier and PaxTravelAgentInfo.

Sample data:

PaxDateDepart = "14122008"
PaxName = "Brian Smith"
PaxOrigin = "AKL"
PaxLeg1 = "SYD"
PaxLeg2 = "LAX"
PaxLeg3 = "LHR"
PaxLeg4 = "AKL"
PaxTicketNumber = "0030458343"
PaxCarrier = "QB"
PaxTravelAgentInfo = "BA1234567890"

Properties Description

The following section provides a detailed description of each Web Service element and indicates if it used as an input or output. If a property is marked as input, it is not updated or output when a call to SubmitTransaction or GetStatus returns. This is important when a call is made to GetStatus for example, the original contents of Amount as input to the SubmitTransaction call are not output by GetStatus.

Authorized (output) Datatype: String Max 1 characters
Indicates if the transaction was authorized or not. Either False (0) or True (1)

Amount (input) Datatype: String Max 12 characters
Total Purchase, Refund, Auth or Complete 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. Note that the original  value used as input to  SubmitTransaction  is not returned by any subsequent DoGetStatus and must be stored by the application if required. Maximum value allowable is $99,999.99. Note that acquirer or card limits may be lower than this amount.

AuthCode (output) Datatype: String Max 22 characters
Authorization code returned for approved transactions.

BillingId (input/output) Datatype: String Max 32 characters
BillingId generated by the customer system. This could be a customer number and is used as input to SubmitTransaction to rebill an existing customer. If EnableAddBillCard

CardHolderResponseDescription (output) Data type: String Max 32 characters
More detailed explanation of result. Intended for card holder.

CardHolderHelpText (output) Data type: String Max 32 characters
More detailed explanation of result. Intended for card holder.

CardHolderName (input) Datatype: String Max 64 characters
The cardholder name as it appears on customer card. Optional and may be left blank.

CardHolderResponseText (output) Data type: String Max 32 characters
Brief (Max 32 character) response text intended for card holder.

CardNumber (input) Datatype: String Max 19 characters
The card number. No leading or embedded blanks are permitted. Must contain a numeric value. Not required for Complete or Refund TxnType.

CardName (output) Datatype: 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. The CardName format is to capitalize the first letter with remaining letters in lowercase. 

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. This is not currently implemented by all acquirer and may not necessarily be checked

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. Not required for Complete or Refund transactions.

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.

DateStart (input) Datatype: String Max 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): 1 digit
Address Verification System property. Valid values are 0, 1, 2 & 3.

0 - do not 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 AVS is unavailable, then the transaction will proceed as normal. If AVS is supported and the AVS check fails, then the transaction will be declined.
2 - The same as 1 except the transaction must be checked by AVS. If AVS isn't available, the transaction will be declined.
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.

DpsBillingId (input/output) Datatype: String Max 16 characters
Returned for a successful billing transaction if EnableAddBillCard is set. Supplied as input to rebill a transaction if BillingId is not used. It is not allowed to specify both a BillingId and a DpsBillingId when rebilling a transaction.

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.

EnableAddBillCard (input/output) Datatype: BOOL
If set to true on input to SubmitTransaction, the details necessary to charge the same customer in the future are securely stored. A BillingId may optionally be attached on input. DpsBillingId is returned. See Token Billing section for details on using this feature. 

MerchantReference (input) Datatype: String Max 64 characters
Free Text Field for use by merchant (could be order number, customer number etc.).

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. Valid valus for Currency are:

EnablePaxInfo (input) Data type: Boolean True/False
Used for Airline Reservation Systems. Enable collection of extended booking data to go through to the acquirer. Value will need to be true (1) if ticket information is included with the transaction.

PaxDateDepart (input) Data type: String Max 8 characters
Used for Airline Reservation Systems. Date departing in YYYYMMDD format. Numeric.

PaxName (input) Data type: String Max 20 characters
Used for Airline Reservation Systems. Passenger Name. Alphanumeric.

PaxLeg1 (input) Data type: String Max 3 characters
Used for Airline Reservation Systems. Leg 1 flight information. Alphanumeric.

PaxLeg2 (input) Data type: String Max 3 characters
Used for Airline Reservation Systems. Leg 2 flight information. Alphanumeric.

PaxLeg3 (input) Data type: String Max 3 characters
Used for Airline Reservation Systems. Leg 3 flight information. Alphanumeric.

PaxLeg4 (input) Data type: String Max 3 characters
Used for Airline Reservation Systems. Leg 4 flight information. Alphanumeric.

PaxOrigin (input) Data type: String Max 3 characters
Used for Airline Reservation Systems. Passenger Origin of departure. Alphanumeric.

PaxTicketNumber (input) Data type: String Max 10 characters
Used for Airline Reservation Systems. Passenger Ticket Number. Format: AAATTTTTTTTTTC. AAA is airline code, TTTTTTTTTT (10 chars) is actual ticket number and C is check digit. Numeric.

PaxCarrier (input) Data type: String Max 2 characters
Used for Airline Reservation Systems. 2 character airline identifier. Alphanumeric.

PaxTravelAgentInfo (input) Data type: String Max 25 characters
Used for Airline Reservation Systems. Travel Agent description field. Also known as the Booking Reference on some of DPS screens. Alphanumeric free text field.

PostPassword (input) Data type: 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 (output) Datatype: String Max 2 characters
Response Code generated by DPS Server (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 according to acquirer. Use the Success property to check for successful finishing of a transaction. Refer to the Response Codes section for a list of valid response code errors generated by Payment Express.

ResponseText (output) Datatype: String Max 32 characters
Response Text associated with the response code of the transaction

Retry (output) Datatype: Boolean True/False
If true, then the transaction should be sent again - the transaction was declined due to a temporary error. If false, then the transaction should not be sent again, regardless of whether it was accepted or declined.

StatusRequired (output): 1 (true) or 0 (false)
If true then the status of the transaction could not be determined, either because the server could not be reached, because of an error, or because the transaction is still in progress. Your application should call GetStatus until StatusRequired is false (0).

TxnData1, TxnData2, TxnData3 (input): String Max 255 characters
Optional free text fields. Usually assigned at origin website.

TxnRef (input / output) Datatype: String Max 16 characters
An identifier provided by your application to uniquely identify the transaction. This is the TxnRef supplied by the client to initiate the transaction, or, if not supplied, a TxnRef value internally generated by DPS on return. This is required as an input for GetStatus operations.

TxnType  (input) Datatype: String Max 8 character