PaySwitch
Getting started

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

RuleValue
Maximum keys per object50
Key name length40 characters
Value length500 characters
Value typeString (flat object: key → string value)

These limits match the OpenAPI schema descriptions on each field.

Where to use metadata

ObjectTypical 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
RefundLink 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.

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

JSONCode
{ "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

TerminalCode
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, open Request body → schema for CustomerRequest, or use the Create customer with metadata example in the playground.

Create payment with metadata

TerminalCode
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.

Last modified on