Create shopper 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 shopper tokens if you only intend to use tokens for your eCommerce channel.

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 shopper token with a payment request

Shopper 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:

  • <authenticatedShopperID> - a reference that uniquely identifies each shopper so that you can associate their payment tokens with them. The maximum length is 64 characters, it must contain only the ISO-latin1 subset of the UTF-8 characters, there must be no white space and it cannot start with an underscore (_). Up to 16 shopper tokens can be created against one <authenticatedShopperID>.

    Best practice: We recommend that you use an <authenticatedShopperID> that you control, and is unique and persistent for each shopper that makes a payment through your site.

Optional elements

<createToken> can optionally contain:

  • tokenScope - an attribute of <createToken> which states whether the token will be a shopper or a merchant token. If tokenScope is not used, the default value will be "shopper", and a shopper token will be created.

  • 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.

Direct create (shopper) 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="T0211010">
      <description>20 red roses from the MyMerchant webshop.</description>
      <amount currencyCode="GBP" exponent="2" value="5000"/>
      <paymentDetails>
        <VISA-SSL>
          <cardNumber>44444433333322221111</cardNumber>
          <expiryDate>
            <date month="01" year="2020"/>
          </expiryDate>
          <cardHolderName>J. Shopper</cardHolderName>
          <cvc>123</cvc>
          <cardAddress>
            <address>
              <address1>47A</address1>
              <address2>Queensbridge Road</address2>
              <address3>Suburbia</address3>
              <postalCode>CB94BQ</postalCode>
              <city>Cambridge</city>
              <state>Cambridgeshire</state>
              <countryCode>GB</countryCode>
              <telephoneNumber>0122312345</telephoneNumber>
            </address>
          </cardAddress>
        </VISA-SSL>
        <session shopperIPAddress="123.123.123.123" id="0215ui8ib1" />
      </paymentDetails>
      <shopper>
        <shopperEmailAddress>jshopper@myprovider.int</shopperEmailAddress>
        <authenticatedShopperID>UniqueshopperID</authenticatedShopperID> <!--Mandatory for shopper tokens, don't send for merchant tokens-->
        <browser>
          <acceptHeader>text/html,application/xhtml+xml,application/xml ;q=0.9,*/*;q=0.8 </acceptHeader>
          <userAgentHeader>Mozilla/5.0 (Windows; U; Windows NT 5.1;en-GB; rv:1.9.1.5) Gecko/20091102 Firefox/3.5.5 (.NET CLR 3.5.30729)</userAgentHeader>
        </browser>
      </shopper>
      <createToken tokenScope="shopper">
        <tokenEventReference>TOK7854321</tokenEventReference>
        <tokenReason>ClothesDepartment</tokenReason>
      </createToken>
    </order>
  </submit>
</paymentService>

Response to a Direct create (shopper) 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="T0211010">
      <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>
        <authenticatedShopperID>UniqueshopperID</authenticatedShopperID>
        <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>
        <paymentInstrument>
          <cardDetails>
            <expiryDate>
              <date month="03" year="2019"/>
            </expiryDate>
            <cardHolderName>J.Shopper</cardHolderName>
            <cardAddress>
              <address>
                <lastName>Shopper</lastName>
                <address1>47A</address1>
                <address2>Queensbridge Road</address2>
                <address3>Suburbia</address3>
                <state>Cambridge</state>
                <countryCode>GB</countryCode>
                <telephoneNumber>0122312345</telephoneNumber>
              </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>

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

Hosted create (shopper) 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="T0211010">
      <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>
        <authenticatedShopperID>UniqueshopperID</authenticatedShopperID> <!--Mandatory for shopper tokens, don't send for merchant tokens-->
      </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="shopper">
        <tokenEventReference>TOK7854321</tokenEventReference>
        <tokenReason>ClothesDepartment</tokenReason>
      </createToken>
    </order>
  </submit>
</paymentService>

Response to a Hosted create (shopper) 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 not 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 shopper 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-->
      <authenticatedShopperID>UniqueshopperID</authenticatedShopperID>
      <createToken tokenScope="shopper">
        <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>

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>
      <authenticatedShopperID>UniqueshopperID</authenticatedShopperID>
      <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="shopper">
  <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: Do 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 shopper 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 shopper 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>
        <authenticatedShopperID>shopperID</authenticatedShopperID> <!--Mandatory for shopper tokens, don't use for merchant tokens-->
      </shopper>
      <createToken tokenScope="shopper">
        <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>
        <authenticatedShopperID>shopperID</authenticatedShopperID>
        <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.
<authenticatedShopperID>If an initial request had the tokenScope set to "shopper" (or not included), then this element will contain the shopper's unique ID. If the tokenScope was set to "merchant", this element will not be included within the response.
<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.