# Manage billing descriptors

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 required 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. <br>
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 TIRES`
    - `THE 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.

---

## Change a static billing descriptor

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 start, ensure your user has the `View and manage billing descriptors` permission.

1. Sign in to the [Dashboard](https://dashboard.checkout.com/).
2. Select the _Settings menu_ in the top navigation bar, and then select _Settings_.
3. Under _Business settings_, select _Billing descriptors_.
4. Select the processing channel for which you want to edit the static billing descriptor.
5. In the _Manage billing descriptor_ page, select _Change_. <br>
    - 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.
6. Under _New billing descriptor_, enter the new static billing descriptor.
7. When you've finished updating your billing descriptor, select _Change_.

The billing descriptor for that processing channel updates instantly.

---

## Enable a dynamic billing descriptor

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 start, ensure your user has the `View and manage billing descriptors` permission.

1. Sign in to the [Dashboard](https://dashboard.checkout.com/).
2. Select the _Settings menu_ in the top navigation bar, and then select _Settings_.
3. Under _Business settings_, select _Billing descriptors_.
4. Select the processing channel you want to enable the dynamic billing descriptor for.
5. 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.
6. 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 (`*`). <br>
    For example – `TOR*THE ONLINE RETAILER BIKE TIRES`
7. Provide a rationale for this change.
8. Select _Submit_.

You receive a confirmation email.

### Change the prefix

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 start, ensure your user has the `View and manage billing descriptors` permission.

1. Sign in to the [Dashboard](https://dashboard.checkout.com/).
2. Select the _Settings menu_ in the top navigation bar, and then select _Settings_.
3. Under _Business settings_, select _Billing descriptors_.
4. Select the processing channel you want to enable the dynamic billing descriptor for.
5. In the _Dynamic billing descriptor_ section, select _Enable_.
6. Under _Prefix_, enter the prefix for your billing descriptor.
7. Provide a rationale for this change.
8. Select _Submit_.

---

## Configure a dynamic billing descriptor

After enabling dynamic billing descriptors, you can add the `billing_descriptor` object to your payment request:

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payments`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments`

#### Request example

```json
{
  "source": {
    "type": "token",
    "token": "tok_4gzeau5o2uqubbk6fufs3m7p54"
  },
  "amount": 100,
  "currency": "USD",
  "billing_descriptor": {
    "name": "The Online Retailer",
    "city": "Anytown",
    "reference": "ORD-123A"
  }
}
```

#### Response example

```json
{
  "id": "pay_mbabizu24mvu3mela5njyhpit4",
  "action_id": "act_mbabizu24mvu3mela5njyhpit4",
  "amount": 100,
  "currency": "USD",
  "approved": true,
  "status": "Authorized",
  "billing_descriptor": {
    "name": "The Online Retailer",
    "city": "Anytown",
    "reference": "ORD-123A"
  },
  "response_code": "10000"
}
```

> **Information**
>
> Do not use `#` in your descriptor fields because this causes a validation error.

### Dynamic billing descriptors for Japanese transactions

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<br><br>Can include Roman and katakana characters | Full width | `Ｃｈｅｃｋｏｕｔ日本` |

### Request example

```json
{
  "source": {
    "type": "token",
    "token": "tok_4gzeau5o2uqubbk6fufs3m7p54"
  },
  "amount": 100,
  "currency": "USD",
  "billing_descriptor": {
    "name": "Checkout.com",
    "city": "London",
    "reference": "ORD-123A",
    "local_descriptors": [
      {
        "name": "Ｃｈｅｃｋｏｕｔ日本",
        "character_set": "kanji"
      },
      {
        "name": "チェックアウトニホン",
        "character_set": "katakana"
      }
    ]
  }
}
```