If you sell several brands or products from one gateway account, every charge used to show the same name on your customers' card statements. A customer who cannot tell which purchase a line belongs to is more likely to dispute it. You can now choose the text yourself, per product, per collection, or once for your whole company, and Flo sends it with every charge it creates.
How the statement text is built
The text a customer sees has two parts: your gateway prefix, then the statement descriptor you save in Flo, joined by an asterisk and a space. With the prefix ACMEGOODS and the descriptor PREMIUM BOX, the statement reads ACMEGOODS* PREMIUM BOX.
The whole text has a budget of 22 characters. When a descriptor is too long, Flo shortens the descriptor at charge time and always keeps your prefix whole, so your brand is never cut.
Three levels, one value per charge
Save a descriptor on a product, on a collection, or on your company. For each charge Flo picks one value:
- Product, when every product in the charge has the same product descriptor.
- Collection, when the collections that contain every product in the charge agree on one value.
- Company, for every other charge.
- Nothing, when no level has a value. The charge goes out exactly as it did before.
A basket that mixes products with different descriptors, or with and without one, falls back to the collection or company value. Flo works the value out again for every new charge from your current settings, so a change you save applies to the next renewal without touching existing subscriptions.
On every charge Flo creates
Stripe. The descriptor is sent on every card and wallet charge: first checkout payments, upsells, saved-card purchases, subscription renewals, dunning retries, one-off charges, and manual captures. The prefix is the shortened descriptor on your Stripe account. You set it in the Stripe Dashboard, and Flo reads it each time your Stripe connection is validated. Flo never changes your Stripe settings.
Worldpay. Every Worldpay order now carries your own statement text instead of the fixed internal text Flo used to send. Set a Worldpay prefix of up to 10 characters in your gateway settings. Each order uses the first of these that applies: your prefix and descriptor, the descriptor alone, the prefix alone, or your company name. If Worldpay refuses an order because of its statement text, Flo retries it once with the next option.
Set it up in the Dashboard or the API
In the Dashboard, the Brand page holds your company descriptor, and the collection and product forms each have a descriptor field. As you type, a live preview shows the final statement text for each of your gateways and which level will win. Your gateway page shows the Stripe prefix Flo read from your account, and on Worldpay it lets you edit your prefix and shows the company-name text orders send without one. Settings > Statement descriptors lists every descriptor at company, collection, and product level in one place, each linking to where you edit it.
Through the API, send statementDescriptor on POST and PATCH for /v1/products and /v1/collections, and on PATCH /v1/company. Send null to clear a value. Changing the company value needs an OAuth access token for an owner or admin.
Warnings before your customers see it
Saving a descriptor never fails because of a warning, but the response tells you what to fix:
statementDescriptorWarningslists each gateway where your value is longer than that gateway's prefix leaves room for, with a preview of the shortened text.preDisputeAlertWarningschecks, when you use pre-dispute alerts, whether alerts for the new statement text would still be matched to you on each network you are enrolled on. A result ofunmatchedmeans you should enroll the new text with your alert provider before using it.
The Dashboard shows the same warnings after you save.
See what each payment carried
Every Stripe and Worldpay payment records the descriptor it sent, where it came from, and the final statement text. The payments API returns them as statementDescriptor, statementDescriptorLevel, and statementDescriptorFinalText, and the payment detail page in the Dashboard shows them. Payment exports can add them as columns, and they are off by default so existing exports keep their layout.
The payment object in item.purchased and the payment.* webhooks carries the same three fields, so you can match statement text to orders without an extra API call. If Flo replicates your data to your own database, the descriptor columns are included there too.
Good to know
- Nothing changes on Stripe until you save a descriptor. Worldpay is the one exception, because its orders now always carry your prefix or company name.
- A descriptor problem never fails or delays a payment. A value a gateway would reject is left off, and the charge goes through with your account's default text.
- A descriptor can be up to 18 characters, needs at least one letter, and cannot contain
<,>,\,',", or*. Stripe prints statement text in upper case. - PayPal and Stripe payment methods other than cards and wallets do not carry descriptors yet. PayPal support is in progress.
Read Show your brand on card statements for the step-by-step setup, including your Stripe shortened descriptor and the alert enrollment check, and the statement descriptors API reference for every field, validation rule, and warning.