Click here to search the entire website

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 Mastercard 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 both the Direct and Hosted integration model, the <subMerchantData> element contains the additional data you must supply.

Statement narrative

For Visa, Mastercard, Maestro and American Express 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 name subName Narrative
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

Second line

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

Content of subMerchantData

Element Format Length M/O/C Description
<pfId> 0-9 1-11 Mandatory Payment facilitator ID. Obtained from Mastercard - contact your Relationship Manager to request registration.
<isoId> 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 <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-9 1-7 Mandatory Sub-merchant ID, supplied by payment facilitator
<subName> [a-z][A-Z][0-9] and spaces 1-25 Mandatory Sub-merchant name, supplied by payment facilitator
<subStreet> [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.

<subCity> [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.
<subState> [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.

<subCountryCode> 0-9 (ISO 31661-1 standard) 1-3 Mandatory Sub-merchant country code
<subPostalCode> [a-z][A-Z][0-9] and spaces 1-10 Mandatory Sub-merchant postal code
<subTaxId> [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.

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.