Menu

Quick start (Direct)

Prerequisite: You need a test account before you can start.Contact usand we'll set you up with one.

Once you have a test account, follow these steps to make your first basic test payments:

Setup

Your Implementation Manager (or support contact) should have given you:

  • A Merchant Code (or codes)
  • A Merchant Administration Interface Username and Password

Get your credentials

  1. Log in to the test Merchant Administration Interface (MAI): https://secure-test.worldpay.com/sso/public/auth/login.html?serviceIdentifier=merchantadmin

  2. Click ACCOUNT, then select Profile from the top menu.

  3. Note your New Username for the connection.
  4. Click the pencil icon (Pencil icon) next to XML Password.
  5. Enter your new password and click Save XML Password.

Restrict IP addresses

You can restrict connections to your test account by specifying a number of IP addresses or ranges that your account can be accessed from. To do this:

  1. Click Integration.
  2. Go to the Merchant Environment tab, and click New Test IP to add a new IP address (or range).

Best practice: Send messages to fully qualified domains
Don’t send messages to specific IP addresses, as these can change, leading to a break in communications – sometimes we need to move to different IP addresses in our range to communicate with you.

Integrate

Connect to Worldpay

To process payments through Worldpay you must:

  • Use a secure connection. We recommend that you use Transport Layer Security v1.2 (TLS v1.2), however as a minimum you should use TLS v1.1
  • Use basic authentication (the New Username and XML Password as created above)
  • Use content type "text/xml"

Create payment request

You interact with Worldpay using XML messages. All messages should conform to the WorldpayDocument Type Definition(DTD) and must be less than 4KB. To avoid issues always use industry-standard tools to validate and parse XML.

Set up your platform

Set up your platform for submitting XML messages to Worldpay’s payment service.

Note: The Worldpay payment service only accepts incoming XML messages if the originating IP address is registered for the merchant code in the message. For more information about registering and managing multiple IP address ranges, see theMerchant Environmentsection of theMerchant Admin Interface Guide.

Payment

The test URL to send XML messages to is: https://secure-test.worldpay.com/jsp/merchant/xml/paymentService.jsp

Example XML order

Here's a basic example of the data submitted for a card test payment. Before you send it you need to change the merchantCode to your own, and be aware that each payment requires a unique orderCode:

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//Worldpay//DTD Worldpay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE"> <!--Enter your own merchant code-->
   <submit>
      <order orderCode="YOUR_ORDER_CODE"> <!--Enter a unique order code each time-->
         <description>YOURDESCRIPTION</description> <!--Enter a description useful to you-->
         <amount currencyCode="GBP" exponent="2" value="5000" />
         <paymentDetails>
            <CARD-SSL>
               <cardNumber>4444333322221111</cardNumber>
               <expiryDate>
                  <date month="01" year="2020" />
               </expiryDate>
               <cardHolderName>A Shopper</cardHolderName>
               <cardAddress>
                  <address>
                     <address1>47A</address1>
                     <address2>Queensbridge Road</address2>
                     <address3>Suburbia</address3>
                     <postalCode>CB94BQ</postalCode>
                     <city>Cambridge</city>
                     <state>Cambridgeshire</state>
                     <countryCode>GB</countryCode>
                  </address>
               </cardAddress>
            </CARD-SSL>
            <session shopperIPAddress="123.123.123.123" id="0215ui8ib1" />
         </paymentDetails>
         <shopper>
            <shopperEmailAddress>ashopper@myprovider.com</shopperEmailAddress>
            <browser>
               <acceptHeader>text/html</acceptHeader>
               <userAgentHeader>Mozilla/5.0 ...</userAgentHeader>
            </browser>
         </shopper>
         <dynamicMCC>5045</dynamicMCC> <!--The merchant category code that applies to this transaction-->
         <dynamicInteractionType type="ECOMMERCE" /> <!--The type of shopper interaction for this transaction-->
         <dynamic3DS overrideAdvice="do3DS" /> <!--Optional override element to ignore preset dynamic 3DSrules-->
      </order>
   </submit>
</paymentService>

The AUTHORISED response to this order

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="ExampleCode1"> <!--The merchantCode you supplied in the order-->
   <reply>
      <orderStatus orderCode="ExampleOrder1"> <!--The orderCode you supplied in the order-->
         <payment>
            <paymentMethod>VISA_CREDIT-SSL</paymentMethod>
            <amount value="5000" currencyCode="GBP" exponent="2" debitCreditIndicator="credit" />
            <lastEvent>AUTHORISED</lastEvent>
            <CVCResultCode description="APPROVED" />
            <balance accountType="IN_PROCESS_AUTHORISED">
               <amount value="5000" currencyCode="GBP" exponent="2" debitCreditIndicator="credit" />
            </balance>
            <cardNumber>4444********1111</cardNumber>
            <riskScore value="0" />
         </payment>
      </orderStatus>
   </reply>
</paymentService>

Note: You may not get this exact response, depending on the configuration of your account and the test card number used.

The AUTHORISED response to this order with <cardBin> details

With the introduction of eight digit BINs, we've made more card data available to you so that you can identify card attributes that were not previously available through the card BIN lookup. This optional data specifies:

  • The type of card used
  • The card account type - consumer, commercial or both
  • The card issuer country code (ISO3166)
  • The name of the card issuer

Talk to your Worldpay Relationship Manager or support representative about enabling this optional data.

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="ExampleCode1"> <!--The merchantCode you supplied in the order-->
   <reply>
      <orderStatus orderCode="ExampleOrder1"> <!--The orderCode you supplied in the order-->
         <payment>
            <paymentMethod>VISA_CREDIT-SSL</paymentMethod>
            <amount value="5000" currencyCode="GBP" exponent="2" debitCreditIndicator="credit" />
            <lastEvent>AUTHORISED</lastEvent>
            <CVCResultCode description="APPROVED" />
            <balance accountType="IN_PROCESS_AUTHORISED">
               <amount value="5000" currencyCode="GBP" exponent="2" debitCreditIndicator="credit" />
            </balance>
            <cardNumber>4444********1111</cardNumber>
            <cardBin cardClass="D" productType="CN" issuerCountryCode="-1" issuerName="CARD_ISSUER_NAME">
            <riskScore value="0" />
         </payment>
      </orderStatus>
   </reply>
</paymentService>

<cardBin> reference table

NameMaximum LengthFormatDescription
cardClass1CHARClass of card which was used - credit, debit or prepaid
productType2CHARType of card the account range represents - consumer, commercial or both
issuerCountryCode5CHARCountry in which the card was issued - ISO 3166 country code (Numeric)
issuerName100CHARName of issuer

Card Class <cardClass>

CodeDescription
CCredit
DDebit
HChange Card
PPrepaid
RDeferred Debit

Product type <productType>

CodeDescription
CPCommercial Corporate Card
CNConsumer Card

LatAm (Latin America) payments and <cardBin>

For payments in the LatAm region, please be aware of the following:

  • In Argentina, for Visa transactions, the issuer name can display as 'Prisma' instead of the issuing bank. Prisma is a license holder in Argentina used by issuing banks to connect to Visa
  • In Brazil, some cards are issued as combo cards, offering both debit and credit to consumers. These will always display as credit payments even when processed as debit
  • Pure debit (non combo card) Brazilian Maestro cards use a legacy, single message platform. As a result, the card lookup will return Country = US and Issuer = MASTERCARD - MDS FOR EUROPE DEBIT ACQUIRER & NON EUROPEAN DEBIT ISSUER