Merchant Descriptors
Overview
A merchant descriptor is the short alphanumeric string that appears on a customer's card statement to identify a transaction. Accurate, recognizable descriptors reduce disputes and chargebacks by helping customers answer "Who charged me, and what is the charge for?"
Highnote builds the descriptor sent to the payment networks for each transaction. Across the supported networks (Visa, Mastercard, Discover, American Express), the combined descriptor is capped at 22 characters by default, or 25 characters when the transaction routes through a Visa DMS or Visa SMS processor.
How descriptors are built
Highnote constructs the descriptor from three parts:
- Prefix: A static value Highnote manages for your merchant based on the Public Merchant Name or Doing Business As (DBA) name collected and validated during onboarding. Where payment network rules require it, Highnote automatically prepends indicators such as the payment facilitator marker (
HNT*). Contact Highnote to change your prefix. - Suffix: An optional, per-transaction value you pass through the API on acquiring mutations. Use the suffix to include transaction-specific details (for example, an order number or store identifier) that help the customer recognize the charge.
- Separator: On push (OCT) transactions, Highnote inserts an asterisk (
*) between the prefix and the suffix. Pull (AFT) and card-acceptance transactions use no separator. The separator counts toward the character cap, so on push it costs one of the characters otherwise available to your suffix.
The combined length of prefix + separator + suffix is capped at 22 characters (25 on a Visa DMS or Visa SMS processor). If the combined value exceeds the cap, Highnote truncates the suffix to fit; if the prefix alone fills the cap, Highnote drops the suffix entirely.
The 25-character allowance applies to the combined value only. Where a rail also checks your raw suffix up front — as transferFunds (INT) does — that check uses the flat 22-character limit.
The characters left for your suffix are therefore the cap minus your prefix length, minus one more on push (OCT) for the * separator. A 22-character cap with an 8-character prefix leaves 13 characters for the suffix on push, or 14 on pull and on card-acceptance mutations.
The Transfer Funds (INT) rail enforces the same combined-length cap. INT also rejects a raw suffix over 22 characters up front, before the combine step runs. See the info box under Supported mutations.
Descriptor types
| Type | What it looks like | When it's used |
|---|---|---|
| Static | Prefix only — the same value on every transaction | No merchantDescriptor passed on the mutation |
| Combination | Prefix plus a per-transaction suffix, separated by * on push (OCT) | merchantDescriptor.suffix passed on the mutation |
Pass a suffix per transaction
Pass a merchantDescriptor on the mutation input to append a per-transaction suffix to the configured prefix.
Supported mutations
merchantDescriptor is an optional field on the input types for the following mutations:
| Category | Mutation | Input |
|---|---|---|
| Verify | verifyPaymentCard | VerifyPaymentCardInput |
| Verify | verifyPaymentMethodToken | VerifyPaymentMethodTokenInput |
| Verify | verifyNetworkToken | VerifyNetworkTokenInput |
| Authorize | authorizePaymentTransaction | AuthorizePaymentTransactionInput |
| Charge | chargePaymentTransaction | ChargePaymentTransactionInput |
| Transfer | transferFunds (INT rail) | TransferFundsInput |
The credential-specific mutations (authorizePaymentCard, authorizeNetworkToken, authorizePaymentMethodToken, chargePaymentCard, chargeNetworkToken, chargePaymentMethodToken) also continue to accept merchantDescriptor.
To move an existing integration to the consolidated mutations, see the migration guide.
Mutations chargePaymentOrder and chargePaymentOrderFromPaymentMethodToken do not accept merchantDescriptor.
On transferFunds, the merchantDescriptor field only applies to Instant Network Transfers.
Highnote checks the raw suffix first: a suffix over 22 characters is rejected with a validation error, before it reaches the network. This input limit is always 22 characters: it is checked before Highnote knows which processor will handle the transfer, so the higher Visa DMS or Visa SMS cap does not apply to it.
After that check, Highnote combines the accepted suffix with the configured prefix, the same as the card-acceptance mutations above, and caps the combined value at 22 characters (25 on a Visa DMS or Visa SMS processor). If the combined length exceeds the cap, Highnote truncates the suffix.
Push (OCT) transfers also spend one character on the * separator; pull (AFT) transfers use no separator. So passing a suffix within the 22-character input limit does not guarantee it survives intact — what reaches the statement is bounded by the combined cap.
Input shape
MerchantDescriptorInput contains a single field:
| Field | Type | Description |
|---|---|---|
suffix | String | Value appended to the configured merchant descriptor prefix. The combined character length of prefix + separator + suffix is capped at 22 characters (25 on a Visa DMS or Visa SMS processor) on every mutation, including transferFunds (INT), and Highnote truncates an over-length suffix to fit. Push (OCT) transactions spend one character on the * separator. On transferFunds (INT), Highnote also rejects a raw suffix over 22 characters up front. See Supported mutations. |
Example
The following snippet shows the merchantDescriptor field passed to chargePaymentTransaction. The same pattern applies to any supported mutation.
mutation ChargePaymentTransaction($input: ChargePaymentTransactionInput!) {
chargePaymentTransaction(input: $input) {
... on CardCaptureStepSummary {
createdAt
transaction {
id
}
}
}
}
{
"input": {
"credential": {
"paymentCard": { "...": "..." }
},
"amount": { "value": 1999, "currencyCode": "USD" },
"merchantDescriptor": {
"suffix": "ORDER-4821"
}
}
}
Allowed characters
The suffix field accepts any string at the API layer, but the payment networks and processors apply character restrictions downstream. To maximize compatibility across networks, limit suffix content to:
- Letters:
a–z,A–Z - Digits:
0–9 - Special characters:
.,,,',_,-,?,+,*, and space
Where the descriptor appears
The constructed descriptor (prefix + optional suffix) is sent to the payment networks with each transaction and appears on the customer's card statement.