Introduction

est. reading time: 4 minutes.

Authentication

This API uses API Keys to authenticate requests. Keep your API Keys secure! They allow access to your account and your gift card transactions. Do not share your API keys in any publicly available areas such as GitHub or client-side code. Authentication is done via HTTP Basic Auth with your API Key as the username and the API Secret as the password.

Data Format

Our API uses JSON as data format. All responses from our API will carry the HTTP Response Header Content-Type: application/json. Data sent to our API in a request body must be in JSON format and your request must include the HTTP Request header Content-Type: application/json.

Responses and Error Handling

The zmyle API uses common HTTP response codes to outline the outcome of API requests. Response codes in the 2xx range indicate success. Response codes in the 4xx range indicate errors that are caused by the information provided in the request (outside influences). For example, you'll get a 4xx response when providing a wrongly formatted money amount or looking for a gift card that does not exist. Response codes in the 5xx range indicate an internal error that occurred on zmyle's servers. This would be our fault, and we hope that you will never encounter any 🤖.

Error Handling

All erroneous responses contain an error code that briefly explains the error. The error code is in the payload of the HTTP response. You can handle lots of those errors programmatically. The specific error codes are mentioned directly in the endpoint descriptions. Here's an example error payload:

{
    "errorId": "api:io:missingRequiredParam",
    "errorMsg": "giftcardId",
    "status": 400,
    "occuredAt": "20171126T060137Z"
}

Dates

Dates are strings in ISO-8601 format yyyyMMdd'T'hhmmss'Z' and are always in UTC. For example 20201008T033240Z.

Money Amounts

Money amounts are always given in the smallest unit of a currency (say 100 cents instead of 1 EUR). Money amounts are always positive integer numbers. There is no negative money amounts, even if the effect of an amount is to withdraw money from a balance.

Metadata

Some objects, notably gift card transactions, have a metadata field. You can use this field to store any key-value data along with those objects. You can specify up to 20 keys, with key names up to 24 characters long and values up to 240 characters long. You can use metadata to store any supporting structured data with zmyle objects. For example, to add your internal receipt identifier to a gift card redeem transaction. Or to attach the name and address of the outlet store from which this transaction originated, in case you have multiple outlets in your portfolio. We do not use your metadata for anything internally. This data is solely for you to make sense of.

Idempotency

The zmyle API provides idempotency for select endpoints. This allows you to safely retry those requests while only executing the same function once. This is great when API calls get interrupted, for example b/c of connection issues, and you were not able to receive a response. You can simply retry such requests.

The endpoints that support idempotency are marked as such, but you will never find this for any GET requests as they are idempotent by nature. Provide an additional body parameter idempotencyKey together with your other body parameters to enable idempotency on those select endpoints.

An idempotency key is a string generated by you and it should be unique; we suggest you use V4 UUIDs or any random string as long as you can avoid collisions. We limit the length of your key to a maximum of 40 characters. If your key is more than 40 characters long we will simply use the first 40 characters. We will not show any errors for keys that are too long.

We keep your idempotency keys for 12 hours. If you reuse the same key after 12 hours we will assume this is a new request.