Formatting

transactionReference format

  • The transactionReference must be a uniquely generated identifier
  • Our Try (https://try.access.worldpay.com/) environment returns a bad request error if a duplicate transactionReference is supplied
  • 64 characters max. We recommend your transactionReference contains between 9-20 characters for ease of onward processing
  • This safeguards you against acquirers who truncate the transactionReference

Supported format, structure and limits for transactionReference:

Valid characters:

  • A-Z
  • a-z
  • 0-9
  • Hyphen -
  • Underscore _
  • Forward Slash /
  • Exclamation mark !
  • At @
  • Pound, number sign, sharp or hash #
  • Dollar $
  • Percent %
  • Parenthesis ()
  • Asterisk *
  • Equal =
  • Full stop .
  • Colon :
  • Semi-colon ;
  • Question mark ?
  • Brackets []
  • Braces or Curly braces {}
  • Tilde ~
  • Plus +
Caution

Some characters, for example: Parenthesis () or Semi-colon ;, can trigger our Web Application Firewall (WAF) rules to block your requests, if used in a combination that might be interpreted as an attempt to inject a command.

reference format

  • This format applies for the reference parameter in partial settlement and partial refund requests
  • reference must be between 1-128 characters

Valid characters:

  • A-Z
  • a-z
  • 0-9
  • Hyphen -

Narrative format

The narrative object helps your customers to better identify you on their statement.

Narrative line1

line1 is used to provide basic details about the merchant.

Note

line1 is mandatory and must be included in your request.

Supported format, structure and limits for line1:

  • This has to be a consistent identifier
  • There is a limit of 24 characters (25 characters for Payouts v1)
  • It is not guaranteed that the bank will show this on the customer's statement
  • Valid characters:
    • A-Z
    • a-z (these may appear as upper case in the statement)
    • 0-9
    • Hyphen -
    • Full stop .
    • Commas ,
    • Space

Narrative line2

line2 is used for additional context about the payment or merchant. eg Order number or Merchant phone number.

Note

line2 is not mandatory.

Supported format, structure and limits for line2:

  • Free form
  • There is a limit of 24 characters
  • Valid characters:
    • A-Z
    • a-z (these may appear as upper case in the statement)
    • 0-9
    • Hyphen -
    • Full stop .
    • Commas ,
    • Space

narrative (Payouts API only)

Supported format, structure and limits for narrative:

  • Free form
  • There is a limit of 24 characters
  • Valid characters:
    • A-Z

Payment facilitator format

  • schemeId - Your payment facilitator ID received from Mastercard, Visa or Amex.
Important

Please ensure you add the correct schemeId to the right brand.

  • independentSalesOrganizationId - Independent Sales Organization (ISO) ID provided by Mastercard. If an ISO is involved in the transaction, you must send this information.

  • subMerchant - Your sub-merchant's details which includes:

ParameterDescription
subMerchant.nameThe name of your subMerchants company.
Valid characters:
  • A-Z
  • a-z
  • 0-9
  • Space

Max 25 characters.
subMerchant.referenceThe subMerchant ID.
Valid characters:
  • 0-9

Max 15 digits.
subMerchant.addressThe address of your subMerchant company.
address.cityValid characters:
  • A-Z
  • a-z
  • Hyphen(-)
  • Space
Max 13 characters.
address.stateValid characters:
  • A-Z
Max 3 characters.
address.postalCodeValid characters:
  • A-Z
  • a-z
  • 0-9
  • Space
Max 10 characters.
address.countryCodeISO 3166-1 alpha-2 code. Valid characters:
  • A-Z
E.g. GB
Max 2 characters.
address.streetValid characters:
  • A-Z
  • a-z
  • 0-9
  • Space
Max 50 characters.
subMerchant.taxReferenceThe subMerchant's tax reference.
Valid characters:
  • A-Z
  • a-z
  • 0-9
  • Space
  • Hyphen(-)
Max 20 characters.
subMerchant.emailThe subMerchant's email address.
Valid characters:
  • A-Z
  • a-z
  • 0-9
  • @
  • Space
  • Hyphen(-)
Max 40 characters.
subMerchant.phoneNumberThe subMerchant's phone number.
Valid characters:
  • 0-9
Max 20 characters.

Marketplace format

Marketplaces can optionally provide further information in both full and partial settlement calls.

ParameterDescription
marketplace.sellerCountryCodeThe country where the seller is domiciled.
Valid characters:
  • A-Z

Max 2 characters.
marketplace.splitFundingreferenceYour reference for split funding.
Valid characters:
  • A-Z
  • a-z
  • Hyphen(-)
  • Space

Max 256 characters.

Name field formatting (Account Payouts API)

First, Middle, Last and Company names must follow specific field requirements for length and content. Below are regular expressions for permissible values of these fields:

ParameterData Type/FormatLength RequirementRegular Expression
parties.personalDetails.companyNameStringMax 140Failure to provide the full name could result in delays and potential rejection of your payment. This should consist of 2 words, separated by a space. If the value is a one-word business name please contact your Relationship Manager.
parties.personalDetails.firstNameANMax 50The full name (firstName + middleName + lastName) should not be longer than 140 characters in total.
parties.personalDetails.middleNameANMax 50The full name (firstName + middleName + lastName) should not be longer than 140 characters in total.
parties.personalDetails.lastNameANMax 50The full name (firstName + middleName + lastName) should not be longer than 140 characters in total.