# Update payment labels (v2)

Add or remove labels for a payment.

Endpoint: PATCH /v2/payments/{paymentId}/labels
Version: 2025.11
Security: Bearer

## Path parameters:

  - `paymentId` (string, required)
    The unique ID that identifies the payment for which you want to update labels.
    Example: "7ea3399c-1234-5678-8d8f-d320ea406630"

## Request fields (application/json):

  - `labelsToAdd` (array)
    Application-defined labels for grouping and categorizing payments (e.g., campaign IDs, workflow tags, or batch identifiers). Labels are optional and mutable; they can be added or removed over the payment’s lifetime.
    Example: ["batchId=aaaaaaaa-1111-bbbb-abab-123412341234"]

  - `labelsToRemove` (array)
    Application-defined labels for grouping and categorizing payments (e.g., campaign IDs, workflow tags, or batch identifiers). Labels are optional and mutable; they can be added or removed over the payment’s lifetime.
    Example: ["batchId=aaaaaaaa-1111-bbbb-abab-123412341234"]

## Response 200 fields (application/json):

  - `labels` (array, required)
    Application-defined labels for grouping and categorizing payments (e.g., campaign IDs, workflow tags, or batch identifiers). Labels are optional and mutable; they can be added or removed over the payment’s lifetime.
    Example: ["batchId=aaaaaaaa-1111-bbbb-abab-123412341234"]

## Response 400 fields (application/json):

  - `errors` (object, required)

  - `errors.code` (string, required)
    A unique identifier for  the error
    Example: "SYS_003"

  - `errors.type` (string, required)
    A high-level categorization of the error, indicating the type of issue that occurred
    Example: "SYSTEM_ERROR"

  - `errors.title` (string, required)
    A brief, user-friendly description of the error
    Example: "Internal Server Error"

  - `errors.description` (string, required)
    A more detailed explanation of the error, potentially including information about what caused the error and the next steps
    Example: "The payout category value must be one of BANK, EWALLET, CASH_PICKUP, or ATM."

  - `errors.timestamp` (string, required)
    Example: "2024-11-21T14:15:22Z"

  - `status` (string, required)
    Error Response Status
    Example: 400

## Response 404 fields (application/json):

  - `errors` (object, required)

  - `errors.code` (string, required)
    A unique identifier for  the error
    Example: "SYS_003"

  - `errors.type` (string, required)
    A high-level categorization of the error, indicating the type of issue that occurred
    Example: "SYSTEM_ERROR"

  - `errors.title` (string, required)
    A brief, user-friendly description of the error
    Example: "Internal Server Error"

  - `errors.description` (string, required)
    A more detailed explanation of the error, potentially including information about what caused the error and the next steps
    Example: "The payout category value must be one of BANK, EWALLET, CASH_PICKUP, or ATM."

  - `errors.timestamp` (string, required)
    Example: "2024-11-21T14:15:22Z"

  - `status` (string, required)
    Error Response Status
    Example: 400

## Response 500 fields (application/json):

  - `errors` (object, required)

  - `errors.code` (string, required)
    A unique identifier for  the error
    Example: "SYS_003"

  - `errors.type` (string, required)
    A high-level categorization of the error, indicating the type of issue that occurred
    Example: "SYSTEM_ERROR"

  - `errors.title` (string, required)
    A brief, user-friendly description of the error
    Example: "Internal Server Error"

  - `errors.description` (string, required)
    A more detailed explanation of the error, potentially including information about what caused the error and the next steps
    Example: "The payout category value must be one of BANK, EWALLET, CASH_PICKUP, or ATM."

  - `errors.timestamp` (string, required)
    Example: "2024-11-21T14:15:22Z"

  - `status` (string, required)
    Error Response Status
    Example: 400