External payments

External payments are payments made to Connect via an external system. In this scenario:

• Interaction with payment providers and actual taking of payment is handled by the client application such (website, mobile app etc.).
• Payments must still be recored in Vista for an order to be completed.
• External payments can be combined with VISTA payment options such as Vista Gift Cards and/or Loyalty Points payments.

Completing order with external payments

Payment information made externally is provided in the CompleteOrder request with the PerformPayment flag set to false. Card details are therefore optional in this case. However, we recommend sending the CardType and a masked CardNumber for reporting and display purposes when reviewing completed bookings.

When completing external payments, you must provide a value to one of the following properties:

• PaymentValueCents - pay a specific amount
• BillFullOutstandingAmount - pay the remainder of the order balance.

  Using this property can get confusing with multiple payment types, so we recommend providing the specific expected payments via the PaymentValueCents property.

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
    }
}

External payments with multiple payment types may be made using the PaymentInfoCollection property on the request.

{
    "PerformPayment": false,
    "UserSessionId": "b47e5287860b9c906125343c8dab09c2",
    "CustomerName": "Bette Davis",
    "CustomerEmail": "bette.davis@hollwood.org",
    "PaymentInfocollection": [
        {
            "CardNumber": "4681......5478",
            "CardType": "VISA",
            "PaymentValueCents": 500
        },
        {
            "CardNumber": "1267......8634",
            "CardType": "CUSTOMGIFTCARD",
            "PaymentValueCents": 500
        }
    ]
}

Notable payment properties

Payment can be quite complex, especially when using the Vista payment connectors to process payments. For external payments Vista cannot infer the payment type for reporting since it doesn't process the payment, as such this must be provided in the CompleteOrder request.

Propert Name	Details
CardNumber	This value should be masked and is used purely for auditing or pickup purposes
CardType	Is sent to Cinema where it can be used to identify the correct payment type to record the payment as.
PaymentTenderCategory	Is sent to Cinema where it can be used to identify the correct payment type to record the payment as if CardType is not used.
PaymentSystemId	Not used for external payments.

Response information

The CompleteOrder response objects will return a result code and the external payments that were attempted as part of the call. For external payments the PaymentStatus and PaymentErrorCode will always be blank.

{
    "Result": 0,
    "VistaBookingId": "WR6R2FG",
    "PaymentInfoCollection": [
        {
            "CardNumber": "411111......1111",
            "CardType": "VISA",
            "PaymentValueCents": 1000,
            "PaymentErrorCode": "",
            "PaymentStatus": "",
            "BillingValueCents": 1000,
        }
    ]
}

Error handling

External payments will not have payment errors since the payment is already made externally. However, there are some CompleteOrder error codes that may affect external payments, which are described in the following sections.

Result code 1 - unexpected exception

Result code 1 from CompleteOrder indicates an unexpected exception. The order is incomplete but in an unknown state.

• Since payment is made externally there is no need to inspect the PaymentInfoCollection in the response.
• Client should initiate failed order error handling with the assumption that one or more payments may still need to be reversed for customer

Result code 14 - post-charge exception

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

• This code should not be returned with External Payments unless they are combined with Loyalty or Gift Card payments which failed to void.
• PaymentStatus will remain blank for external payment in response
• Client should initiate failed order error handling with the assumption that one or more payments defintiely 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": "SVS",
            "PaymentErrorCode": "5692",
            "PaymentErrorDescription": "Technical error voiding gift card payment",
            "PaymentStatus": "VF",
            "BillingValueCents": 500
        },
        {
            "CardNumber": "411111......1111",
            "CardType": "VISA",
            "PaymentValueCents": 1000,
            "PaymentErrorCode": "",
            "PaymentStatus": "",
            "BillingValueCents": 1000,
        }
    ]
}

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, or in this case not needed as payment was external.

• In this case external payment will have PaymentStatus whereas other payments will have PaymentStatus of V.
• 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,
        }
    ]
}