Manage metadata

Submit additional information about a transaction.

Overview

Metadata is the additional, optional information you can append to individual payments. That way you, as a merchant, can store important order or payment information with every charge or authorize.
Neither the content, nor the amount of metadata, matters for the payment procedure. It’s just an additional service for you, to mark or recognize certain payments.

A metadata resource consists of key-value pairs inside a simple json. It can be created, fetched and updated.

Create metadata

To create a new metadata resource, make a POST call to /metadata, using your private key. In the request body, add your desired information as JSON key-value pairs. For example, to add your shop’s ID and code, and an invoice number:

POST https://api.unzer.com/v1/metadata
{
    "shop_id":"s-001",
    "shop_code":"sample001",
    "invoice_number": "Rechnung-4711"
}

In response, you receive the ID of your newly-created metadata resource:

{
  "id" : "s-mtd-irw2xptj0tng"
}

Add metadata to a transaction

After creating a metadata resource, you can add it to a transaction. When making a charges or authorize call, add the ID of your metadata resource to the request body, as metadataId:

POST https://api.unzer.com/v1/payments/charges
{
  "amount": 100.00,
  "currency": "EUR",
  "returnUrl" "http://www.heidelpay.com",
  "resources": [
    {
      "typeId": "s-crd-fm7tifzkqewy",
      "metadataId": "s-mtd-irw2xptj0tng"
    }
  ]
}

Fetch metadata

To fetch an existing metadata resource, make a GET call to /metadata, with your metadata resource’s ID in the request path:

GET https://api.unzer.com/v1/metadata/s-mtd-irw2xptj0tng

{
    "shop_id":"s-001",
    "shop_code":"sample001",
    "invoice_number": "Rechnung-4711"
}

Remember to use your private key, when making the request.

Update metadata

You can update a specific metadata resource by executing a PUT request with the corresponding ID in the request path. When updating metadata, all existing metadata content is replaced by the new one.

PUT https://api.unzer.com/v1/metadata/s-mtd-irw2xptj0tng
{
    "key1": "newValue1",
    "newKey": "newValue2"
}

    "key1": "newValue1",
    "newKey": "newValue2"
}

Remember to use your private key, when making the request.

Pay later billing CSV mapping

For the Pay later (BNPL) payment methods — Unzer Invoice, Unzer Installment, and Unzer Direct Debit (secured) — two specific metadata keys are recognized and mapped through to downstream systems. When the merchant billing CSV is enabled, the following keys from the metadata resource attached to the transaction are included in the billing CSV:

Key	Type	Description
`shop_id`	`string`	The merchant shop identifier. Included as a dedicated column in the billing CSV.
`shop_name`	`string`	The merchant shop name. Included as a dedicated column in the billing CSV.

Both keys are optional. Other metadata keys are persisted on the metadata resource but are not mapped to billing CSV columns.

The example below shows how to send shop_id and shop_name together with any additional metadata fields you already use:

POST https://api.unzer.com/v1/metadata
{
    "shop_id":"s-001",
    "shop_name":"Sample Shop",
    "invoice_number": "Rechnung-4711"
}

Attach the resulting metadata ID to your Pay later authorize or charge call as metadataId, the same way as for any other metadata resource.

For details on the metadata call, go to the API reference.

UnzerAI

Welcome to UnzerAI!