Redirect connector payments (Web Payment Module)

Vista redirect payments are made via the connectors configured in Web Payment Module and sometimes referred to as Web Payment Module Payments. These provide a means of payment wherein the customer is redirected perform payment on the external payment provider web-site.

This process removes security concerns by ensuring card details are not passed through any system other than that of the payment provider

Initiating redirect payment

Once an order is ready for payment/completion the first call is to the ExternalPaymentStarting end-point. Important properties of note include:

• AutoCompleteOrder should be set to true
• OrderCompletionInfo should be provided, this will include information about the customer and properties that control the order completion process
• ExternalPaymentInfo defines the redirect payment provider to use and the ReturnUrl that the customer should be redirected back to once complete in the external system

POST: /RESTTicketing.svc/order/startexternalpayment

{  
   "UserSessionId": "a53ac319775849499dd04fd23a6c867b",
   "AutoCompleteOrder": true,
   "ExternalPaymentInfo":    {
      "ReturnUrl": "https:\/\/abccinemas.com/orders/45345345/payment-complete",
      "PaymentMethod": "payment-master",
      "IsInAppPayment": false
   },
   "OrderCompletionInfo":    {
      "CustomerInfo":       {
         "Name": "Ben Button",
         "Email": "benjamin.button@email.com",
      },
      "PrintSettings":       {
         "PrintStreamType": "0",
         "GeneratePrintStream": true
      }
   }
}

If successfully configured a return URL will be returned to which the customer browser should be redirected.

{
    "ExtendedResultCode": 0,
    "PaymentRedirectUrl": "https://wpm.abc-cinemas.com/VistaWebPay/Request.aspx?token=4c41cf8cda4a44709029077555762c63",
    "Result": 0
}

Confirming payment

Once the user has completed or cancelled the payment at the external site they will be redirected back to the specified ReturnUrl.

The ReturnUrl will have a token query string parameter appended e.g. https://abc-cinemas.com/orders/34534634/payment-complete?token=4c41cf8cda4a44709029077555762c63

At the same time the Web Payment Module process will have automatically attempt to complete the order in Connect, CompleteOrder does not need to be called by the client application in this scenario.

The client should instead poll the GetOrderDetails end-point to confirm successful order completion. This will return the IsCompletedOrder flag to determine the success of the order as well as the same information returned during CompleteOrder itself.

GET /RESTTicketing.svc/order/details?userSessionId=

Response:

{
    "ExtendedResultCode": 0,
    "OrderIdentifiers": {
        "CinemaId": "0000000001",
        "UserSessionId": "a53ac319775849499dd04fd23a6c867b",
        "ClientId": "111.111.111.111",
        "HistoryId": 42856,
        "VistaBookingNumber": 3733,
        "VistaBookingId": "WQNJG5L",
        "VistaTransNumber": 3774,
        "IsCompletedOrder": false
    },
    "OrderWebPaymentData": {
        "UserId": "a53ac319775849499dd04fd23a6c867b",
        "CustomerName": "Ben Button",
        "CardNumber": "411111......1111",
        "CardType": "VistaWebPay",
        "CardExpiryMonth": "03",
        "CardExpiryYear": "2023",
        "HasCheckedSendSMS": false,
        "LoyaltyCardNumber": "",
        "AttemptNumber": 1,
        "Token": "d3de14aee7dd45608886e3774a3fef65",
        "BankService": "VistaWebPay",
        "VistaTransRef": "3776",
        "AmountInCents": 1000,
        "PaymentStatus": "P"
    },
    "MemberBalances": [],
    "Attachments": [],
    "PrintStreams": [
        {
            "PrintStream": "~pdfAuthor=ABC Cinemas~pdfTitle=YourTicket.pdf~txtCinemaName=ABC St Louis~bcdBooking=C1001QQQN1NV~bcdBooking2=C1001QQQN1NV~imgAdvert1=Templates/Images/advert1.png~imgAdvert2=Templates/Images/advert2.png~txtTicketTypes=1 x Ad~txtFilmName=Local Hero~txtShowTime=08/03/2018 05:35 pm~txtTicketTypes=1,0000000000000 x Booking Fe",
            "PrintDocType": 1
        }
    ]
    "Result": 0
}

Combining redirect payment with gift card / Loyalty points payment

Redirect payments can be combined with gift card or loyalty points payments via the use of ApplyGiftCard and ApplyLoyaltyPointsPayment end-points. By calling these end-points prior to ExternalPaymentStarting the payments are recorded and processed automatically upon successful completion of the redirect payment.

In these scenarios the additional payments will be returned as well as the redirect payment in the GetOrderDetails reponse as shown in this gift-card example:

GET /RESTTicketing.svc/order/details?userSessionId=

Response:

{
    "ExtendedResultCode": 0,
    "OrderIdentifiers": {
        "CinemaId": "0000000001",
        "UserSessionId": "a53ac319775849499dd04fd23a6c867b",
        "ClientId": "111.111.111.111",
        "HistoryId": 42856,
        "VistaBookingNumber": 3733,
        "VistaBookingId": "WQNJG5L",
        "VistaTransNumber": 3774,
        "IsCompletedOrder": false
    },
    "OrderWebPaymentData": {
        "UserId": "a53ac319775849499dd04fd23a6c867b",
        "CustomerName": "Ben Button",
        "CardNumber": "411111......1111",
        "CardType": "VistaWebPay",
        "CardExpiryMonth": "03",
        "CardExpiryYear": "2023",
        "HasCheckedSendSMS": false,
        "LoyaltyCardNumber": "",
        "AttemptNumber": 1,
        "Token": "d3de14aee7dd45608886e3774a3fef65",
        "BankService": "VistaWebPay",
        "VistaTransRef": "3776",
        "AmountInCents": 1000,
        "PaymentStatus": "P"
    },
    "AdditionalPayments": [
        {
            "AmountInCents": 100,
            "BilledAmountInCents": 100,
            "MaskedCardNumber": "000010..0001",
            "CardType": "SVS",
            "PaymentStatus": "P",
        }
    ],
    "Result": 0
}

Error handling

Error handling with redirect payments comes down to how the client handles the subsequent polling of the GetOrderDetails end-point. For a successful payment the GetOrderDetails end-point should return a successful IsCompletedOrder within seconds. The client should treat the failure of this flag to come back successfully after a time as a failed order initiate the failed order process.