Use tokens

Tokens can only be used via the Direct API call.

How to:

Submit a Direct 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 the3D Securesection.

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

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

Response to a use token submission

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

Submit a Hosted payment request with a token

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.
  • captureCvc - an attribute of <TOKEN-SSL> which allows you to capture the CVC on the Hosted Payment Page. Must be set to "true".
  • <paymentTokenID> - required to retrieve details of the token.
  • <session> - you need to provide the shopperIPAddress and session id as part of your submission.
  • <authenticatedShopperID> - child of <shopper>. Mandatory for shopper tokens, do not submit for merchant tokens.

Note: If you include <preferredPaymentMethod> in your request (which is not required), ensure this is set to NULL.

Example use token submission

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="MERCHANT_CODE">
  <submit>
    <order orderCode="ORDER_CODE" installationId="INSTALLATION_ID">
      <description>20 red roses from the MyMerchant webshop.</description>
      <amount currencyCode="GBP" exponent="2" value="5000"/>
      <paymentDetails>
        <TOKEN-SSL tokenScope="shopper" captureCvc="true">
          <paymentTokenID>9978051453841540125</paymentTokenID>
        </TOKEN-SSL>
        <session shopperIPAddress="123.123.123" id="session1" />
      </paymentDetails>
      <shopper>
        <shopperEmailAddress>shopper@testshop.com</shopperEmailAddress>
        <authenticatedShopperID>UniqueshopperID</authenticatedShopperID>
      </shopper>
    </order>
  </submit>
</paymentService>

Response to a use token submission

The response to a use token submission is exactly the same as astandard Hosted order response, and the shopper is redirected to a payment page where they only need to enter their CVC.

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

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

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

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

Visa submission

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="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>
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="DEMO">
  <reply>
    <ok>
      <refundReceived orderCode="ORDER_CODE">
        <amount value="1230" currencyCode="GBP" exponent="2" debitCreditIndicator="credit"/>
      </refundReceived>
    </ok>
  </reply>
</paymentService>

Mastercard submission

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="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>
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="YOUR_MERCHANT_CODE">
  <reply>
    <orderStatus orderCode="ORDER_CODE">
      <payment>
        <paymentMethod>ECMC_DEBIT-SSL</paymentMethod>
        <amount value="1110" currencyCode="GBP" exponent="2" debitCreditIndicator="credit"/>
        <lastEvent>SENT_FOR_REFUND</lastEvent>
        <AuthorisationId id="987654"/> <!--This is the online authorisation ID-->
        <balance accountType="IN_PROCESS_CAPTURED">
          <amount value="1110" currencyCode="GBP" exponent="2" debitCreditIndicator="debit"/>
        </balance>
      </payment>
    </orderStatus>
  </reply>
</paymentService>

Feedback or bugs to report?

Ask our developer community.

Get support

STAY CONNECTED

©2020 Worldpay, LLC and/or its affiliates. All rights reserved.

Within this page
Submit a Direct payment request with a tokenSubmit a Hosted payment request with a tokenExample use token submissionOverride card details held against a tokenUse tokens for payouts

​

Search our documentation, API references and articles.