Stored Credentials

How to comply with scheme mandates for storing (and subsequently using) card payment credentials for cardholder and merchant-initiated transactions. For more product and support information on Stored Credentials, please visit ourStored Credentials overviewon our support site.

On this page:

• Storing Credentials
• Using Credentials
• Tokenisation
• Pay As Order
• Hosted Payment Pages
• XML Reference
• Error Codes

Jump toreferencetable.

Storing Credentials

Include the storedCredentials element

To indicate that you're storing payment details, include <storedCredentials> with the usage value of "FIRST" in your authorisation request:

...
  <storedCredentials usage="FIRST"/>
</paymentDetails>

Store the transactionIdentifier from the response

In the response, you get a <transactionIdentifier> (a child of <schemeResponse>), as shown below. This must be stored and (where applicable) supplied with subsequent use of these card details.

...
  <schemeResponse>
    <transactionIdentifier>1234567890</transactionIdentifier>
  </schemeResponse>
</payment>

Using Credentials

There are two ways to use stored credentials, depending on whether the cardholder or merchant initiates a transaction.

Cardholder initiates

If the cardholder initiates a transaction with their stored details, you must include <storedCredentials> with the usage value of "USED":

...
  <storedCredentials usage="USED">
  </storedCredentials>
</paymentDetails>

Merchant initiates

If the merchant initiates a transaction with the stored details (such as with a recurring payment), you must include:

• <storedCredentials> with:
  • the usage value of "USED", and
  • the appropriate merchantInitiatedReason (explainedbelow)
• <schemeTransactionIdentifier>, which is the <transactionIdentifier> from either:
  • The "FIRST" response message
  • The previous "USED" response message

<storedCredentials usage="USED" merchantInitiatedReason="UNSCHEDULED">
    <schemeTransactionIdentifier>1234567890</schemeTransactionIdentifier> <!-- <transactionIdentifier> response from FIRST or USED request-->
  </storedCredentials>
</paymentDetails>

merchantInitiatedReason

Standing instructions

The standing instruction reasons are used when setting up multiple transactions.

Industry-specific practices

These reasons are used for industry specific business practices, and are for merchant-initiated transactions as a follow-up to cardholder-initiated transactions.

Example Direct 'first' 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="YOUR_MERCHANT_CODE">
  <submit>
    <order orderCode="YOUR_ORDER_CODE"> 
      <description>YOUR DESCRIPTION</description> 
      <amount currencyCode="GBP" exponent="2" value="5000"/>
      <paymentDetails>
        <CARD-SSL>
          <cardNumber>4444333322221111</cardNumber>
          <expiryDate>
            <date month="01" year="2020"/>
          </expiryDate>
          <cardHolderName>A 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>
        </CARD-SSL>
        <storedCredentials usage="FIRST"/> <!--Indicates that you are storing credentials-->
        <session shopperIPAddress="123.123.123.123" id="0215ui8ib1"/>
      </paymentDetails>
      <shopper>
        <shopperEmailAddress>ashopper@myprovider.com</shopperEmailAddress>
        <browser>
          <acceptHeader>text/html</acceptHeader>
          <userAgentHeader>Mozilla/5.0 ...</userAgentHeader>
        </browser>
      </shopper>
    </order>
  </submit>
</paymentService>

Response to 'first' request

Your response includes the <schemeResponse> parameter, within which you get the <transactionIdentifier>. Where required, use the value returned in <transactionIdentifier> as the <schemeTransactionIdentifier> in your request to use credentials:

<?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="ExampleCode1"> 
  <reply>
    <orderStatus orderCode="ExampleOrder1"> 
      <payment>
        <paymentMethod>VISA-SSL</paymentMethod>
        <amount value="5000" currencyCode="GBP" exponent="2" debitCreditIndicator="credit"/>
        <lastEvent>AUTHORISED</lastEvent>
        <AuthorisationId id="666"/> 
        <balance accountType="IN_PROCESS_AUTHORISED">
          <amount value="5000" currencyCode="GBP" exponent="2" debitCreditIndicator="credit"/>
        </balance>
        <cardNumber>4444********1111</cardNumber>
        <riskScore value="0"/>
        <schemeResponse>
          <transactionIdentifier>20005060720116005061</transactionIdentifier> <!--Store this for later use-->
        </schemeResponse>
      </payment>
    </orderStatus>
  </reply>
</paymentService>

Example Direct 'used' 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="YOUR_MERCHANT_CODE">
  <submit>
    <order orderCode="YOUR_ORDER_CODE"> 
      <description>YOUR DESCRIPTION</description> 
      <amount currencyCode="GBP" exponent="2" value="5000"/>
      <paymentDetails>
        <CARD-SSL>
          <cardNumber>4444333322221111</cardNumber>
          <expiryDate>
            <date month="01" year="2020"/>
          </expiryDate>
          <cardHolderName>A 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>
        </CARD-SSL>
        <storedCredentials usage="USED" merchantInitiatedReason="UNSCHEDULED">
          <schemeTransactionIdentifier>20005060720116005061</schemeTransactionIdentifier> <!-- Only include this if it's a merchant-initiated transaction-->
        </storedCredentials>
        <session shopperIPAddress="123.123.123.123" id="0215ui8ib1"/>
      </paymentDetails>
      <shopper>
        <shopperEmailAddress>ashopper@myprovider.com</shopperEmailAddress>
        <browser>
          <acceptHeader>text/html</acceptHeader>
          <userAgentHeader>Mozilla/5.0 ...</userAgentHeader>
        </browser>
      </shopper>
    </order>
  </submit>
</paymentService>

Response to 'used' request

In transactions that have astanding instructionmerchantInitiatedReason, you receive another <transactionIdentifier>. You can either:

• Store and submit this new <transactionIdentifier> as the <schemeTransactionIdentifier> next time (a way of tracking each use specifically)
• Just use the original <transactionIdentifier> (from the 'first' response) as the <schemeTransactionIdentifier> each time you make a new 'used' 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="ExampleOrder1"> <!--The orderCode you supplied in the order-->
      <payment>
        <paymentMethod>VISA-SSL</paymentMethod>
        <amount value="5000" currencyCode="GBP" exponent="2" debitCreditIndicator="credit"/>
        <lastEvent>AUTHORISED</lastEvent>
        <AuthorisationId id="666"/> 
        <balance accountType="IN_PROCESS_AUTHORISED">
          <amount value="5000" currencyCode="GBP" exponent="2" debitCreditIndicator="credit"/>
        </balance>
        <cardNumber>4444********1111</cardNumber>
        <riskScore value="0"/>
        <schemeResponse>
          <transactionIdentifier>94443862893748229682</transactionIdentifier> 
        </schemeResponse>
      </payment>
    </orderStatus>
  </reply>
</paymentService>

Tokenisation

If you useTokenisationfor recurring or future transactions, you must inform the schemes why you're storing your customer's credentials. We strongly recommend understanding the difference between acardholder-initiated and a merchant-initiated transactionbefore you start to integrate.

Worldpay manages the scheme transactionIdentifier forstanding instructionswhere there's only ever a single agreement with one cardholder. Where you handle multiple agreements for one cardholder using a token, please use the transactionIdentifer returned to you which allows you to handle the separate agreements appropriately.

Industry-specific practicesrequire that you record the transactionIdentifier received for payments, and then send this with the subsequent industry-specific request.

Creating tokens with a payment

You must include the <storedCredentials> parameter in all create token requests that will be used for future transactions. This applies to tokens that are created both with and without a payment. For tokens created without a payment, seebelow.

<storedCredentials usage="FIRST"/>

The response is the same as a standardcreate shopperorcreate merchanttoken response.

Creating tokens without a payment

For tokens created without a payment that fall under the stored credentials remit, you need to provide a transaction identifier:

1. Make a zero value authorisation prior to creating the token.
2. Store the <transactionIdentifier> from the response, and include it as the <schemeTransactionIdentifier> in your create token request.

Using tokens

When you're using a token in a payment request, you need to include the usage attribute as USED and, if the merchant initiated the transaction, the appropriate merchantInitiatedReason.

Customer initiates

<storedCredentials usage="USED" />

Merchant initiates

<storedCredentials usage="USED" merchantInitiatedReason="INSTALMENT" />

Other than that, the use token request doesn't change.

Response

The responses you receive are the same as a standard create token (shopperormerchant), oruse tokenresponse. We manage the transactionIdentifier returned by the schemes for cases where there's only ever a single agreement with one cardholder. Store the transactionIdentifer being returned to you for cases where you need to handle multiple agreements for one cardholder in a single token.

Change Pay As Order (PAO)

Standing instruction merchant-initiated transactions

For these PAO transactions there are two scenarios affected by stored credentials:

• PAO based on stored credential payments submitted with stored credential usage 'FIRST'
• PAO based on pre stored credential payments submitted prior to the stored credentials mandate

PAO based on stored credential payments

To create PAO payments that comply with the stored credentials mandate:

1. Send the initial payment as a normal stored credentials 'first' request. If applicable add the merchantInitiatedReason as described inWhat to do when using stored credentials.
2. Send all subsequent requests based on this initial payment, with <storedCredentials> as "USED":

<?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_PAO_MERCHANT_CODE"> 
  <submit>
    <order orderCode="YOUR_NEW_ORDER_CODE"> 
      <description>YOUR DESCRIPTION</description> 
      <amount currencyCode="GBP" exponent="2" value="1399"/> 
      <orderContent>
        <![CDATA[]]>
      </orderContent>
      <payAsOrder orderCode="YOUR_ORDER_CODE" merchantCode="YOUR_MERCHANT_CODE"> <!--The order and merchant code from the first request-->
        <amount value="5000" currencyCode="EUR" exponent="2"/> 
        <storedCredentials usage="USED" merchantInitiatedReason="UNSCHEDULED"/>
      </payAsOrder>
    </order>
  </submit>
</paymentService>

Note that the order code specified for the <payAsOrder> tag can either refer to the original order, or it can refer to the previous one in the series. Both methods will be compliant, but referring to the original order will only work for 2 years until it is archived.

Response to 'used' PAO subsequent request

Our response is the same as aDirect 'used' response.

PAO based on pre stored credential payments

For PAO payments that were set up before the mandate came into effect, Worldpay does not have the stored credentials details associated with the original payment. We will therefore need to resubmit the payment details as usage="FIRST" and obtain a <transactionIdentifier>.

1. The first time you submit a subsequent PAO payment with the <storedCredentials> usage value of "USED", Worldpay will actually submit this as a "FIRST" and will obtain a <transactionIdentifier>. This is so that you don't need to track which PAO order codes are compliant. Just send all PAO payments as "USED" when you start to use the <storedCredentials> element to be compliant.

   Copy

   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_PAO_MERCHANT_CODE"> 
    <submit>
      <order orderCode="YOUR_NEW_REFERENCE_ORDER_CODE"> 
        <description>YOUR DESCRIPTION</description> 
        <amount currencyCode="GBP" exponent="2" value="1399"/> <!--The amount, etc. of this subsequent request-->
        <orderContent>
          <![CDATA[]]>
        </orderContent>
        <payAsOrder orderCode="YOUR_INITIAL_ORDER_CODE" merchantCode="YOUR_MERCHANT_CODE"> <!--The order and merchant code from the initial transaction-->
          <amount value="5000" currencyCode="EUR" exponent="2"/> <!--The amount, etc. from the first request-->
          <storedCredentials usage="USED" merchantInitiatedReason="UNSCHEDULED"/>
        </payAsOrder>
      </order>
    </submit>
   </paymentService>

   <?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_PAO_MERCHANT_CODE"> <submit> <order orderCode="YOUR_NEW_REFERENCE_ORDER_CODE"> <description>YOUR DESCRIPTION</description> <amount currencyCode="GBP" exponent="2" value="1399"/> <!--The amount, etc. of this subsequent request--> <orderContent> <![CDATA[]]> </orderContent> <payAsOrder orderCode="YOUR_INITIAL_ORDER_CODE" merchantCode="YOUR_MERCHANT_CODE"> <!--The order and merchant code from the initial transaction--> <amount value="5000" currencyCode="EUR" exponent="2"/> <!--The amount, etc. from the first request--> <storedCredentials usage="USED" merchantInitiatedReason="UNSCHEDULED"/> </payAsOrder> </order> </submit> </paymentService>

2. We will respond with the addition of <payAsOrderUseNewOrderCode/> (which also shows innotificationsto indicate that the update has happened. If you use the order code from the previous transaction in the series, simply ignore this tag. However if you always use the order code of the initial request as your source PAO order code, then you must now switch to use your new reference order code (and the corresponding amount) from this request. This must be submitted as the referenced order code in all further subsequent requests for this series:

   Copy

   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="YOUR_NEW_REFERENCE_ORDER_CODE"> <!--The new orderCode to use when referencing your initial payment-->
        <payment>
          <paymentMethod>VISA-SSL</paymentMethod>
          <amount value="5000" currencyCode="GBP" exponent="2" debitCreditIndicator="credit"/>
          <lastEvent>AUTHORISED</lastEvent>
          <AuthorisationId id="666"/> 
          <balance accountType="IN_PROCESS_AUTHORISED">
            <amount value="5000" currencyCode="GBP" exponent="2" debitCreditIndicator="credit"/>
          </balance>
          <cardNumber>4444********1111</cardNumber>
          <riskScore value="0"/>
        </payment>
        <payAsOrderUseNewOrderCode/> <!--Indicates that you should now use the new order code-->
      </orderStatus>
    </reply>
   </paymentService>

   <?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="YOUR_NEW_REFERENCE_ORDER_CODE"> <!--The new orderCode to use when referencing your initial payment--> <payment> <paymentMethod>VISA-SSL</paymentMethod> <amount value="5000" currencyCode="GBP" exponent="2" debitCreditIndicator="credit"/> <lastEvent>AUTHORISED</lastEvent> <AuthorisationId id="666"/> <balance accountType="IN_PROCESS_AUTHORISED"> <amount value="5000" currencyCode="GBP" exponent="2" debitCreditIndicator="credit"/> </balance> <cardNumber>4444********1111</cardNumber> <riskScore value="0"/> </payment> <payAsOrderUseNewOrderCode/> <!--Indicates that you should now use the new order code--> </orderStatus> </reply> </paymentService>

3. For the next, and all future PAO requests:

   • Place the orderCode received in the response above, in the orderCode attribute of <payAsOrder> (along with the corresponding amount)
   • Send the <storedCredentials> information as child of <payAsOrder>, with a usage value of "USED"
   • Add thestanding instructionmerchantInitiatedReason as described inWhat to do when using stored credentials

Below is an example PAO request that now references the new order code, and includes merchantInitiatedReason data:

<?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_PAO_MERCHANT_CODE">
  <submit>
    <order orderCode="YOUR_SUBSEQUENT_ORDER_CODE"> 
      <description>YOUR DESCRIPTION</description> 
      <amount currencyCode="GBP" exponent="2" value="1399"/> <!--The amount, etc. of this subsequent request-->
      <orderContent>
        <![CDATA[]]>
      </orderContent>
      <payAsOrder orderCode="THE_NEW_REFERENCE_ORDER_CODE" merchantCode="YOUR_MERCHANT_CODE"> <!--The new order code, referencing stored credentials-->
        <amount value="5000" currencyCode="EUR" exponent="2"/> 
        <storedCredentials usage="USED" merchantInitiatedReason="UNSCHEDULED"/>
      </payAsOrder>
    </order>
  </submit>
</paymentService>

Industry-specific merchant initiated transactions

For Pay As Order:

• The usage attribute must be either "USED" or "NA"
• You must include theindustry-specific reason

Customer-initiated transactions

For customer PAO transactions, subsequent payments should be submitted without a merchantInitiatedReason. Other than that they are the same as MITs previously discussed.

Hosted Payment Pages (HPP) and Tokenisation

When using Worldpay's Hosted Payment Pages with Tokenisation, you must comply with thestored credentials mandate.

To be compliant, you will need to specify the <storedCredentials> information within the initial order XML.

Hosted payment create token example

The following applies to the XML code for these requests:

• Add storedCredentials

And apply:

• usage must be "FIRST"
• merchantInitiatedReason is optional (specify if the token will be used for a Recurring or Installment series)
• schemeTransactionIdentifier must not be present

<?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="jsxml3671821383" installationId="1008057">
         <description>test order</description>
         <amount value="100" currencyCode="EUR" exponent="2" />
         <orderContent />
         <paymentMethodMask>
            <storedCredentials usage="FIRST" merchantInitiatedReason="UNSCHEDULED" />
            <include code="ALL" />
         </paymentMethodMask>
         <shopper>
            <shopperEmailAddress>shopper@worldpay.com</shopperEmailAddress>
            <authenticatedShopperID>shopperID</authenticatedShopperID>
         </shopper>
         <shippingAddress>
            <address>
               <firstName>A</firstName>
               <lastName>Shopper</lastName>
               <street>Queensbridge Road</street>
               <houseNumber>47A</houseNumber>
               <postalCode>CB94BQ</postalCode>
               <city>Cambridge</city>
               <countryCode>GB</countryCode>
            </address>
         </shippingAddress>
         <createToken tokenScope="shopper">
            <tokenEventReference>eventReference</tokenEventReference>
            <tokenReason>reason</tokenReason>
         </createToken>
      </order>
   </submit>
</paymentService>

Submit a Hosted Payment request with a token

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

• <paymentTokenID>enter token here</paymentTokenID>
• tokenScope = "shopper"
• captureCvc = "true"

When using a token with CVC capture, the following applies to the XML:

• usage must be "USED"
• merchantInitiatedReason must not be present
• schemeTransactionIdentifier must not be present

<?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="newOrder12345" installationId="1234567">
         <description>20 red roses from the MyMerchant webshop.</description>
         <amount currencyCode="GBP" exponent="2" value="3000" />
         <paymentDetails>
            <TOKEN-SSL tokenScope="shopper" captureCvc="true">
               <paymentTokenID>enter token here</paymentTokenID>
            </TOKEN-SSL>
            <storedCredentials usage="USED" />
            <session shopperIPAddress="127.0.0.1" id="ssn538305674" />
         </paymentDetails>
         <shopper>
            <shopperEmailAddress>ashopper@myprovider.com</shopperEmailAddress>
            <authenticatedShopperID>shopperID</authenticatedShopperID>
         </shopper>
      </order>
   </submit>
</paymentService>

Details of our Hosted Payment Pages integration can be foundhere.

XML Reference

Order elements

Response elements

Error codes

Direct errors

Tokenisation errors

HPP errors