HomeProduct DocsAPI ReferenceChangelog
RecurlyAPI GuidesRecurly.jsWebhooksAPI ReferenceSupportBook demo
Product Docs
RecurlyAPI GuidesRecurly.jsWebhooksAPI ReferenceSupportBook demo

Payment descriptors

Configure dynamic payment descriptors in Recurly to display your business name and charge details on customer bank statements — reducing friendly chargebacks and improving transparency.

Dynamic descriptors let merchants control the text that appears on a customer's bank statement alongside a charge — showing your business name and a recognizable description of what was purchased. Recurly builds descriptors automatically from your DBA and plan or invoice data.
Available on all Recurly plans
1Definition 2Key benefits 3Key details

Prerequisites

  • Visa trial descriptors — Supported on all card-supporting gateways. Recurly adds the word "Trial" to any Visa transaction converting after a trial period.
  • Descriptors beyond Visa trial (feature flag required) — Contact Recurly Support or your account manager to enable: Stripe, Braintree.
  • Dynamic descriptors (no flag required) — Supported automatically on: Commerce Hub, FreedomPay, Checkout.com, Nuvei.

Limitations

  • Descriptors cannot be modified via the API — the only exception is sending a unique invoice description.
  • The descriptor prefix cannot be modified for Stripe from within Recurly — it must be set at the gateway level. Only the suffix (plan name or invoice description) is sent to Stripe.
  • Braintree prefixes must be 3, 7, or 12 characters. If your DBA doesn't meet these limits, it will be padded with spaces where possible.
  • Braintree descriptor support is limited to cards and PayPal.
  • Stripe descriptor support is limited to cards, Apple Pay, Google Pay, and network tokens.
  • While Recurly sends dynamic descriptors to gateways, gateways may not pass them on to card networks, and issuers have final say on descriptor display. Contact your gateway to confirm descriptor support for your merchant account.
  • Only the Default Business Entity is used for prefix information. Dynamic Business Entity support is planned.

Definition

A dynamic descriptor (also called a soft descriptor) is customizable text included with a card transaction that appears on the customer's bank statement. It helps customers recognize charges from your business and reduces friendly chargebacks caused by unrecognizable transactions.

Descriptors are typically limited to 22 characters and follow the format:

DBA*Description of Charge (Suffix)

More specifically, a descriptor is two parts joined by a separator (usually an asterisk):

Prefix*Suffix — where the prefix is the DBA from your business entity, and the suffix is either a custom field sent via API or derived from your plan name or invoice description.

Recurly builds descriptors as follows:

  • Subscriptions — Uses your company name or DBA as the prefix and the plan name as the suffix. For Visa transactions converting from a trial, "Trial" is added. Example: AcmeInc*Trial Gold Plan
  • One-time transactions and invoices without plans — Uses your company name or DBA as the prefix and the invoice description as the suffix. Examples: AcmeInc*Charge or AcmeInc*One-Time Payment

Key benefits

Chargeback reduction Clear, recognizable descriptor text reduces friendly-fraud chargebacks caused by customers not recognizing a charge on their statement.
Transparency Customers see accurate, meaningful information on their bank statement, building trust in your billing process.
Consistency Customers see the same prefix and recognizable plan or charge details every billing cycle. If your business name changes, notify existing customers to expect the update on their statements.

Key details

Supported transactions and payment methods

Supported transaction types:

  • One-time transactions
  • Initial subscription transactions and subsequent recurring transactions
  • Recurring subscription renewals
  • Recovery invoices

Supported payment methods:

Best practices

  • Keep your Company Name and DBA current in Site Settings and your Business Entity. Recurly uses DBA over Company Name for descriptor prefixes when both are present. Update these fields whenever your business name changes.
  • Name plans something customers will recognize on their bank statement. The first ~22 characters of the plan name are most important — make them immediately identifiable.
  • Always add an Invoice Description to one-time charges. Use something recognizable to the customer — order numbers work well. If no description is provided, Recurly fills in "Charge" as the suffix.
  • Confirm that dynamic descriptors are enabled at your gateway. Some gateways require a setting or feature flag to pass descriptor data.