Manage billing descriptors
Last updated: January 15, 2025
A billing descriptor is the explanation of a transaction or order that appears on a customer's statement to identify it. The descriptor usually includes your merchant name and registered city, but can include custom data. This helps your customers recognize transactions and reduces the likelihood of chargebacks.
You can also set up a billing descriptor prefix. A prefix is a short string of text that precedes the descriptor, and helps to further identify the transaction.
Information
Prefixes are mandatory for payment facilitators (PayFacs), as per card scheme requirements.
Billing descriptors can be static or dynamic:
- Static – A predefined combination of your company name and registered city for each of your processing channels.
For example,THE ONLINE RETAILER LONDON. - Dynamic – A custom descriptor per transaction that may include your company name, the transaction amount, and the order reference number. For example, a customer who bought bike tires from The Online Retailer would see a different billing descriptor on their statement than a customer who bought bike chains:
THE ONLINE RETAILER*BIKE TIRESTHE ONLINE RETAILER*BIKE CHAINS
The billing descriptor that you configure for your processing channel in the Dashboard is not displayed for alternative payment method (APM) payments.
During your account onboarding, you set up static billing descriptors for your different processing channels. You can edit them later in the Dashboard.
Before you begin, ensure your user has the View and manage billing descriptors permission.
- Sign in to the Dashboard.
- Select the Settings icon in the top navigation bar and open the Billing descriptors tab.
- Select the processing channel for which you want to edit the static billing descriptor.
- In the Manage billing descriptor page, select Change.
- Depending on your processing channel configuration, you may need to contact us to update your static billing descriptor. In such cases, a link to request support is displayed.
- Under New billing descriptor, enter the new static billing descriptor.
- When you've finished updating your billing descriptor, select Change.
The billing descriptor for that processing channel updates instantly.
You can enable dynamic billing descriptors per processing channel in the Dashboard. Once enabled, you can then send a custom billing descriptor when requesting a payment using the API.
Before you begin, ensure your user has the View and manage billing descriptors permission.
- Sign in to the Dashboard.
- Select the Settings icon in the top navigation bar and open the Billing descriptors tab.
- Select the processing channel you want to enable the dynamic billing descriptor for.
- In the Dynamic billing descriptor section, select Enable.
- Depending on your processing channel configuration, you may need to contact us to update your static billing descriptor. In such cases, a link to request support is displayed.
- Optionally, under Prefix, enter the prefix for your billing descriptor.
- If you're a payment facilitator, this field is required. The prefix is concatenated with your billing descriptor using an asterisk (
*).
For example –TOR*THE ONLINE RETAILER BIKE TIRES
- If you're a payment facilitator, this field is required. The prefix is concatenated with your billing descriptor using an asterisk (
- Provide a rationale for this change.
- Select Submit.
You and your organization administrators receive a confirmation email.
A billing descriptor prefix is a short string of text that precedes the billing descriptor. A prefix is required for payment facilitators, and is concatenated with the billing descriptor using an asterisk (*).
Before you begin, ensure your user has the View and manage billing descriptors permission.
- Sign in to the Dashboard.
- Select the Settings icon in the top navigation bar and open the Billing descriptors tab.
- Select the processing channel you want to enable the dynamic billing descriptor for.
- In the Dynamic billing descriptor section, select Enable.
- Under Prefix, enter the prefix for your billing descriptor.
- Provide a rationale for this change.
- Select Submit.
After enabling dynamic billing descriptors, you can add the billing_descriptor object to your payment request:
post
https://api.checkout.com/payments
Information
Do not use # in your descriptor fields because this causes a validation error.
Issuers in Japan require billing descriptors to be in both katakana and kanji characters. Card schemes like Visa and Mastercard request both character sets to process and settle domestic transactions without friction with Japanese issuers.
If you process domestic transactions in Japan, you must also provide the billing_descriptor.local_descriptors[] array in the following character sets:
- Roman characters – for example,
a,b,c - Katakana characters – either full-width or half-width kana
- Kanji characters – full-width kana only
The character set that you use determines the maximum length of the value:
- Katakana – The maximum length is 23 characters, equivalent to 23 katakana characters.
- Kanji – The maximum length is 40 characters, equivalent to 20 kanji characters.
Checkout.com strongly recommends you set up character sets in both katakana and kanji.
The following table lists example values for the billing_descriptor.local_descriptors.name field in katakana and kanji, respectively. In each example, 'Checkout Japan' is the equivalent name in Roman characters.
| Character type | Length type | Example |
|---|---|---|
Katakana | Full width |
|
Katakana | Half width |
|
Kanji Can include Roman and katakana characters | Full width |
|