Ticket voucher redemption

Ticket vouchers allow customers to redeem a voucher barcode in their possession for a special ticket that will have zero price. In some circumstances the customer may still be required to pay certain surcharges as described below.

Validating a voucher barcode and pin

ValidateTicketVoucherForSession will check whether a voucher barcode can be used for a particular session. If the voucher requires a PIN before it can be redeemed, the endpoint will check whether a PIN has been provided, and whether the provided PIN is correct.

POST: /vouchers/validate-ticket-voucher-for-session

{
	"Barcode": "TK0S10000001",
	"Pin": "1234",
	"SessionId": "1000000",
	"CinemaId": "0000000001"
}

If the voucher barcode is valid for use with the session, then the response will contain the ticket types available for the voucher, along with the number of redemptions remaining.

{
  "ticketTypes": [
    {
      "ticketTypeCode": "0060"
    }
  ],
  "numberOfRedemptionsRemaining": 1
}

Voucher ticket types

GetTicketTypesForBarcode which will return a list of valid ticket types for the specific barcode. This endpoint allows the ticket selection page to be updated to display the new ticket type available to order.

Typically a single ticket type will be returned however it is possible to configure the same voucher barcode to apply to multiple different ticket types.

GET: /RESTData.svc/cinemas/0001/sessions/1234/tickets-for-barcode?voucherBarcode=JP0010001235

{
    "ResponseCode": 0,
    "ErrorDescription": null,
    "Tickets": [
        {
            "CinemaId": "0000000001",
            "TicketTypeCode": "0056",
            "AreaCategoryCode": "0000000001",
            "HeadOfficeGroupingCode": "A000000065",
            "Description": "Voucher Ticket",
            "IsRedemptionTicket": true,
            "PriceInCents": 0,
            "SurchargeAmount": 0,
            "EnforceUseOfBarcode": true
        }
    ]
}

Voucher ticket surcharges

A voucher will offset the base price of a ticket however redeeming a voucher does not exclude the customer from paying any surcharge associated with the ticket. In the example below a voucher ticket is configured with a surcharge that the customer must pay to redeem the voucher.

GET: /RESTData.svc/cinemas/0001/sessions/1234/tickets-for-barcode?voucherBarcode=JP0010001235

{
    "ResponseCode": 0,
    "ErrorDescription": null,
    "Tickets": [
        {
            "CinemaId": "0000000001",
            "TicketTypeCode": "0056",
            "AreaCategoryCode": "0000000001",
            "HeadOfficeGroupingCode": "A000000065",
            "Description": "Voucher Ticket",
            "IsRedemptionTicket": true,
            "PriceInCents": 200,
            "SurchargeAmount": 200
        }
    ]
}

Ticket voucher details

The GetVoucherDetails can be used to get details about the voucher itself including the voucher's status, the number of times the voucher can be redeemed and its expiry date. This information can be useful to provide useful messages back to the customer.

GET: /vouchers/JP0010001235

{
    "id": "JP0010001235",
    "code": "JP001",
    "typeName": "Voucher Ticket",
    "ticketRedemptions": {
        "available": 1
    },
    "paymentRedemptions": {
        "available": 0,
        "paymentValueInCents": 0
    },
    "miscellaneousRedemptions": {
        "available": 0
    },
    "status": "Issued",
    "validFromDateTime": "2018-09-08T11:05:26.804Z",
    "expiryDateTime": "2019-09-08T11:05:26.804Z"
}

Redeeming the voucher

To redeem a voucher barcode for a voucher ticket the barcode and any associated pin should be provided in the SetTickets or AddTickets calls.

POST: /orders/a53ac319775849499dd04fd23a6c867b/sessions/1234/set-tickets

{
    "Tickets": [
        {
            "TicketDetails": {
                "voucherBarcode": "JP0010001235",
                "voucherPin": "6839"
            },
        }
	]
}

The ticket the voucher will be redeemed for is returned in the response

{
    "order": {
        "cinemaId": "0001",
        "userSessionId": "a53ac319775849499dd04fd23a6c867b",
        "sessions": [
            {
                "id": 1234,
                "filmTitle": "Airplane!",
                "tickets": [
                    {
                        "ticketDetails": {
                            "ticketId": 1,
                            "ticketTypeCode": "0056",
                            "description": "Voucher Ticket",
                            "voucherBarcode":"JP0010001235",
                            "finalPriceInCents": 0,
                            "originalPriceInCents": 0
                        }
                    }
                ]
            }
        ]
    }
}

If multiple ticket types exist for the same barcode the ticket type selected may be indeterminate. An additional voucherAreaCategoryCode can be provided in this case to add more specificity to the ticket type chosen.

{
    "Tickets": [
        {
            "TicketDetails": {
                "voucherBarcode": "JP0010001235",
                "voucherPin": "6839",
                "voucherAreaCategoryCode": "0000000001"
            },
        }
	]
}

Redemption without barcode

If the booking is unpaid, a voucher ticket can also be added without a barcode being provided. In this scenario the voucher will be presented and validated on site upon pickup/payment, hence the requirement that the booking be unpaid. These tickets will be returned via the standard GetTicketsForSession call.

{
    "Tickets": [
        {
            "TicketDetails": {
               "ticketTypeCode"0056"
            }
        }
	]
}