Labels

Labels are custom data fields that you define and attach to specific PPRO objects. When sent in a request, they are returned in the corresponding response, enabling you to associate charges, agreements and other entities with your own internal metadata.

Labels are supported on selected objects, such as payment charges, payment agreements, payment sessions and are structured as key–value pairs for your internal use. For example, you can use them to store consumer identifiers from your system, such as marketing campaign name, relationship manager name etc.

Configuration

You can add 20 total key-value pairs within following data limits:

key: 20 character limit & value: 100 character limit.

If your use case requires more labels than supported, we recommend storing the additional data in your own external database / CRM systems and using a key–value pair within labels to reference the external object’s ID.

• PPRO does not use labels when processing payment authorizations, declines, captures, voids or refunds. PPRO does not transmit labels to payment method providers, schemes or networks.
• Labels are not exposed to consumers. For example, they are not displayed on the Hosted Payments Page or included in bank or card statement narrations.
• Labels are not included in webhooks sent by PPRO. Additionally, the API does not support querying or searching objects based on label key–value pairs, nor does it support updating existing label key–values once they have been set. You can view and search labels directly within the PPRO Dashboard.
• Use the standard payment charge and payment agreement attributes to capture consumer, order and industry-related attributes. Labels should only be used where the existing, well-known attributes do not sufficiently support your specific use case. Please avoid reusing established PPRO API attribute names as label keys to prevent ambiguity or conflicts.
• Label keys and values have following restrictions:
  • Allowed characters: Unicode characters with UTF-8 encoding
  • Disallowed characters: Square brackets ([ ]) can’t be included.
  • Do not store sensitive data, such as bank account numbers or card details, in labels.

POST /v1/payment-charges

Request

{
    "paymentMethod": "WERO",
    "amount": {
        "currency": "EUR",
        "value": 200000
    },
    "consumer": {
        "country": "DE"
    },
    "labels":{
        "key1":"value1",
        "key2":"value2",
        "key3":"value3",
        "key4":"value4",
        "key5":"value5"
    }   
}

Response

{
    "id": "charge_CrYaa3zCIdhHF5Ib7QBPV",
    "paymentMethod": "WERO",
    "status": "AUTHENTICATION_PENDING",
    "createdAt": "2025-12-12T17:37:58.786Z",
    "updatedAt": "2025-12-12T17:38:02.041Z",
    "labels":{
        "key1":"value1",
        "key2":"value2",
        "key3":"value3",
        "key4":"value4",
        "key5":"value5"
    }
}

As described above, this is also supported for the following endpoints: POST /v1/payment-agreements, POST /v1/payment-agreements/{agrId}/payment-charges and POST /v1/payment-sessions.