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

How to:

Jump toreference table

Retrieve token details

There are three ways to get details about a token -token inquiries, standardorder inquiriesandorder notifications.

Prerequisite: In order to receive token details using any of the methods, your systems will need a secure HTTP(S) URL that will be able to interpret and process the information contained within the message.

Order notifications

Order notifications for tokens behave in the same way as normal notifications, except that they return the <token> details if a token was created as part of the order.

If you use the Hosted integration model, you must use order notifications to obtain the details of created tokens.

The <token> details are not returned in notifications:

  • if a token was used to make a payment

  • if, in the Hosted integration model, a shopper selects a payment method that can't be tokenised

If you're creating tokens in the Hosted integration model, you must enable order notifications so that you can obtain the <paymentTokenID> (in order to use or inquire about the token). As a minimum, the Order Notifications must be set to return orders in the status of AUTHORISED, REFUSED and CANCELLED.

Token inquiries

You can send a query to retrieve details about a specific token to check the last recorded status of it, or to recover the information associated with it.

Submit this information as children of the <inquiry> element:

  • <paymentTokenInquiry> - the request for token details, including the optional attribute tokenScope. If the attribute is not included, the default value is shopper. If you use merchant tokens, be sure to set tokenScope to "merchant"

  • <authenticatedShopperID> - your unique reference to identify the shopper (only used for shopper tokens)

  • <paymentTokenID> - the unique token identifier, returned by us when we created the token

Example token inquiry

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">
  <inquiry>
    <paymentTokenInquiry tokenScope="shopper"> 
      <authenticatedShopperID>shopper1</authenticatedShopperID> 
      <paymentTokenID>9902019934757792074</paymentTokenID>
    </paymentTokenInquiry>
  </inquiry>
</paymentService>

Example token inquiry response

An example response to the above inquiry:

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>shopper1</authenticatedShopperID>
      <tokenDetails>
        <paymentTokenID>9902019934757792074</paymentTokenID>
        <paymentTokenExpiry>
          <date dayOfMonth="3" month="03" year="2019" hour="03" minute="51" second="35"/>
        </paymentTokenExpiry>
        <tokenEventReference>TOK7854321</tokenEventReference>
        <tokenReason>ClothesDepartment</tokenReason>
      </tokenDetails>
      <paymentInstrument>
        <cardDetails>
          <expiryDate>
            <date month="06" year="2019"/>
          </expiryDate>
          <cardHolderName>J.Shopper</cardHolderName>
          <cardAddress>
            <address>
              <lastName>Shopper</lastName>
              <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>
  </reply>
</paymentService>

Shopper token retrieval

Use this inquiry to retrieve up to the 16 tokens that can be stored against a single authenticated shopper ID. The inquiry could be used to display a list of tokenised payment methods to a shopper during the checkout stage of a transaction. The tokens will be returned in the order of last use, so the most recently-used token will be returned first.

Submit this information as children to the <inquiry> element:

  • <shopperTokenRetrieval> - the request for all of the shopper's tokens
  • <authenticatedShopperID> - your unique reference to identify the shopper (only used for shopper tokens)

Example Shopper Token Retrieval inquiry

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">
  <inquiry>
    <shopperTokenRetrieval>
      <authenticatedShopperID>shopperID</authenticatedShopperID>
    </shopperTokenRetrieval>
  </inquiry>
</paymentService>

In the case that an invalid authenticated shopper ID is provided in the inquiry, or that there are no tokens attributed to the ID, then a blank response will be provided.

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

Order Inquiries

In response to a standardorder inquiry(with the same XML submission as normal), you'll also receive any relevant token information.

Update tokens

How it works

You update tokens with a modification request. Unlike amanual override, updating tokens will permanently replace existing token data with any updated fields.

Each token can only be updated a maximum of 10 times in a rolling 30 day period. If you exceed this limit, an error message is returned. If you have a specific need to submit more than 10 update token requests within a 30 day period, this limit can be temporarily overridden by contacting corporatesupport@worldpay.com.

Warning: The PAN (credit or debit card number) cannot be updated. You will need to submit a newCreate Tokenrequest.

What to send

Within the standard <modify> element, you instruct the <paymentTokenUpdate> (with the optional tokenScope attribute) and include the:

  • <paymentTokenID> - the unique token identifier, returned by us when we created the token

  • <authenticatedShopperID> (for shopper tokens only)

  • <paymentInstrument> with at least one of:

    • <cardAddress> and within this <address1>, <address2>, <address3>, <postCode>, <city>, <state>, <countryCode>.

      Best practice: Always send us the <cardAddress> and child elements with a token update request, whether any of it has changed or not. If it isn't included in the update token request, the stored information will not be kept.

    • <expiryDate> - updates the expiry date of the credit or debit card. If this element is not included in an update token request, the stored information will be kept.

    • <cardHolderName> - updates the name which appears on the front of a credit or debit card. If this element is not included in an update token request, the stored information will be kept.

Example update token details request

In this example, the submission requests that the <expiryDate>, <cardHolderName> and <cardAddress> are updated by including these elements within <paymentInstrument>.

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">
  <modify>
    <paymentTokenUpdate tokenScope="shopper"> 
      <paymentTokenID>99444433060076481111</paymentTokenID>
      <authenticatedShopperID>shopperID22</authenticatedShopperID> <!--Mandatory for shopper tokens, don't send for merchant tokens-->
      <paymentInstrument>
        <cardDetails>
          <expiryDate>
            <date month="06" year="2022"/>
          </expiryDate>
          <cardHolderName>Mr Name</cardHolderName>
          <cardAddress> <!--Anything not included within this will be removed from the token-->
            <address>
              <firstName>Mr Bert</firstName>
              <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>
        </cardDetails>
      </paymentInstrument>
      <tokenEventReference>eventReference</tokenEventReference>
      <tokenReason>reason</tokenReason>
    </paymentTokenUpdate>
  </modify>
</paymentService>

Update token response

An example response to the above 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>
    <ok>
      <updateTokenReceived paymentTokenID="99444433060076481111"/>
    </ok>
  </reply>
</paymentService>

Note: If an error is returned instead, it'll be one of the errors described inTroubleshoot.

Delete tokens

How it works

You delete tokens with a modification request. Useful if you want to add the functionality to your website to allow a customer to delete their tokenised card details. This also works with merchant tokens.

As soon as the request is successfully processed, the token will be scheduled for deletion and you will no longer be able to use it. The request cannot be undone, nor can a deleted token be recovered. If you attempt to use a token following a successful delete request, an error message will be returned.

What to send

Within the standard <modify> element, you instruct the <paymentTokenDelete> (with the optional tokenScope attribute) and include the:

  • <paymentTokenID> - the unique token identifier, returned by us when we created the token

  • <authenticatedShopperID> (for shopper tokens only)

  • <tokenEventReference> - optional. the reference used when the token was created.

  • <tokenReason> - optional. The reason for token deletion. If left blank, we'll populate it with "Token expired: YYYY-MM-DD"

Example delete 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">
  <modify>
    <paymentTokenDelete tokenScope="shopper"> 
      <paymentTokenID>9902019934757792074</paymentTokenID>
      <authenticatedShopperID>UniqueShopperID</authenticatedShopperID> <!--Mandatory for shopper tokens, don't send for merchant tokens-->
      <tokenEventReference>TOK7854321</tokenEventReference>
      <tokenReason>ClothesDepartment</tokenReason>
    </paymentTokenDelete>                
  </modify>                    
</paymentService>

Delete token 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>
    <ok>
      <deleteTokenReceived paymentTokenID="9902019934757792074"/>
    </ok>
  </reply>
</paymentService>

Note: If an error is returned instead, it'll be one of the errors described inTroubleshoot.

Detokenise

How it works

Detokenisation lets you see the card details of a tokenised card. You detokenise with an inquiry request. To do this:

  1. Create a 2048-bit encrypted key pair.

  2. Contact Worldpay to enable the service and inform us of your public key (which we'll use to encrpyt the PAN).

  3. Keep your private key safe - this will be used to decrypt the PAN we return.

  4. Submit an inquiry to us as shown below.

What to send

Within the standard <inquiry> element, you instruct the <paymentTokenInquiry> (with the optional tokenScope attribute) to include detokenisation="true" , and include:

  • <paymentTokenID> - the unique token identifier, returned by us when we created the token

  • <authenticatedShopperID> (for shopper tokens only)

Example detokenisation 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">
  <inquiry>
    <paymentTokenInquiry tokenScope="shopper" detokenisation="true"> 
      <authenticatedShopperID>shopperID</authenticatedShopperID> <!--Mandatory for shopper tokens, don't send for merchant tokens-->
      <paymentTokenID>9902019934757792074</paymentTokenID>
    </paymentTokenInquiry>
  </inquiry>
</paymentService>

Detokenisation response

Our response is similar to a standard inquiry response, with one exception; the addition of the <encryptedPAN>, which can be decrypted with your private key:

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>shopperID</authenticatedShopperID>
      <tokenDetails>
        <paymentTokenID>99444433580187371111</paymentTokenID>
        <paymentTokenExpiry>
          <date dayOfMonth="9" month="08" year="2020" hour="16" minute="25" second="15"/>
        </paymentTokenExpiry>
        <tokenEventReference>eventReference</tokenEventReference>
        <tokenReason>reason</tokenReason>
      </tokenDetails>
      <paymentInstrument>
        <cardDetails>
          <expiryDate>
            <date month="06" year="2019"/>
          </expiryDate>
          <cardHolderName>
            <![CDATA[AUTHORISED]]>
          </cardHolderName>
          <encryptedPAN>
            <![CDATA[J4xb6RPwclvJU/QHYHe6yfCzm6dQUUMgGS8xYKuU7hL7cUBDRU7CtfuIvzT4iwpl2ZTI2Lxcg3xgqAmcfljxCHlLQJYZ2i+Eo1ASv4vy+mGAZ/or3kMFLmA0jiYdcMC4L6
            lJpVuvMwS2h+F41Rr673b0BG+caGz+yiGceCNKlTc8tY+VxN4RJeeSnqhmiwUW8uCSboNGM9tiTSFLUNJLeFvRs9niqY8Uo9H1p29LUO3gP+XpVNfdTcpQmb2bXxooxUiWK/ucvm1aW
            3S6IWdgCAulyGxh/q2KNDtHs0HAuG7B3F4cVikVRUWY7zR3VN2CP+DnVbc2TTw5PUfN0HOPYQ==]]>
          </encryptedPAN>
          <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>
  </reply>
</paymentService>

Account Updater token inquiries

You can use Tokenisation with the Account Updater service to check the status of a cardholder's account, including a change to the card PAN and/or expiry date.

How it works

You send a token enquiry request containing a Payment Token ID to Worldpay. We decrypt the card details and send a request to the card issuer, who provides a response about whether the details have been updated or changed. Depending on whether anything has changed, the token details are either updated with new information (and a new Payment Token ID is created if using a merchant or format-preserving token), or no action is taken.

What can be updated

Using Account Updater, you can check to see whether:

  • a shopper's card PAN and/or expiry date have changed

  • a shopper has cancelled a card

  • a shopper has cancelled a recurring payment agreement through their card issuer

  • the card issuer has cancelled a shopper's card account

Note: For more information, see theSubmitting token inquiry requestssection of theAccount Updater guide.

XML reference

Response element/attributeDescription
<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 the <token> element, it contains the event reference you supplied in your current order submission. However where it appears within the <tokenDetails> element, 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

The <paymentTokenID> that's returned within the CONFLICT response is the ID of the existing token.
USE – An existing token has been used to make a payment.
<paymentTokenID>The unique token identifier. This must be included whenusing a token, or making atoken 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 `` 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.
``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 (_VISADEBIT).
<cardCoBrand>The co-brand of the card used, if applicable, such as Cartebleue (CARTEBLEUE).
<obfuscatedPAN>The masked PAN from the card used.

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.