Dynamic billing descriptor
Last updated: July 3, 2023
The billing descriptor is the text displayed on the customer's credit card statement, identifying a purchase from a merchant’s website. This descriptor can be set dynamically in a payment request.
Information
To enable this functionality, contact our Support team.
Field name | Description |
---|---|
optional object | The billing descriptor's details. |
required string | The dynamic description of the charge. Up to 25 characters Allowed characters:
|
optional string | If you process domestic transactions in Japan, you need to provide this field in:
The character set specified will determine the maximum length of the field. For katakana, the maximum length is 23 characters, equivalent to 23 katakana characters. For kanji, the maximum length is 40 characters, equivalent to 20 kanji characters. For Mastercard, it is mandatory to provide the character set in kanji characters. For Visa, this is optional. However, Checkout.com strongly recommends that you provide character sets for these schemes in both katakana and kanji. Learn more about katakana and kanji descriptor values. |
required string | The city the charge originated in. Up to 13 characters Allowed characters:
|
1{2"billing_descriptor": {3"name": "Checkout.com",4"city": "London",5"reference": "ORD-123A"6}7}
Note
Do not use #
in your descriptor as this will cause a validation error.
The katakana and kanji descriptor values are required by issuers in Japan. Schemes like Visa and Mastercard request both values so they can process and settle domestic transactions without friction with the Japanese issuers.
The following table lists some example values for the billing_descriptor.name
field in katakana and kanji, respectively. In each example, ‘Checkout Japan’ is the equivalent name in Latin characters.
Character type | Length type | Example |
---|---|---|
katakana | Full width |
|
katakana | Half width |
|
kanji (may include Latin and katakana characters) | Full width |
|
1{2"billing_descriptor": {3"name": "Checkout.com",4"city": "London",5"reference": "ORD-123A",6"local_descriptors": [7{8"name": "Checkout日本",9"character_set": "kanji"10},11{12"name": "チェックアウトニホン",13"character_set": "katakana"14}15]16}17}