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.

A stored credential is Visa, Mastercard, or AMEX information (such as a card number) that a customer has opted for you, as the merchant, to store and use to process future transactions. For Visa and Mastercard, this storage additionally extends to your agent,Payment Facilitator(PF) or aStaged Digital Wallet Operator(SDWO).

These are not considered stored credentials:

  • Credentials received by merchants from third parties including pass-through digital wallets that are not stored by the merchant, its agent, or PF.

    Example: A payment credential received by a merchant on a purchase from Visa Checkout and not stored by that merchant, its agent, or PF.
  • When the merchant or its agent, PF, or SDWO stores the credential to complete a single transaction (or a single purchase) for a cardholder, including multiple authorizations related to that particular transaction.

    Example: When the cardholder provides the payment credential to a hotel to cover charges related to a specific reservation only.

Warning: You must notify the cardholder and receive their agreement before you can store credentials. We explain more about thishere.

On this page:

Jump toreferencetable.

Storing Credentials

Best practice: At present, Visa mandate that you must provide the <schemeTransactionIdentifier> when using EMV tokenised PANs inmerchant-initiatedtransactions. However, we strongly recommend that you provide the <schemeTransactionIdentifier> for all stored credentials submissions.

Include the storedCredentials element

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

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

Note: The <transactionIdentifier> may contain up to 56 characters, and may include spaces, even at the beginning or end. Preserve all of these characters.

Copied!
...
  <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":

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

merchantInitiatedReasonDescription
INSTALMENTA single purchase of goods or services billed to a cardholder in multiple transactions, over a period of time agreed by the cardholder and you.
RECURRINGTransactions processed at fixed, regular intervals not to exceed one year between transactions, representing an agreement between a cardholder and you to purchase goods or services provided over a period of time.
UNSCHEDULEDA transaction using a stored credential for a fixed or variable amount that does not occur on a scheduled or regularly occurring transaction date. This includes account top-ups triggered by balance thresholds.
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.

Best practice: When sending the original payment you may not know if a subsequent payment is needed. Since you will need the <transactionIdentifier> for any follow-up payments, we recommend that you request to always have this returned for industry-specific reasons. Contact us to enable this feature.

Note: If you're using an industry-specific reason and the original cardholder-initiated transaction was not submitted as a 'FIRST', you can set the usage attribute to "NA" as it is not applicable.

merchantInitiatedReasonDescription
REAUTHReauthorisation - a purchase made after the original purchase. A common scenario is delayed/split shipments.
DELAYEDA delayed charge is typically used in hotel, cruise lines and vehicle rental environments to perform a supplemental account charge after original services are rendered.
INCREMENTALAn incremental authorisation is typically found in hotel and car rental environments, where the cardholder has agreed to pay for any service incurred during the duration of the contract.

An incremental authorisation is where you need to seek authorisation of further funds in addition to what you have originally requested. A common scenario is additional services charged to the contract, such as extending a stay in a hotel.
RESUBMISSIONWhen the original purchase occurred, but you were not able to get authorisation at the time the goods or services were provided. It should only be used where the goods or services have already been provided, but the post-event authorisation request is declined for insufficient funds.
NOSHOWA no-show is a transaction where you are enabled to charge for services which the cardholder entered into an agreement to purchase, but the cardholder did not meet the terms of the agreement.

Example Direct 'first' 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="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:

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

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

Copied!
<storedCredentials usage="FIRST"/>

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

Creating tokens without a payment

Prerequisite: As you need the <schemeTransactionIdentifer> for your create token (without payment) request, you need to request to always have this returned. Contact us to enable this feature.

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

Copied!
<storedCredentials usage="USED" />

Merchant initiates

Copied!
<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)

Best practice: As an alternative to PAO, we recommend switching toTokenisationand converting to eithershopperormerchanttokens to process your recurring payments. PAO will eventually be phased out.

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":
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_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

Note: This mechanism is only applicable for transactions using astanding instructionmerchantInitiatedReason.

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.

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

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

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

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.

Note: You must get consent from your shopper, before they have specified how they will pay, when using HPP. By using the "save payment details" opt-in on the payment pages, you are meeting the requirement to include the truncated card number (i.e. last four digits) in your consent agreement.

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

Note: To submit a subsequent MIT (Merchant Initiated Transaction) using the token, see the section above on using tokens. You are not required to submit the transactionIdentifier for single agreement per card use cases since we handle it for you.

Submit a Hosted Payment request with a token

Note: This is appropriate if the transaction is CIT (cardholder initiated) and so you need to supply the CVC in your XML request.

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

Elements/attributesM/O/CDescription
<storedCredentials>OptionalInstructs Worldpay that this is a stored credential transaction.
<storedCredentials>
usage
`MandatorySpecifies whether you are storing credentials or using stored ones. Values can be:
  • "FIRST" - You are storing credentials
  • "USED" - You are using stored credentials
  • "NA" - Industry-specific payment reason submission
<storedCredentials>
merchantInitiatedReason
ConditionalGives the reason for the transaction being made. Mandatory if the merchant is initiating the transaction (as opposed to the cardholder). For values, see the tableabove.
<storedCredentials>
schemeTransactionIdentifier
ConditionalThe <transactionIdentifier> from the response message when you first stored the credentials. Mandatory if the merchant is initiating the transaction (as opposed to the cardholder) and using stored credentials (usage="USED").
Maximum 56 characters, can contain spaces.

Note: Reuse the <transactionIdentifier> you receive from the "FIRST" response for the standing instruction series. Alternatively, extract each new <transactionIdentifier>, you get back, as a way of uniquely tracking each use of stored credentials.

Response elements

Elements/attributesM/O/CDescription
<schemeResponse>
<transactionIdentifier>
ConditionalReturned if either:
  • <storedCredentials> was present in the request, or
  • You have requested to have <transactionIdentifier> always returned
This is the transaction identifier response from the scheme. Maximum 56 characters, can contain spaces.

Note: Preserve this exactly as you receive it, including any spaces.

<payAsOrderUseNewOrderCode/>ConditionalReturned if you send <storedCredentials> to update an existing PAO payment that was created before the mandate came into effect.

Instructs you to use the new order code we returned (and the corresponding amount) in all further subsequent requests.

Error codes

Direct errors

ValueMessageDescription
2Attribute "usage" with value "Test" must have a value from the list "FIRST USED "Incorrect value for usage indicator
2Attribute "usage" is required and must be specified for element type "storedCredentials"Usage indicator not supplied
2Attribute "merchantInitiatedReason" with value "merchantInitiatedReason" must have a value from the list "NA REAUTH UNSCHEDULED DELAYED INSTALMENT INCREMENTAL RECURRING RESUBMISSION NOSHOWIncorrect or missing value for merchantInitiatedReason
5schemeTransactionIdentifier present for FIRST payment: schemeTransactionIdentifier should not be present when storedCredential = FIRST.schemeTransactionIdentifier present for FIRST payment
5schemeTransactionIdentifier has an invalid length, it should have max 56 charsschemeTransactionIdentifier exceeds 56 chars
5schemeTransactionIdentifier should be present when merchantInitiatedReason is provided for storedCredential = USED.For a subsequent payment, schemeTransactionIdentifier is absent but merchantInitiatedReason is present

Tokenisation errors

ValueMessageDescription
5Use TOKEN does not support schemeTransactionIdentifier in storedCredentialsUse token with MIT details, usage=USED and schemeTransactionIdentifier
5Use TOKEN does not support storedCredentials = FIRSTUse token with MIT details, usage=FIRST
5schemeTransactionIdentifier present for FIRST payment: schemeTransactionIdentifier must not be present when storedCredential = FIRSTCreate payment token with MIT details, usage=FIRST and schemeTransactionIdentifier present
5storedCredentials usage can't have a value different than FIRST in a request for creating a tokenCreate payment token with MIT details, usage=USED
5schemeTransactionIdentifier must be present when storedCredential = FIRSTCreate token without payment with MIT details, usage=FIRST and schemeTransactionIdentifier not present
5storedCredentials usage can't have a value different than FIRST in a request for creating a tokenCreate token without payment with MIT details, usage=USED

HPP errors

ValueMessageDescription
5storedCredentials usage cannot have a value different than FIRST in a request for creating a tokenCreate payment token with HPP, MIT details - usage=USED/NA
5schemeTransactionIdentifier must not be present when storedCredential = FIRSTCreate payment token with HPP, MIT details - usage=FIRST and schemeTransactionIdentifier present
5storedCredentials usage cannot have a value different than USED in a request for using token and capturing CVV with Hosted Payment PagesCapture CVV with HPP with MIT details - usage=FIRST/NA
5merchantInitiatedReason must not be present in a request for using token and capturing CVV with Hosted Payment PagesCapture CVV with HPP, MIT details - merchantInitiatedReason present
5schemeTransactionIdentifier must not be present in a request for using token and capturing CVV with Hosted Payment PagesCapture CVV with HPP, MIT details - schemeTransactionIdentifier present