Metadata allows you to attach custom key-value data to supported PaySway objects, helping you correlate operations across your systems. When you include metadata with an API request, PaySway preserves it throughout the entire process and returns it in both API responses and webhook events. This is particularly useful for tracking requests across different parts of your application. For example, you might attach your internal user ID or correlation ID that helps you connect API results back to the original context in your system.

​
Constraints

When working with metadata, these restrictions apply:
  • Limited entries: You can specify up to 10 entries
  • Key format: Keys must match ^[A-Za-z0-9._-]{1,40}$ (1-40 characters: letters, numbers, dots, underscores, hyphens)
  • Value format: Values must be strings with a maximum length of 250 characters
  • Flat structure: Metadata must be a flat object. Nested objects and arrays are not supported
  • No indexing: Metadata is stored as-is and cannot be used for searching or filtering in queries

​
Implementation

Include metadata as a JSON object in your API requests: 
{
  // ...
  "metadata": {
    "user_id": "user_12345",
    "correlation_id": "d126d635-a854-4b13-8c33-906146a4055f"
  }
}
Don’t store sensitive information like personally identifiable information (PII) or secrets as metadata.