GlossaryRequest Access

Card Payments Overview

The API allows card payments to be made to an existing booking using the following endpoint:
/bookings/{bookingReference}/cardPaymentUrl?amount={amountToPay}

which returns an URL to the TTC Payment Services card payment form, e.g:-

                https://payment-services.travcorpservices.com/makePayment/TTUSAS/BXXXXXX?cardTypes=VISA%2CAMEX%2CECMC%2CDISCOVER&postMessage=true&amount=300&bookingType=TA
                

This URL can be used to render the card payment form within an iFrame, e.g:-

                <iframe id='paymentServicesForm' class='Payment-iframe'
                src='https://payment-services.travcorpservices.com/makePayment/TTUSAS/BXXXXXX?cardTypes=VISA%2CAMEX%2CECMC%2CDISCOVER&postMessage=true&amount=300&bookingType=TA'
                width='100%' scrolling='no' />
                

After the card payment form is submitted. TTC Payment Services sends a callback response which is published to the browser as a window event.

TTC Payment Services browser window event callback response

Below is an example of the TTC Payment Services callback response:-

              {
              "paymentSuccessful":"true",
              "paymentStatus":"SUCCESS",
              "type":"CyberSourcePaymentResponse",
              "amountPaid":{"total":"1000","fee":"0"}
              }
            
Response Fields
NameDescription
paymentSuccessful"true" or "false" depending on whether the payment was successfully submitted to the payment provider i.e. CyberSource
typedetermines the response type, currently only set to "CyberSourcePaymentResponse"
paymentStatuscan be either "SUCCESS" - payment was successfully processed by both the payment provider and TTC downstream systems
or "PARTIALLY_COMPLETED" - payment was successfully processed by the payment provider but the failed to update TTC downstream systems
amountPaidspecifies the amount paid and any fees if applicable

The following JavaScript code provides an example of how to attach an event listener to the browser window. It checks the paymentSuccessful boolean flag in the TTC Payment Services response JSON.
The JavaScript function needs to run within the same page which contains the card payment form embedded as an iFrame.

// function for attaching a TTC Payment Services event listener to the browser window
function listenForPaymentServicesPostMessages () {
  if (window._paymentServicesPostMessageHandler) {
    window.removeEventListener('message', window._paymentServicesPostMessageHandler, false)
  }
  var postMessageHandler = function(event) {
    return this.paymentServicesResponseReceived(event)
  }
  window._paymentServicesPostMessageHandler = postMessageHandler
  window.addEventListener('message', postMessageHandler, false)
}

function paymentServicesResponseReceived (event) {
  // Get TTC Payment Services card payment form URL
  var paymentFormURL = // i.e. $https://payment-services.travcorpservices.com/makePayment/...
  var origin = event.origin || event.originalEvent.origin
  if (paymentFormURL.indexOf(origin) !== -1) {
    var paymentServicesResponse = JSON.parse(event.data)
    if (paymentServicesResponse.paymentSuccessful === 'true') {
      // HANDLE THE SUCCESSFUL RESPONSE HERE!
    }
  }
}

TTC Payment Services server-to-server callback response

Below is an example of the TTC Payment Services server-to-server callback response:-

{
 "status": "success",
 "amount": "1000",
 "currency": "USD",
 "bookingId": "B12345",
 "sellingCompany": "TTUSAS",
 "transactionId": "TTUSAS-B12345-1234567",
 "billingAddress": {
   "line1": "11 Grosvenor Place",
   "line2": "",
   "city": "London",
   "country": "United Kingdom",
   "state": "",
   "postCode": "SW1X 7HH"
 },
 "authToken": "eyJhbGciOiJIUzI1N.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
}
Response Fields
NameDescription
status"success" or "failure" depending on whether the payment was successfully processed
amountthe amount paid and any fees if applicable
currencythe currency that was used to make the payment
bookingIdId of the booking for which payment was made
sellingCompanySelling company of the tour
transactionIdUnique identifier of a payment made for a booking
billingAddressBilling address used to make the card payment
authTokenJWT signature for the response data

How to verify signature in the card payment server-to-server callback response

We use JWT asymmetric keys mechanism to sign the card payment response sent in the server-to-server callback after a payment is done. The response payload is signed by a private key on the sender end and a public key is used on the receiver end to verify the signature.

In order to verify the signature in the response payload, please use this public key :-

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArQcfETwPE5P9tpr4gUgm
bihdDGllrQjC4E7tAoURugaGUK2MwoxhuaMyBYJyXXye+MGuDevvmN18L5HclnXj
LpLIkS2hHdPs3jy/FP1Xc4lcqZmIKWZP7okELoU1btnwJvCBmPxajSFtM1SkXWYA
23J3lITtpdTIuXBn2JLM43w2Oz4kBDY1avTCFh7nB+Ck9CMBTrF4uIwcWhkwQ8iy
WPAyHtMNFBAbQv5NXlz4cu4nGI4mlfJRYfyndKBJ4MuIPJiX4hfwPzTO5lNl+lEl
gy1XMOeK+xdJzHn59bLGns+V/tUE/JZBrHNig5cfnMhH8CNdwMi36/LYQTp6xOtC
QwIDAQAB
-----END PUBLIC KEY-----

Availability

Departure availability status. Some statuses are only shown to internal API clients. Possible values are:

ValueDescriptionNotes
availableDeparture can be booked online.
closedDeparture is no longer available and can not be booked.
cancelledDeparture has been cancelled and can not be booked.
onRequestDeparture is still available but can not be booked online. One needs to get in touch with the selling company.
noYieldThe departure has not been entered into yield management.
tooLateDeparture date is too close to the current date.internal
closedNotAmendableDeparture has been closed and can not be reopened.internal

Brands

Travel Corporation tour operator. Possible values are:

ValueDescription
aatkingsAAT Kings
brendanvacationsBrendan Vacations
contikiContiki
insightvacationsInsight Vacations
luxurygoldLuxury Gold
trafalgarTrafalgar
costsaverCostsaver
grandeuropeantravelGrand European Travel <i>(coming soon)</i>

Departures

A particular date on which tour departs. Tours have typically many departures sold in (and localised to) multiple regions.

Seasons

Tours may have seasonal differences in itinerary, prices, accommodation, etc. Each season has its own set of departures.

Tour Options

Tours can have options. For example "Best of Greece" tour may have a "3 day Aegean cruise" extension resulting in "Best of Greece" having 2 options. Each option has its own set of seasons with departures.

Regions

Regions where tours are sold (aka Point of Sale). In API responses, tour content and departures differ for each selling region. Possible values are:

ValueDescriptionCurrency
usUnited StatesUSD
ukUnited KingdomGBP
euEuropeEUR
caCanadaCAD
auAustraliaAUD
nzNew ZealandNZD
sgSingaporeUSD
zaSouth AfricaZAR
zzRest of WorldUSD