Metadata

You can include custom metadata in some requests. For example, in the payout requests the metadata will be associated with the payout and included in webhook events related to 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 10 separate key-value pairs.
• Each metadata key and value must have at least one character.
• Each metadata key can be up to 40 characters long. Each value can contain a maximum of 255 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.