Click here to search the entire website

Create tokens

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

Jump to reference table

Note:  This page covers the creation of shopper tokens. You can also create merchant tokens (useful if you have a Point of Sale branch), which is explained in Merchant tokens. If you want to send us tokens from another provider, or if you want to create bulk tokens from a list of details, contact your Relationship Manager.

Create a token with a payment request

Tokens can be created by requesting them with an order, either with the Direct or Hosted integrations. If you use the Direct model and our Client Side Encryption service, you can send the encrypted card data as part of the request.

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

  • tokenScope - an attribute of <createToken> which states whether the token will be a merchant or a shopper token. For more information, see Shopper or merchant tokens. If tokenScope is not used, the default value will be "shopper", and a shopper token will be 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 (_).

  • <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. See Example Direct order with create token request for an example.

Additionally, for shopper tokens only, you must also submit the <authenticatedShopperID>. This is 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 a reference that you control, and is unique and persistent for each shopper that makes a payment through your site. We also recommend that you make the <tokenEventReference> unique for each order submission - this allows you to track the creation of tokens in your system.

Example Direct order with create token request

Select

<?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>

        <paymentTokenExpiry> <!--Provide this to override the default token life-->

          <date dayOfMonth="03" month="06" year="2017" hour="10" minute="24" second="16"/> <!--This cannot be longer than four years from token creation-->

        </paymentTokenExpiry>

      </createToken>

    </order>

  </submit>

</paymentService>

Example order with create token request (Direct)

 

Response to a Direct create token request

<?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" hour="02" minute="25" second="15"/>

          </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>

            </derived>

          </cardDetails>

        </paymentInstrument>

      </token>

    </orderStatus>

  </reply>

</paymentService>

Response to a create token request

Note:  The response is the same whether it's from the Client Side Encryption or unencrypted submission.

Example Hosted order with create token request

Select

<?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>

      </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 order with a create 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 - see Retrieve token details.

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

Create a 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 you use a token which was created alongside a payment.

Select

<?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>

Example create token request (without an order)

 

Response

<?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>

          </derived>

        </cardDetails>

      </paymentInstrument>

    </token>

  </reply>

</paymentService>

Response to a create token request (without an order)

Note:  The response is the same whether it's from the Client Side Encryption or 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.

Select

<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:  You should not submit the <paymentTokenExpiry> element in your submission when you're creating a short life token, as this will result in 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 the Token does not exist error. The <paymentTokenExpiry> within the response will reflect the short life token:

<paymentTokenExpiry>

  <date dayOfMonth="31" month="05" year="2017" hour="10" minute="24">

</paymentTokenExpiry>

Create a 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 in Create a token with a payment request above.

Example Pay as Order payment with create token request

Select

<?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>

Example PAO payment with create token request

Pay as Order response with create token information

<?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>

            </derived>

          </cardDetails>

        </paymentInstrument>

      </token>

    </orderStatus>

  </reply>

</paymentService>

Example PAO response with create token information

XML reference

Token response elements

Response element Description

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

For example, 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:

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

This is also why we recommend that you make the <tokenEventReference> unique for each request.

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

tokenEvent

Attribute 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

    The <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 - see Create a token with a payment request.

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

Use Tokens