Custom Descriptors

Control what appears on bank statements with custom transaction descriptors

Custom descriptors allow you to control the text that appears on customer and merchant bank statements for transactions. Set explicit descriptors on individual transactions or configure default descriptors with template variables in your processing settings. Descriptors help customers identify charges, reduce chargebacks, maintain consistent branding across all statements, and help with bank reconciliation.

Common use cases:

Brand consistency: Set explicit descriptors on payment transactions for clear brand identification and chargeback reduction
Multi-brand businesses: Use different descriptors per brand or product line for better customer recognition
Marketplace platforms: Configure default_descriptor templates for funding settlements with platform identification
Order tracking: Link statement text to customer orders using order_number variable for easy lookup

Transaction descriptors are limited to 32 characters and appear on customer bank or card statements. The descriptor field is immutable once a transaction is created. Use clear, recognizable text that helps customers identify the charge and reduces confusion or disputes.

Prerequisites

Before using custom descriptors, understand:

Transaction basics

Understand how transactions work and when descriptors are applied.

Processing settings

Learn about processing account configuration and funding settings.

What Are Custom Descriptors

Custom descriptors control the text displayed on bank and card statements.

The descriptor field

Every transaction includes a descriptor field that determines the statement text:

{
  "id": "txn_abc123",
  "type": "payment",
  "amount": 150.00,
  "description": "Product purchase - Invoice #12345",
  "descriptor": "ACME STORE"
}

Key characteristics:

32 character limit: Descriptors are truncated to meet card network requirements
Immutable: Cannot be changed after transaction creation
Statement visibility: Appears on customer or merchant bank statements
Automatic formatting: Formatted to meet processor and card network standards
Fallback behavior: Derived from description or default settings if not provided

Where descriptors appear

Descriptors appear on statements for different transaction types:

Transaction Type	Statement Location
Payment	Customer's bank or card statement
Payout	Customer's bank
Refund	Customer's statement (typically with "REFUND" prefix)
Funding	Processing account's bank statement

How Descriptors Work

Descriptor behavior varies by transaction type and configuration.

Payment transaction descriptors

For payment transactions (charges to customers), the descriptor is determined by:

Explicit descriptor provided

If you provide a descriptor field when creating the transaction, that exact text is used (truncated to 32 characters if necessary).

{
  "type": "payment",
  "amount": 150.00,
  "description": "Product purchase",
  "descriptor": "ACME STORE"
}

Derived from description

If no descriptor is provided, it's automatically derived from the transaction description field.

{
  "type": "payment",
  "amount": 150.00,
  "description": "Monthly subscription renewal"
}

Funding transaction descriptors

For funding transactions (settlements to the processing account), the descriptor is determined by:

Explicit descriptor provided

If you provide a descriptor field, that text is used.

Default descriptor from processing settings

If no descriptor is provided, the system uses the default_descriptor configured in your processing settings. The default_descriptor in processing settings defaults to "Payload" but can be customized and supports template variables.

Funding style considerations

Standard funding (gross, netted, manual): Uses default_descriptor template from processing settings (default is "Payload")
Itemized funding: Descriptor derived from the associated funding transaction's description field

Funding Style Impact: When funding style is set to itemized, each transaction creates a separate funding entry, and descriptors are derived from individual transaction descriptions rather than the default_descriptor template. This provides transaction-specific statement text on the processing account (merchant)'s bank statement.

Setting Custom Descriptors

Set descriptors explicitly on transactions or configure defaults in processing settings.

payment.py

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Set custom descriptor on payment transaction
 
# Create payment with custom descriptor
def create_payment_with_descriptor():
    payment = pl.Transaction.create(
        type='payment',
        amount=150.00,
        description='Product purchase - Invoice #12345',
        descriptor='ACME STORE',  # Custom text for customer's bank statement
        sender={
            'account_id': 'acct_customer123',
            'method_id': 'pm_card456'
        },
        receiver={
            'account_id': 'acct_merchant789'
        }
    )
 
    print(f'Payment created: {payment.id}')
    print(f'Descriptor: {payment.descriptor}')
    print('This descriptor will appear on the customer\'s statement')
    return payment
 
# Create payment without descriptor (uses description)
def create_payment_without_descriptor():
    payment = pl.Transaction.create(
        type='payment',
        amount=250.00,
        description='Subscription renewal - Monthly plan',
        # No descriptor provided - will be derived from description
        sender={
            'account_id': 'acct_customer123',
            'method_id': 'pm_card456'
        },
        receiver={
            'account_id': 'acct_merchant789'
        }
    )
 
    print(f'Payment created: {payment.id}')
    print(f'Descriptor (derived from description): {payment.descriptor}')
    return payment
 
# Example usage
create_payment_with_descriptor()

Set explicit descriptors on payment transactions to control customer statement text.

When to use:

Brand-specific charges
Multi-product businesses with different brands
Clear identification for customers
Chargeback reduction

Best practices:

Use recognizable business names
Keep under 32 characters
Avoid special characters
Include brand or product identifier
Test descriptor readability on actual statements

payout.py

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Set custom descriptor on payout transaction
 
# Create payout with custom descriptor
def create_payout_with_descriptor():
    payout = pl.Transaction.create(
        type='payout',
        amount=1500.00,
        description='Weekly merchant settlement',
        descriptor='ACME PAY',  # Custom text for merchant's bank statement
        sender={
            'account_id': 'acct_platform789'
        },
        receiver={
            'account_id': 'acct_merchant123',
            'method_id': 'pm_bank456'
        }
    )
 
    print(f'Payout created: {payout.id}')
    print(f'Descriptor: {payout.descriptor}')
    print('This descriptor will appear on the merchant\'s statement')
    return payout
 
# Create payout without descriptor
# Descriptor will be derived from default_descriptor in processing settings
def create_payout_without_descriptor():
    payout = pl.Transaction.create(
        type='payout',
        amount=2500.00,
        description='Monthly earnings payout',
        # No descriptor provided - will use default_descriptor from processing settings
        sender={
            'account_id': 'acct_platform789'
        },
        receiver={
            'account_id': 'acct_merchant123',
            'method_id': 'pm_bank456'
        }
    )
 
    print(f'Payout created: {payout.id}')
    print(f'Descriptor (from processing settings): {payout.descriptor}')
    return payout
 
# Example usage
create_payout_with_descriptor()

Set explicit descriptors on payout transactions to control customer statement text.

When to use:

Payouts to customers or recipients
Multi-brand payout sources
Clear payout identification
Customer statement clarity

Best practices:

Identify the payout source clearly
Include settlement period or batch ID if relevant
Use consistent descriptor formats
Consider customer recognition needs

Configuring Default Funding Descriptor

Configure default descriptors with template variables in processing settings for funding transactions. The default_descriptor in processing settings provides a default for all funding transactions.

Default value: If not configured, the default_descriptor defaults to "Payload", unless funding style is itemized, then the source transaction's descriptor will be used instead.

When applied:

Funding transactions without an explicit descriptor field
Not applied to payment or payout transactions

Configuration scope:

Set at the processing settings level
Applies to all funding transactions for that processing account
Maximum 128 characters in configuration (truncated to 32 on statements)

default.py

import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
# Configure default_descriptor in processing settings
 
 
# Set default descriptor for processing account
def configure_default_descriptor():
    settings = pl.ProcessingSettings.get("ps_abc123")
 
    settings.update(funding={"default_descriptor": "ACME CORP"})
    print(settings.funding, settings.object)
 
    print(f"Default descriptor set: {settings.funding.default_descriptor}")
    print(
        "This will be used for funding transactions when no explicit descriptor is provided"
    )
    return settings
 
 
# Get current default descriptor
def get_default_descriptor():
    settings = pl.ProcessingSettings.get("ps_abc123")
 
    print(f"Current default descriptor: {settings.funding.default_descriptor}")
    return settings.funding.default_descriptor
 
 
# Example usage
configure_default_descriptor()

template.py

import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
# Use template variables in default_descriptor
 
 
# Set default descriptor with template variables
def set_template_descriptor():
    settings = pl.ProcessingSettings.get("ps_abc123")
 
    settings.update(
        funding={
            # Template with multiple variables
            "default_descriptor": "{default} - {ref_number}"
        }
    )
 
    print(f"Template descriptor set: {settings.funding.default_descriptor}")
    print("This template will be populated with transaction data")
    return settings
 
 
# Example template patterns
def show_template_patterns():
    # Pattern 1: Default name with reference number
    processingsetting_obj = pl.ProcessingSettings.get("ps_abc123")
 
    processingsetting_obj.update(
        funding={"default_descriptor": "{default} - {ref_number}"}
    )
    print('Pattern 1: "Payload - REF123456"')
 
    # Pattern 2: Default name with description
    processingsetting_obj = pl.ProcessingSettings.get("ps_abc123")
 
    processingsetting_obj.update(
        funding={"default_descriptor": "{default} - {description}"}
    )
    print('Pattern 2: "Payload - Weekly Settlement"')
 
    # Pattern 3: Default name with order number
    processingsetting_obj = pl.ProcessingSettings.get("ps_abc123")
 
    processingsetting_obj.update(
        funding={"default_descriptor": "{default} - Order {order_number}"}
    )
    print('Pattern 3: "Payload - Order ORD-12345"')
 
    # Pattern 4: Description only
    processingsetting_obj = pl.ProcessingSettings.get("ps_abc123")
 
    processingsetting_obj.update(funding={"default_descriptor": "{description}"})
    print('Pattern 4: "Weekly Settlement"')
 
    # Pattern 5: Custom brand with reference
    processingsetting_obj = pl.ProcessingSettings.get("ps_abc123")
 
    processingsetting_obj.update(
        funding={"default_descriptor": "ACME PAY - {ref_number}"}
    )
    print('Pattern 5: "ACME PAY - REF123456"')
 
 
# Create transaction that uses template descriptor
def create_transaction_with_template():
    # First set the template
    processingsetting_obj = pl.ProcessingSettings.get("ps_abc123")
 
    processingsetting_obj.update(
        funding={"default_descriptor": "{default} - {ref_number}"}
    )
 
    # Create funding transaction
    payout = pl.Transaction.create(
        type="payout",
        amount=1500.00,
        description="Weekly merchant settlement",
        order_number="ORD-2024-001",
        # No descriptor provided - will use template from processing settings
        sender={"account_id": "acct_platform789"},
        receiver={"account_id": "acct_merchant123", "method_id": "pm_bank456"},
    )
 
    print(f"Transaction created: {payout.id}")
    print(f"Reference number: {payout.ref_number}")
    print(f"Final descriptor: {payout.descriptor}")
    # Output example: "Payload - REF123456"
    return payout
 
 
# Example usage
set_template_descriptor()

Template Variables Reference

Detailed reference for descriptor template variables used in funding transaction default_descriptor.

Example templates

Template syntax: Use curly braces around variable names. You can combine text and multiple variables.

Default with reference number
"{default} - {ref_number}"
Result: "Payload - REF123456"

Description only
"{description}"
Result: "Weekly Settlement"

Custom brand with order
"ACME PAY - Order {order_number}"
Result: "ACME PAY - Order ORD-12345"

Branded with reference
"MyBrand - {ref_number}"
Result: "MyBrand - REF123456"

Description with reference
"{description} - {ref_number}"
Result: "Settlement - REF123456"

Character Limit: While default_descriptor accepts up to 128 characters in configuration, the final descriptor on statements is truncated to 32 characters. Design templates that produce concise output, especially when using variables that may have long values.

Variable	Value/Description	Example	Notes
`{default}`	Default value "Payload"	`{default} - {ref_number}` → `Payload - REF123456`	Maintain Payload branding on statements. Combine with transaction identifiers for quick setup without custom configuration.
`{description}`	Transaction `description` field	`{description}` → `Weekly Settlement`	Dynamic descriptors based on transaction purpose. Description can be long (128 chars) and will be truncated to 32 on statement. Make descriptions concise and statement-friendly.
`{order_number}`	Transaction `order_number` field	`Order {order_number}` → `Order ORD-12345`	Link statement text to orders in your system for customer order tracking. Only populated if you provide order_number on transaction, empty if not set.
`{ref_number}`	System-generated reference number	`{default} - {ref_number}` → `Payload - REF123456`	Unique identifiers on every statement entry for transaction lookup and support. Always available (system-generated), unique for each transaction, fixed format (typically "REF" + digits).

Schema Reference

Fields relevant to custom descriptors.

Transaction descriptor

description

string

A human-readable description of what this transaction is for. This text provides context about the purchase, service, or payment purpose and may be displayed to customers on receipts and in transaction histories.

Max length: 128

Processing settings default_descriptor

default_descriptor

string

The default text descriptor that appears on the customer's bank or card statement for transactions. This helps customers identify the merchant on their statements. Typically includes the business name or recognizable identifier. Maximum length varies by processor.

Max length: 128

Next Steps

Enhance transaction management and reduce chargebacks with clear descriptors

Generate Customer Receipts

Create branded receipts with Transaction Receipts documentation, understand the full transaction lifecycle with Transaction Status, and learn about comprehensive transaction data with Transaction Metadata.

Reduce Chargebacks

Minimize disputes with clear descriptors by reviewing Chargebacks best practices, understand payment processing with Transactions documentation, and configure optimal settings with Processing Settings.

Add Custom Metadata

Combine descriptors with custom attributes using Custom Attributes for comprehensive tracking, build powerful reports with Reporting Overview for analytics, and explore Report Examples for common patterns.

Bank Reconciliation

Match funding transactions with bank statements using Match Funding Transactions guidance, understand settlement timing with Funding documentation, and reconcile accounts with Bank Reconciliation best practices.

Custom Attributes Match Funding Transactions