Fetch a Giftcard

Fetch a Giftcard

GET /service/v1.1/gift_cards/find

Use this endpoint to discover/find giftcards in our API.

Query Parameters

Name	Type	Description
query	string	The API will do its best to find a giftcard matching the provided query. You can use a 4/6 digit short ID, or the scanned contents of a QR Code.

200 Returns a list of matching giftcards.

[
  {
    "activation": {
        "amount": 2000,
        "minAmount": 100,
        "maxAmount": 25000,
        "isDynamicAmount": false
    },
    "expectedAction": "redeem",
    "authorizedActions": [
        "redeem",
        "activate"
    ],
    "availableBalance": 2000,
    "balance": 2000,
    "id": "18jja4mf08fn08f7gp9l",
    "initialAmount": 2000,
    "shortId": "QTHX",
    "accessToken": "hg84zhgnzuigui4hg3hg7834",
    "currency": "EUR",
    "transactions": [
        {
            "confirmedAt": "20171124T213259Z",
            "statementDescriptor": "Aktivierung",
            "amount": 2000,
            "id": "18k5ejn09hm88394qz32"
        }
    ]
  }
]

You can use this endpoint to find a giftcard when scanning a QR Code. Just use the entire content from the QR Code as the value for the query parameter. Our API will parse the URL and fetch the giftcard.

Make sure to URL-encode the value that you use with the query parameter. Our QR Codes often contain URLs; if you simply use this URL without URL-encoding it, your request won't be a valid request.

Example Request using a short ID:

cURL

curl https://posapi.zmyledemo.de/service/v1.1/gift_cards/find?query=JHU2U2 \
  -u <api_key>:<api_secret>
  

Example Request using contents from a QR Code:

This example demonstrates how to use the scanned contents of a QR Code to find a giftcard. In this scenario, you have a QR Code scanner that scans the code on a zmyle gift card. The scanned contents of the QR Code are passed into the query parameter (URL encoded). In this example, the QR Code contains the zmyle giftcard url: https://www.smartcity-gutschein.de/g/20ad4j13mnj16k3fgrhq/redeem?rt=kqmn20ad4j13nijlha3mux And the encoded query parameter is: https%3A%2F%2Fwww.smartcity-gutschein.de%2Fg%2F20ad4j13mnj16k3fgrhq%2Fredeem%3Frt%3Dkqmn20ad4j13nijlha3mux

cURL

curl https://posapi.zmyledemo.de/service/v1.1/gift_cards/find?query=https%3A%2F%2Fwww.smartcity-gutschein.de%2Fg%2F20ad4j13mnj16k3fgrhq%2Fredeem%3Frt%3Dkqmn20ad4j13nijlha3mux \
  -u <api_key>:<api_secret>
  

Response Error Codes

error code	reason
api:io:missingRequiredParam	You forgot to provide a value for the query parameter.
api:biz:noSuchGiftcard	The API could not find any giftcards for the provided search query. This either means that such a giftcard simply does not exist, or that you are not authorized to access this giftcard (not your gift card or not your network).
api:biz:retailerStatus	Your account is not in good standing.