World Pay (XML Direct) Payment Integration
About World Pay:
Our story started in 1989 with the launch of Streamline. The business at this point was a simple UK-based electronic payment provider that focused on point of sale transactions.
Worldpay emerged later as one of the first online payment companies in the UK. And in 2002, RBS brought them together – though they continued to operate as separate brands.
Over the next eight years, the business continued to grow organically with the acquisition of Lynk, TrustMarque International, Bibit, and Cardsave.
By 2010, Worldpay had become the largest merchant acquirer in Europe – and one of the largest globally.
Merchants who collect and store their shoppers’ payment details on their own platform can use the XML Direct model as an effective payment-processing gateway. With this model, the
The merchant collects both order and payment details and then communicates the relevant payment details on a per order basis with WorldPay, for processing.
The benefits of using the Direct Method for the merchant include being able to retain full control over the payment process and also the payment pages displayed to shoppers.
However, for this method to work successfully, it is important that the merchant ensures their own system operates within a secure environment so that payment details, which they collect and store, are protected. In view of the cost involved in establishing appropriate security
measures, this model only applies to merchants with established high transaction volumes.
Implemented Features:
| Feature | Level of Support |
|---|
| Auth | Implemented |
| Sale (Auth+Capture) | Implemented |
| Capture | Implemented |
| Void | Implemented |
| Credit | Implemented |
| Send XML | Implemented |
| 3DS 2 Full Integration | Implemented |
| Credentials on File | Implemented |
Authentication and Security Credentials:
Supported Parameters:
| Key Name | Format | Mandatory | Descriptions |
|---|
| apiVersion | Numerical | Required | “1.0.1” |
| apiType | Alphabetical | Required | “pxyhpci” |
| userName | Alphanumeric | Required | API Username |
| userPassKey | Alphanumeric | Required | API PassKey |
| pxyCreditCard.creditCardNumber | Numerical | Required | HostedPCI Token Representing Credit Card |
| pxy.CreditCard.cardCodeVerification | Numerical | Optional | HostedPCI Token Representing CVV Code |
| pxyCreditCard.expirationMonth | Numerical | Required | Expiration month with 2 digits for example, for December use “12” |
| pxyCreditCard.expirationYear | Numerical | Required | Expiration year with 4 digits for example, for 2025, use “2025” |
| pxyTransaction.txnCurISO | Alphabetical | Required | 3 letter ISO Currency Code for example, “USD” or “CAD” |
| pxyTransaction.txnAmount | Numerical | Required | Amount to Authorize, for example for $10.50 use 10.50 |
| pxyTransaction.merchantRefId | Numerical | Required | Merchant reference number can be order id or invoice id |
| pxyTransaction.txnPayName | Alphanumeric | Required | HostedPCI payment profile name, for example “DEF” |
| pxyTransaction.txnComment | Alphabetical | Optional | Short comment |
| pxyCustomerInfo.email | Alphanumeric | Optional | Customer’s Email Address |
| pxyCustomerInfo.customerIP | Numerical | Optional | Customer’s IP Address |
| pxyCustomerInfo.sessionId | Numerical | Optional | World Pay Session ID |
| pxyCustomerInfo.billingLocation.firstName | Alphabetical | Optional | Customer’s First Name |
| pxyCustomerInfo.billingLocation.lastName | Alphabetical | Optional | Customer’s Last Name |
| pxyCustomerInfo.billingLocation.address | Alphanumeric | Required | Customer’s Billing Address |
| pxyCustomerInfo.billingLocation.city | Alphabetical | Required | Customer’s Billing City |
| pxyCustomerInfo.billingLocation.zipCode | Numerical | Required | Customer’s Billing Zip Code or Postal Code |
| pxyCustomerInfo.billingLocation.country | Alphabetical | Required | Customer’s Billing Country |
API Endpoint URL:
https://[HPCI_API_HOSTENAME]/iSynSApp/paymentAuth.action
API Request Body:
apiVersion=1.0.1&apiType=pxyhpci&userName=[APIuserName]&userPassKey=[APIPassKey]&pxyCreditCard.creditCardNumber=[CreditCardToken]&pxyCreditCard.cardCodeVerification=[CVVToken]&pxyCreditCard.expirationMonth=[ExpiryMonth]&pxyCreditCard.expirationYear=[ExpiryYear]&pxyTransaction.txnCurISO=[Currency]&pxyTransaction.txnAmount=[Amount]&pxyTransaction.merchantRefId=[UniqueMerchantRefID]&pxyTransaction.txnPayName=[ProfileName]&pxyTransaction.txnComment=[ShortComment]&pxyCustomerInfo.billingLocation.firstName=[CustomerFirstName]&pxyCustomerInfo.billingLocation.lastName=[CustomerLastName]&pxyCustomerInfo.billingLocation.address=[BillingStreetAddress]&pxyCustomerInfo.billingLocation.city=[BillingCity]&pxyCustomerInfo.billingLocation.state=[State/Province]&pxyCustomerInfo.billingLocation.zipCode=[ZipCode/PostalCode]&pxyCustomerInfo.billingLocation.country=[Country]&pxyCustomerInfo.shippingLocation.firstName=[ShippingFirstName]&pxyCustomerInfo.shippingLocation.lastName=[ShippingLastName]&pxyCustomerInfo.shippingLocation.address=[ShippingStreetAddress]&pxyCustomerInfo.shippingLocation.city=[ShippingCity]&pxyCustomerInfo.shippingLocation.state=[ShippingState/Province]&pxyCustomerInfo.shippingLocation.zipCode=[ShippingZipCode/PostalCode]&pxyCustomerInfo.shippingLocation.country=[ShippingCountry]&pxyCustomerInfo.sessionId=[WorldpaySessionId]
World Pay (XML Direct) offers 3DS 1.0 and 3DS 2.0 authentication feature:
3d Secure 1.0 WorldPay Implementation
World Pay 1.0 “verifyenroll” API Call
- HostedPCI offers 3dSec 1.0 implementation with WorldPay.
- In Order to make a successful verifyenroll call the following parameters are required.
| PARAMETER | VALUE |
|---|
| pxyTransaction.txnPayName | [3dsPayProfile] – Name of the 3d secure payment profile. |
| pxyThreeDSecAuth.actionName | [verifyenroll] |
| pxyCustomerInfo.browserAcceptHeader | [browserAcceptHeader] |
| pxyCustomerInfo.browserUserAgentHeader | [browseruserAgentHeader] |
| pxyThreeDSecAuth.callMode | [reportall] – will return once 3d secure has been authenticated with credentials for second API call |
| pxyCustomerInfo.sessionId | [sessionID] – also needed in the verifyresp call |
| pxyCustomerInfo.billingLocation.firstName | [3D] – to initiate world pay 3DSec 1.0 |
World Pay 1.0 “verifyresp” API Call
- If verifyenroll call was successful it will return parameters required to make verifyresp call.
- The following parameters are required for PIN verification call.
| PARAMETER | VALUES |
|---|
| pxyTransaction.txnPayName | [3dPayProfileName] |
| pxyThreeDSecAuth.actionName | [verifyresp] |
| pxyThreeDSecAuth.authTxnId | [threeDSTransactionId] – returned from the ‘verifyenroll’ call. |
| pxyCustomerInfo.sessionId | [sessionID] – same as the verifyenroll call |
| pxyThreeDSecAuth.paReq | [pxyResponse.threeDSPARequest] – response from the verifyenroll call |
| pxyThreeDSecAuth.authAcsUrl | [pxyResponse.threeDSAcsUrl] – response from the verifyenroll call |
WorldPay 3D Secure 2 Implementation
In order to implement 3D Secure 2, the World Pay payment profile must include these three parameters during profile setup.
| Parameter Name | Required Value |
|---|
| 3DS Parameters (enable=Y;apiKey=XXX) | enable=Y;apiKey=ae9715ef-99d8-4467-a3bb-8c463c10edf0;apiIdentifier=5fda1ca955f105709e269351;orgUnitId=5fda1ca94e370853219266ee;ttlMillis=0 |
| 3DS Setup Init URL | https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect |
| 3DS Override PIN URL | https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp |
3D Secure 2.0 Implementation with World Pay – “verifyenroll” API call
- In Order to implement ThreeDSecure 2.0 with WorldPay the following parameters are required.
- The table below contains the parameter required for the verifyenroll call.
| PARAMETERS | VALUES |
|---|
| pxyThreeDSecAuth.authSessionId | [cruiseSessionId returned within threeDSValuesObj in hpciSiteSuccessHandlerV4 and later versions] |
| pxyThreeDSecAuth.authOrderId | [threeDSOrderId returned within threeDSValuesObj in hpciSiteSuccessHandlerV4 and later versions] |
| pxyCustomerInfo.billingLocation.firstName | [ AUTHORISED or REFUSED] – to initiate 3ds challange process |
| pxyCustomerInfo.browserAcceptHeader | [browserAcceptHeader] |
| pxyCustomerInfo.browserUserAgentHeader | [browserUserAgentHeader] |
| pxyThreeDSecAuth.callMode | [reportall] |
| pxyTransaction.txnPayName | [3dsecProfileName] |
| pxyThreeDSecAuth.actionName | [verifyenroll] |
3ds 2.0 World Pay “verifyresp” call
- If ‘verifyenroll’ was successful it will return parameters required for verification call.
- The table below contains parameters required to make the second auth call with worldpay 3ds 2.0.
| PARAMETERS | VALUES |
|---|
| pxyThreeDSecAuth.authTxnId | [pxyResponse.threeDSTransactionId] – returned from the ‘verifyenroll’ call] |
| pxyTransaction.txnPayName | [3dPayProfileName] |
| pxyThreeDSecAuth.actionName | [verifyresp] |
| pxyThreeDSecAuth.authSessionId | [same as the verifyenroll call] |
| pxyThreeDSecAuth.paReq | [pxyResponse.threeDSPARequest] – response from the verifyenroll call |
| pxyThreeDSecAuth.authAcsUrl | [pxyResponse.threeDSAcsUrl] – response from the verifyenroll call |
| pxyThreeDSecAuth.messageId | [pxyResponse.threeDSMessageId] – response from the verifyenroll call |
World Pay XML Direct Credentials on File:
Credentials on FIle with Bambora can be set up during the Bambora Payment profile setup. In Order to set up the Beanstream payment profile as Card on File the parameter Card On File defaults needs to be set up as enable=Y;merInitReason=R. The parameter enable=Y tells the system to income the Credentials on the FIle process. The parameter merInitReason=R will set cardOnFileTxnType to R (Recurring). It can be overridden with the parameter listed below. Otherwise, the Card on FIle process is initiated based on the availability of CVV.
World Pay XML Direct Override Parameters
| PARAMETERS | VALUES |
|---|
| pxyTransaction.cardOnFileTxnRef | [0 /1] – 1 for MIT transaction |
| pxyTransaction.cardOnFileTxnType | [C/R/U] – CIT or Reaccuring MIT or Unscheduled MIT |
| pxyTransaction.cardOnFileIssuerId | [cardOnFile Issuer ID] |