Documentation

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.

Payment Charges

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"
    }
}

Payment Agreements

As described above, this is also supported for the following Agreements endpoints:

  • Create Payment Agreements POST /v1/payment-agreements
  • Create Payment Charge on an Agreement POST /v1/payment-agreements/{agrId}/payment-charges

Payment Sessions

As described above, this is also supported for the following Sessions endpoints:

  • Create Payment Session POST /v1/payment-sessions
  • Authorize a Payment Session for a Charge or an Agreement POST /v1/payment-sessions/{sessionId}/authorizations

Note: By default, the labels object defined on the parent session is propagated unchanged to the resulting charge/agreement that is being authorized. However, if a labels object is explicitly provided during the session authorization request, it overrides the existing one. In such case, the updated labels object is applied both to the resulting charge/agreement and to the parent session.

Updated 19 days ago