Connect API - version 5.0.9.24 - 7e0560eca05bb0f97d04d090565b2aa195fd9502

Refunds

The refunding process in the Connect API consists of a single call which does two things:

  • Cancels transaction lines on the booking
  • Refunds or records the refund of payment to the customer

Refunds can either be full (entire booking is refunded) or partial (sub-set of booking items is refunded). This can be controlled by the sequences provided to the request. Multiple partial refunds can potentially be made on the same booking.

Partial refunds

When refunding part of a booking, the following rules must be followed:

  • You cannot refund part of a package - all sequences in the package must be refunded together
  • You cannot refund part of a deal - all sequences affected by the deal must be refunded together
  • You can refund booking fees separately from tickets. However, if only booking fees remain un-refunded on a booking, the booking is considered cancelled and they can no longer be refunded

Payments

Depending on how payment systems are set up with the specific Connect instance, different refund payment types will need to be provided. Before beginning work on refund integration it is important to understand the exact payment processes configured inside the Vista circuit. Since different payment providers have different rules and restrictions around refunds, clients wishing to offer refunds will have to think carefully about what kind of refund restrictions they in turn put into their application.

Unmatched payments

Unmatched payments act as a pass-through to a payment system configured at the cinema site. These take full card details and pass them directly to the payment provider for processing. Due to PCI concerns, this is not recommended for credit/debit based payments.

Matched payments

Matched payments act by taking the ID of one of the payments used to make the booking and reversing the original payment. They do this by using the original bank reference data stored during the payment. This is the recommended approach as it does not require re-entry of card details by customer.

External payments

For systems that do not process payments through Vista, the Connect API simply asks for a record of the already-made payment so that Vista can record it against the cancellation of transaction lines. In this case details of the external payment are simply recorded (generally for reporting or auditing purposes). The level of information you provide for these payments should be agreed upon with the Connect administrators.

Standard refund call flow

  • V1.Bookings.GetSingleBooking
    • Check the status of booking items
    • Get sequence numbers
    • Calculate the payment amount to refund to the customer
  • V2.Bookings.RefundBooking
    • Provide sequences to refund (or all items)
    • Provide payment details (external or through Vista)
  • V1.Bookings.GetSingleBooking
    • Optional call, required if error was returned from refund
    • Confirm refunded status of items and payments
    • Confirm payment status

Refunding part of a booking (partial refund)

Returning a booking with GetSingleBooking will return order items with sequences to use for refund in the TicketSequenceNumber, ItemSequenceNumber and BookingFeeSequenceNumber properties.

{
    "ResultCode": 0,
    "Booking": {
        "BookingNumber": 3638,
        "BookingId": "WPM8TS9",
        "VistaTransactionId": 3679,
        "TotalValueCents": 1450,
        "Tickets": [
            {
                "TicketTypeCode": "0001",
                "TicketSequenceNumber": 1,
                "SessionId": 35626,
                "PriceInCents": 1000,
                "Description": "Adult",
                "CollectedStatus": "0",
                "RefundedStatus": "0",
                "SeatRowId": "G",
                "SeatNumber": "16",
            }
        ],
        "Concessions": [
            {
                "ItemId": "75",
                "ItemSequenceNumber": 2,
                "PriceInCents": 350,
                "Description": "Small Pop Corn",
                "QuantityBooked": 1
            },
        ],
        "BookingFees": [
            {
                "BookingFeeSequenceNumber": 3,
                "PriceInCents": 100,
                "RefundedStatus": "0",
                "ParentTicketSequenceNumber": 1
            }
        ],
        "TotalBookingFeeValueCents": 100
    }
}

To refund part of the order the sequences you wish to refund should be included in the sequencesToRefund parameter. In this case the concession and ticket are refunded but the booking fee remains.

POST: /cinemas//bookings//refund

{
"
    "sequencesToRefund": [1,2],
    "externalPaymentDetails": [{
        "amountInCents": 1350,
        "cardNumberMasked": "412403....5226",
        "cardType": "VISA"
    }]
}

Unmatched payment refunds

Providing unmatched payment details will essentially do a negative payment with the payment provider. The new transaction will have no link to the original purchase transaction withing either the payment system or Vista. To make this payment type the full card details are required.

POST: /cinemas//bookings//refund

{
	"unmatchedPaymentDetails": [{
		"amountInCents": 1450,
        "cardNumber": "4111111111111111",
        "cardCVC": "123",
        "cardExpiryMonth": "05",
        "cardExpiryYear": "23",
        "cardType": "VISA",
	}]
}

Unmatched payments are are currently only supported via the same cinema connector process used in cinema connector payments.

Matched payment refunds

Returning a booking with GetSingleBooking will return order the original payments made returned.

{
    "ResultCode": 0,
    "Booking": {
        "BookingNumber": 3638,
        "BookingId": "WPM8TS9",
        "VistaTransactionId": 3679,
        "TotalValueCents": 1450,
        "Payments": [
            {
                "BillingValueCents": 1450,
                "OrderPaymentAmount": 1450,
                "CardName": "",
                "MaskedCardNumber": "411111......1111",
                "CardType": "VISA",
                "TenderCategory": "CREDIT",
                "BankReference": "41980",
                "CardExpiry": "202012",
                "PaymentId": "OPH-29299"
            }
        ],
        "PaymentsRefunded": []
    }
}

Assuming the payment configuration is setup correctly in Connect and the related payment system can handle bank-reference style matched refunds a refund should be possible by providing simply the PaymentId back in the refund call.

POST: /cinemas//bookings//refund

{
	"matchedPaymentDetails": [{
		"amountInCents": 1450,
		"paymentId": "OPH-29299"
	}]
}

Matched payment refunds for external payments

Payments made through Vista payment systems will automatically record the information of the original payment appropriately to enable the matched refund payment. For external payments the client must provide appropriate data to the CompleteOrder call when making the booking to enable this sort of refund in Connect.

The ReversalData and RefundPaymentMethod are key properties that must be populated with the ReversalData in the format required by the refunding payment connectorl.

POST: /RESTTicketing.svc/order/payment

{
    "PerformPayment": false,
    "UserSessionId": "b47e5287860b9c906125343c8dab09c2",
    "CustomerName": "Bette Davis",
    "CustomerEmail": "bette.davis@hollwood.org",
    "PaymentInfo": {
        "CardNumber": "4681......5478",
        "CardType": "VISA",
        "PaymentValueCents": 1000,
        "BankTransactionNumber":"094834939",
        "RefundPaymentMethod": "PaymentPlus",
        "ReversalData": "PP-094834939-GBRTYDFWTY",
    }
}

External payment refunds

To perform an external payment refund the payment details of the already-processed transaction are simply provided and recorded against the booking, much like external payments.

POST: /cinemas//bookings//refund

{
	"externalPaymentDetails": [{
		"amountInCents": 1450,
        "cardNumberMasked": "411111....1111",
        "cardCVC": "123",
        "cardExpiryMonth": "05",
        "cardExpiryYear": "23",
        "cardType": "VISA",
	}]
}

Refunding with multiple payment types

Refunding with multiple payment types can be done by providing multiple payment types in the refund request. The following example demostrates refunding an order that may have been paid with a combination of an external credit card and a Vista gift card.

POST: /cinemas//bookings//refund

{
	"unmatchedPaymentDetails": [{
		"amountInCents": 800,
		"cardNumber": "035464666587",
		"cardType": "SVS"
	}],
	"externalPaymentDetails": [{
		"amountInCents": 200,
		"cardNumberMasked": "412403....5226",
		"cardType": "VISA"
	}]
}

Any number of any refund payment type can be supplied. However, most scenarios are similar to the above example and will only require two payments to be provided.

Refund error handling

Since refunding, like order completion, performs both payment and transactional work and involves both the Connect system and downstream cinema systems, there is always a small chance that a part of the process might fail or time out.

When multiple payment types are involved for a single refund, the chance of an error occurring increases slightly as there is now a risk that one payment could be processed and the subsequent payment(s) fail. The following table describes the recommended actions to take for errors returned from V1.Booking.RefundBooking.

Scenario Action
First/only payment fails Retry is possible
Second payment fails Retry not currently possible, manual resolution required
Error occurs after payment Retry is not currently possible, manual resolution required

Security

Security is very important for refunds and as such there are several security behaviours that control what a client can do with the refund API. These include restricting what bookings can be refunded, what parts of a booking can be refunded, and what kind of payments will be accepted. Consult your Connect administrator for rules that will affect your client.