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:
SourceDescription
Client sessionPass data from SDK at checkout (e.g., device info, session context)
API operationsSet via POST /payments, POST /subscriptions, PATCH /customers
Workflow nodesAdd data during payment processing via Set Metadata node
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: 
POST /client-session
{
  "customer": {
    "metadata": {
      "signup_source": "mobile_app",
      "device_id": "abc123"
    }
  },
  "payment": {
    "metadata": {
      "order_id": "ORD-456"
    }
  }
}

​
API Operations

Attach metadata to customers, payments, or subscriptions: 
PATCH /customers/:id
{
  "metadata": {
    "tier": "premium",
    "account_manager": "[email protected]"
  }
}

​
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: 
{ "metadata": { "descriptor_suffix": "ORDER-123" } }
Braintree — Map to descriptor.name, descriptor.phone, descriptor.url: 
{ "metadata": { "descriptor_name": "MYSTORE" } }

​
Fraud Tools

Braintree Fraud Tools — Pass device data from the Braintree data collector: 
{ "metadata": { "braintree_device_data": "{\"correlation_id\":\"...\"}" } }
Map braintree_device_data → device-data Stripe Radar — Pass session IDs for enhanced fraud scoring: 
{ "metadata": { "radar_session": "rds_1234567890" } }
Map radar_session → radar_options.session

​
Reconciliation

Pass order IDs, invoice numbers, or internal references to match payments with your records: 
{ "metadata": { "invoice_id": "INV-2024-001", "erp_reference": "SAP-123456" } }

​
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:
ProcessorSupportDocumentation
Stripe✓ FullStripe integration
Braintree✓ LimitedBraintree integration
PayPal✓ LimitedPayPal integration
Unlimit✓ LimitedUnlimit integration

​
System-Reserved Keys

Two metadata namespaces are managed automatically:
NamespaceDescription
fingerprintAuto-populated during checkout—see Device Fingerprinting
workflowSet by workflow nodes (e.g., workflow.ab_test_variant)
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