Metadata
Metadata lets you attach your own key/value data to a transaction — an order reference, a campaign name, an internal customer ID, or anything else you want to carry alongside the payment. Preczn stores the metadata object you send to the Process Transaction endpoint and returns it back to you, and where the processor supports it, forwards it on so your data reaches their reporting too.
What Preczn Accepts
The metadata object must be flat — a single level of keys with string values. Nested objects, arrays, numbers, and booleans are rejected.
| Rule | Limit |
|---|---|
| Number of keys | 20 |
| Key length | 20 characters |
| Value type | String only |
| Value length | 255 characters |
"metadata": {
"receiptUrl": "https://www.example.com/receipts/abc123",
"userId": "23c216c4-5fe4-4e09-9863-355b6a151fc8"
}A metadata object that breaks any of these rules fails validation, and the transaction is rejected with:
metadata must be a flat object consisting of no more than 20 keys each of a max length of 20 characters, with only string values of a max length of 255 characters
Metadata Is Optional
metadatais never required. Transactions sent without it behave exactly the same.
Frequently Asked Questions
Does my metadata get sent to the payment processor?
It depends on the processor. Preczn always stores your metadata and returns it to you, but forwarding it onward is only possible where the processor's API has somewhere to put it — usually a custom fields or user fields concept of their own.
Check the connection page for your processor under Supported Connections to see whether it forwards metadata and how it maps the data.
Why was one of my metadata values shortened?
Processors set their own maximum length for custom field values, and some accept fewer characters than Preczn's 255-character maximum.
When a value is longer than the processor accepts, Preczn shortens it to fit rather than failing the transaction. The payment is more important than the note attached to it, so the transaction goes through and the value arrives trimmed at the processor.
If exact values matter to your reporting, keep them comfortably short — or store the full value on your side and send a shorter reference key in metadata.
Why did none of my metadata reach the processor?
Some processors cap the combined size of all custom fields on a single transaction, rather than capping each value individually. When your metadata exceeds that combined cap, those processors may discard all of it at once instead of trimming it — and because they still approve the payment, nothing about the transaction itself signals that the data was dropped.
This only tends to happen with unusually large metadata: many keys, each carrying a long value. The connection page for your processor documents its specific limit where one applies.
Can I send numbers, booleans, or nested objects?
No. Values must be strings, and the object must be flat.
Convert other types to strings before sending — "amountDue": "49.99" rather than "amountDue": 49.99 — and flatten anything nested into separate keys, keeping each key within the 20-character limit.
Where can I see the metadata on a transaction?
The metadata object is returned on the transaction record from the Get Transaction and List Transactions endpoints.
Updated 9 days ago