Metadata

Overview

You can attach custom key-value pairs (metadata) to objects such as transactions operation. Metadata allows you to store additional structured information that doesn’t impact payment processing — such as internal IDs, customer notes, or reference numbers.

Each object can include up to 20 metadata pairs, where both keys and values are strings.

Key length limit: 40 characters maximum.
Value length limit: 500 characters maximum.
Keys cannot contain special characters such as [ or ] (for example, order[id] is invalid).

Metadata is returned in API responses and can be used for filtering and search queries.

Adding Metadata

To attach metadata, include a metadata object in your request payload.
Each property inside metadata is a simple key-value pair.

Example Request

curl --location 'https://sandbox-platform.jupico.com/v1/transactions/creditcard/sale' \
--header 'Content-Type: application/json' \
--data-raw '{
  "subMerchantId": "jpt-sim-md-1",
  "amount": 10,
  "paymentToken": {
    "type": "creditcard",
    "token": {
      "cardHolderName": "John Doe",
      "cardLogo": "Visa",
      "expirationMonth": "02",
      "expirationYear": "29",
      "subMerchantId": "874767775",
      "token": "c808c35c-0ddf-4225-bdfd-51a87077572c",
      "truncatedCardNumber": "xxxx-xxxx-xxxx-4242",
      "provider": "jupico"
    }
  },
  "description": "Hamburger",
  "cardHolderInitiated": true,
  "subscriptionId": "123",
  "billing": {
    "address": "123 Silent Hill",
    "city": "Danbury",
    "zipCode": 12356,
    "state": "CT",
    "email": "[email protected]",
    "name": "John Doe",
    "phone": "123123123"
  },
  "source": {
    "type": "subscription"
  },
  "metadata": {
    "order_id": "ORD-9090"
  }
}'

Retrieving Metadata via Query

You can filter or search for transactions using metadata fields via the /query API..

Example Request

curl --location 'https://sandbox-platform.jupico.com/v1/query/transactions' \
--header 'Content-Type: application/json' \
--data-raw '{
  "metadata.order_id": "ORD-9090"
}'