Payment facilitator rules
All payment facilitators must supply additional transaction information which clearly identifies both the facilitator and the sub-merchant involved. This page explains what needs to be included and where:
About payment facilitators Where the rules apply Setup Example use of subMerchantData Statement narrative Content of subMerchantData Errors
About payment facilitators
Payment facilitators take the role of a service provider, and are merchants registered by an acquirer to facilitate transactions on behalf of sub-merchants. The provider of the goods/services becomes the sub-merchant instead of the merchant. When the cardholder makes a purchase, the sub-merchant routes the transaction data to the payment facilitator. The payment facilitator incorporates all necessary transaction and merchant identification data and sends this to the acquirer.
Where the rules apply
If (and only if) you are a payment facilitator, you must send the additional data covered on this page with all transactions except refunds.
To set up and register for the service, contact your Relationship or Implementation Manager.
How it works
Sub-merchant data is mandatory on any merchant code flagged as a payment facilitator, and if it is not supplied you will get an error. Sub-merchant data must be provided for all transactions, regardless of the payment method. We send the sub-merchant data on to the appropriate schemes (currently Mastercard and Visa) only, but we have set up our system to collect the additional data by merchant code in the event that more card schemes mandate this data in future.
Example use of subMerchantData
In the Direct integration model, the
<subMerchantData> element contains the additional data you must supply.
<?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>5555555555554444</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> <session shopperIPAddress="18.104.22.168" id="0215ui8ib1"/> </paymentDetails> <shopper> <shopperEmailAddress>email@example.com</shopperEmailAddress> <browser> <acceptHeader>text/html</acceptHeader> <userAgentHeader>Mozilla/5.0 ...</userAgentHeader> </browser> </shopper> <subMerchantData> <!--Supply data in the order shown below--> <pfId>12345678901</pfId> <!--Use your <pfId> supplied by Mastercard or Visa Card--> <subName>Example Shop</subName> <subId>1234567</subId> <subStreet>123 Street</subStreet> <subCity>San Francisco</subCity> <subState>CA</subState> <subCountryCode>840</subCountryCode> <subPostalCode>94101</subPostalCode> <subTaxId>987-65-4321</subTaxId> </subMerchantData> <dynamicMCC>5045</dynamicMCC> <!--Optional dynamic value explained in the Payment Requests page--> <dynamicInteractionType type="MOTO"/> <!--Optional dynamic value explained in the Payment Requests page--> </order> </submit> </paymentService>
Note: You must use
<pfId>your-provided-pfID</pfId> from Mastercard or Visa.
You should take care to provide the right pfId for the right card brand.
For Visa, Mastercard, and Maestro payments, the statement narrative can be made up of 2 lines. Permitted characters are A-Z, a-z, 0-9 and spaces . Diacritics (e.g. "ü") are normalised and all other characters are converted to spaces.
Note: Although Worldpay will pass the 2 line narrative through, what is actually displayed to the shopper depends on the issuer.
The first line is made up of the Shop Name and the content of
This is the payment facilitator name, set up during the boarding process. It is visible in the Profile page of the MAI (under Identification), but can only be changed by contacting Worldpay.
The first word of Shop Name will be used for the first part of the narrative, and if it is:
- less than 3 characters, will be padded (with spaces) to 3
- between 4 and 6 characters, will be padded (with spaces) to 7
- between 8 and 11 characters, will be padded (with spaces) to 12
- greater than 12 characters, will be truncated to 12
This is the sub-merchant name supplied in
<subName> and it will:
- be added to the end of Shop Name
- be prefixed with a asterisk
- use what's left of the total maximum of 22 characters, then will be truncated
Examples of first line construction
|A||Short Name||A*Short Name|
|A||Short Name but Very Long subName||A*Short Name but Very|
|The First Word Of Shop Name Only||Short Name||The*Short Name|
|Four||and a Very Long subName||Four*and a Very Long|
|EightCha||and a Very Long subName||EightCha*and a Very|
|AVeryLongShopNameBut||Also subName||AVeryLongSho*Also subNa|
The second line is taken from
<subCity>, and can be a maximum of 13 characters.
Content of subMerchantData
|0-9||1-11||Mandatory||Payment facilitator ID. Obtained from Mastercard/Visa - contact your Relationship Manager to request registration.|
|0-9||1-11||Conditional||Independent Sales Organisation (ISO) ID provided by Mastercard. If an ISO is involved in the transaction, you must send this information.Both the |
|0-9||1-7||Mandatory||Sub-merchant ID, supplied by payment facilitator|
|[a-z][A-Z][0-9] and spaces||1-25||Mandatory||Sub-merchant name, supplied by payment facilitator|
|[a-z][A-Z][0-9] and spaces||1-50||Mandatory||Sub-merchant street address (line 1). Only 26 characters will be sent for onward processing.|
|[a-z][A-Z][0-9] and spaces||1-13||Mandatory||Sub-merchant city. For Mail/Telephone Order, Ecommerce and Recurring transactions, this can be the Merchant Helpdesk telephone number, web address, and so on, as agreed with your Implementation Manager.|
|[a-z][A-Z][0-9] and spaces (ISO 3166-2 standard)||1-3||Conditional||Sub-merchant state. Mandatory for USA, CAN and ITA sub-merchants. It is your responsibility as the payment facilitator to send this information.|
|0-9 (ISO 31661-1 standard)||1-3||Mandatory||Sub-merchant country code|
|[a-z][A-Z][0-9] and spaces||1-10||Mandatory||Sub-merchant postal code|
|[a-z][A-Z][0-9] hyphens and spaces||1-20||Conditional||Sub-merchant tax ID. Mandatory for USA and CAN sub-merchants. It is your responsibility as the payment facilitator to send this information.|
These errors all display Error Code 5:
|The pfId cannot be longer than 11 digits.|
|The isoId cannot be longer than 11 digits.|
|The subName cannot be longer than 25 characters.|
|The subId cannot be longer than 7 digits.|
|The subStreet cannot be longer than 50 characters.|
|The subCity cannot be longer than 13 characters.|
|The subState cannot be longer than 3 characters.|
|The subCountryCode cannot be longer than 3 digits.|
|The subPostalCode cannot be longer than 10 characters.|
|The subTaxId cannot be longer than 20 characters.|
|The subCountryCode must be entered in digits.|
|The pfId must be entered in digits.|
|The subId must be entered in digits.|
|The isoId must be entered in digits.|
|Sub Merchant Data must be provided.|