​
Overview

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

You can specify up to 50 keys, with:

  • Key names up to 40 characters long
  • Values up to 500 characters long

Metadata is useful for storing additional, structured information on an object. For example, you could store your user’s corresponding unique identifier from your system on an Ivy Checkout Session object. This allows you to attach information about returning users to an Ivy Payment.

When a user successfully completes the payment flow, all metadata parameters transfer from the Ivy Checkout Session to the Ivy Order. By default, Ivy doesn’t use Metadata for any processing logic - for example, it’s not used to authorize or decline payments. Your users will only see Metadata if you explicitly show it to them.

Do not store sensitive information (bank account numbers, card details, etc.) in the metadata parameter.

​
Sample Metadata Use Cases

Attach your system’s unique IDs to an Ivy object for easy lookups:

  • Add your order number to a charge
  • Add your user ID to a customer or recipient
  • Add a unique receipt number to a transfer

​
Refund Paper Trails

Store information about:

  • Why a refund was created
  • Who created the refund
  • Any associated internal tracking numbers

​
Recognize Returning Customers

Annotate a Checkout Session object by storing an internal ID for later use.

When creating a new Ivy Checkout Session for a payment flow (See payment flow details), 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 Checkout Session 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 payment status details), the metadata field will be included in the payload. This allows you to easily match a new Order status to an internal user - for example, to fulfill orders more quickly.