Connect API - version 5.0.9.24 - 7e0560eca05bb0f97d04d090565b2aa195fd9502

Cinema connector payments

Cinema connector payments involve the passing of card details down to the cinema which will process the payment via the payment connector system in Cinema Payments Module.

Note that:

  • We do not recommend this process as it requires unmasked card details to traverse systems, adding PCI and security complications.
  • This process requires specific configuration of payments in Vista Cinema, and optionally in Connect. Consult your Connect administrator to ensure this has been done.

Completing order with cinema payments

Payment information to be passed to the Cinema Payments Module is provided in the CompleteOrder request with the PerformPayment flag set to true. Depending on the specific payment service, the card details required will vary. However, the following properties are typically required:

  • CardNumber
  • CardCVC
  • CardExpiry

Consult with your Connect administrator to discuss specific card requirements.

Either the PaymentValueCents property must be provided giving the payment a specific amount or the BillFullOutstandingAmount property which will try and pay the remainder of the balance. BillFullOutstandingAmount can get confusing with multiple payment types so it is recommended to provide the specific expected payments via the PaymentValueCents property.

POST: /RESTTicketing.svc/order/payment

{
    "PerformPayment": true,
    "UserSessionId": "b47e5287860b9c906125343c8dab09c2",
    "CustomerName": "Bette Davis",
    "CustomerEmail": "bette.davis@hollywood.org",
    "PaymentInfo": {
        "CardNumber": "4111111111111111",
        "CardCVC": "123",
        "CardExpiryMonth": "05",
        "CardExpiryYear": "23",
        "CardType": "VISA",
        "PaymentValueCents": 1000
    }
}

Cinema split payments may be made using the PaymentInfoCollection property on the request.

{
    "PerformPayment": false,
    "UserSessionId": "b47e5287860b9c906125343c8dab09c2",
    "CustomerName": "Bette Davis",
    "CustomerEmail": "bette.davis@hollywood.org",
    "PaymentInfoCollection": [
        {
            "CardNumber": "4111111111111111",
            "CardCVC": "123",
            "CardExpiryMonth": "05",
            "CardExpiryYear": "23",
            "CardType": "VISA",
            "PaymentValueCents": 500
        },
        {
            "CardNumber": "5222222222222222",
            "CardCVC": "542",
            "CardExpiryMonth": "07",
            "CardExpiryYear": "22",
            "CardType": "MASTERCARD",
            "PaymentValueCents": 500
        }
    ]
}

Notable payment properties

Payment can be quite complex, especially when using the Vista payment connectors to process payments. Understanding how the payments are configured at Vista are vital before understand the specifics of what must be provided to this endpoint. Simplest possible configuration requires simply the passing of CardNumber only however the back-end may be more complex.

Propert Name Details
CardNumber Sent to Cinema for processing by connector. Can also be used by cinema to determine which connector to use if PaymentSystemId not specified..
CardType Determines which Connect payment configuration (if any) Connect uses when processing the payment.
PaymentTenderCategory Sent to Cinema and can be used to determine payment type for reporting.
PaymentSystemId Sent to Cinema and can be used to determine connector to use for processing payment.

Response information

CompleteOrder response objects will return a result code and the payments that were attempted as part of the call. Important properties to note include the PaymentStatus which should be P for a successful payment and the BillingValueCents which indicates the amount that was successfully paid.

{
    "Result": 0,
    "VistaBookingId": "WR6R2FG",
    "PaymentInfoCollection": [
        {
            "CardNumber": "411111......1111",
            "CardType": "VISA",
            "CardExpiryMonth": "12",
            "CardExpiryYear": "2020",
            "CardValidFromMonth": "",
            "CardValidFromYear": "",
            "CardIssueNumber": "",
            "PaymentValueCents": 2200,
            "PaymentTenderCategory": "CREDIT",
            "PaymentErrorCode": "",
            "PaymentErrorDescription": "",
            "PaymentStatus": "P",
            "BillingValueCents": 2200,
            "CardBalance": 0
        }
    ]
}

Error handling

CompleteOrder will return a non-zero result code for failed payments. Check the payment collection in the response to determine the status of each payment that was attempted.

Result code 12 - payment declined

This is returned if one or more of the payments was declined by the payment service. It is an expected error code the client should handle. The PaymentStatus property is the key to determining the status of each payment in the response.

  • If only one payment is requested and the PaymentStatus is D then the client can safely retry CompleteOrder.
  • If multiple payments are requested and a payment declined occurs after a successful payment the response will be treated as a post-charge error and code 14 or 26 will be returned.
{
    "Result": 12,
    "VistaBookingId": "WRDBX97",
    "PaymentInfoCollection": [
        {
            "CardNumber": "411111......1111",
            "CardType": "VISA",
            "CardExpiryMonth": "12",
            "CardExpiryYear": "2020",
            "PaymentValueCents": 2200,
            "PaymentTenderCategory": "CREDIT",
            "BillFullOutstandingAmount": false,
            "PaymentErrorCode": "30",
            "PaymentErrorDescription": "INSUFFICIENT FUNDS ON THE CARD",
            "PaymentStatus": "D",
            "BillingValueCents": 0,
        }
    ]
}

Result code 1 - unexpected exception

Result code 1 from CompleteOrder indicates an unexpected exception. The order is incomplete but in an unknown state. Since cinema payments may have been processed the PaymentInfoCollection can be inspected to see what must be done.

  • If a payment has a PaymentStatus then that payment has either succeeded or been declined.
  • If a payment does not have a PaymentStatus but does have a PaymentErrorCode then this indicates the payment was attempted but Connect was unable to determine its status. This scenario must be treated as an 'unknown' payment and must be handled manually by the client.
  • Client should initiate failed order error handling with the assumption that one or more payments may still need to be reversed for customer
{
    "Result": 1,
    "CinemaID": "0000000001",
    "VistaBookingId": "WR6RW7L",
    "PaymentInfoCollection": [
        {
            "CardNumber": "411111......1111",
            "CardType": "VISA",
            "CardExpiryMonth": "12",
            "CardExpiryYear": "2020",
            "PaymentValueCents": 2200,
            "PaymentTenderCategory": "CREDIT",
            "BillFullOutstandingAmount": false,
            "PaymentErrorCode": "V-3",
            "PaymentErrorDescription": "Unexpected exception occurred performing payment at cinema",
            "PaymentStatus": "",
            "BillingValueCents": 0,
        }
    ]
}

Result code 14 - post-charge exception

This error indicates the payments were successful but one of the order completion steps post-payment failed.

  • In this scenario, one or more of the payments could not be voided
  • PaymentStatus will be set to VF indicating the void failed
  • Client should initiate failed order error handling with the assumption that one or more payments definitely needs to be reversed for customer
{
    "ExtendedResultCode": 14,
    "Result": 14,
    "CinemaID": "0000000001",
    "VistaBookingNumber": "3719",
    "VistaBookingId": "WRLST8F",
    "VistaTransNumber": "3760",
    "HistoryID": "",
    "PrintStream": "",
    "PrintStreamCollection": null,
    "PaymentInfoCollection": [
        {
            "CardNumber": "000010..0001",
            "CardType": "SVS",
            "PaymentValueCents": 500,
            "PaymentTenderCategory": "CREDIT",
            "PaymentErrorCode": "",
            "PaymentErrorDescription": "",
            "PaymentStatus": "V",
            "BillingValueCents": 500
        },
        {
            "CardNumber": "411111......1111",
            "CardType": "VISA",
            "CardExpiryMonth": "12",
            "CardExpiryYear": "2020",
            "PaymentValueCents": 500,
            "PaymentTenderCategory": "CREDIT",
            "PaymentErrorCode": "5001",
            "PaymentErrorDescription": "Request not supported by this bank system",
            "PaymentStatus": "VF",
            "BillingValueCents": 500,
        }
    ]
}

Result code 25 - post-charge exception with successful payment void

This error indicates that an error occurred after successful payment and the payments were successfully voided.

  • In this case all payments should have PaymentStatus of V.
  • Order is still incomplete but not customer payments are outstanding
  • Client should initiate failed order error handling with assumption that no payment needs to be reversed for customer
{
    "Result": 1,
    "CinemaID": "0000000001",
    "VistaBookingId": "WR6RW7L",
    "PaymentInfoCollection": [
        {
            "CardNumber": "411111......1111",
            "CardType": "VISA",
            "CardExpiryMonth": "12",
            "CardExpiryYear": "2020",
            "PaymentValueCents": 2200,
            "PaymentTenderCategory": "CREDIT",
            "BillFullOutstandingAmount": false,
            "PaymentErrorCode": "",
            "PaymentErrorDescription": "",
            "PaymentStatus": "V",
            "BillingValueCents": 0,
        }
    ]
}

3D secure with cinema payments

Currently 3D Secure payment verification is no supported in Connect for cinema payments.