The Web Service (WS) Client Application (CA) connects directly to the Payment Express Host WS via HTTPS Posts. Client applications talk to the Web Service using SOAP (Simple Object Access Protocol). SOAP provides a way to communicate between applications running on different operating systems, with different technologies and programming languages.
When consuming the web service at the "sec" subdomain (https://sec.paymentexpress.com/WS/PXWS.asmx) please ensure that your web service stack supports lax versioning: that is, it does not throw exceptions for new unknown data members in received data.
If the merchant's checkout process requires 3D Secure (3DS) integrated in the merchant's web site or application, please go through the 3D Secure with Web Service section.
Implementing 3DS in the checkout process allows the liability for fraudulent chargebacks (stolen or counterfeit cards) to shift from the merchant to the card issuer.
There is no Web Service installation to do on the client side as this is held at the Payment Express Host.
The address to connect to the Web Service is at https://sec.paymentexpress.com/WS/PXWS.asmx for testing please use https://uat.paymentexpress.com/WS/PXWS.asmx. Each method call is self documented at this address by clicking on each method.
Figure 2 The Web Service and it's method calls
The Web Service (WSDL) Standard Schema can be found at https://sec.paymentexpress.com/WS/PXWS.asmx?WSDL for testing please use https://uat.paymentexpress.com/WS/PXWS.asmx?WSDL
The SubmitTransaction SOAP method calls/outputs can be found at https://sec.paymentexpress.com/WS/PXWS.asmx?op=SubmitTransaction for testing please use https://uat.paymentexpress.com/WS/PXWS.asmx?op=SubmitTransaction
The GetStatus SOAP method calls/outputs can be found at https://sec.paymentexpress.com/WS/PXWS.asmx?op=GetStatus for testing please use https://uat.paymentexpress.com/WS/PXWS.asmx?op=GetStatus
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://sec.paymentexpress.com/WS/PXWS.asmx?WSDL.
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.
Add the appropriate XML input fields (Amount, TxnType etc) with the SubmitTransaction SOAP operation to perform a Validate, Purchase, Refund, Auth (Authorisation) or Complete (Completion) transaction.
Please refer to the specifications for details: https://sec.paymentexpress.com/WS/PXWS.asmx?op=SubmitTransaction
| Element | Required | Description |
|---|---|---|
| amount | Yes | Amount of transaction in 1.23 format |
| billingId | No | Specified for token billing transactions |
| cardHolderName | No | Card Holder Name as on Card. |
| cardNumber | No | Credit Card Number. Left justified no embedded spaces or other delimiters. |
| clientType | No | Allows the Client type to be passed through at transaction time. |
| 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. |
| cvc2Presence | No | Indicates information regarding submission of cvc2 value. |
| dateExpiry | Yes | Expiry date of card in 4 digit MMYY format. Note: do not include "/" or other delimiters. |
| dpsBillingId | No | The Billing Id generated by Payment Express when adding a card for recurring billing. Needed for rebilling transactions when you do not use your own BillingId. |
| dpsTxnRef | Yes | Only required for refund or completion transactions. |
| enableAddBillCard | Optional | Needed for recurring billing transactions when adding a card to the Payment Express system. Set element to 1 for true and 0 for false |
| extendedData | Optional | SOAP XML element to add extended data for ArrayOfNameValueField - see SOAP WSDL for more information. |
| NameValueField | Optional | SOAP XML element to add in the extendedData element to specify the fieldName and fieldValue. |
| fieldName | Optional | SOAP XML element to add the fieldName in extendedData and NameValueField. String Options: RecurringMode - specifies the card storage reason on tokenisation (storing a card) and rebilling (rebilling card with a token) requests. Further details defined in the Token Billing section. |
| fieldValue | Optional | SOAP XML element to add the fieldValue for the fieldName in extendedData and NameValueField SOAP XML fields. |
| inputCurrency | No | Specify the currency here. |
| merchantReference | No | 64 character free text field |
| enablePaxInfo | No | Used for Airline Reservation Systems. Enable collection of extended booking data to go through to the acquirer if they support it. |
| paxDateDepart | No | Used for Airline Reservation Systems. Date departing in YYYYMMDD format. |
| PaxDate PaxDate2 PaxDate3 | No | Used for Airline Reservation Systems. Flight date information. |
| paxName | No | Used for Airline Reservation Systems. Passenger Name. |
| paxClass1 paxClass2 | ||
| paxClass3 paxClass4 | No | Used for Airline Reservation Systems. Class flight information. |
| paxFareBasis1 paxFareBasis2 | ||
| paxFareBasis3 paxFareBasis4 | No | Used for Airline Reservation Systems. Fare Basis flight information. |
| paxFlightNumber1 paxFlightNumber2 | ||
| paxFlightNumber3 paxFlightNumber4 | No | Used for Airline Reservation Systems. Flight number information. |
| paxLeg1 paxLeg2 paxLeg3 paxLeg4 | No | Used for Airline Reservation Systems. Leg 1 flight information. |
| paxStopOverCode1 paxStopOverCode3 | ||
| paxStopOverCode3 paxStopOverCode4 | No | Used for Airline Reservation Systems. Stop over code flight information. |
| paxTicketNumber | No | Used for Airline Reservation Systems. Passenger Ticket Number. Format: AAATTTTTTTTTTC |
| paxCarrier | No | Used for Airline Reservation Systems. 2 character airline identifier. |
| paxOrigin | No | Used for Airline Reservation Systems. Passenger Origin. |
| paxTravelAgentInfo | No | Used for Airline Reservation Systems. Travel Agent description field. |
| postPassword | Yes | Combined with Username selects Account |
| postUsername | Yes | Combined with Password selects Account |
| txnData1 | No | Optional Free Text |
| txnData2 | No | Optional Free Text |
| txnData3 | No | Optional Free Text |
| txnRef | Yes | Set by client to uniquely identify transaction. You will need to set this value if wanting to use GetStatus |
| txnType | Yes | Purchase / Refund / Auth Complete / Validate |
| enableAvsData | No2 | Address Verification System property. Values are 1 (Enable Verification) 0 (Disable Verification). |
| avsAction | No | Address Verification System property. Valid values are 0 1 2 & 3. |
| avsPostCode | No | Address Verification System property. Post Code that is listed on the customer's bank statement |
| avsStreetAddress | No | Address Verification System property. Address that is listed on the customer's bank statement. |
| dateStart | No3 | The Issue date of the customer's credit card if Issuer requires this field to be present. |
| issueNumber | No3 | The Issue Number of your credit card if Issuer requires this field to be present. |
1 - 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.
2 - Feature not supported by all acquirers.
3 - Not required unless card issuer requires it.
These Elements are given when the SubmitTransaction method returns results.
| Element | Description |
|---|---|
| authCode | Authorisation Code |
| authorized | Indicates if the transaction was authorized or not. Either False (0) or True (1) |
| billingId | Billing Id specified for a token billing transaction |
| cardHolderHelpText | Any tips or hints for the CardHolder. Usually just the Response Text associated with the ReCo |
| cardHolderName | Card Holder Name as on Card. |
| cardHolderResponseDescription | A description of the transaction error to help the CardHolder associated with the ReCo |
| cardHolderResponseText | Response Text of the transaction to help the CardHolder associated with the ReCo. |
| cardName | Card used (Visa / MasterCard / Bankcard etc) |
| cvc2ResultCode | Contains information regarding verification of cvc2. |
| dateSettlement | Date transaction will be settled to Bank Account in YYYYMMDD format. This is supported for most but not all banks and card acquirers. If the DateSettlement is not available from the banking network the DateSettlement will contain the current calendar date. |
| dpsBillingId | Contains the BillingId generated by Payment Express when adding a card for recurring billing. |
| dpsTxnRef | Unique transaction identifier returned for every transaction. Required input for Refund transactions or Complete transactions. |
| issuerCountryId | The ISO 3166-1 code for the country the credit card was issued in. -1 - Not checked 0 - Checked but country not recognized N - Where n is the ISO 3166-1 standard country code (e.g. NZ=554 AU=036) |
| reCo | 2 character response code. |
| responseText | Response Text associated with ReCo |
| retry | If true; retry transaction if false do not retry. |
| statusRequired | If true then the result of the transaction could not be determined and you will have to call GetStatus to get the result. |
| txnRef | Set by client to uniquely identify transaction. |
This is used in the same way as SubmitTransaction call, however it also includes the Acquirer response in the result.
| Element | Description |
|---|---|
| acquirerReco | 2 character response code from the Acquiring bank |
| acquirerResponseText | Response Text associated with ReCo from the Acquiring bank |
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.
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.
| Element | Required | Description |
|---|---|---|
| postPassword | Yes | Combined with Username selects Account |
| postUsername | Yes | Combined with Password selects Account |
| txnRef | Yes | Value assigned to the txnRef property of the transaction to look up. |
| Element | Description |
|---|---|
| authCode | Authorisation Code |
| authorized | 1 if transaction successful - 0 if declined or unsuccessful |
| billingId | Billing Id specified for a token billing transaction |
| cardHolderHelpText | Any tips or hints for the CardHolder. Usually just the Response Text associated with the ReCo |
| cardHolderName | Card Holder Name as on Card. |
| cardHolderResponseDescription | A description of the transaction error to help the CardHolder associated with the ReCo |
| cardHolderResponseText | Response Text of the transaction to help the CardHolder associated with the ReCo. |
| cardName | Card used (Visa / Master Card / Bankcard etc) |
| cvc2ResultCode | Contains information regarding verification of cvc2. |
| dateSettlement | Date transaction will be settled to Bank Account in YYYYMMDD format. This is supported for most but not all banks and card acquirers. If the DateSettlement is not available from the banking network the DateSettlement will contain the current calendar date. |
| dpsBillingId | Contains the BillingId generated by Payment Express when adding a card for recurring billing. |
| dpsTxnRef | Unique transaction identifier returned for every transaction. Required input for Refund transactions or Complete transactions. |
| reCo | 2 character response code. |
| responseText | Response Text associated with ReCo |
| retry | If true; retry transaction if false do not retry. |
| statusRequired | If true then the result of the transaction could not be determined and you will have to call GetStatus again. |
| txnRef | Set by client to uniquely identify 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.
This is used in the same way as GetStatus call, however it also includes the Acquirer response in the result.
| Element | Description |
|---|---|
| acquirerReco | 2 character response code from the Acquiring bank |
| acquirerResponseText | Response Text associated with ReCo from the Acquiring bank |
UpdateCard call is used to update the expiry date of a BillingId, DpsBillingId or CardNumber2 associated with a credit card. This is useful when a customer's credit card has expired and they receive a new one from their bank with the same credit card number.
| Element | Required | Description |
|---|---|---|
| postPassword | Yes | Indicates the Payment Express account under which the token is stored |
| postUsername | Yes | Authenticates the client application |
| cardDetails | Yes | An escaped XML document containing dateExpiry and BillingId DpsBillingId or CardNumber2. |
| Element | Description |
|---|---|
| UpdateCardResult | An escaped XML document indicating the outcome of the operation. |
The input SOAP message contains an element named cardDetails. The cardDetails string value should be an XML document which has be escaped before submission. dateExpiry and either billingId, dpsBillingId or cardNumber2 must be supplied.
The output SOAP message contains a single element named updateCardResult. The updateCardResult string value contains escaped XML which must be unescaped in order to parse the values. The updateSucceeded value indicates the success of the update and the reco and responseText values provide further details.
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.
1) Authorization
Use the SubmitTransaction operation with TxnType set to "Auth" 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 theDpsTxnRef 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 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 $0.00 Validate (only a validation of card transaction - no funds held) or $1.00 Authorisation (Auth) 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 -
In the RecurringMode request field, please set one of the card storage reason as the string listed below.
When tokenising the card, please set one of the following:
| RecurringMode | Usage explanation |
|---|---|
| credentialonfileinitial | Cardholder will save card and for future orders the cardholder selects to reuse the saved card for the one-off payment. |
| unscheduledcredentialonfileinitial | Cardholder will save their card and for future order based on an event (such as topup) the merchant will reuse the saved card on behalf of the cardholder for the one-off payment. |
| recurringinitial | Cardholder will save their card and merchant will reuse the saved card on behalf of cardholder for the subscribed recurring payments. |
| installmentinitial | Cardholder will save their card and merchant will reuse the saved card on behalf of cardholder for the installment payments. |
Please discuss with our Implementation and Sales team about your tokenisation use cases if you are unsure. The RecurringMode string value should be set based on the merchant’s business case for tokenising.
Sample Setup Tokenisation (using DpsBillingId or CardNumber2) SubmitTransaction Web Service request with RecurringMode in the extendedData field:
2) Rebill Phase
The merchant application or Batch processor requests a new transaction and supplies the appropriate DpsBillingId or CardNumber2 or BillingId, RecurringMode (mandatory), 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.
It is important to set the RecurringMode request field, please set one of the card storage reason as the string listed below.
When rebilling the card with token, please set one of the following:
| RecurringMode | Usage explanation |
|---|---|
| credentialonfile | Cardholder selects their saved card to make the one-off rebill payment. |
| unscheduledcredentialonfile | Merchant initiated and event driven one-off rebilling with stored card (e.g. auto topups). |
| installment | Merchant initiated rebilling payments in installments with a stored card token. |
| incremental | Merchant initiated incremented transaction amount to rebill e.g. hospitality or rentals etc. |
| recurring | Merchant initiated recurring transaction with a stored card token (e.g. subscriptions). |
| recurringnoexpiry | Merchant initiated recurring transaction with a stored card token where no card expiry check needs to occur (e.g. subscriptions). |
| resubmission | Merchant resubmits rebill with token where it requested an authorisation but may have received a decline due to insufficient funds and the order already delivered to the cardholder. Used with the token to get an outstanding payment from cardholder. |
| reauthorisation | Merchant initiated when the completion or conclusion of the original order or service extends beyond the authorisation validity. Common for retail (split or delayed shipments) and hospitality or rental services scenarios. |
| delayedcharges | Merchant initiated to process additional account rebill charge after original order and payment has been already processed and fulfilled. |
| noshow | Merchant initiated to charge the cardholder a penalty relevant to the merchant’s cancellation policy. Common for guaranteed reservations scenarios (e.g. Hospitality). |
Please discuss with our Implementation and Sales team about your rebilling use cases if you are unsure. The RecurringMode string value should be set based on the merchant’s business case for rebilling the card.
Sample Token Rebill (using DpsBillingId or CardNumber2) SubmitTransaction Web Service request with RecurringMode in the extendedData field:
Note: CardNumber2 functionality is only available via SOAP Requests made to the subdomain "sec".
CardNumber2 is a token generated by Payment Express and associated with the card details supplied. It has 16 numeric characters and conforms to a Luhn "mod 10" algorithm. This makes it ideal for storage within the database in place of a card number where the value is validated against checks which might normally be made against credit card numbers. A CardNumber2 value is always unique for a given card number and includes a card type indicator. Should a card number be presented for tokenization multiple times the same CardNumber2 value will be returned.
CardNumber2 tokens are generated for all transactions once enabled by Payment Express (please contact your Payment Express account manager to discuss).The token will be returned in the "cardNumber2" property of the transaction response "TransactionResult2".
Charging a CardNumber2 token involves a request from the merchant application or Batch processor including an appropriate cardNumber2, a TxnType (Purchase) and the amount to be charged (an optional MerchantReference can be added for reporting purposes). EnableAddBillCard value will need to be set to "False" (or 0) 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.
CardNumber2 transactions use the card expiry date stored with the token regardless of whether one is passed through in the transaction data. On a successful transaction with the real card number associated with a CardNumber2 token the expiry date stored with this token will be updated to that which was used to process the transaction. If your client application displays details of stored tokens to cardholders eg: masked number and expiry date, then it is advisable upon a successful transaction for the merchant application to update the expiry date that is stored with the generated token.
The Web Service is capable of handling Refund (credit) transactions. A Refund transaction will credit the transaction amount back to the cardholder’s account. It has to be supported by the merchant’s bank or acquirer.
To process a Refund transaction, please match the original Purchase or Complete transaction with a DpsTxnRef. The original transaction reference may have been processed by other Payment Express gateway interfaces. Hence please request the Web Service gateway account to be under the same Group as the other gateway accounts where the original transaction may be processed from.
Please send the DpsTxnRef value as a reference that was provided from the response of the original Purchase or Complete transaction.
Multiple refund transactions can be processed to the maximum amount of the original matched transaction.
The TxnType is set to Refund.
The Payment Manager (Payline, provided to all merchants by default) allows merchants to request Refund transactions manually via our portal.
However, if merchants wish to implement a Refund transaction request into their own interface via an API, then the following input properties need to be provided for a Refund transaction:
The Web Service is capable of handling Void (advice) transaction requests. A Void transaction will cancel or reverse the original transaction. It has to be supported by the merchant’s bank or acquirer.
To process a Void transaction, please match the original Purchase, Auth or Refund transaction with a DpsTxnRef. The original transaction reference may have been processed by other Payment Express gateway interfaces. Hence please request the Web Service gateway account to be under the same Group as the other gateway accounts where the original transaction may be processed from.
Please send the DpsTxnRef value as a reference provided from the response of the original Purchase, Auth or Refund transaction.
Normally a Void transaction can be useful to reverse an Auth transaction in order to release the funds held on the cardholder’s account (normally within 7 days maximum).
The TxnType is set to Void.
The Payment Manager (Payline, provided to all merchants by default) allows merchants to request Void transactions manually via our portal.
However, if merchants wish to implement a Void transaction request into their own interface via an API, then the following input properties need to be provided for a Void transaction:
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 -
PaxCarrier,PaxCarrier2,PaxCarrier3,PaxCarrier4,PaxDateDepart,
PaxDate,PaxDate3,PaxDate3,PaxDat4,paxTime1,paxTime2,paxTime3,paxTime4,
PaxLeg1, PaxLeg2, PaxLeg3, PaxLeg4, paxStopOverCode1, paxStopOverCode2,
paxStopOverCode3, paxStopOverCode4, paxClass1, paxClass2, paxClass3, paxClass4,
paxFareBasis1, paxFareBasis2,paxFareBasis3, paxFareBasis4,
paxFlightNumber1, paxFlightNumber2, paxFlightNumber3, paxFlightNumber4,
PaxOrigin,PaxName, PaxTicketNumber and PaxTravelAgentInfo.
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. When submitting transactions for currencies with no decimal division of units such as JPY the AmountInput must be in an appropriate format e.g. "10".
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.
CardNumber2 (input) Datatype: String Min/Max 16 characters
A Billing Token value formatted to resemble a card number and pass a Luhn check. To use CardNumber2 tokens your account must be configured to generate them. Please contact our support team if you intend to use this feature.
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.
| CardName Value | Description |
|---|---|
| Amex | American Express |
| Bankcard | Bank Card |
| Diners | Diners Card |
| Jcb | JCB |
| Mastercard | Mastercard |
| Visa | Visa |
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:
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
Cvc2Presence
Merchant to send Payment Express a presence indicator within "Cvc2Presence" field in the transaction request to one of the below:
Cvc2ResultCode
Depending on the response code, the merchant can make a more informed decision on the payment that has taken place. Please see below table for interpretation of response codes:
| RESPONSE CODE | DEFINITION | DEFINITION |
|---|---|---|
| M | CVC matched. | You will want to proceed with transactions for which you have received an authorisation approval. A CVC match indicates the values provided matches the Issuing Banks details |
| N | CVC did not match. | You may want to follow up with the cardholder to verify the CVC value before completing the transaction even if you have received an authorisation approval. The CVC details provided by the Cardholder do not match their Issuing Banks details |
| P | CVC request not processed. | Issuing Bank is unable to process CVC at this time |
| S | CVC should be on the card but merchant has sent code indicating there was no CVC. | You may want to follow up with the cardholder to verify that the customer checked the correct location for the CVC. If the transaction is Approved you may also wish to consider not fulfilling the transaction |
| U | Issuer does not support CVC. | The card Issuing bank does not support CVC process |
ClientType (input) Datatype: String
Allows the Client type to be passed through at transaction time. Allowed values:
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.
issuerCountryId (output) Datatype: INT
The Country code for the country the credit card used was issued in.
-1 - Not checked
0 - Checked but country not recognized possibly invalid bin range or invalid card
N - Where n is the ISO 3166-1 standard country code (e.g. NZ=554, AU=036)
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 - 4 as described below.
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 specify 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 values for Currency are:
| Currency | Country |
|---|---|
| CAD | Canadian Dollar |
| CHF | Swiss Franc |
| DKK | Danish Krone |
| EUR | Euro |
| FRF | French Franc |
| GBP | United Kingdom Pound |
| HKD | Hong Kong Dollar |
| JPY | Japanese Yen |
| NZD | New Zealand Dollar |
| SGD | Singapore Dollar |
| THB | Thai Baht |
| 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 |
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.
PaxCarrier (input) Data type: String Max 2 characters
Used for Airline Reservation Systems. Carrier flight information. Alphanumeric.
PaxCarrier2 - 4 (input) Data type: String Max 2 characters
Used for Airline Reservation Systems. Carrier flight information. Alphanumeric.
PaxdateDepart (input) Data type: String Max 20 characters
Used for Airline Reservation Systems. Carrier flight information. Alphanumeric.
PaxDate2 - 4 (input) Data type: String Max 20 characters
Used for Airline Reservation Systems. Leg depart date flight information. Alphanumeric.
PaxTime1 - 4 (input) Data type: String Max 4 characters
Used for Airline Reservation Systems. Leg depart time flight information. Alphanumeric.
PaxClass1 - 4 (input) Data type: String Max 1 characters
Used for Airline Reservation Systems. Class flight information. Alphanumeric.
PaxStopoverCode1 - 4 (input) Data type: String Max 1 characters
Used for Airline Reservation Systems. Stop over code flight information. Alphanumeric.
paxFareBasis1 - 4 (input) Data type: String Max 6 characters
Used for Airline Reservation Systems. Fare basis flight information. Alphanumeric.
paxFlightNumber1 - 4 (input) Data type: String Max 6 characters
Used for Airline Reservation Systems. Flight number information. Alphanumeric.
PaxLeg1 - 4 (input) Data type: String Max 3 characters
Used for Airline Reservation Systems. Flight number information. Alphanumeric.
PaxName (input) Data type: String Max 20 characters
Used for Airline Reservation Systems. Passenger Name. 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.
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 Payment Express 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 Payment Express 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 based on the acquirer. Use the Success property to determine the result 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. The transaction result returned was not directly influenced by the card details supplied or the standing of the cardholder's account with the card issuer. Rather, the transaction result can be attributed to a transient state. Payment Express recommend that, if possible, the merchant resubmit the transaction within reasonable frequencies given that the duration of the state affecting transactions is unknown. If transactions are being repeatedly rejected in excess of that expected to be handled by the application these should be raised for manual intervention and the Payment Express support team contacted by the merchant.
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 Payment Express on return. This is required as an input for GetStatus operations.
TxnType (input) Datatype: String Max 8 character
| Value | Meaning |
|---|---|
| Auth | Authorise - amount is authorised no funds transferred. |
| Complete | Complete a previous authorisation - funds are transferred. |
| Purchase | Purchase - Funds are transferred immediately. |
| Refund | Refund - Funds transferred immediately. Must be enabled as a special option. |
| Validate | Validation transaction. On the amount 0.00 or 1.00 validates card details including expiry date. Often utilised with the EnableAddBillCard property set to 1 to automatically generate a card's token for rebilling. Note that the Validate transaction type may not be enabled by default on live accounts. Please make a request to Payment Express Support if you would like to utilise this transaction type. |
The client application should not interpret the ReCo (Response Code) property contents - it is to be used for REFERENCE PURPOSES only. The Authorized property should be used to determine the outcome of a transaction.
| ReCo | Description |
|---|---|
| 00-99 | Numerical Response Codes are generally returned by the card issuing bank. These values and descriptions are confidential and usually vary from bank to bank. |
| U5 | Invalid User / Password |
| D2 | Invalid username |
| D3 | Invalid / missing Password |
| D4 | Maximum number of logon attempts exceeded |
| Q4 | Invalid Amount |
| Q8 | Invalid Currency |
| QG | Invalid TxnType |
| QI | Invalid Expiry Date (month not between 1-12) |
| QJ | Invalid Expiry Date (non numeric value submitted) |
| QK | Invalid Card Number Length |
| QL | Invalid Card Number |
| JC | Invalid BillingId |
| JD | Invalid DPSBillingId |
| JE | DPSBillingId not matched |
The 3D secure web service allows merchants to accept credit card details within their own interface whilst allowing them to authenticate the user via the 3D secure system. The merchant website utilises Payment Express merchant plug-in (MPI) through functionality exposed by way of a SOAP web service.
