Menu

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

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.

Setup

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.

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>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="123.123.123.123" id="0215ui8ib1"/>
      </paymentDetails>
      <shopper>
        <shopperEmailAddress>jshopper@myprovider.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.

Statement narrative

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.

First line

The first line is made up of the Shop Name and the content of <subName>.

Shop Name

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

subName

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

Shop namesubNameNarrative
AShort NameA*Short Name
AShort Name but Very Long subNameA*Short Name but Very
The First Word Of Shop Name OnlyShort NameThe*Short Name
Fourand a Very Long subNameFour*and a Very Long
EightChaand a Very Long subNameEightCha*and a Very
AVeryLongShopNameButAlso subNameAVeryLongSho*Also subNa

Second line

The second line is taken from <subCity>, and can be a maximum of 13 characters.

Content of subMerchantData

ElementFormatLengthM/O/CDescription
<pfId>0-91-11MandatoryPayment facilitator ID. Obtained from Mastercard/Visa - contact your Relationship Manager to request registration.
<isoId>0-91-11ConditionalIndependent Sales Organisation (ISO) ID provided by Mastercard. If an ISO is involved in the transaction, you must send this information.Both the <pfId> and <isoId> are unique to the Service Provider/Agent that is registered with Mastercard. If the Service Provider/Agent is both a payment facilitator and an ISO, then upon registration the same ID is assigned as the <pfId> and <isoId>.
<subId>0-91-7MandatorySub-merchant ID, supplied by payment facilitator
<subName>[a-z][A-Z][0-9] and spaces1-25MandatorySub-merchant name, supplied by payment facilitator
<subStreet>[a-z][A-Z][0-9] and spaces1-50MandatorySub-merchant street address (line 1). Only 26 characters will be sent for onward processing.
<subCity>[a-z][A-Z][0-9] and spaces1-13MandatorySub-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.
<subState>[a-z][A-Z][0-9] and spaces (ISO 3166-2 standard)1-3ConditionalSub-merchant state. Mandatory for USA, CAN and ITA sub-merchants. It is your responsibility as the payment facilitator to send this information.
<subCountryCode>0-9 (ISO 31661-1 standard)1-3MandatorySub-merchant country code
<subPostalCode>[a-z][A-Z][0-9] and spaces1-10MandatorySub-merchant postal code
<subTaxId>[a-z][A-Z][0-9] hyphens and spaces1-20ConditionalSub-merchant tax ID. Mandatory for USA and CAN sub-merchants. It is your responsibility as the payment facilitator to send this information.

Errors

These errors all display Error Code 5:

Error Content
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.