Metadata
Attach your own key/value data to payments and read it back in API responses and webhooks.
metadata lets you store your own information on a payment, such as an internal order ID, a customer ID or a campaign code. Teyra Pay doesn't use it; it returns it unchanged on the object, in list results and in every webhook payload.
{
"amount": 12500,
"currency": "KWD",
"return_url": "https://shop.example.com/thanks",
"metadata": {
"order_id": "1042",
"customer_id": "cus_8812",
"campaign": "ramadan-2027"
}
}Rules
| Rule | Limit |
|---|---|
| Number of keys | Up to 20 |
| Keys | Strings of up to 40 characters |
| Values | Strings of up to 500 characters. Convert numbers and booleans to strings ("42", "true"). Nested objects and arrays aren't allowed. |
Requests that break these rules fail with 422 validation_error. The problem is described in details.fields, under metadata (too many keys, a key that is too long) or under metadata.<key> (a value that isn't a string).
Good uses
- Linking a payment to records in your own systems (
order_id,cart_id,invoice_number). - Recording where a payment came from (
source: "mobile-app",campaign). - Reconciling payouts and exports with your ERP or accounting system.
What not to store
Don't put sensitive data in metadata: no card numbers, CVVs, passwords, civil ID numbers or health information. Metadata is visible to everyone on your team in the dashboard and is sent to your webhook endpoints.
reference or metadata?
Use reference for your one main identifier, usually the order number: you can filter GET /v1/payments?reference=1042 by it and it appears in the dashboard search and exports. Use metadata for anything else.