Metadata

Overview

Most updatable Ivy objects have a metadata parameter. You can use this parameter to attach arbitrary key-value data to these Ivy objects.

You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long.

Metadata is useful for storing additional, structured information on an object. For example, you could keep your user's corresponding unique identifier from your system on an Ivy checkoutSession object to attach information about a returning user to an Ivy Payment.

All metadata parameters are transferred from the Ivy checkoutSession to the Ivy order when a user finishes the payment flow successfully. By default, Ivy doesn't use metadata - for example, it's not used to authorize or decline a payment. Your users will only see metadata if you show it to them.

Don't store sensitive information (bank account numbers, card details, and so on) in the metadata parameter.

Sample metadata use cases

Link IDs

Attach your system's unique IDs to an Ivy object for easy lookups. For example, add your order number to a charge, your user ID to a customer or recipient, or a unique receipt number to a transfer.

Refund paper trails

Store information about why a refund was created and by whom.

Recognize returning customers

Annotate a checkoutSession object by storing an internal ID for your later use.

When creating a new Ivy checkoutSession for a new payment flow (See for more details on payment flows), specify your system's internal customer ID in the metadata field. The example below adds an internalCustomerId with the value customer_abcdefg to the Ivy checkoutSession object.

curl https://api.getivy.de/api/service/checkout/session/create \
  -H 'Content-Type: application/json'
  -H 'X-IVY-API-KEY: <api-key>'
  -D: '{
    "price": {
      "total": 100,
      "currency": "EUR"
    },
    "referenceId": "my-unique-reference-id",
    "metadata": {
      "internalCustomerId": "customer_abcdefg",
    }
  }'

When receiving status updates (See for more on payment status update), the metadata field will be in the payload. This way, you can easily match a new status for an order to an internal user, e.g., fulfill the order more quickly.