Create merchant tokens

Warning: On 02 July 2019 we have made changes to test to support3DS Flex. The <derived> element includes an additional child element <bin>. We will update you once these changes are planned to go into live.

Integrate merchant tokens if you intend to share tokens between your eCommerce and your Point of Sale (POS) channels.

This is the first integration step, and there are several ways to do it:

Jump toreference table

Note: If you want to send us tokens from another provider, or if you want to create bulk tokens from a list of details, seeBulk Token Migrationand contact your relationship manager.

Create a merchant token with a payment request

Merchant tokens can be created by requesting them with an order, either with the Direct or Hosted integrations. If you use the Direct model and ourClient Side Encryptionservice, you can send the encrypted card data as part of the request.

Mandatory elements

<createToken> is the instruction to create a token for the card used. <createToken> must contain:

  • tokenScope="merchant" - an attribute of <createToken> which states that the token will be a merchant token.

Optional elements

<createToken> can optionally contain:

  • tokenOptIn - an attribute of <createToken> which is used for providing atokenisation promptwhen creating tokens through the Hosted integration. If tokenOptIn is not used, the default value is "silent", and the shopper is not prompted that a token is created.

  • <tokenEventReference> - a unique reference generated by you to track key token events (such as token creation). Maximum 64 characters, and can only contain alphanumeric characters and an underscore (_).

    Best practice: We recommend that you make the <tokenEventReference> unique for each order submission - this allows you to track the creation of tokens in your system

  • <tokenReason> - the reason the token was created. The maximum number of characters is 255 - if you supply more, we’ll only use the first 255. If you don't submit <tokenReason> we’ll create one with a default value that uses the order code.

  • <paymentTokenExpiry> - an override of the default token life. Within the <date> child element, specify the dayOfMonth and month, the year, and the hour, minute and second. The expiry date cannot be longer than four years. SeeExample Direct order with create token requestfor an example.

Direct create (merchant) token request

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="MYMERCHANT">
  <submit>
    <order orderCode="TS211010">
      <description>20 red roses from the MyMerchant store.</description>
      <amount value="5000" currencyCode="GBP" exponent="2"/>
      <paymentDetails>
        <VISA-SSL>
          <cardNumber>4444333322221111</cardNumber>
          <expiryDate>
            <date month="06" year="2019" />
          </expiryDate>
          <cardHolderName>J. Shopper</cardHolderName>
          <cvc>123</cvc>
        </VISA-SSL>
      </paymentDetails>
      <createToken tokenScope="merchant"> <!--mandatory for merchant tokens-->
        <tokenEventReference>TOK7854321</tokenEventReference>
        <tokenReason>ClothesDepartment</tokenReason>
      </createToken>
    </order>
  </submit>
</paymentService>
Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd"&gt;
<paymentService version="1.4" merchantCode="MYMERCHANT">
  <submit>
    <order orderCode="TS211010">
      <description>20 red roses from the MyMerchant store.</description>
      <amount value="5000" currencyCode="GBP" exponent="2"/>
      <paymentDetails>
        <CSE-DATA>
          <encryptedData>
            eyJhbGciOiJSU0EtT0FFUCIsImNvbS53b3JsZHBheS5hcGlWZXJzaW9uIjoiMS4wIiwiY29tLndvcmxk
            cGF5LmNoYW5uZWwiOiJjdXN0b20iLCJjb20ud29ybGRwYXkubGliVmVyc2lvbiI6IjEuMC4wIiwiZW5j
            IjoiQTI1NkNCQy1IUzUxMiIsImtpZCI6IjIifQ.WlLLbIdn-_5JXVBzz2tJOK1rofXz41MRAVBiIxwrj
            DBZfatQKLq8iYSFBO6lAuLP38vEtazPAO-Z8L7gUNO9KqDMHeUdDNJ7HxOzLYyQdnOzLMZKetfhlrKAT
            MMjQk4ZUq8HHdvhx_dWbxugcRfQbCDUPtxFMVuirMpGw6VYESu0ZTlFOKy8YPlf8spafVvgINXVUbPKm
            1fxQpSvwrBi_vaMpLbn0GjyDnpv2YkOZgq0Mcd5O1K2ZmEZdx8ZYTUOWnhN7SFzv9BduEndUNhHCoLkh
            JRtoVwqYYgrsEXL_j4PsvAZF0_PI_NIOviYRe9RSoYZDkRzKuCWFsxHtSStPQ.y-cOrxjqAJhsa1RYDG
            hpag.-PEsJ6a5VwAatWbk7saa8Rty6iGvPiBfP8V9r26eIksir8cb-JHdPjldBGqI6EdGSTNv9K5Pa73
            Jk9KRaWs3Co6sOvmSkqJqGOc3oIeaacvWp5m3SEJQZu2ZVx9bjTElG67cOLR5XTaP5AzOg13HptZ-T9J
            GT-pe2V-i_m-wJy4.pVKcqWbUQ0IwBo9HF3sXQoLlOauRg3_uGVEBs-cfB34
          </encryptedData>
        </CSE-DATA>
      </paymentDetails>
      <createToken tokenScope="merchant"> <!--mandatory for merchant tokens-->
        <tokenEventReference>TOK7854321</tokenEventReference>
        <tokenReason>ClothesDepartment</tokenReason>
      </createToken>
    </order>
  </submit>
</paymentService>

Response to a Direct create (merchant) token request

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="MYMERCHANT">
  <reply>
    <orderStatus orderCode="TS211010">
      <payment>
        <paymentMethod>VISA-SSL</paymentMethod>
        <amount value="5000" currencyCode="GBP" exponent="2" debitCreditIndicator="credit"/>
        <lastEvent>AUTHORISED</lastEvent>
        <CVCResultCode description="UNKNOWN"/>
        <AVSResultCode description="UNKNOWN"/>
        <balance accountType="IN_PROCESS_AUTHORISED">
          <amount value="5000" currencyCode="GBP" exponent="2" debitCreditIndicator="credit"/>
        </balance>
        <cardNumber>4444********1111</cardNumber>
        <riskScore value="4"/>
      </payment>
      <token>
        <tokenEventReference>TOK7854321</tokenEventReference> <!--The event reference from your current submission-->
        <tokenReason>ClothesDepartment</tokenReason>
        <tokenDetails tokenEvent="NEW">
          <paymentTokenID>9902019934757792074</paymentTokenID>
          <paymentTokenExpiry>
            <date dayOfMonth="3" month="03" year="2019"/>
          </paymentTokenExpiry>
          <tokenEventReference>TOK7854321</tokenEventReference> <!--The event reference from the initial token creation-->
          <tokenReason>ClothesDepartment</tokenReason>
        </tokenDetails>
      </token>
    </orderStatus>
  </reply>
</paymentService>

Hosted create (merchant) token request

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="MYMERCHANT">
  <submit>
    <order orderCode="TS211010">
      <description>20 red roses from the MyMerchant webshop</description>
      <amount value="5000" currencyCode="GBP" exponent="2"/>
      <orderContent>
        <![CDATA[    ]]>
      </orderContent>
      <paymentMethodMask>
        <include code="ALL"/>
      </paymentMethodMask>
      <shopper>
        <shopperEmailAddress>jshopper@myprovider.int</shopperEmailAddress>
      </shopper>
      <billingAddress>
        <address>
          <firstName>John</firstName>
          <lastName>Shopper</lastName>
          <address1>47A</address1>
          <address2>Queensbridge Road</address2>
          <address3>Suburbia</address3>
          <postalCode>CB94BQ</postalCode>
          <city>Cambridge</city>
          <state>Cambridgeshire</state>
          <countryCode>GB</countryCode>
        </address>
      </billingAddress>
      <createToken tokenScope="merchant"> <!--mandatory for merchant tokens-->
        <tokenEventReference>TOK7854321</tokenEventReference>
        <tokenReason>ClothesDepartment</tokenReason>
      </createToken>
    </order>
  </submit>
</paymentService>

Response to a Hosted create (merchant) token request

The response to a Hosted order with a create token request is exactly the same as a standard Hosted response, redirecting the shopper to our payment page. The shopper then selects a payment method, and if it is compatible with Tokenisation, a token is created for the payment method used.

To obtain the token details, however, you must use Order Notifications - seeRetrieve token details.

Note: For information about any error messages you may receive, seeTroubleshoot.

Tokenisation prompt (Hosted only)

On the Hosted Payment Pages, you can prompt your shopper to opt-in to tokenise their card details, or you can inform them that you will tokenise their card. This is done in three ways:

  • Silent - You tokenise the shopper's card details without an opt-in (good for if you already have their consent or if it's in your Terms and Conditions).
  • Notify - You inform the shopper that you're going to tokenise their card details without an opt-in (if you do notify, you still need to have obtained the shopper's consent).
  • Ask - You ask the shopper for their consent to tokenise their card details. This adds a Save payment details tickbox to the page, which they tick to opt-in, or ignore to opt-out.

    Note: If the shopper does tick Save payment details, a token is not created.

Add an attribute in your request to include this opt-in. This is included within the <createToken> element. If tokenOptIn is not used, the default value is "silent", and the shopper is not prompted that a token is created.

Copied!
<createToken tokenScope="shopper" tokenOptIn="silent|notify|ask">

The response is the same as a standard create token response.

Create a merchant token without a payment request

If your shopper adds a credit or debit card to their account, you can store the details as a token by creating a token without a payment request.

To do this, do not use the <order> element. Instead, instruct with <paymentTokenCreate> and use the child elements in the order shown below.

Once you've created a token which holds cardholder details, you use it in the same way youuse a tokenwhich was created alongside a payment.

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="MYMERCHANT">
  <submit>
    <paymentTokenCreate> <!--used instead of order element-->
      <createToken tokenScope="merchant">
        <tokenEventReference>TOK7854321</tokenEventReference>
        <tokenReason>ClothesDepartment</tokenReason>
      </createToken>
      <paymentInstrument>
        <cardDetails>
          <cardNumber>4444333322221111</cardNumber>
          <expiryDate>
            <date month="06" year="2019" />
          </expiryDate>
          <cardHolderName>J. 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>
        </cardDetails>
      </paymentInstrument>
    </paymentTokenCreate>
  </submit>
</paymentService>
Copied!
<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN"
 "http://dtd.worldpay.com/paymentService_v1.dtd"&gt;
<paymentService version="1.4" merchantCode="MYMERCHANT">
  <submit>
    <paymentTokenCreate>
      <createToken tokenScope="merchant">
        <tokenEventReference>TOK7854321</tokenEventReference>
        <tokenReason>ClothesDepartment</tokenReason>
      </createToken>
      <CSE-DATA>
        <encryptedData>
          eyJhbGciOiJSU0EtT0FFUCIsImNvbS53b3JsZHBheS5hcGlWZXJzaW9uIjoiMS4wIiwiY29tLndvcmxk
          cGF5LmNoYW5uZWwiOiJjdXN0b20iLCJjb20ud29ybGRwYXkubGliVmVyc2lvbiI6IjEuMC4wIiwiZW5j
          IjoiQTI1NkNCQy1IUzUxMiIsImtpZCI6IjIifQ.WlLLbIdn-_5JXVBzz2tJOK1rofXz41MRAVBiIxwrj
          DBZfatQKLq8iYSFBO6lAuLP38vEtazPAO-Z8L7gUNO9KqDMHeUdDNJ7HxOzLYyQdnOzLMZKetfhlrKAT
          MMjQk4ZUq8HHdvhx_dWbxugcRfQbCDUPtxFMVuirMpGw6VYESu0ZTlFOKy8YPlf8spafVvgINXVUbPKm
          1fxQpSvwrBi_vaMpLbn0GjyDnpv2YkOZgq0Mcd5O1K2ZmEZdx8ZYTUOWnhN7SFzv9BduEndUNhHCoLkh
          JRtoVwqYYgrsEXL_j4PsvAZF0_PI_NIOviYRe9RSoYZDkRzKuCWFsxHtSStPQ.y-cOrxjqAJhsa1RYDG
          hpag.-PEsJ6a5VwAatWbk7saa8Rty6iGvPiBfP8V9r26eIksir8cb-JHdPjldBGqI6EdGSTNv9K5Pa73
          Jk9KRaWs3Co6sOvmSkqJqGOc3oIeaacvWp5m3SEJQZu2ZVx9bjTElG67cOLR5XTaP5AzOg13HptZ-T9J
          GT-pe2V-i_m-wJy4.pVKcqWbUQ0IwBo9HF3sXQoLlOauRg3_uGVEBs-cfB34
        </encryptedData>
        <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>
      </CSE-DATA>
    </paymentTokenCreate>
  </submit>
</paymentService>

Response

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="MYMERCHANT">
  <reply>
    <token>
      <tokenEventReference>TOK7854321</tokenEventReference>
      <tokenReason>ClothesDepartment</tokenReason>
      <tokenDetails tokenEvent="NEW">
        <paymentTokenID>9969102663680209289</paymentTokenID>
        <paymentTokenExpiry>
          <date dayOfMonth="17" month="11" year="2015" hour="18" minute="57" second="45"/>
        </paymentTokenExpiry>
        <tokenEventReference>TOK7854321</tokenEventReference>
        <tokenReason>ClothesDepartment</tokenReason>
      </tokenDetails>
      <paymentInstrument>
        <cardDetails>
          <expiryDate>
            <date month="06" year="2019"/>
          </expiryDate>
          <cardHolderName>
            <![CDATA[J. 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>
          <derived>
            <cardBrand>VISA</cardBrand>
            <cardSubBrand>VISA_CREDIT</cardSubBrand>
            <issuerCountryCode>N/A</issuerCountryCode>
            <obfuscatedPAN>4444********1111</obfuscatedPAN>
            <bin>444433</bin>
          </derived>
        </cardDetails>
      </paymentInstrument>
    </token>
  </reply>
</paymentService>

Note: The response is the same whether it's from theClient Side Encryptionor unencrypted submission.

Short life tokens

You can create tokens that have a life from 1 to 120 minutes by including the <shortLifeMins> element in the XML. This only works for tokens created without a payment.

Copied!
<createToken tokenScope="merchant">
  <tokenEventReference>TOK7854321</tokenEventReference>
  <tokenReason>ClothesDepartment</tokenReason>
  <shortLifeMins>15</shortLifeMins> <!--This signifies that you want to create a token with a life of 15 minutes-->
</createToken>

Warning: You should not submit the <paymentTokenExpiry> element in your submission when you're creating a short life token, as this will resultin an error.

After the token is created, it will expire after the determined time. If you try and use the token after this time, you'll get theToken does not existerror. The <paymentTokenExpiry> within the response will reflect the short life token:

Copied!
<paymentTokenExpiry>
  <date dayOfMonth="31" month="05" year="2017" hour="10" minute="24">
</paymentTokenExpiry>

Create a merchant token in a Pay as Order request

You can migrate from Pay as Order by creating a token in a (subsequent) request. Add the same elements covered inCreate a merchant token with a payment requestabove.

Example Pay as Order payment with create token request

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="MYMERCHANT">
  <submit>
    <order orderCode="jsxml3589919975">
      <description>Monthly subscription to sweets magazine</description>
      <amount value="100" currencyCode="EUR" exponent="2"/>
      <orderContent>Provide your order content here</orderContent>
      <payAsOrder orderCode="1111" merchantCode="CGTOKM1">
        <amount value="100" currencyCode="EUR" exponent="2"/>
      </payAsOrder>
      <shopper>
        <shopperEmailAddress>shopper@worldpay.com</shopperEmailAddress>
      </shopper>
      <createToken tokenScope="merchant">
        <tokenEventReference>TOK7854321</tokenEventReference>
        <tokenReason>SweetsDepartment</tokenReason>
      </createToken>
    </order>
  </submit>
</paymentService>

Pay as Order response with create token information

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="MYMERCHANT">
  <reply>
    <orderStatus orderCode="jsxml3589919975">
      <payment>
        <paymentMethod>VISA-SSL</paymentMethod>
        <amount value="100" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
        <lastEvent>AUTHORISED</lastEvent>
        <CVCResultCode description="NOT SUPPLIED BY SHOPPER"/>
        <AVSResultCode description="NOT SUPPLIED BY SHOPPER"/>
        <balance accountType="IN_PROCESS_AUTHORISED">
          <amount value="100" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
        </balance>
        <cardNumber>4444********1111</cardNumber>
        <riskScore value="3"/>
      </payment>
      <token>
        <tokenEventReference>TOK7854321</tokenEventReference>
        <tokenReason>ClothesDepartment</tokenReason>
        <tokenDetails tokenEvent="NEW">
          <paymentTokenID>9961191959944156907</paymentTokenID>
          <paymentTokenExpiry>
            <date dayOfMonth="24" month="03" year="2019" hour="14" minute="01" second="14"/>
          </paymentTokenExpiry>
          <tokenEventReference>TOK7854321</tokenEventReference>
          <tokenReason>ClothesDepartment</tokenReason>
        </tokenDetails>
        <paymentInstrument>
          <cardDetails>
            <expiryDate>
              <date month="06" year="2019"/>
            </expiryDate>
            <cardHolderName>
              <![CDATA[AUTHORISED]]>
            </cardHolderName>
            <cardAddress>
              <address>
                <address1>Worldpay</address1>
                <address2>270-289 The Science Park</address2>
                <address3>Milton Road</address3>
                <postalCode>CB4 0WE</postalCode>
                <city>Cambridge</city>
                <countryCode>GB</countryCode>
              </address>
            </cardAddress>
            <derived>
              <cardBrand>VISA</cardBrand>
              <cardSubBrand>VISA_CREDIT</cardSubBrand>
              <issuerCountryCode>N/A</issuerCountryCode>
              <obfuscatedPAN>4444********1111</obfuscatedPAN>
              <bin>444433</bin>
            </derived>
          </cardDetails>
        </paymentInstrument>
      </token>
    </orderStatus>
  </reply>
</paymentService>

XML reference

Token response elements

Response elementDescription
<token>Contains all details associated with the token.
<tokenEventReference>Allows you to track the creation of tokens within your system.
Where it appears within <token>, it contains the event reference you supplied in your current order submission. However where it appears within <tokenDetails>, it contains the event reference you supplied when the token was first created.
There's an examplebelow.
<tokenReason>Allows you to track the reason for the creation of tokens within your system.
Where it appears within the <token> element, it contains the token reason you supplied in your current order submission. However, where it appears within the <tokenDetails> element it contains the token reason you supplied when the token was first created.
If you did not supply one, this element is populated with a default reason, which includes the orderCode.
tokenEventAttribute of <tokenDetails>. Values can be:
NEW – a new token has been successfully created
MATCH – when trying to create a token with the same authenticatedShopperID and cardNumber as an existing token, all of the following details supplied also match those associated with the existing token:
  • expiryDate
  • cardHolderName
  • cardAddress
The <paymentTokenID> that's returned within the MATCH response is the ID of the existing token.
CONFLICT – when trying to create a token with the same authenticatedShopperID and cardNumber as an existing token, at least one of the following details supplied does not match those associated with the existing token:
  • expiryDate
  • cardHolderName
  • cardAddress
<paymentTokenID> that's returned within the CONFLICT response is the ID of the existing token.
<paymentTokenID>The unique token identifier. This must be included when using a token, or making a token inquiry.
<paymentTokenExpiry>The expiry date of the token. By default, tokens are created with a lifespan of 4 years but you can override this - contact your Relationship or Implementation Manager.
<paymentInstrument>Contains the payment details associated with the token.
Note: You do not need to submit this element when you use an existing token, unless payment details have changed since the token was created. For more information see: Override card details held against a token.
<cardDetails>Contains the card <expiryDate>, <cardHolderName>, <cardAddress>, and the <derived> elements.
<expiryDate>The expiry date of the card used.
<cardHolderName>The given name on the card used.
<cardAddress>The billing address of the person making the payment.
<derived>This element holds details of the card used.
<cardBrand>The brand of the card used to make payments, such as Visa (VISA).
<cardSubBrand>The sub-brand of the card used, if applicable, such as debit (VISA_DEBIT).
<cardCoBrand>The co-brand of the card used, if applicable, such as Cartebleue (CARTEBLEUE).
<obfuscatedPAN>The masked PAN from the card used.
<bin>The BIN of the card.

Example use of token event reference

If you create a token with a <tokenEventReference> of CLD01JAN2015, and then send a second request to create a token (for the same card details and shopper ID) with a <tokenEventReference> of CLS20MAY2015, the second response will show as below.

Copied!
<token>
<authenticatedShopperID>shopperID12</authenticatedShopperID>
<tokenEventReference>CLS20MAY2015</tokenEventReference>
<tokenReason>ClothesDepartment</tokenReason>
<tokenDetails tokenEvent="MATCH">
  <paymentTokenID>9902019934757792074</paymentTokenID>
  <paymentTokenExpiry>
    <date dayOfMonth="3" month="03" year="2019" hour="23" minute="18" second="08"/>
  </paymentTokenExpiry>
  <tokenEventReference>CLD01JAN2015</tokenEventReference>
  <tokenReason>ClothesDepartment</tokenReason>
<tokenDetails/>

Best practice: We recommend that you make the <tokenEventReference> unique for each request.