> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revolv3.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dynamic Descriptor Guide

> Customize what appears on customer credit card statements using dynamic descriptors. Reduce chargebacks and improve customer recognition of charges.

## What is a Statement Descriptor?

A **statement descriptor** (also called a "merchant descriptor") is the text that appears on a customer's credit card or bank statement describing the charge. It's what customers see when they review their statements.

**Why it matters:**

* **Customer recognition**: Customers can easily identify your charges
* **Reduces chargebacks**: Clear descriptors reduce "I don't recognize this charge" disputes
* **Brand awareness**: Customers see your business name
* **Support**: Easier for customers to find charges when contacting support

**Example**: Instead of seeing "REVOLV3" or a processor name, customers see "ACME STORE - ORDER #12345" which is much clearer.

## Static vs Dynamic Descriptors

### Static Descriptor

A **static descriptor** is the same for all transactions. It's simple to set up but less flexible.

**When to use:**

* Single product or service
* No need for transaction-specific information
* Simple setup preferred

**Example**: All charges show "ACME STORE"

### Dynamic Descriptor

A **dynamic descriptor** can be customized for each transaction, showing specific information like order numbers, product names, or locations.

**When to use:**

* Multiple products or services
* Want to show order numbers or transaction details
* Need location-specific information (for multi-location businesses)
* Payment facilitator (showing sub-merchant information)

**Example**: Charges show "ACME STORE - ORDER #12345" or "ACME STORE OAKLAND"

## Important: Configuration Required

<Warning>
  **Special configuration is required** to use static or dynamic descriptors. Contact Revolv3 Support to enable this feature for your account.
</Warning>

You cannot use dynamic descriptors without Revolv3 enabling it first. Contact support to:

* Enable descriptor customization
* Configure which processors support it
* Set up any required merchant settings

## Static Descriptor

### What It Is

A **static descriptor** shows the same text on every customer statement. It's the simplest option.

### Processor Support

<Info>
  **Important clarification**: Every payment processor supports static descriptors in some form, since statements must show something. Usually this is your legal or DBA (Doing Business As) name, which can be configured with the processor directly.

  Revolv3 also provides the ability to configure static descriptors through our portal, but this is only available for certain processors.
</Info>

**Static descriptors can be configured in the Revolv3 Portal for:**

* WorldPay
* Nuvei
* Adyen
* Paymentech
* PaymentLync

For other processors, configure static descriptors directly with the processor.

### How to Set Up

1. Contact Revolv3 Support to enable static descriptors
2. Configure in the Revolv3 Portal (Merchant Settings)
3. Set your business name or DBA name
4. All future transactions will use this descriptor

## Dynamic Descriptor

### What It Is

A **dynamic descriptor** lets you customize the statement text for each transaction. You can include:

* Order numbers
* Product names
* Location information
* Sub-merchant information (for payment facilitators)

### Why Use Dynamic Descriptors

**Benefits:**

* **Better customer recognition**: "ACME STORE - ORDER #12345" is clearer than just "ACME STORE"
* **Reduced chargebacks**: Customers can easily identify charges
* **Support efficiency**: Customers can reference order numbers when calling support
* **Multi-location businesses**: Show which location processed the charge

**Example scenarios:**

* E-commerce: "STORE - ORDER #12345"
* Restaurant: "RESTAURANT - LOCATION OAKLAND"
* Subscription: "SERVICE - MONTHLY PLAN"
* Payment facilitator: "MARKETPLACE - SELLER NAME"

### Dynamic Descriptor Object

Include this object in your API request to set a dynamic descriptor:

<CodeGroup>
  ```bash bash theme={null}
  {
    "DynamicDescriptor": {
      "SubMerchantId": "98765",
      "SubMerchantName": "Test",
      "SubMerchantPhone": "408-555-1212",
      "CountryCode": "US",
      "City": "Oakland"
    }
  }
  ```
</CodeGroup>

### Dynamic Descriptor Fields

All fields are optional. Include only what you need.

| Field              | Description                                                                             | Example                                  |
| ------------------ | --------------------------------------------------------------------------------------- | ---------------------------------------- |
| `SubMerchantId`    | Your internal merchant/sub-merchant ID. Sent to the card network.                       | `"98765"`                                |
| `SubMerchantName`  | The merchant name as displayed on the customer's statement. This is what customers see. | `"ACME STORE"` or `"ACME - ORDER #123"`  |
| `SubMerchantPhone` | Contact information (phone or email) displayed on the statement.                        | `"408-555-1212"` or `"support@acme.com"` |
| `CountryCode`      | Country code (ISO format).                                                              | `"US"`, `"CA"`, `"GB"`                   |
| `City`             | City name where the transaction occurred.                                               | `"Oakland"`, `"San Francisco"`           |

### Character Limits

* **Total length**: Usually limited to 22-25 characters (varies by processor)
* **Best practice**: Keep it short and clear
* **What gets truncated**: If too long, processors may truncate the descriptor

**Tips for good descriptors:**

* Use abbreviations if needed: "ACME" instead of "ACME STORE INC"
* Include key info: Order number or location
* Test what customers see: Make a test purchase and check your statement

## Endpoints Supporting Dynamic Descriptor

You can include `DynamicDescriptor` in these endpoints:

* `POST /api/payments/sale` - One-time payment
* `POST /api/payments/sale/{paymentMethodId}` - Payment with stored method
* `POST /api/payments/capture/{paymentMethodAuthorizationId}` - Capture authorized payment
* `POST /api/payments/authorization` - Authorize payment
* `POST /api/payments/authorization/{paymentMethodId}` - Authorize with stored method

> **Note**: The endpoint `/api/invoices/payment` is obsolete and should not be used.

## Processor Support for Dynamic Descriptors

Dynamic descriptors are supported by:

* WorldPay
* Nuvei
* Paymentech
* PaymentLync

**What this means:**

* If your request includes `DynamicDescriptor` and you're using a supported processor, the descriptor will be used
* If you're using an unsupported processor, the descriptor will be ignored (no error, it just won't be used)
* Check with Revolv3 which processors you're using

## Real-World Examples

### Example 1: E-Commerce with Order Numbers

**Goal**: Show order number on statement

**Request**:

```json theme={null}
{
  "DynamicDescriptor": {
    "SubMerchantName": "ACME - ORDER #12345"
  },
  "Invoice": {
    "MerchantInvoiceRefId": "12345",
    "Amount": { "value": 99.99 }
  }
}
```

**Customer sees**: "ACME - ORDER #12345" on their statement

### Example 2: Multi-Location Business

**Goal**: Show which location processed the charge

**Request**:

```json theme={null}
{
  "DynamicDescriptor": {
    "SubMerchantName": "ACME STORE",
    "City": "Oakland"
  }
}
```

**Customer sees**: "ACME STORE OAKLAND" (format may vary by processor)

### Example 3: Payment Facilitator

**Goal**: Show sub-merchant information

**Request**:

```json theme={null}
{
  "DynamicDescriptor": {
    "SubMerchantId": "SELLER-123",
    "SubMerchantName": "MARKETPLACE - SELLER",
    "SubMerchantPhone": "support@marketplace.com"
  }
}
```

**Customer sees**: Marketplace and seller information

## Best Practices

1. **Keep it short**: Descriptors are limited to \~22-25 characters
2. **Be descriptive**: Include order numbers or key identifiers
3. **Test it**: Make a test purchase and check what appears on the statement
4. **Be consistent**: Use the same format across transactions
5. **Include contact info**: Add phone or email so customers can reach you
6. **Consider your brand**: Use your recognizable business name

## Common Questions

**Q: Do I need to enable this feature?**
A: Yes, contact Revolv3 Support to enable dynamic descriptors for your account.

**Q: Will it work with all processors?**
A: No, only certain processors support dynamic descriptors. Check with Revolv3 which processors you're using.

**Q: What if my descriptor is too long?**
A: Processors will truncate it. Keep it under 22-25 characters to be safe.

**Q: Can I use both static and dynamic?**
A: Typically you use one or the other. Dynamic overrides static when provided.

**Q: What if I don't provide a descriptor?**
A: The processor's default descriptor will be used (usually your legal/DBA name).

## Next Steps

* **[Make a Payment](/docs/getting-started/make-a-payment)** — See how to include descriptors in payment requests
* **[Authorizations & Captures](/docs/integration-flows/authorizations-captures)** — Use descriptors with authorization/capture flows
* Contact Revolv3 Support to enable dynamic descriptors for your account

***