Redemption object
| Name | Type | Notes |
|---|---|---|
| id | integer | Unique identifier of the Redemption. |
| redemption_amount | float | The used amount of the evoucher for this redemption. |
| ticket_amount | float | The amount of the ticket the evoucher has tried to redeem. |
| amount_to_pay | float | Difference between the ticket amount and the redemption amount. |
| reference | string | Reference of the ticket bought using the evoucher. |
| issuer_id | integer | Unique identifier of the evoucher issuer registered on Gonvert. |
Create Redemption
Create a Redemption object.
With this API you will create a redemption for an evoucher, but the redemption amount will be deducted from the residual amount only after confirmation.
The redemption amount is calculated based on the ticket amount, the holder contribution if set and the residual amount of the evoucher.
In the event that the redemption amount is greater than the evoucher residual amount the amount to pay will be the difference between these two values. If the issuer has set up a contribution (fixed or percentage) for the evoucher the amount to pay will always include at least that contribution.
If the evoucher was configured for a single redemption, it won't be usable again after the confirmation.
If the response will contains the variable beneficiary_only_restriction set as true, it will be up to you to set the ticket valid only for the person indicated by first_name and last_name.
POST https://api.gonvert.com/en/v1/voucher/redemption-create
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| redemption_code | string | Yes | Redemption code of the evoucher. |
| ticket_amount | float | Yes | Amount of the ticket to buy in the standard numeric format string (example: 30.5). |
| reference | string | Yes | A unique reference of the ticket bought using the evoucher. |
| travel_type | string | No | One of 'Monthly','Annual' or 'Quarterly'. If the evoucher has a travel type restriction, it will be checked using this parameter. |
| origin_place_coordinates | string | No | Coordinates encoded in json format. If the evoucher has an origin place restriction, it will be checked using this parameter. |
| destination_place_coordinates | string | No | Coordinates encoded in json format. If the evoucher has a destination place restriction, it will be checked using this parameter. |
| origin_place_code | string | No | A simple string. Gonvert will check the code of each fare pole configured in your account to use its coordinates if found. This parameter will be ignored if the coordinates are passed. |
| destination_place_code | string | No | A simple string. Gonvert will check the code of each fare pole configured in your account to use its coordinates if found. This parameter will be ignored if the coordinates are passed. |
Example request
https://api.gonvert.com/en/v1/voucher/redemption-create
redemption_code: G#1E8497-1234
ticket_amount: 30.5
travel_type: Monthly
reference: AB123
origin_place_coordinates: [{"lat":"43.230375", "lng":"11.421241"}]
destination_place_coordinates: [{"lat":"43.230375", "lng":"11.421241"}]
origin_place_code: null
destination_place_code: null
Example successful response
{
"success": true,
"message": null,
"voucher_id": 126,
"voucher_code": "G#1E8497",
"redemption_id": 414,
"redemption_amount": "30.5",
"ticket_amount": "30.5",
"amount_to_pay": "0",
"reference": "AB123",
"issuer_id": "6",
"issuer_name": "Red Coaches",
"beneficiary_only_restriction": false,
"first_name": "John",
"last_name": "Smith"
}
Example failed response
{
"success": false,
"message": "Oops! The redemption code is not valid or expired.",
"errorCode": 2174,
"identifierValue": null
}
Confirm Redemption
Confirm a Redemption object.
Confirm a pending redemption after you have already created it.
POST https://api.gonvert.com/en/v1/voucher/confirm-redemption
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| reference | integer | Yes | Unique identifier of the redemption transaction you passed during creation |
Example request
https://api.gonvert.com/en/v1/voucher/confirm-redemption reference: BC58693214
Example successful response
{
"success": true,
"message": null,
"reference": BC58693214
"redemption_id": 414,
"voucher_id": 245,
}
Example failed response
{
"success": false,
"message": "The record was not found. @BC58693214",
"errorCode": "2001",
"identifierValue": null
}
Discard Redemption
Discard a Redemption object.
Discard a pending redemption after you have already created it.
POST https://api.gonvert.com/en/v1/voucher/discard-redemption
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| reference | integer | Yes | Unique identifier of the redemption transaction you passed during creation |
Example request
https://api.gonvert.com/en/v1/voucher/discard-redemption reference: BC58693214
Example successful response
{
"success": true,
"message": null,
"reference": "BC58693214",
"redemption_id": "414",
"voucher_id": "245",
}
Example failed response
{
"success": false,
"message": "The record was not found. @BC58693214",
"errorCode": "2001",
"identifierValue": null
}
Read Redemption
Read a Redemption object.
If you need you can read any of the Redemption objects you have previously created.
POST https://api.gonvert.com/en/v1/voucher/redemption-read
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| voucher_id | integer | Yes | Unique identifier of the evoucher |
| redemption_id | integer | Yes | Unique identifier of the redemption |
Example request
https://api.gonvert.com/en/v1/voucher/redemption-read voucher_id: 126 redemption_id: 414
Example successful response
{
"success": true,
"message": null,
"voucher_id": 126,
"voucher_code": "G-1E8497",
"redemption_id": 414,
"redemption_amount": "30.5",
"ticket_amount": "30.5",
"amount_to_pay": "0",
"reference": "BC58693214"
}
Example failed response
{
"success": false,
"message": "Oops! This evoucher does not exists.",
"errorCode": 2174,
"identifierValue": null
}