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"
}