Transaction Descriptors

A transaction descriptor is meant to describe a transaction in order to help your customer easily recognize the transaction.

Chargebee provides you with the option of adding the transaction descriptor that will appear on your customers' card/bank statements. However, the customer's bank will decide how these descriptors appear on the bank statement. This means, the bank can decide on the number of characters, capitalization of letters and words, and so on.

Additionally, the gateway you use may have several rules and restrictions about the descriptors that they pass on. The character limitations imposed by the various payment gateways we support, are as below:

• Checkout.com
• GoCardless
• Stripe
• Braintree
• Spreedly
• PayPal Express Checkout
• PayPal Commerce
• Amazon Payments
• Adyen
• Ingenico
• Mollie
• Global Payments
• Pay.com
• NMI
• dLocal via payFURL
• Worldpay US eCom (formerly called Vantiv)

Configure Transaction Descriptor

A Transaction descriptor added is applicable for every gateway in your Chargebee site.

Via the Chargebee Site

To configure the transaction descriptor from the Chargebee site, navigate to Settings > Configure Chargebee > Payment Gateways > Add a Descriptor

You can add a descriptor in the dialog box that opens.

Additionally, you can choose to pass Invoice ID, Plan Name, Customer ID, or Subscription ID along with the descriptor. Copy and paste the merge vars tag that you would like to use next to the descriptor.

Here, the plan.name merge var will contain the value of the Invoice Name field that you add while creating a new plan.

Via API

In situations involving multiple products or plans, a one-size-fits-all description is inadequate, and the customization of descriptors becomes crucial for business. Dynamic descriptors allow you to provide specific and clear information about each transaction, reducing ambiguity for customers and minimizing the likelihood of chargebacks.

You can tailor descriptors to include relevant details, such as product names or unique identifiers, making it easier for customers to recognize and remember their purchases. You have the option to configure a dynamic descriptor on your Chargebee site, which would be transmitted for every transaction. However, it is now also possible to selectively send them using the following APIs:

• create_subscription_for_item
• create_invoice_for_items_and_one-time_charges
• update_invoice_details
• update_subscription_for_items

You can pass the parameter called statement_descriptor in any of these APIs which will override the descriptor you have set on your Chargebee site.

GoCardless

BACS

Alphanumeric (A-Z, a-z, 0-9) string; characters allowed:

• space
• ampersand (&)
• hyphen (-)
• period (.)
• solidus (/)

Maximum no. of characters allowed: 10 characters

SEPA

Alphanumeric(A-Z, a-z, 0-9) string; characters allowed:

• space
• period (.)
• hyphen (-)
• solidus (/)
• question mark (?)
• colon (:)
• left parenthesis [ ( ]
• right parenthesis [ ) ]
• comma (,)
• plus sign (+)
• single quote (')

Maximum no. of characters allowed: 140 characters

BECS

Alphanumeric (A-Z, a-z, 0-9) string; characters allowed:

• space
• plus sign (+)
• at (@)
• esclamation mark (!)
• circumflex (^)
• dollar sign ($)
• percentage symbol (%)
• ampersand (&)
• single quote (')
• parentheses
• asterisk (*)
• hyphen (-)
• colon (:)
• semicolon (;)
• equal sign (=)
• question mark (?)
• period (.)
• hash sign (#)
• underscore (_)
• comma (,)
• square brackets
• solidus (/)

Maximum no. of characters allowed: 30 characters

Autogiro

Alphanumeric (A-Z, a-z, 0-9) string; characters allowed:

• space
• esclamation mark (!)
• double quote (")
• hash sign (#)
• dollar sign ($)
• percentage symbol (%)
• ampersand (&)
• single quote (')
• parentheses
• asterisk (*)
• plus (+)
• comma (,)
• hyphen (-)
• period (.)
• solidus (/)
• colon (:)
• semicolon (;)
• lesser than and greater than symbols ( < and >)
• equal sign (=)
• question mark (?)

Maximum no. of characters allowed: 11 characters

Stripe

The statement descriptor for Stripe must meet the following requirements:

• Contains only Latin characters.
• Contains between 5 and 22 characters, inclusive.
• Contains at least one letter (if using a prefix and a suffix, both require at least one letter).
• Doesn't contain any of the following special characters: <, >, \, ' " *.
• Reflects your Doing Business As (DBA) name.
• Contains more than a single common term or common website URL. A website URL only is acceptable if it provides a clear and accurate description of a transaction on a customer's statement.

Braintree

Format: < DBA > * < Product Descriptor >.

• Company name/DBA(doing business as) section must be either 3, 7 or 12 characters product descriptor can be up to 18, 14, or 9 characters respectively (with an * in between for a total descriptor name of 22 characters)
• Alphanumeric (A-Z, a-z, 0-9) string; characters allowed:
  • period (.)
  • plus sign (+)
  • hyphen (-)

Spreedly

• Spreedly supports transaction descriptors only for Bambora, Pin, PayPal Pro, Orbital, BlueSnap, and CyberSource.
• There is no character limit set by Spreedly but gateway specific limitations will be applicable.
• Shown in Chargebee as merchant-name-descriptor.
• Chargebee will truncate the descriptor if it exceeds 140 characters.

PayPal Express Checkout

Format of the descriptor:

< PP *|PAYPAL * > < Merchant descriptor present in gateway > < 1 space > < soft descriptor >

Character length and limitations:

• The alphanumeric soft descriptor can contain only the following characters:

  • hyphen (-)
  • asterisk (*)
  • period (.)
  • space (" ")

• The maximum number of characters allowed is 22 characters. Of this, the PayPal prefix uses 4 or 8 characters of the data format.

PayPal Commerce

The maximum number of characters allowed for soft descriptor via API is 30.

Amazon Payments

The soft descriptor sent to the payment processor is: "AMZ* < soft descriptor specified here >".

Default format: "AMZ* < SELLER_NAME > amzn.com/pmts WA"

Maximum no. of characters allowed: 16 characters

Adyen

No limitations. Chargebee will truncate the descriptor if it exceeds 140 characters.

Checkout.com

The maximum number of characters allowed is 25.

You can use the following characters in your descriptor:

• Uppercase: A-Z
• Lowercase: a-z
• Numbers: 0-9
• Special characters: . ! * - = _

Ingenico

Character restrictions:

• Maximum no. of characters allowed: 22 characters, any characters beyond maybe truncated and the truncated value maybe sent to the bank.
• lesser than and greater than symbols ( < and >)
• double quote (")
• single quote (')

Mollie

The maximum number of characters allowed is 140.

Global Payments

Alphanumeric (A-Z, a-z, 0-9) string Maximum number of characters allowed: 17 characters

Pay.com

The maximum number of characters allowed is 22.

NMI

• Make sure you enable Dynamic Billing Descriptors in NMI. Learn more about NMI's advanced merchant features for the supported processors.
• By default, Chargebee does not send descriptors to NMI as it can lead to payment disruptions with the error "Custom descriptors are not allowed for this processor". Contact support to enable statement descriptors for NMI in Chargebee.

dLocal via payFURL

Chargebee supports Statement Descriptors for dLocal transactions. dLocal enforces a character limit of 22 characters for these descriptors.

Allowed special characters are:

• hyphen(-)
• underscore(_)
• comma(,)
• dot (.)
• space
• forward slash (/)
• ampersand (&)
• asterisk (*)

Worldpay US eCom (formerly called Vantiv)

Chargebee supports Statement Descriptors for transactions via Worldpay US eCom. Worldpay US eCom enforces the following character limits for descriptors:

• The minimum number of characters allowed is 4.
• The maximum number of characters allowed is 25.

Alphanumeric (A-Z, a-z, 0-9) string; characters allowed:

• Space
• Asterisk (*)
• Comma (,)
• Hyphen (-)
• Quotation (')
• Hash sign (#)
• Ampersand (&)
• Period (.)