Metadata

You can include custom metadata in some requests. For example, in payout requests, the metadata will be associated with the payout and included in webhook events for this payout.

To add metadata, include a top-level JSON object with the key metadata. The value of this key should be another JSON object containing your desired key-value pairs.

{
    ...
    "customerId": "ba388054-4512-441e-a9c4-cbe9b0fe0332",
    "metadata": {
        "orderId": "PO-2025-001",
        "internalUserId": "user-456",
        "reason": "Customer withdrawal"
    }
}

When adding metadata to your request, keep the following in mind:

• You can include up to five separate key-value pairs.
• Each metadata key and value must have at least one character.
• Each metadata key can be up to 50 characters long. Each value can contain a maximum of 100 characters.
• Metadata keys can only contain:
  • Uppercase letters (A-Z)
  • Lowercase letters (a-z)
  • Numbers (0-9)
  • Underscores (_)
  • Hyphens (-)
• Metadata values cannot contain the characters "<>".

The provided metadata will also be returned in the status endpoint for reference.