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:
Code
Use stable, lowercase snake_case keys. Document your key catalog internally.
Create customer with metadata
Code
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
Code
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.