Credit Card Verification Guide

Some merchants/ suppliers require credit/ debit cards to be verified by the card issuer (E.g. 'Verified by Visa' or 'Mastercard Securecode'). This involves forwarding the customer to a website operated by the card issuer (Visa / Mastercard etc). The user enters a password on the card issuer's website and is then returned to a specified URL. This process is reflected in the XML booking API as an 'interruption' to the CheckBooking polling process. Full details are given below. 

Stage 1 - Indication that Card Verification is Required

As usual, after submitting the StartBooking request, the CheckBooking request is submitted repeatedly, awaiting booking completion. A typical CheckBooking request looks like this:

CheckBooking request XML example

<CommandList>
  <CheckBooking>
    <XmlLoginId>****</XmlLoginId>
    <LoginId>****</LoginId>
    <TFBookingReference>B1KL3B76P</TFBookingReference>
  </CheckBooking>
</CommandList>
A typical CheckBooking response looks like this:

CheckBooking response XML example while booking is still in progress

<CommandList>
  <CheckBooking>
    <TFBookingReference>B1KL3B76P</TFBookingReference>
    <Status>BookingInProgress</Status>
  </CheckBooking>
</CommandList>
At any time during this polling process, it may be discovered that the supplier requires card verification. In this case, the CheckBooking response will contain an extra element indicating this. See the CardVerificationRequired element in the example below: 

CheckBooking response XML example where card verification is required

<CommandList>
  <CheckBooking>
    <TFBookingReference>B1KL3B76P</TFBookingReference>
    <Status>BookingInProgress</Status>
    <CardVerificationRequired>true</CardVerificationRequired>
  </CheckBooking>
</CommandList>
When a response is returned containing the CardVerificationRequired element with value true, polling must be stopped, and no more CheckBooking requests should be sent until verification is complete (see below). 

Stage 2 - Submitting a Return URL and Redirecting the User

Next, a ProcessCardVerification request must be submitted as in the example below. The ReturnUrl element defines the URL that the user should be returned to after they have verified their card. This is needed because the user will be passed to the card issuer's website, and the card issuer needs to know where to pass them back to once the verification process is complete. The URL must contain everything that your application will need to identify the booking and resume CheckBooking polling. 

ProcessCardVerification request XML example

<CommandList>
  <ProcessCardVerification>
    <XmlLoginId>****</XmlLoginId>
    <LoginId>****</LoginId>
    <Command>setclientreturnurl</Command>
    <TFBookingReference>B1KL3B76P</TFBookingReference>
    <ReturnUrl>http://www.yourUrl.com/postCardVerify?ref=ABC123</ReturnUrl>
  </ProcessCardVerification>
</CommandList>
The response will be similar to that shown below. The Url element indicates where the user must be directed in order to complete the verification of their card. The user's browser must be directed immediately to that URL.

ProcessCardVerification response XML example

<CommandList>
  <ProcessCardVerification>
    <CardVerificationData>
      <Url>https://www.travelfusion.com/card_verify_redirect/?tfref=B1KL3B76P</Url>
    </CardVerificationData>
  </ProcessCardVerification>
</CommandList>

Stage 3 - After Verification is Complete

Once the user has been redirected to the Url above, they will complete the verification process on the card issuer's website. Then, they will be automatically returned to the ReturnUrl specified earlier in the ProcessCardVerification request. At this point, control is effectively returned to your application and an appropriate page should be displayed to the end user to indicate that the booking process is continuing. The usual CheckBooking polling process should be resumed, awaiting the completion of the booking.

Development Aid - Fake or Simulated Card Verification

When the booking process is started (with a StartBooking request), the FakeBooking element can be used to request a fake or simulated booking for development purposes. Within that element, the EnableFakeCardVerification element may be used to request that the card verification process is also included in the simulation. During development, the FakeBooking element should be submitted within the StartBooking element as in the example below. The other elements within the FakeBooking element are described fully in the StartBooking request specification. Note that the FakeBookingSimulatedDelay will be applied twice for simulated card verification - first as the delay between the submission of the StartBooking request and the first CheckBooking response to contain the CardVerificationRequired element with value true; then as the delay between completion of verification by the user and the completion of the simulated booking.

StartBooking request XML example, requesting simulated booking with card verification

<CommandList>
  <StartBooking>
    <XmlLoginId>****</XmlLoginId>
    <LoginId>****</LoginId>
    <TFBookingReference>B1KL3B76P</TFBookingReference>
    <FakeBooking>
      <EnableFakeBooking>true</EnableFakeBooking>
      <FakeBookingSimulatedDelaySeconds>15</FakeBookingSimulatedDelaySeconds>
      <FakeBookingStatus>Succeeded</FakeBookingStatus>
      <EnableFakeCardVerification>true</EnableFakeCardVerification>
    </FakeBooking>
  </StartBooking>
</CommandList>