Add transaction metadata

Submit additional information about a transaction.

About transaction metadata

Metadata is additional information that you can add to each transaction.

The content or the amount of transaction metadata doesn’t affect the transaction itself.

Using metadata is optional for all payment methods.

Use a metadata resource

To send metadata, use a metadata resource.

Each metadata resource consists of JSON key-value pairs. You can fill it with any information you want.

To use a metadata resource:

1. Create a new metadata resource.
2. Optional: Update an existing metadata resource.
3. Add an existing metadata resource to your transaction.
4. Optional: Fetch an existing metadata resource.

Step 1: Create a metadata resource

To create a new metadata resource, make a POST call to /metadata, using your private key.

In the request body, add any information you want, 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"
}

Optional: Update a metadata resource

To update an existing metadata resource, you can overwrite its existing content with new content.

Make a PUT call to /metadata, with your metadata resource’s ID in the request path.

In the request body, add your new metadata. The metadata resource’s existing content is deleted and overwritten by the new content.

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

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

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

Step 2: 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"
    }
  ]
}

Optional: Fetch a metadata resource

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