# Formatting

## `transactionReference` format

* The `transactionReference` must be a uniquely generated identifier
* Our Try (`https://try.access.worldpay-bsh.securedataplatform.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:


| Parameter | Description |
|  --- | --- |
| `subMerchant.name` | The name of your subMerchants company.Valid characters:A-Za-z0-9spaceMax 25 characters. |
| `subMerchant.reference` | The subMerchant ID. Valid characters:0-9Max 15 digits. |
| `subMerchant.address` | The address of your subMerchant company. |
| `address.city` | Valid characters:A-Za-zhyphen(-)spaceMax 13 characters. |
| `address.state` | Valid characters:A-Z Max 3 characters. |
| `address.postalCode` | Valid characters:A-Za-z0-9spaceMax 10 characters. |
| `address.countryCode` | ISO 3166-1 alpha-2 code. Valid characters:A-ZE.g. `GB` Max 2 characters. |
| `address.street` | Valid characters:A-Za-z0-9spaceMax 50 characters. |
| `subMerchant.taxReference` | The subMerchant's tax reference.  Valid characters:A-Za-z0-9spacehyphen(-)Max 20 characters. |
| `subMerchant.email` | The subMerchant's email address.  Valid characters:A-Za-z0-9@spacehyphen(-)Max 40 characters. |
| `subMerchant.phoneNumber` | The subMerchant's phone number.  Valid characters:0-9Max 20 characters. |


## Marketplace format

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

| Parameter | Description |
|  --- | --- |
| `marketplace.sellerCountryCode` | The country where the seller is domiciled.Valid characters:A-ZMax 2 characters. |
| `marketplace.splitFundingreference` | Your reference for split funding.Valid characters:A-Za-zhyphen(-)spaceMax 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:

| Parameter | Data type/format | Length requirement | Regular expression |
|  --- | --- | --- | --- |
| parties.personalDetails.companyName | String | Max 140 | Failure 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.firstName | AN | Max 50 | The full name (firstName + middleName + lastName) should not be longer than 140 characters in total. |
| parties.personalDetails.middleName | AN | Max 50 | The full name (firstName + middleName + lastName) should not be longer than 140 characters in total. |
| parties.personalDetails.lastName | AN | Max 50 | The full name (firstName + middleName + lastName) should not be longer than 140 characters in total. |