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. The combined descriptor is limited to 22 characters across all supported networks (Visa, Mastercard, Discover, American Express).

How descriptors are built

Highnote constructs the descriptor from two 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.

Combined length of prefix + suffix is capped at 22 characters. If the combined value exceeds the limit, the suffix is truncated.

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	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 acquiring mutations:

Category	Mutation	Input
Verify	verifyPaymentCard	VerifyPaymentCardInput
Verify	verifyPaymentMethodToken	VerifyPaymentMethodTokenInput
Verify	verifyNetworkToken	VerifyNetworkTokenInput
Authorize	authorizePaymentCard	AuthorizePaymentCardInput
Authorize	authorizePaymentMethodToken	AuthorizePaymentMethodTokenInput
Authorize	authorizeNetworkToken	AuthorizeNetworkTokenInput
Charge	chargePaymentCard	ChargePaymentCardInput
Charge	chargePaymentMethodToken	ChargePaymentMethodTokenInput
Charge	chargeNetworkToken	ChargeNetworkTokenInput

Not supported: chargePaymentOrder and chargePaymentOrderFromPaymentMethodToken do not accept merchantDescriptor.

Input shape

MerchantDescriptorInput contains a single field:

Field	Type	Description
suffix	String	Value appended to the configured merchant descriptor prefix. Combined length (prefix + suffix) is capped at 22 characters; if exceeded, the suffix is truncated.

Example

The following snippet shows the merchantDescriptor field passed to chargePaymentCard. The same pattern applies to any supported mutation.

chargePaymentCard with a suffix

mutation ChargePaymentCard($input: ChargePaymentCardInput!) {
  chargePaymentCard(input: $input) {
    ... on PaymentTransactionSummary {
      id
      createdAt
    }
  }
}

Variables

{
  "input": {
    "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.