Payment vouchers

Payment vouchers are vouchers that instead of being redeemed for certain tickets or concessions can be used as a form of payment. These vouchers work similarly in the Connect API to gift cards with the ability to pass them to CompleteOrder or add them to the order beforehand to enable combination with external and redirect payments.

Currently Connect has the following restrictions:

• Payment vouchers that have already been partially redeemeed are not supported
• Payment vouchers cannot be partially redeemed, their full value will be redeemed and represent a payment of the same value
• As such, using part of a voucher value as payment and recording difference as change is not supported
• Payment voucher payments currently cannot be refunded

Validating a payment voucher barcode

To validate the validity of a payment voucher barcode the GetVoucherDetails endpoint can be used.

Request:

GET: /vouchers/666660001951

Response:

{
    "id": "666660001951",
    "code": "66666",
    "typeName": "Payment Vouchers",
    "ticketRedemptions": {
        "available": 0
    },
    "paymentRedemptions": {
        "available": 1,
        "paymentValueInCents": 2000
    },
    "miscellaneousRedemptions": {
        "available": 0,
        "deals": []
    },
    "status": "Issued",
    "validFromDateTime": "2018-07-11T00:00:00",
    "expiryDateTime": "2101-10-11T00:00:00"
}

The paymentRedemptions property holds information on how this voucher can be used for payment.

• available indicates how many redemptions are available left on the voucher
• paymentValueInCents indicates the value of the voucher that can be used for payment (currently only full redemptions of payment vouchers are supported in Connect)

While the GetVoucherDetails endpoint will return enough information for a client to enable its use or not based on the current rules/restrictions in Connect it will not validate pin. Pins are validated as part of the ApplyPaymentVoucher and CompleteOrder calls described below.

Using vouchers with CompleteOrder

To use a payment voucher with a standard CompleteOrder call the voucher details can be passed in with the PaymentInfo entity and the PerformPayment flag set to true. These can be combined with other payments being provided in the CompleteOrderRequest

The following represents an order being paid with credit card and payment voucher.

POST: /RESTTicketing.svc/order/payment

Request:

{
    "PerformPayment": true,
    "UserSessionId": "b47e5287860b9c906125343c8dab09c2",
    "CustomerName": "Bette Davis",
    "CustomerEmail": "bette.davis@hollwood.org",
    "PaymentInfoCollection": [{
            "CardNumber": "4111111111111111",
            "CardCVC": "123",
            "CardExpiryMonth": "05",
            "CardExpiryYear": "23",
            "CardType": "VISA",
            "PaymentValueCents": 2000
        },{
            "PaymentValueCents": 1000,
            "PaymentTenderCategory":"Voucher",
            "PaymentVoucher":{
                "VoucherBarcode": "666660001040",
                "VoucherPin": "4544"
            }
        }]
}

Response:

{
    "Result": 0,
    "VistaBookingId": "WR6R2FG",
    "PaymentInfoCollection": [
        {
            "CardNumber": "4111111111111111",
            "CardCVC": "123",
            "CardExpiryMonth": "05",
            "CardExpiryYear": "23",
            "CardType": "VISA",
            "PaymentValueCents": 2000
        },
        {
            "CardType": "PaymentVoucher",
            "PaymentTenderCategory":"Voucher",
            "PaymentValueCents": 1000,
            "PaymentStatus": "P",
            "BillingValueCents": 1000
        }
    ]
}

Applying payment vouchers

The ApplyPaymentVoucher endpoint works like ApplyGiftCard allowing the payment voucher to be applied prior to CompleteOrder. This is useful if the client required pin validation before CompleteOrder or if the payment is to be combined with external or redirect payments.

POST: /RESTTicketing.svc/payment-voucher

{
    "UserSessionId": "a53ac319775849499dd04fd23a6c867b",
      "VoucherDetails": {
	      "VoucherBarcode": "666660001060",
	      "VoucherPin": "2526"
      }
}

The response will include the value of payment voucher to be redeemed as a payment along with other payment vouchers currently applied to the order.

{
    "ResponseCode": 0,
    "ErrorDescription": null,
    "PaymentVouchers": [
        {
            "Id": 1,
            "VoucherBarcode": "666660001060",
            "AmountToRedeemAsPayment": 2000
        }
    ],
    "OrderValueRemainingInCents": 750,
    "LastUpdated": "/Date(1532570378921+1200)/",
    "LastUpdatedUtc": "2018-07-26T01:59:38.9219157Z"
}

Applied payment vouchers can be removed via the RemovePaymentVoucher end-point.

DELETE: /RESTTicketing.svc/payment-voucher

{
  "UserSessionId": "a53ac319775849499dd04fd23a6c867b",
  "PaymentVoucherId": 1
}

Which will return the same response as ApplyPaymentVoucher.

{
    "ResponseCode": 0,
    "ErrorDescription": null,
    "PaymentVouchers": [],
    "OrderValueRemainingInCents": 2750,
    "LastUpdated": "/Date(1532570388921+1200)/",
    "LastUpdatedUtc": "2018-07-26T01:59:39.9219157Z"
}

Combining payment vouchers & external payments

By using ApplyPaymentVoucher payment vouchers can be combined with external payments.

Payment voucher is applied first.

POST: /RESTTicketing.svc/payment-voucher

{
    "UserSessionId": "a53ac319775849499dd04fd23a6c867b",
      "VoucherDetails": {
	      "VoucherBarcode": "666660001060",
	      "VoucherPin": "2526"
      }
}

CompleteOrder will have PerformPayment false and only the external payment details provided.

POST: /RESTTicketing.svc/order/payment

{
    "PerformPayment": false,
    "UserSessionId": "b47e5287860b9c906125343c8dab09c2",
    "CustomerName": "Bette Davis",
    "CustomerEmail": "bette.davis@hollwood.org",
    "PaymentInfo": {
        "CardNumber": "411111......1111",
        "CardType": "VISA",
        "PaymentValueCents": 500
    }
}

The response will include both the payment voucher and the external payment.

{
    "Result": 0,
    "VistaBookingId": "WR6R2FG",
    "PaymentInfoCollection": [
        {
            "CardType": "PaymentVoucher",
            "PaymentTenderCategory":"Voucher",
            "PaymentValueCents": 1000,
            "PaymentStatus": "P",
            "BillingValueCents": 1000
        }
        {
            "CardNumber": "411111......1111",
            "CardType": "VISA",
            "PaymentValueCents": 500,
            "PaymentStatus": "",
            "BillingValueCents": 500,
        }
    ]
}

Error handling

Error handling for payment vouchers should be the same as for other Cinema Payments with the following exceptions.

• Payment vouchers should not get declined on CompleteOrder as the voucher redemption should be validated prior to payment being executed.
• Payment vouchers added via ApplyPaymentVoucher do not support void in the event of a post-charge error