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

# Metadata Mapping

> Forward custom data to processors during payment authorization.

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:

| Source                                                        | Description                                                         |
| :------------------------------------------------------------ | :------------------------------------------------------------------ |
| **Client session**                                            | Pass data from SDK at checkout (e.g., device info, session context) |
| **API operations**                                            | Set via `POST /payments`, `POST /subscriptions`, `PATCH /customers` |
| **[Workflow nodes](/guides/platform/workflows#set-metadata)** | Add data during payment processing via Set Metadata node            |

<Info>
  PayNext merges metadata from payment, customer, and subscription objects. Payment metadata takes priority, then customer, then subscription—later sources overwrite duplicate keys.
</Info>

### Client Session

Pass metadata when creating a client session via SDK:

```json theme={"system"}
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:

```json theme={"system"}
PATCH /customers/:id
{
  "metadata": {
    "tier": "premium",
    "account_manager": "john@example.com"
  }
}
```

### Workflow Nodes

Use the **Set Metadata** node in [Workflows](/guides/platform/workflows) to add metadata during payment processing—useful for A/B testing, routing flags, or processor-specific data.

## Configure Mappings

<Steps>
  <Step title="Open processor integration">
    Go to **Dashboard → Integrations** and select your processor.
  </Step>

  <Step title="Open Metadata mapping">
    Click the **Metadata mapping** icon.
  </Step>

  <Step title="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`)
  </Step>

  <Step title="Save">
    Run a test transaction to confirm mappings work as expected.
  </Step>
</Steps>

## Use Cases

### Statement Descriptors

Customize what appears on customer bank statements.

**Stripe** — Map to `statement_descriptor_suffix`:

```json theme={"system"}
{ "metadata": { "descriptor_suffix": "ORDER-123" } }
```

**Braintree** — Map to `descriptor.name`, `descriptor.phone`, `descriptor.url`:

```json theme={"system"}
{ "metadata": { "descriptor_name": "MYSTORE" } }
```

### Fraud Tools

**Braintree Fraud Tools** — Pass device data from the [Braintree data collector](https://developer.paypal.com/braintree/docs/guides/premium-fraud-management-tools/client-side/javascript/v3/):

```json theme={"system"}
{ "metadata": { "braintree_device_data": "{\"correlation_id\":\"...\"}" } }
```

Map `braintree_device_data` → `device-data`

**Stripe Radar** — Pass session IDs for enhanced fraud scoring:

```json theme={"system"}
{ "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:

```json theme={"system"}
{ "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:

| Processor | Support   | Documentation                                                                |
| :-------- | :-------- | :--------------------------------------------------------------------------- |
| Stripe    | ✓ Full    | [Stripe integration](/integrations/processors/stripe#metadata-mapping)       |
| Braintree | ✓ Limited | [Braintree integration](/integrations/processors/braintree#metadata-mapping) |
| PayPal    | ✓ Limited | [PayPal integration](/integrations/processors/paypal#metadata-mapping)       |
| Unlimit   | ✓ Limited | [Unlimit integration](/integrations/processors/unlimit#metadata-mapping)     |

## System-Reserved Keys

Two metadata namespaces are managed automatically:

| Namespace     | Description                                                                                        |
| :------------ | :------------------------------------------------------------------------------------------------- |
| `fingerprint` | Auto-populated during checkout—see [Device Fingerprinting](/guides/advanced/device-fingerprinting) |
| `workflow`    | Set 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