# Metadata

Many PaySwitch objects support optional **metadata**: your own string key/value pairs attached to customers, payments, refunds, and other resources. Metadata is stored with the object, returned in API responses, and included in webhooks when the object is sent.

PaySwitch **does not assign meaning** to your keys (for example `kyc_status` or `trust_tier`). You define conventions in your product; routing and fraud rules only use metadata if **you** configure them to.

## Limits

| Rule | Value |
| ---- | ----- |
| Maximum keys per object | 50 |
| Key name length | 40 characters |
| Value length | 500 characters |
| Value type | String (flat object: key → string value) |

These limits match the OpenAPI schema descriptions on each field.

## Where to use metadata

| Object | Typical use |
| ------ | ----------- |
| **Customer** (`POST /customers`, update customer) | Long-lived payer traits: internal user id, KYC/trust flags, segment, account tier |
| **Payment** (`POST /payments`, update metadata) | Per-checkout context: order id, session id, campaign, product line |
| **Refund** | Link to internal ticket or reason code alongside the API `reason` field |

Prefer **customer** metadata for anything that describes the **player or account**. Prefer **payment** metadata for anything tied to a **single transaction**.

## Recommended conventions (optional)

You may use names like these; they are **not** enforced by the API:

```json
{
  "kyc_status": "passed",
  "trust_tier": "high",
  "internal_user_id": "998877"
}
```

Use stable, lowercase snake_case keys. Document your key catalog internally.

## Create customer with metadata

```bash
curl -X POST 'https://your-router.example.com/customers' \
  -H 'Content-Type: application/json' \
  -H 'api-key: snd_your_secret_key' \
  -d '{
    "customer_id": "player_123",
    "email": "guest@example.com",
    "name": "John Doe",
    "metadata": {
      "kyc_status": "passed",
      "trust_tier": "high"
    }
  }'
```

In the [API Reference](/api/customers#customers-create), open **Request body → schema** for `CustomerRequest`, or use the **Create customer with metadata** example in the playground.

## Create payment with metadata

```bash
curl -X POST 'https://your-router.example.com/payments' \
  -H 'Content-Type: application/json' \
  -H 'api-key: snd_your_secret_key' \
  -d '{
    "amount": 1000,
    "currency": "USD",
    "metadata": {
      "order_id": "ord_456",
      "udf1": "campaign-summer"
    }
  }'
```

You can also update payment metadata later via `POST /payments/{payment_id}/update_metadata`.

## What metadata is not

- **Not** a substitute for KYC or compliance fields required by a payment method or connector (`document_details`, billing address, etc. remain separate where the API provides them).
- **Not** automatically sent to acquirers unless a connector integration explicitly maps specific keys.
- **Not** encrypted—treat it as merchant-visible data; **never** put secret API keys, full card numbers, CVV, or passwords in metadata.

## Structured fields vs metadata

If the API exposes a first-class field (email, `tax_registration_id`, `document_details`, …), use it for data that integrations or reporting expect in that shape. Use **metadata** for everything else you need to round-trip for your own systems.
