Skip to main content

Statement Descriptors

A statement descriptor is the short line of text a buyer sees next to a charge on their card statement or banking app. It has two parts, and they behave very differently:

PartWhat it isWho controls itReliable?
Brand prefixYour business name — the part a buyer reads as "who charged me".Your merchant account, registered with your payment processor at boarding.Set once, at the account level — not per charge.
Dynamic tailA short per-transaction identifier appended after the brand (e.g. an order number).You, per charge, through the Payments API.Depends on your processor connection: some show it after your brand, others never print it.

Put together, a statement typically reads like:

BRAND*ORD-1234

where BRAND is your registered business name and ORD-1234 is the dynamic tail you sent on that specific charge.

To change the brand a buyer sees, update the registered descriptor on your merchant account with your payment processor — many banks show that registered name and ignore any business name sent on an individual charge. The tail is what you send per charge. Whether it prints depends on the processor connection: some show it after your account's prefix, some always show a fixed descriptor registered with your acquirer that nothing sent through this API can change, and others show only the brand name, with no tail.

How the descriptor is configured​

Descriptor behaviour is configured per merchant by Von Payments — ask your Von Payments contact to set it up or change it. A configuration has two pieces:

  1. A fixed identity — your business name, plus optional city, country, phone, url, and postal code. These describe your business and, where a processor accepts a structured descriptor, travel with the charge.
  2. A dynamic-suffix rule — how the per-transaction tail is chosen. The rule has a source (where the tail comes from) and a fallback (what to do when that source is missing on a given charge).

Where the brand line actually comes from​

⚠️ Your configured name is not always what prints as the brand. It depends on the processor connection your account uses, and the difference matters if you are building a preview of what the buyer will see.

Connection styleWhat supplies the brandWhat your name does
A structured-descriptor connectionYour configured name is sent with the charge as the brand.It is the brand.
A prefix-and-suffix connectionThe prefix comes from your own account settings held at the processor, and those take precedence.It does not print. It only estimates the character budget left for the tail — and that estimate is wrong when the two differ.

On a prefix-and-suffix connection the printed result is PREFIX* tail, and the separator (* plus a space) counts against the total — so two characters of your budget go to punctuation before any of your text does.

Do not build a buyer-facing preview screen from your configuration alone. Use it to see what you have configured and to compute the tail your metadata will produce; confirm the final printed descriptor at the processor. Confirming what was sent covers how.

Tail sources​

The source decides which value becomes the tail. All except none read a field from the charge's metadata:

SourceReads fromTypical use
order_idmetadata.order_idShow the order number on the statement.
subscription_idmetadata.subscription_idShow the subscription a renewal belongs to.
customer_idmetadata.customer_idShow your internal customer reference.
custommetadata.<your key>Any metadata key you choose (e.g. product_name).
none—No dynamic tail; the statement shows the brand only.

Fallbacks​

The fallback decides what happens when the source field is absent or empty on a charge:

FallbackBehavior when the source field is missing
skipNo tail is added — the statement shows the brand alone.
pi_refThe last 8 characters of the payment intent ID are used as the tail, so the charge is still traceable.
literalA fixed text you configured is used as the tail.

Feeding the tail from your code​

You supply the tail's value per charge in the PaymentIntent metadata — the same metadata object you already send on POST /v1/payment_intents. The key is fixed by your configured rule; you provide the value.

If your rule's source is order_id:

{
"amount": 4999,
"currency": "USD",
"metadata": { "order_id": "ORD-1234" }
}

If your rule uses a custom source with the key product_name:

{
"amount": 4999,
"currency": "USD",
"metadata": { "product_name": "Blue Widget" }
}

The buyer's statement then reads roughly BRAND*ORD-1234 or BRAND*Blue Widget (subject to the length and character rules below). If you omit the configured key on a charge, the rule's fallback applies.

On a checkout session​

When the buyer pays on a checkout session with charge-at-submit card fields or a wallet button on your own page, the tail is read from the session's metadata, with the same rule. Set the key when you create the session, or add it later with PATCH /v1/sessions/{id} while the session is still open, for example once your store has created the order. The value is taken when the payment starts, so a change after that does not apply to it. If the processor refuses the descriptor on such a payment, the payment is sent again once without it, so the buyer is not refused over the descriptor.

The tail can never be sourced from buyer PII

A custom key that looks like buyer-identifying data — email, phone, card, ssn, tax_id, address, and similar — is rejected when the rule is set up. Choose a non-PII key such as order_id or product_name.

Length and character rules​

Card networks give the whole descriptor very little room, so a few rules apply before anything reaches the bank:

  • Total length: 22 characters. The entire descriptor — brand prefix, the separator, and the tail — is capped at 22 characters. The prefix and separator consume part of that budget; the tail gets whatever remains.
  • The tail is hard-truncated. If the tail is longer than the remaining room, it is cut to fit — there is no … ellipsis. A tail of ORDER-2026-000199 can land on the statement as ORDER-2026-00 if that's all that fits. Keep tails short and put the most identifying characters first.
  • Printable ASCII only. Tail values are reduced to printable ASCII (letters, digits, and common punctuation) before use; emoji, accented letters, and non-Latin characters are stripped out. The configured brand name is likewise limited to 5 to 22 printable-ASCII characters and can't contain < > \ ' " *.

Because the tail is cut, not summarised, front-load the part that identifies the charge: 1234-ORDER truncates more usefully than ORDER-NUMBER-1234.

Limits by connection​

Each connection style takes different fields, with different limits. A name outside its limits means no descriptor is sent (skipped / invalid_for_provider). Any other field outside its limits is left off, and the rest is sent.

FieldStructured-descriptor connectionPrefix-and-suffix connection
name5 to 22 characters. A connection that prints only the name fits 20, so keep the name to 20 there.Not sent. The prefix comes from your processor account.
Per-charge tailSent as the description, cut to 22 characters. A tail under 5 characters, such as a 4-digit order number, is left off, and the name still goes out.Prefix, * and tail together: at most 22 characters.
literal fallback text5 to 22 charactersCounts as the tail
city, url, postal code1 to 50 characters eachNot sent
country2 capital letters, such as USNot sent
phone+, the country code and the number, at most 15 digits, such as +14155551234Not sent

A name under 5 characters cannot be saved. If one was saved before this limit, it is not sent on a structured-descriptor connection: the charge goes through with your processor account's default descriptor, and resolved_descriptor reads skipped / invalid_for_provider.

One statement name per product or campaign​

On a connection that prints only the name, the per-charge tail never reaches the statement. A name pattern puts the per-charge value into the name instead. Von Payments sets it on your account, for example ACME {product}. Each charge fills {product} with the same per-charge value your tail rule reads, such as metadata.product_name. A pattern applies on a structured-descriptor connection.

PartRule
The whole nameAt most 20 characters. Only the {product} part is cut; the rest is never cut.
The text outside {product}1 to 15 characters, counting a space next to {product}. Capital letters A to Z, digits 0 to 9 and single spaces only. No *, and no payment company's name.
{product}Exactly once, in lower case, with the braces.
The per-charge valueAt most 128 characters as sent, and at least 5 after cleaning. No email address, phone number, web address or payment company's name, and none of < > \ ' " *. Other symbols become spaces.

Cleaning turns every character that is not a letter, a digit or a space into a space, and runs of spaces into one. Case is kept. ACME {product} with Glow-Serum prints ACME Glow Serum.

If the per-charge value breaks a rule, your business name fills the slot instead. If that is under 5 characters after cleaning, the plain name is sent.

GET /v1/descriptor_config returns the pattern as dynamic_name_pattern. It returns null when no pattern is set, or when the stored one is not one that charges use.

Confirming what was sent​

Every POST /v1/payment_intents response includes a resolved_descriptor object so your integration can confirm exactly what was applied — no dashboard or database access needed.

A payment made on a checkout session returns no resolved_descriptor; confirm its descriptor at your processor.

  • When a descriptor was applied, resolved_descriptor echoes what was dispatched. Read it to see the exact tail that was sent, after truncation. It records what was sent, not what the bank printed.

    kind tells you which of two applied shapes you got, and it never names a payment provider. Branch on these three values only:

    kindShapeMeaning
    suffix{ kind, suffix }A dynamic tail appended to the descriptor prefix registered on your processing account.
    descriptor{ kind, descriptor: { name, description, city, country, phoneNumber, url, postalCode } }A full descriptor block sent with the charge.
    skipped{ kind, reason }Nothing was applied. See the reasons below.
  • When nothing was applied, it's a skipped record naming the reason. The charge then falls back to your processor's own default statement descriptor:

{
"resolved_descriptor": {
"kind": "skipped",
"reason": "no_config"
}
}

Why a descriptor was skipped​

Four reasons reach you:

reasonWhat happenedWhat to do
no_configNo descriptor was sent for this charge.If your account has no descriptor configured, ask your Von Payments contact to set one up. Otherwise see the caution below: this reason also covers a transient lookup failure and a configuration that produced nothing for this charge.
kill_switchDescriptor passthrough is switched off platform-wide.Nothing on your side. Charges still succeed; they carry your processor's default descriptor until it is switched back on.
binder_unsupportedThe processor connection your account uses does not accept a descriptor from us today.Nothing on your side — this is a property of the connection, not of your configuration.
invalid_for_providerYour configured descriptor breaks a length or format limit the processor enforces (for example a name shorter than 5 characters). The charge went through without it, so your account's default descriptor applies.Ask your Von Payments contact to correct the descriptor; it is applied again from the next charge after that.

On a structured-descriptor connection, an optional field (description, city, country, phoneNumber, url, postalCode) that breaks a processor limit is dropped on its own and the rest of the descriptor, including your name, still goes out. The usual case is a per-charge description that resolves to a short order number. That is not a skip: resolved_descriptor reads kind: "descriptor" and simply lacks the field. Compare it with your configuration to spot one.

no_config does not always mean "you have not configured one." It means no descriptor was sent, for one of three reasons that report identically:

  • the account has no descriptor configured;
  • the configuration read failed (it never fails the charge, which proceeds without a descriptor);
  • on a connection that appends a dynamic suffix, the configuration was read but resolved to an empty suffix for this charge, so the connection's default applies.

On an account with a descriptor configured, no_config is not a sign that the configuration was lost; do not re-create it on the strength of this value.

Descriptor passthrough is resolved only on a real processor connection, so verify a descriptor with a live key, or on a sandbox account with its own processor test account. A merchant account's test key cannot take a test payment (sandbox_account_required).

The SDK types and the contract also list a fourth value, circuit_open. No API response returns it today: on POST /v1/payment_intents, the one response that carries resolved_descriptor, a configuration read failure reports no_config. Do not write a branch that waits for it.