Metadata

Submit additional information about the payment itself.

Metadata is defined as 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 and fetched.

Creating metadata

To create a new metadata resource, simply execute a POST request with your desired contents in json format. Here is an example:

Creating metadata

POST https://api.unzer.com/v1/metadata

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

The result will be a metadata ID, just like this: s-mtd-irw2xptj0tng

Fetching metadata

You can fetch a specific metadata resource by using a simple GET request with the corresponding ID. Again, you have to use your private key, otherwise the request won’t work:

Fetching metadata

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

Your output should display all the key-value pairs you’ve defined when creating the metadata resource. It should look something like this:

Result

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

You can find additional examples on creating and fetching metadata in the API reference.

Updating metadata

You can update a specific metadata resource by executing a PUT request with the corresponding ID. Just as with fetching metadata, you have to use your private key.

When updating metadata, all existing metadata content get’s deleted and overwritten by the new one.

Here’s an example - consider the following metadata resource:

POST metadata

POST https://api.unzer.com/v1/metadata

Body:
{
    "key1": "value1",
    "key2": "value2",
    "key3": "value3"
}

Then update it like so:

PUT metadata

PUT https://api.unzer.com/v1/metadata

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

The response to the PUT will look like this:

Response

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

Adding metadata to charges

In order to use metadata effectively, you not only have to create new resources, you also have to pass the correct parameter and ID with your authorize or charge request.

Down below is a simple cURL example - just add -d resources.metadataId:<your_metadata_ID> to your parameter list, like so:

curl https://api.unzer.com/v1/payments/charges
  -u s-priv-xxxxxxxxxx:
  -d amount=100.00
  -d currency=EUR
  -d returnUrl=http://www.unzer.com
  -d resources.typeId=s-crd-fm7tifzkqewy
  -d resources.metadataId=s-mtd-irw2xptj0tng