Accepting Giftcards

What you'll learn:

• to redeem a giftcard.

What you will need:

• your API keys

• A giftcard with a balance > 0

What you will do:

• Identify the giftcard by QR-Code or by the 4/6-digit Short ID.

• Fetch the giftcard data from the zmyle API.

• Reserve giftcard funds.

• Confirm your reservation.

Step 1: Identify the Giftcard

All zmyle giftcards have a QR-Code and a 4/6-digit Short ID. Either of those will allow you to fetch the giftcard data from our API.

If you are using the 4/6-digit Short ID:

• use the Short ID, as seen on the giftcard, in the next step.

If you are using the QR-Code:

• read the QR-Code contents with a scanner.

• (optional) detect if the QR-Code is a zmyle giftcard url.

• url-encode the QR-Code contents and use the encoded value in the next step.

Step 2: Fetch the Giftcard Data

Fetch the giftcard data by using the value from Step 1:

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

(replace <value> with the value from Step 1)

Then, use the giftcard data from the response to see if you can access the giftcards funds and how much money is available:

• expectedAction == "redeem" : this field must contain the literal string "redeem". More info on expected giftcard actions in the giftcard object description.

• authorizedActions: this is an array of strings, and it must contain a value with the literal string "redeem".

• availableBalance: this is the availble money amount on this giftcard. This is the maximum amount you can deduct from this giftcard.

Step 3: Reserve Giftcard Funds

Find the id and the accessToken from the giftcard data in Step 2. Then, reserve the funds on the giftcard by creating a transaction intent. For example, to reserve 50,00 EUR on a giftcard:

curl --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --user '<your-api-key>:<your-api-secret>' \
  --data-raw '{"giftcardId": "<id>", "accessToken": "<accessToken>", "amount": 5000}' \
  https://posapi.zmyledemo.de/service/v1.1/transaction_intents

See "Create a Transaction Intent" in the API Reference for more info.

Step 4: Confirm the Reservation

The last step is to confirm your reservation. This comitts the reservation to the giftcard and takes the funds out of the giftcard balance.

To confirm a reservation, you only need the id of the transaction intent (not the giftcard id):

curl --request POST \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --user '<your-api-key>:<your-api-secret>' \
  https://posapi.zmyledemo.de/service/v1.1/transaction_intents/<id>/confirm

See "Confirm a Transaction Intent" in the API Reference for more info.

That's it!

That's it! You have redeemed a giftcard. Our system will recognize your redeem transaction, and we will send you your money with the next billing cycle.