Connect API - version 5.0.9.24 - 7e0560eca05bb0f97d04d090565b2aa195fd9502

Gift card payments

Gift card payments are supported in Connect and work the same way as Cinema Connector Payments. Card details are passed to cinema and the payment is processed by a Vouchers & Gift Cards payment connector.

  • This process requires specific configuration of payments in Cinema and optionally in Connect. Please consult your Connect administrator to ensure this has been done.

Completing order with a gift card payment only

To pay entirely with a Vista gift card payment information can be provided in the CompleteOrder request with the PerformPayment flag set to true.

POST: /RESTTicketing.svc/order/payment

Request:

{
    "PerformPayment": true,
    "UserSessionId": "b47e5287860b9c906125343c8dab09c2",
    "CustomerName": "Bette Davis",
    "CustomerEmail": "bette.davis@hollwood.org",
    "PaymentInfo": {
        "CardNumber": "000010870001",
        "CardType": "SVS",
        "PaymentValueCents": 1000
    }
}

Response:

{
    "Result": 0,
    "VistaBookingId": "WR6R2FG",
    "PaymentInfoCollection": [
        {
            "CardNumber": "000010..0001",
            "CardType": "SVS",
            "PaymentValueCents": 1000,
            "PaymentErrorCode": "",
            "PaymentErrorDescription": "",
            "PaymentStatus": "P",
            "BillingValueCents": 1000
        }
    ]
}

Partial payment gift card providers

Certain stored value payment providers support a form of automated partial payments. In this scenario a request is provided with the PaymentTenderCategory of SVS and BillFullOutstanding set to true. A credit payment is also provided with BillFullOutstanding set to true. The full amount will be attempted with the SVS provider but if it has insufficient balance it does a partial payment instead of declining the payment. The remaining order balance is charged to subsequent payment, typically a credit card payment.

  • This for of partial payment is not supported in conjunction with redirect or external payments.
  • Vista VGC does not support partial payment

In the following example an order of 5000 is being paid by a customer with a 4200 SVS balance.

POST: /RESTTicketing.svc/order/payment

Request:

{
    "PerformPayment": true,
    "UserSessionId": "b47e5287860b9c906125343c8dab09c2",
    "CustomerName": "Bette Davis",
    "CustomerEmail": "bette.davis@hollwood.org",
    "PaymentInfoCollection": [{
        "CardNumber": "000010870001",
        "CardType": "SVS",
        "BillFullOutstandingAmount ": true
    },{
        "CardNumber": "4111111111111111",
        "CardCVC": "123",
        "CardExpiryMonth": "05",
        "CardExpiryYear": "23",
        "CardType": "VISA",
        "BillFullOutstandingAmount ": true
    }]
}

Response:

{
    "PaymentInfoCollection": [
        {
            "CardNumber": "000010..0001",
            "CardType": "SVS",
            "PaymentValueCents": 4200,
            "PaymentTenderCategory": "SVS",
            "PaymentStatus": "P",
            "BillingValueCents": 4200
        },
        {
            "CardNumber": "411111......1111",
            "CardType": "VISA",
            "PaymentValueCents": 800,
            "PaymentTenderCategory": "CREDIT",
            "PaymentStatus": "P",
            "BillingValueCents": 800,
        }
    ]
}

Apply gift card

A more flexible way to pay with gift card is to use the ApplyGiftCard end-point.

  • This can be called at any point during the order and will store a gift card payment against the order.
  • The payment is actually processed upon CompleteOrder without the gift-card payment details being provided again.

POST: /RESTTicketing.svc/gift-card

{
    "UserSessionId": "a53ac319775849499dd04fd23a6c867b",
    "CardNumber": "000010780001",
    "AmountInCents": 1000
}

The response will include the gift cards currently applied (including the applied one) and the order value remaining to be paid outside the applied gift cards.

{
    "ResponseCode": 0,
    "GiftCards": [
        {
            "CardIndex": 0,
            "CardNumberMasked": "000010..0001",
            "AmountInCents": 1000
        },
        {
            "CardIndex": 1,
            "CardNumberMasked": "000010..0002",
            "AmountInCents": 1000
        }
    ],
    "OrderValueRemaining": 0
}

Applied gift cards can be removed via the RemoveGiftCard end-point.

DELETE: /RESTTicketing.svc/gift-card

{
  "UserSessionId": "a53ac319775849499dd04fd23a6c867b",
  "CardIndex": 0
}

Which will return the same response as ApplyGiftCard.

{
    "ResponseCode": 0,
    "GiftCards": [
        {
            "CardIndex": 0,
            "CardNumberMasked": "000010..0002",
            "AmountInCents": 1000
        }
    ],
    "OrderValueRemaining": 1000
}

##Completing Order with Apply Gift Card

CompleteOrder can be called and any applied gift cards will be automatically processed regardless of whether the PerformPayment flag is set. This allows the combination of gift card payment with external payments.

POST: /RESTTicketing.svc/order/payment

{
    "PerformPayment": true,
    "UserSessionId": "b47e5287860b9c906125343c8dab09c2",
    "CustomerName": "Bette Davis",
    "CustomerEmail": "bette.davis@hollwood.org",
}

The response returned will be as if you had provided the payment in the CompleteOrder request itself.

{
    "Result": 0,
    "VistaBookingId": "WR6R2FG",
    "PaymentInfoCollection": [
        {
            "CardNumber": "000010..0001",
            "CardType": "SVS",
            "PaymentValueCents": 1000,
            "PaymentErrorCode": "",
            "PaymentErrorDescription": "",
            "PaymentStatus": "P",
            "BillingValueCents": 1000
        }
    ]
}

Combining gift cards & external payments

By using ApplyGiftCard gift card purchases can be combined with external payments.

Gift card is applied first.

POST: /RESTTicketing.svc/gift-card

{
    "UserSessionId": "a53ac319775849499dd04fd23a6c867b",
    "CardNumber": "000010780001",
    "AmountInCents": 1000
}

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": "4681......5478",
        "CardType": "VISA",
        "PaymentValueCents": 1000
    }
}

The response will include both the gift card payment and the external payment.

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

Error handling

Error handling for gift-cards should be the same as for other Cinema Payments with the following exceptions.

  • Gift card payments made via ApplyGiftCard should not get declined on CompleteOrder as the card balance/number is validated as part of the ApplyGiftCard call.
  • Gift card payments made via ApplyGiftCard are currently not automatically voided on post-charge.