Statement descriptors

Every payment and payout carries a line for the statement it lands on. Tuppence sets all of them with no setup, from the business’s name. A business can change its own, and a platform can set them for its connected accounts.

Line	Where it shows	Default (business “Bella’s Barks”)
Card payments	The cardholder’s card statement	TUPPENCE* BELLAS BARKS
Other payments	The payer’s bank statement for a bank debit and other non-card payments	TUPPENCE BELLAS BARKS
Payouts	The business’s own bank statement, when it is paid	TUPPENCE

A card line is the prefix, * , then the card statement name: at most 22 characters in all. Cardholders dispute payments they don’t recognise, so the business’s own name is the default.

Which line wins

Scroll sideways to see all of it →

The other-payments line always starts with the prefix that applies: BELLA CAKES set as the line reads TUPPENCE BELLA CAKES under the TUPPENCE prefix.

1. Change a business’s own lines

POST /v1/account, or the dashboard’s Settings → Statements, which previews each line as printed. null puts a line back to its default.

curl https://api.tuppence.ai/v1/account \
  -H "Authorization: Bearer $TUPPENCE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"settings": {
        "card_payments": {"statement_descriptor_suffix": "BELLA CAKES"},
        "payouts": {"statement_descriptor": "BELLA PAYOUT"}
      }}'

Field	Line	Who can set it
settings.card_payments.statement_descriptor_prefix	The card prefix	A business that isn’t part of a platform. A platform’s connected account gets 403 managed_by_platform
settings.card_payments.statement_descriptor_suffix	The card statement name	The business
settings.payments.statement_descriptor	Other payments	The business
settings.payouts.statement_descriptor	Payouts	The business

The account object answers with every line as resolved, and settings.statement_descriptors:

Field	What it is
card_line	A card statement as printed, for example TUPPENCE* BELLA CAKES
prefix, suffix, full, payouts	Each line
suffix_max	The most characters a card statement name can have after this prefix
sources	For each line: account, platform or default
locked	true when the business’s platform manages its lines
prefix_editable	Whether the business can set its own prefix

2. Name one payment

statement_descriptor_suffix on POST /v1/payments replaces the card statement name for that payment only: TUPPENCE* SPRING SALE. It can be at most suffix_max characters (12 after TUPPENCE* ). See Payments.

3. Set them as a platform

Your defaults for every connected account, in settings.connect.defaults on POST /v1/account or the dashboard’s Settings → Platform. A change reaches every account within minutes.

Field	What it sets
defaults.statement_descriptor_prefix	Your accounts’ card prefix: ACMEPAY reads ACMEPAY* BELLAS BARKS. null: TUPPENCE
defaults.payout_statement_descriptor	Your accounts’ payout line. null: TUPPENCE
defaults.statement_descriptors_locked	true: only you can change your accounts’ lines. Their own changes get 403 managed_by_platform

One account’s lines, on POST /v1/accounts/{id}: the same four fields as above, the prefix included. Your own changes are never refused, locked or not. Turning the lock on keeps lines an account set already; set them again to change them.

Limits

Rule	Limit
Characters	Letters, digits, spaces and . , - & / #, with at least one letter. Upper case on the statement
Prefix	2 to 10 characters
Card line	22 characters in all: prefix, * and the card statement name
Other payments and payouts	5 to 22 characters
How often	10 changes a day per account. The next gets 429 rate_limited

A card statement name that a longer prefix no longer fits is cut at a word, never refused. Some banks show fewer than 22 characters. A line that shares no word with the business’s names is allowed and flagged for Tuppence’s review.

Next

• Payments: take a payment, and name it on the statement.
• Platform settings: the rest of your defaults.
• Payouts and settlement: when the payout line appears.