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:
Note: Metadata resources can only be created/accessed using your private key.
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