Statement Descriptor

Contents

Overview

The Statement Descriptor controls how a payment appears on a customer's bank or card statement. A clear descriptor helps customers recognize transactions and reduces the likelihood of disputes or chargebacks.

In the application, the Statement Descriptor is dynamically populated using a custom field configured on the Payment object. When a payment is created, the value from the selected custom field is passed to the payment gateway (for example, Stripe) as the statement_descriptor.

This descriptor helps customers identify the merchant responsible for the charge when reviewing their bank or card statements. Payment gateways such as Stripe allow merchants to pass a custom value for this descriptor through their APIs.

How Statement Descriptor Works

The system allows you to configure a custom field whose value will be used as the statement descriptor.

Workflow

1. Configure a Statement Descriptor field mapping in Setup → Settings.
   
2. The mapping references a custom field on the Payment object.
   
3. When a payment is created:
   • The system retrieves the value from the configured custom field.
   • This value becomes the statement descriptor.
4. During payment processing, the value is sent to the payment gateway API.
5. The payment gateway displays the descriptor on the customer's bank statement.

Create a Custom Field

Create a custom field that will store the statement descriptor value.

1. Navigate to Setup → Customize.
2. Create a new Text-type custom field.
   

Example

For more information about creating custom fields, refer to Manage Custom Fields – Ordway Support Portal. 

Configure Statement Descriptor Field

You must configure which custom field will be used as the Statement Descriptor.

Steps

1. In the left navigation menu, click Setup → Settings. The Settings page is displayed.
2. Under the Payments section, locate the Statement Descriptor.
   
3. Select a custom field from the drop-down list.
4. Click Save to update the configuration.

Result

Once configured:

• The selected custom field becomes the source for the statement descriptor value.
• The field is automatically available when creating a payment.
• The value entered in the field will be sent to the payment gateway as the statement descriptor.

Create a Payment with Statement Descriptor

When creating a payment, the configured custom field determines the descriptor sent to the payment gateway.

Steps

1. Select a Customer from Customer Accounts page.
   
2. In the customer details page, under the More Details section, click Payments. 
   
3. Click Add. The New Payment page is displayed.   For more details, refer to Create a Payment for an Account – Ordway Support Portal
4. Locate the configured custom field.
   
5. Enter or modify the value if required.
6. Confirm the payment.

Behavior

When the payment is processed:

• The system reads the value of the configured custom field.
• The payment gateway displays this value on the customer's bank statement. 
• The value is passed to the payment gateway as the statement descriptor.
  

Using Formula Fields for Statement Descriptor

You can configure a Formula custom field to dynamically generate the value used as the statement descriptor.

A formula field allows you to construct the descriptor using predefined text combined with dynamic values, such as the Payment ID, Invoice ID, or other available fields.

This is particularly useful during Payment Runs, where multiple payments are generated automatically. A formula-based descriptor ensures that each payment receives a unique and identifiable statement descriptor without requiring manual input.

For example, you can configure a formula to concatenate a fixed prefix with the payment identifier.

Example Formula

Example Result

When this formula field is mapped as the Statement Descriptor field, the generated value is automatically sent to the payment gateway during payment processing.

Configure a Formula Field for Statement Descriptor

Follow these steps to configure a formula field for use as a statement descriptor.

Step 1: Create a Formula Custom Field

1. Navigate to Setup → Customize → Payments.
   
2. Click Add Custom Field.
3. Select Formula as the field type.
4. Define the formula using supported functions (for example, CONCAT). 

For more details, see Manage Custom Fields

Step 2: Configure the Statement Descriptor Field

1. Navigate to Setup → Settings → Statement Descriptor.
   
2. Select the created Formula Custom Field from the dropdown list.
3. Click Save to apply the configuration.

Step 3: Create a Payment

1. Navigate to Customer Accounts → More Details → Payments.
   
2. Click ADD.
3. Enter the required payment details.
4. Click SAVE.
5. When a payment is created, the system evaluates the formula and dynamically generates the statement descriptor.
   

For more details, see Create Payment Run

Gateway Behavior (Stripe)

When the payment is processed through Stripe:

• The generated value is sent to Stripe as the statement_descriptor parameter.
• The descriptor appears in:
  • The Stripe Dashboard
  • The customer's bank or card statement
    

Default Behavior

The statement descriptor configuration is optional. If no descriptor value is passed:

• Stripe automatically uses the default business descriptor configured in the Stripe account settings.
  

Gateway Integration - Stripe 

When the payment is processed via Stripe, the value of the configured custom field is sent as the statement_descriptor parameter.

Example API payload

API Usage - Create Payment

When creating a payment through the API, the client must include the configured custom field.

Example Request: POST /payments

Example Response

Limitations

Current limitations include:

• Only Text, inherited, and formula custom fields are supported.
• Statement descriptor length restrictions depend on the payment gateway.

Custom Field Requirements

• The custom field must exist on the Payment object.
• The field value can be a maximum of 22 characters in length.
• If a value longer than 22 characters is provided, it will be automatically trimmed to 22 characters.
• Special characters allowed
  • underscore (_)
  • hyphen (-)

Best Practices

Use clear and recognizable descriptors to reduce payment disputes.

Recommended practices:

• Include your business or product name
• Avoid generic values
• Keep descriptors short and identifiable

Troubleshooting

Descriptor Not Appearing in Gateway, the Possible causes and resolutions: