Redeeming Giftcards

est. reading time: 2 minutes.

Find a Giftcard

Before you can redeem a giftcard you need to find the giftcard record within our API. You can find more info on how to find a giftcard in the API reference. Once you have a giftcard object, you can determine if and how you can redeem that giftcard.

Eligibility to Redeem

Once you found the giftcard object in our API, before you can redeem, you need to check if you are allowed to redeem this giftcard, and if this giftcard has a balance. You can use the following attributes in the giftcard object:

• authorizedActions: this is an array of strings. This array needs to contain the string redeem. Otherwise this giftcard cannot be redeemed by you.

• availableBalance: this is a money amount that represents the remaining, available balance of the giftcard. If this is 0, then this giftcard has no balance and cannot be redeemed.

You are always authorized to redeem your own giftcards that are only valid in your own store. But if you also want to redeem community giftcards you need to be a member of that community. Just get in touch with us at [e-mail] if you're interested in any of our communities.

Failure to check results in an error response from our API if you try to redeem a giftcard but are not authorized to do so. Likewise, you'll receive an error response if you try to redeem a giftcard that has no available balance.

Redeem

You redeem a giftcard by first creating a transaction intent, and then later confirming that transaction intent. Creating a transaction intent will reserve funds on the giftcard for your redemption. And confirming will then commit the transaction and actually redeem the giftcard.

1. Create a Transaction Intent

To create a transaction intent, you need to use the id and the accessToken from the giftcard object, and you need to define the redeem amount in the request payload. For example to redeem a giftcard for 50,00 EUR:

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

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

2. Confirm a Transaction Intent

You only need the id of the transaction intent to confirm:

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.