When shoppers check their bank statements, they need to be able to easily identify the charges they see. The text that describes charges is known as a transaction description, statement descriptor, shopper statement, or billing descriptor. If shoppers do not recognize a transaction by its description:
- There is a higher chance your shopper issues a chargeback.
- You can get a fine from the relevant card scheme related to your chargeback rate.
To prevent these issues, ensure that your transaction description contains your brand or the (chain) merchant name that is most recognizable to the cardholder (as required by the card schemes), and optionally customize your transaction description.
Requirements
Before you begin, take into account the following requirements, limitations, and preparations.
Requirement | Description |
---|---|
Integration type | Any payments integration with Adyen. |
API credential roles | To customize transaction descriptions using the Management API, make sure that you have the following role:
|
Customer Area roles | To customize transaction descriptions using the Customer Area, make sure that you have one of the following roles:
|
Limitations | Take into account the following:
|
Without customization
Without customization, the transaction description consists of the Name set in your live Customer Area under Settings > Account, combined with the City and the Country/Region from your merchant account address.
The city and country/region are always added to transaction descriptions, even if you customize the description.
Customization options
To help your shoppers easily identify the payments made to your business, you can customize the transaction description by adding information. You can add either of the following:
- A Doing Business As (DBA) name: a static value that represents your business.
- A dynamic value: the transaction-specific shopper statement that is specified in the payment request.
- A combination of your DBA name followed by the shopper statement from the payment request.
If you do business in Japan, we highly recommend that you add localized shopper statements in Japanese characters.
Doing Business As (DBA) name
Your DBA name is a static value that represents your business. To add your DBA name to your transaction descriptions, you need to turn on this setting, and specify the text to use.
We recommend that you set your DBA name to the name by which your shoppers know your business.
Dynamic values
Using dynamic values, you can customize the transaction description for each of your shoppers. For example, you can add the order reference number corresponding to the payment.
To add a dynamic, transaction-specific shopper statement to your transaction descriptions, you need to turn on this setting, and specify a shopper statement in each individual payment request.
Be aware of the following:
- If you do not turn on dynamic values, the shopper statement from the payment request will not appear in your shoppers' bank statements.
- If you turn on dynamic values but do not send a shopper statement in the payment request, your DBA name will be used instead.
Combination
To add both your DBA name and a transaction-specific shopper statement to your transaction descriptions, you need to turn on this setting, specify a DBA name, and specify a shopper statement in each payment request.
With this setting, your DBA name is used as a base for the transaction description. The shopper statement defined in the payment request is appended to this description.
Customer Area or Management API
To add information to the transaction description, you can use the live Customer Area or the live Management API.
-
Using the live Customer Area, you have two options:
- You can define the same transaction description for an individual merchant account or store or for multiple accounts or stores in one go.
- Or you can upload a CSV file to define various different transaction descriptions for multiple merchant accounts and stores.
In both cases the customized transaction description is applied to transactions made using all the payment methods that support customization and that have been added to the merchant account or store.
-
Using a live Management API endpoint, you can customize the transaction description per payment method. In this way you can use different descriptions for different payment methods. Not all payment methods that are available through the Management API support customization.
A payment method-specific customization overrules the general transaction description settings from the Customer Area.
Japan
If you do business in Japan and want to set a transaction description in Japanese characters for your account, you need to contact our Support Team with the Kanji and Katakana values that you want to use. For more information, see Add localized shopper statements in Japanese characters.
Check the transaction description
In your live Customer Area you can check the transaction description that applies to your merchant account or store. Using the live Management API you can check the transaction description that applies to specific payment methods.
Customize the transaction description
When you configure the transaction description, take into account that the description can be a maximum of 22 characters including spaces for the DBA name, dynamic value, or combination. Anything exceeding that is truncated and left out. What remains is then sent along with the city and country/region.
Allowed characters:
- Lowercase and uppercase characters:
[a-z]
[A-Z]
- Numbers:
[0-9]
- Special characters:
.
,,
,'
,_
,-
,?
,+
,*
, and space.
Specify a shopper statement
If you want your transaction descriptions to contain a dynamic shopper statement, it is not enough to configure the dynamic value option or the combination option as described under Customize the transaction description. You also need to add a shopperStatement
parameter to each payment request.
- For ecommerce transactions, add a
shopperStatement
parameter to your /sessions or /payments request. - For point-of-sale transactions, pass the
shopperStatement
inside theSaleToAcquirerData
parameter of your Terminal API request.
(Optional) Add a localized transaction description
If you are in Japan, go to the Japan-specific section for instructions.
If you are active in a local market that uses a different character set, you can add a localized shopper statement. This is supported for ecommerce transactions using the /payments endpoint.
Do the following:
- Configure the dynamic value option or the combination option as described under Customize the transaction description.
- In your API request, include both the
shopperStatement
parameter and thelocalizedShopperStatement
parameter.
If you do not include alocalizedShopperStatement
or leave it empty,shopperStatement
is used.
For cross-border transactions,shopperStatement
is used.
Add localized shopper statements in Japan
For Japan, we support the following character sets, in combination with the other allowed values for transaction descriptions:
- ja-Hani (Kanji)
- ja-Kana (Katakana)
You can set what appears in the shopper statement in one of the following ways:
- Contact our Support Team with the Kanji and Katakana values that you want to set for your account.
-
In the /payments request, include the
localizedShopperStatement
parameter. Including this parameter overrides any values that are set for your account.
Character width
The width of the characters that show up on the shopper's bank statement depends on the card brand and character set:
Brand | Kanji characters | Katakana characters |
---|---|---|
Visa | Full-width | Half-width |
Mastercard | Full-width | Half-width |
JCB Includes Diners and Discover, which process through JCB. |
Full-width | Full-width |
Supported payment methods
The following sections list the payment methods that support customized transaction descriptions. If defined in the Customer Area, the customized transaction description applies to all listed payment methods. This description can be overwritten by a transaction description that has been defined using the Management API for the individual payment method.
Cards
- Cartes Bancaires
- China Union Pay (CUP)
- Diners
- Discover
- Eftpos
- Girocard
- Interac
- JCB
- Maestro
- Mastercard
- NYCE
- Pulse
- Star
- Visa
Wallets
Your transaction description configuration also applies if the shopper paid using a wallet payment method that contains one of the card brands above.
For example, if a shopper pays with Apple Pay using their Visa card, the transaction description you configured in the Customer Area will be used. Or if you used the Management API to configure a specific transaction description for Visa, that description will be used.
Other payment methods
- Bancontact (BCMC) - both card and mobile integrations
- iDEAL