Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.augustus.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Most updatable Augustus objects have a metadata parameter. You can use this parameter to attach arbitrary key-value data to Augustus 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 Augustus Checkout Session object. This allows you to attach information about returning users to an Augustus Payment. When a user successfully completes the payment flow, all metadata parameters transfer from the Augustus Checkout Session to the Augustus Order. By default, Augustus 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 Augustus 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 Augustus 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 Augustus Checkout Session object: 
curl -X POST 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.