Introduction

Gonvert allows the simple management of evouchers.
Here you can learn how to use Gonvert API to let users redeem on your website the evouchers they have received.


First of all you have to register an account as a carrier and get your private token.
That will be your personal key to use for the API.
Your private token uniquely identifies your website when calling the Gonvert API, so be sure to keep it safe! Do not show your private token in public areas such as client-side-code and so on.


Once you have registered as a carrier you can do one, or both, of these:

  • You can issue your evouchers and give them to your own staff members.
  • You can receive payment authorization requests from other issuers registered on Gonvert. Once authorized, the evouchers issued by those companies will be redeemable on your website.

Now it's time to work on the code!
In the checkout page of your website, add the option to pay with an evoucher.


The user will have to specify the redemption code, a temporary code that he can retrieve from his evoucher in the 'Gonvert' app.
On the app, he will also have a qr code to use instead of writing the code by hand, if you will provide a way to scan it.


Once you have collected the information on your page, call the API from your server for the creation of a Redemption intent.
The call to that API is useful to check if the data are all correct, and to get a preview of the redemption result.


Show the redemption preview to the user using the API response fields redemption_amount and ticket_amount.
When the user confirms that everything is fine, proceed to call the API to create the Redemption. You have to be sure that the reference that you pass during the creation is a unique identifier for this transaction.


There is the possibility that the amount of the evoucher does not fully cover that of the ticket purchased.
In this case you will need to provide the user with a way to pay the difference (indicated in the field amount_to_pay in the API response).
The amount_to_pay may be valorized even if a contribution (fixed or percentage) is specified on the evoucher.


Finally, you have to call the confirmRedemption API by passing the reference you used during its creation.
If the payment of the amount_to_pay fails in any way, you have to call the discardRedemption API by passing the same reference.
It is good practice to prevent user interaction from creation to confirmation or discard of the redemption.


That's it.
For more information on the API you can look at the specific documentation of each one.