Metadata

Most Casharc objects — payments, payouts, and appeals — accept a metadata parameter. It lets you attach your own key-value data to an object, so you can carry your internal context alongside the Casharc record.

Casharc never interprets metadata: it isn't used to process, authorize, or route an object, and it isn't shown to the payer. It is stored as you send it and returned unchanged on the object and in webhook events.

Limits

Rule	Limit
Keys per object	50
Key length	40 characters
Value length	500 characters

Keys and values are stored as strings. Square brackets ([ and ]) aren't allowed in keys.

Structure

Metadata is a flat map of string keys to string values — nested objects and arrays aren't supported. To store structured data, serialize it into a string under a single key (for example, JSON) and parse it back when you read the object.

{
  "metadata": {
    "order_id": "ord_10426",
    "source": "checkout"
  }
}

What not to store

Metadata is not encrypted and is not a secure store. Never put sensitive data in it — card numbers, CVVs, bank account numbers, credentials, tokens, or personal data. Use it for references and context, such as:

Linking IDs — attach your own order, user, or invoice IDs so you can cross-reference an object with your system.

Operational context — record the reason for a refund or appeal, the operator who triggered it, or the channel a payment came from.

Reading it back

Metadata is returned on the object from every endpoint and included in webhook payloads, so you can reconcile events against your own records without a separate lookup.

Limits#

Structure#

What not to store#

Reading it back#

Limits

Structure

What not to store

Reading it back