- Home
- All APIs
- WPG guide
- Airline data
- Stored Credentials
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 our
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,
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 this
On this page:
Storing Credentials Using Credentials Tokenisation Pay As Order Hosted Payment Pages XML Reference Statement narratives for VISA Error Codes Jump toreference table.
Storing Credentials
Best practice: At present, Visa mandate that you must provide the <schemeTransactionIdentifier>
when using EMV tokenised PANs in<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:
...
<storedCredentials usage="FIRST"/>
</paymentDetails>
... <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.
...
<schemeResponse>
<transactionIdentifier>1234567890</transactionIdentifier>
</schemeResponse>
</payment>
... <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>
... <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 )
- the
<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>
<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.
merchantInitiatedReason | Description |
---|---|
INSTALMENT | A single purchase of goods or services billed to a cardholder in multiple transactions, over a period of time agreed by the cardholder and you. |
RECURRING | Transactions 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. |
UNSCHEDULED | A 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.
merchantInitiatedReason | Description |
---|---|
REAUTH | Reauthorisation - a purchase made after the original purchase. A common scenario is delayed/split shipments. |
DELAYED | A delayed charge is typically used in hotel, cruise lines and vehicle rental environments to perform a supplemental account charge after original services are rendered. |
INCREMENTAL | An 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. |
RESUBMISSION | When 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. |
NOSHOW | A 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
<?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>
<?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>
<?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>
<?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 amerchantInitiatedReason
, 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>
<?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 use
Worldpay manages the scheme transactionIdentifier
fortransactionIdentifer
returned to you which allows you to handle the separate agreements appropriately.
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, see
<storedCredentials usage="FIRST"/>
<storedCredentials usage="FIRST"/>
The response is the same as a standard
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:
- Make a zero value authorisation prior to creating the token.
- 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" />
<storedCredentials usage="USED" />
Merchant initiates
<storedCredentials usage="USED" merchantInitiatedReason="INSTALMENT" />
<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 (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 to
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:
- Send the initial payment as a normal stored credentials 'first' request. If applicable add the merchantInitiatedReason as described in
What to do when using stored credentials . - 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>
<?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 a
PAO based on pre stored credential payments
Note: This mechanism is only applicable for transactions using a
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>
.
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>
<?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>
We will respond with the addition of
<payAsOrderUseNewOrderCode/>
(which also shows innotifications to 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>
<?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>
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 the
standing instruction merchantInitiatedReason as described inWhat to do when using stored credentials
- Place the orderCode received in the response above, in the orderCode attribute of
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>
<?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 the
industry-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 the
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
<?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>
<?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 presentschemeTransactionIdentifier
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>
<?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 found
XML Reference
Order elements
Elements/attributes | M/O/C | Description |
---|---|---|
<storedCredentials> | Optional | Instructs Worldpay that this is a stored credential transaction. |
<storedCredentials> usage | `Mandatory | Specifies whether you are storing credentials or using stored ones. Values can be:
|
<storedCredentials> merchantInitiatedReason | Conditional | Gives the reason for the transaction being made. Mandatory if the merchant is initiating the transaction (as opposed to the cardholder). For values, see the table |
<storedCredentials> schemeTransactionIdentifier | Conditional | The <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 |
Response elements
Elements/attributes | M/O/C | Description |
---|---|---|
<schemeResponse> <transactionIdentifier> | Conditional | Returned if either:
Note: Preserve this exactly as you receive it, including any spaces. |
<payAsOrderUseNewOrderCode/> | Conditional | Returned 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. |
Statement Narratives for VISA
From April 2021, Visa suggest that you use an enhanced descriptor (statement narrative) when a trial period or discounted promotional period ends.
Example
What do we mean by a trial period or discounted promotional offer? One example is a special offer on an annual magazine subscription, 12 magazines per year.
For the first three months of the offer, the magazine costs £1 per month and customer is billed that amount. On the fourth month the special offer expires. From the fourth month to the end of the subscription (month 12) the magazine costs its normal price which is £5 per month.
In the past, some customers have questioned why the price of the magazine has gone up, in this case by 500%. If statement narratives are enabled, the customer's bank statement has a message next to the magazine subscription. In this case it would be something like Special offer ends.
Enhanced descriptors should cut down on the number of inquiries sent to your customer service team. Visa hope that the number of chargebacks and demands for refunds are also reduced.
Implementation
We assume you start a transaction with stored details of the customer.
If you already have dynamic statement narratives configured, you may be able to use the existing description to provide the enhanced descriptor.
Otherwise, you can include the <overrideNarrative>
attribute in your request. If the content of the <overrideNarrative>
is valid, Worldpay will use it for merchant-initiated requests paid by Visa.
Note: As the name suggests, the override narrative replaces any other statement narrative you may already have configured. But the override only applies to this individual transaction.
XML example:
In the example below, the special statement narrative text appears between the overrideNarrative
tags.
Note: Only include the schemeTransactionIdentifier
line if it is a merchant-initiated transaction.
<?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>An example 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>
<overrideNarrative>End of Trial</overrideNarrative>
</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_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>An example 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> <overrideNarrative>End of Trial</overrideNarrative> </order> </submit> </paymentService>
Rules for overrideNarrative contents
Valid characters
A-Z; a-z; 0-9
*; - ; . ; , ; ; ; SPACE These appear in the Narrative in BO and also in Pay server logs.
The # character is replaced by a space.
The + and - characters are replaced by a space.
; Deletes the previous/following space characters.
Invalid characters
! @ \\ /' ^ % < > Invalid characters
If any invalid characters are included, the system ignores the override narrative.
Lengths
Maximum length of line 1 = 22 characters.
Maximum length of line 2 = 13 characters.
Minimum length of line 1 = 0 characters.
Minimum length of line 2 = 1 character.
Note: Please contact your Implementation manager before you use the overrideNarrative (supported from early 2021). This feature is not available for non-Worldpay acquired merchants.
Error codes
Direct errors
Value | Message | Description |
---|---|---|
2 | Attribute "usage" with value "Test" must have a value from the list "FIRST USED " | Incorrect value for usage indicator |
2 | Attribute "usage" is required and must be specified for element type "storedCredentials" | Usage indicator not supplied |
2 | Attribute "merchantInitiatedReason" with value "merchantInitiatedReason" must have a value from the list "NA REAUTH UNSCHEDULED DELAYED INSTALMENT INCREMENTAL RECURRING RESUBMISSION NOSHOW | Incorrect or missing value for merchantInitiatedReason |
5 | schemeTransactionIdentifier present for FIRST payment: schemeTransactionIdentifier should not be present when storedCredential = FIRST. | schemeTransactionIdentifier present for FIRST payment |
5 | schemeTransactionIdentifier has an invalid length, it should have max 56 chars | schemeTransactionIdentifier exceeds 56 chars |
5 | schemeTransactionIdentifier should be present when merchantInitiatedReason is provided for storedCredential = USED. | For a subsequent payment, schemeTransactionIdentifier is absent but merchantInitiatedReason is present |
Tokenisation errors
Value | Message | Description |
---|---|---|
5 | Use TOKEN does not support schemeTransactionIdentifier in storedCredentials | Use token with MIT details, usage=USED and schemeTransactionIdentifier |
5 | Use TOKEN does not support storedCredentials = FIRST | Use token with MIT details, usage=FIRST |
5 | schemeTransactionIdentifier present for FIRST payment: schemeTransactionIdentifier must not be present when storedCredential = FIRST | Create payment token with MIT details, usage=FIRST and schemeTransactionIdentifier present |
5 | storedCredentials usage can't have a value different than FIRST in a request for creating a token | Create payment token with MIT details, usage=USED |
5 | schemeTransactionIdentifier must be present when storedCredential = FIRST | Create token without payment with MIT details, usage=FIRST and schemeTransactionIdentifier not present |
5 | storedCredentials usage can't have a value different than FIRST in a request for creating a token | Create token without payment with MIT details, usage=USED |
HPP errors
Value | Message | Description |
---|---|---|
5 | storedCredentials usage cannot have a value different than FIRST in a request for creating a token | Create payment token with HPP, MIT details - usage=USED/NA |
5 | schemeTransactionIdentifier must not be present when storedCredential = FIRST | Create payment token with HPP, MIT details - usage=FIRST and schemeTransactionIdentifier present |
5 | storedCredentials usage cannot have a value different than USED in a request for using token and capturing CVV with Hosted Payment Pages | Capture CVV with HPP with MIT details - usage=FIRST/NA |
5 | merchantInitiatedReason must not be present in a request for using token and capturing CVV with Hosted Payment Pages | Capture CVV with HPP, MIT details - merchantInitiatedReason present |
5 | schemeTransactionIdentifier must not be present in a request for using token and capturing CVV with Hosted Payment Pages | Capture CVV with HPP, MIT details - schemeTransactionIdentifier present |