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
}