Skip to main content
Metadata mapping forwards custom data from your application to processor authorization requests. Use it to pass fraud signals, customize statement descriptors, add reconciliation IDs, enable processor-specific features, or share context for reporting.

​
Metadata Sources

PayNext accepts metadata from multiple entry points:
PayNext merges metadata from payment, customer, and subscription objects. Payment metadata takes priority, then customer, then subscription—later sources overwrite duplicate keys.

​
Client Session

Pass metadata when creating a client session via SDK:

​
API Operations

Attach metadata to customers, payments, or subscriptions:

​
Workflow Nodes

Use the Set Metadata node in Workflows to add metadata during payment processing—useful for A/B testing, routing flags, or processor-specific data.

​
Configure Mappings

1

Open processor integration

Go to Dashboard → Integrations and select your processor.
2

Open Metadata mapping

Click the Metadata mapping icon.
3

Add field mappings

Click Add field and set:
  • Key: Path in your metadata (e.g., fraud.device_data)
  • Value: Processor field (e.g., device-data)
4

Save

Run a test transaction to confirm mappings work as expected.

​
Use Cases

​
Statement Descriptors

Customize what appears on customer bank statements. Stripe — Map to statement_descriptor_suffix:
Braintree — Map to descriptor.name, descriptor.phone, descriptor.url:

​
Fraud Tools

Braintree Fraud Tools — Pass device data from the Braintree data collector:
Map braintree_device_data → device-data Stripe Radar — Pass session IDs for enhanced fraud scoring:
Map radar_session → radar_options.session

​
Reconciliation

Pass order IDs, invoice numbers, or internal references to match payments with your records:

​
Processor-Specific Features

Enable features unique to each processor by mapping the required fields. See individual processor pages for available fields.

​
Processor Support

Each processor supports different metadata fields. See the Metadata Mapping section on each processor’s integration page for available fields:

​
System-Reserved Keys

Two metadata namespaces are managed automatically: Treat these as read-only—avoid overwriting them.

​
Tips

  • Test in sandbox — Verify mapped values appear correctly in processor dashboards
  • Remove unused mappings — Missing keys return empty/null in requests
  • MIT payments inherit customer metadata — Recurring charges use customer-level metadata
  • Use dot notation for nested paths — e.g., fingerprint.ip or workflow.variant for nested objects