Click here to search the entire website

Use tokens

Tokens can only be used via the Direct API call.

How to:

Submit a payment request with a token

Warning:  Due to PCI DSS regulations, the CVC is not stored with the token details. However, you can optionally submit the CVC for checking.

If you have created tokens through the Hosted model and want to perform 3D Secure checks on payments where a token is used, you must send additional information, which is covered in the 3D Secure section.

To use a token you have already created, send <TOKEN-SSL> as part of <paymentDetails>, with:

  • tokenScope - an attribute of <TOKEN-SSL> which states whether the token used is a merchant or a shopper token. If not sent, defaults to "shopper". If an incorrect tokenScope is used, you'll get an error.

  • <paymentTokenID> - required to retrieve details of the token

  • <authenticatedShopperID> - child of <shopper>. Mandatory for shopper tokens, do not submit for merchant tokens.

Example use token submission

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>

        <TOKEN-SSL tokenScope="shopper">

          <paymentTokenID>efnhiuh7438rhf3hd9i3</paymentTokenID>

        </TOKEN-SSL>

        <session shopperIPAddress="123.123.123" id="0215ui8ib1" />

      </paymentDetails>

      <shopper>

        <shopperEmailAddress>jshopper@myprovider.int</shopperEmailAddress>

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

    </order>

  </submit>

</paymentService>

Example use token request

Response to a use token submission

The response to a use token submission is exactly the same as a standard order response.

Override card details held against a token

How it works

Overriding is useful when you want to use a token and supplement information that wasn’t supplied when the token was created.

The overriding information must be submitted each time an order is processed, because the details in the token store are not replaced.

You do not have to submit all of the optional fields, but any that you do not submit will be taken from the token store.

Note:  You can also permanently update a token's details. See Update tokens.

What to send

To override the stored token details, submit <cardDetails> as part of <paymentInstrument>. You can override:

  • <expiryDate> - the expiry date on the card used to make the payment

  • <cardHolderName> - the name on the card used to make the payment

  • <cardAddress> - the address associated with the card used to make the payment

Example use token submission with override data

An example with all optional elements included to override the data associated with the token:

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>

        <TOKEN-SSL tokenScope="shopper">

          <paymentTokenID>efnhiuh7438rhf3hd9i3</paymentTokenID>

          <paymentInstrument>

            <cardDetails>

              <expiryDate>

                <date month="06" year="2019"/>

              </expiryDate>

              <cardHolderName>J.Shopper</cardHolderName>

              <cvc>121</cvc> <!--not stored with the token, but you can submit it for checking-->

              <cardAddress>

                <address>

                  <address1>Worldpay</address1>

                  <postalCode>CB4 0WE</postalCode>

                  <city>Cambridge</city>

                  <countryCode>GB</countryCode>

                </address>

              </cardAddress>

            </cardDetails>

          </paymentInstrument>

        </TOKEN-SSL>

        <session shopperIPAddress="123.123.123.123" id="0215ui8ib1" />

      </paymentDetails>

      <shopper>

        <shopperEmailAddress>jshopper@myprovider.int</shopperEmailAddress>

        <authenticatedShopperID>shopperID1234</authenticatedShopperID>

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

    </order>

  </submit>

</paymentService>

Example use token request with override data

Response to a use token submission with override data

The response to a use token submission with override data is exactly the same as a standard payment response.

Use tokens for payouts

You can use Tokenisation for payouts by issuing funds to a tokenised card. Card payouts work the same as standard payment submissions, but the <paymentDetails> element contains the action="REFUND" attribute. See Card payouts.

For more information, please speak to your Relationship Manager or contact corporatesupport@worldpay.com.

Visa submission

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="YOUR_MERCHANT_CODE">

  <submit>

    <order orderCode="ORDER_CODE">

      <description>description</description>

      <amount value="1200" currencyCode="GBP" exponent="2"/>

      <orderContent>Order Content</orderContent>

      <paymentDetails action="REFUND">

        <TOKEN-SSL tokenScope="shopper">

          <paymentTokenID>9986026996721218712</paymentTokenID>

          <paymentInstrument>

            <cardDetails>

              <expiryDate>

                <date month="06" year="2022"/>

              </expiryDate>

              <cardHolderName>

                <![CDATA[AUTHORISED]]>

              </cardHolderName>

            </cardDetails>

          </paymentInstrument>

        </TOKEN-SSL>

      </paymentDetails>

      <shopper>

        <shopperEmailAddress>sp@worldpay.com</shopperEmailAddress>

        <authenticatedShopperID>shopperID</authenticatedShopperID>

        <browser>

          <acceptHeader>text/html</acceptHeader>

          <userAgentHeader>Mozilla/5.0 ...</userAgentHeader>

        </browser>

      </shopper>

    </order>

  </submit>

</paymentService>

Mastercard submission

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="YOUR_MERCHANT_CODE">

  <submit>

    <order orderCode="ORDER_CODE">

      <description>description</description>

      <amount value="1100" currencyCode="GBP" exponent="2"/>

      <orderContent>Order Content</orderContent>

      <paymentDetails action="REFUND">

        <TOKEN-SSL tokenScope="shopper">

          <paymentTokenID>9986090008001925106</paymentTokenID>

          <paymentInstrument>

            <cardDetails>

              <expiryDate>

                <date month="06" year="2022"/>

              </expiryDate>

              <cardHolderName>

                <![CDATA[AUTHORISED]]>

              </cardHolderName>

            </cardDetails>

          </paymentInstrument>

        </TOKEN-SSL>

      </paymentDetails>

      <shopper>

        <shopperEmailAddress>sp@worldpay.com</shopperEmailAddress>

        <authenticatedShopperID>shopperID</authenticatedShopperID>

        <browser>

          <acceptHeader>text/html</acceptHeader>

          <userAgentHeader>Mozilla/5.0 ...</userAgentHeader>

        </browser>

      </shopper>

    </order>

  </submit>

</paymentService>

Manage tokens