Integrating with Sagepay

Before starting

Before starting to integrate a website with sagepay, there are some important steps to complete first.

1. Read documentation that is specified in the doc block of the helper class most notably: http://www.sagepay.co.uk/support/online-payments

2. Ensure that your have a valid sagepay account and have configured it to allow eCommerce transactions.

3. Ensure that your server's IP address is added to the Simulator/Test and Live accounts on the MySagePay system (https://live.sagepay.com/mysagepay). Your tabs client will have access details to this, please liaise with them regarding your access.

Overview

This documentation was written as a guide to help integrate a website with the sagepay inFrame mechanism. The mechanism relies on several actions from the initiating website.

1: Initialise an inframe by posting the transaction registration request to sagepay. See sagepay docuementation for more details.

2: The transaction request will include a callback url which outputs three lines of structured text which the inframe system uses to redirect the user to the correct page. Note, this page should be publicly accessible and should not rely on sessions as the callback session will be different from the user.

2: Provide completion/urls for the user to be redirected too.

First Step

Once the booking is ready to take a payment (Note, the booking should not be confirmed at this stage), a new sagepay help object can be created. An optional step is specify a credit card charge (as a percentage).

Create a transaction

The second step is to register a transaction with sagepay. This will involve posting data specified in the sagepay documentation. To specify a Credit Card Charge you must add SurchargeXML. If a valid sagepay response is returned, an iframe url will be returned that can be used to display a payment form on a website.

Performing the callback.

Once a customer has filled in an submitted the payment form, sagepay will post to the designated callback (with the post parameters specified in page 63 of the documentation). Providing it is an OK status, these parameters can then be passed into the tabs api and the booking could then be completed. Note, the amount and payment type fields will determine the type of payment that is added in tabs so developers must take care that they provide the correct data. There will be four different scenarios:

1 - Payment type "deposit". Deposit payment, can be determined from the booking data endpoint.

2 - Payment type "balance". Full payment of the booking.

If the sagePay callback specifies a surcharge the use one of the following -

3 - Payment type "deposit-ccc". Deposit payment including a credit card charge.

4 - Payment type "balance-ccc". Balance/Full payment including credit card charge.

For 3 and 4 you will also need to add a Credit Card Charge (CCC) extra using the [extra endpoint] (http://docs.carltonsoftware.apiary.io/#reference/booking-resources/adds-an-extra-to-a-booking/add-a-new-extra) This does not apply to payments made on the tabsbooking endpoint, in this case Tabs automatically adds the CCC extra when the payment is added to Tabs if it is greater that the amount outstanding on the booking. You may find the percentage amount charged for credit card fees in the GET /api/setting endpoint but please contact the agency you are working with to confirm what their credit card fees are.

For new bookings, the amount specified in the payment endpoint post must match the total amount of the transaction (including any surcharges that may have been applied).

For existing bookings, the payment amount must equal the balance outstanding excluding any credit card charges that may have been applied (the payment amount is specified in the endpoint http://docs.carltonsoftware.apiary.io/#reference/tabs-bookings/payments/add-a-payment). Existing booking payments must also use the PAYMENT TxType rather than the DEFERRED method.