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 +

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 customers statement
  • Valid characters:
    • A-Z
    • a-z
    • 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
    • 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

  • pfId - Your payment facilitator ID received from Mastercard.
  • isoId - 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.cityThe city your sub-merchant is based.
Valid characters:
  • A-Z
  • a-z
  • 0-9
  • Hyphen(-)
  • Space

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

Max 25 characters.
subMerchant.stateValid characters:
  • A-Z

Max 30 characters
subMerchant.postalCodeValid characters:
  • A-Z
  • a-z
  • 0-9
  • Space

Max 15 characters.
subMerchant.merchantIdValid characters:
  • 0-9

Max 7 digits
subMerchant.countryCodeSeeISO country codesfor more information.
subMerchant.streetValid characters:
  • A-Z
  • a-z
  • 0-9
  • Space

Max 50 characters.
subMerchant.taxIdValid characters:
  • A-Z
  • a-z
  • 0-9
  • Space
  • Hyphen(-)

Max 20 characters.