The Interspire Shopping Cart Checkout Module Documentation is an introduction in to implementing additional payment providers in to Interspire Shopping Cart. This guide assumes you have knowledge of PHP.

Interspire Shopping Cart 3.5 Required
This documentation has been written for the upcoming release of Interspire Shopping Cart 3.5. There are numerous changes between Interspire Shopping Cart 3.5 and earlier releases for modules.

Contents

  1. Introduction
  2. Payment Type
  3. Available Methods
  4. Callbacks

Introduction

Checkout modules allow additional payment methods and gateways to be integrated in to Interspire Shopping Cart. Checkout modules can be as simple as offline methods (Bank deposit, Cash on Delivery etc), payment gateways where the customer is send to a payment provider to complete payment (PayPal Website Payments Standard) or more complex inline processing methods where the transaction is processed on your store by a remote service (Authorize.net, eWay etc) or completely replace the checkout process (Google Checkout, PayPal Website Payments Pro)

This document continues on from the Interspire Shopping Cart Modules Documentation which provides an overview of how Interspire Shopping Cart modules work and their structure.

Checkout modules exist within the /modules/checkout/ directory and extend upon the base ISC_CHECKOUT_PROVIDER class.

Payment Type

There are two types of payment types supported by Interspire Shopping Cart – online and offline. An online payment type implemented by a payment method indicates that this is an automatically processed transaction whereas an offline payment method is one that is processed offline such as Bank Deposit or Pick Up In Store.

The payment method type is defined as a class member variable of the payment method and can accept two different defined values, PAYMENT_PROVIDER_OFFLINE and PAYMENT_PROVIDER_ONLINE.

The payment type must be set as a class member variable of the checkout module. For example:

class ISC_CHECKOUT_EXAMPLE extends ISC_CHECKOUT_PROVIDER {
	private $_paymenttype = PAYMNT_PROVIDER_ONLINE;
}

Available Methods

GetTotal

The GetTotal method will return the order amount that should be processed through the payment gateway.

Callbacks

TransferToProvider

If a checkout module transfers the customer to another location for payment (such as to an offsite payment gateway similar to PayPal Website Payments Standard), TransferToProvider should perform this redirection.

GetOrderToken

Returns: String containing the token for the order that's being processed.

If for some reason the unique token assigned to this order cannot be returned or is not available, this method should be implemented for the payment module. This method should look up the order token (as was passed in a specific GET or POST variable, session or something else) and return it.

You should not rely on the customers cookies or session being available as this callback may be fired by an external payment gateway. For example, when WorldPay processes an order, it fetches the Interspire Shopping Cart page via their server and displays it to the user. Because it isn’t the customer that’s visiting the page but is the WorldPay servers, the customers cookies aren’t available containing the order token so the value of $_REQUEST[‘cartId’] is returned.

VerifyOrder

Arguments:
  • Array containing the pending order, passed by reference (&$pendingOrder)
Returns: Boolean. True if the pending order was verified successfully, false if there was an error.

This function verifies a pending order after the customer returns from the payment gateway (transferred to in the TransferToProvider method mentioned above). At a minimum, verification should be performed on the order total to ensure it matches the expected amount.

The VerifyOrder method should either return true or false. True should be returned when an order is verified successfully and false if there was a problem verifying the order.

This method can set the “paymentstatus” item in the $pendingOrder array to set the returned states of an order. Values include:

  • 1 — Payment is completed. The order should be set to either “Awaiting Fulfillment” or “Completed” (digital orders)
  • 2 — Payment is pending. The order should be set to “Awaiting Payment”
  • 3 — Payment declined. The order should be set to “Declined”

ProcessGatewayPing

If a payment provider (such as PayPal via IPN) contacts a website back to validate payment, this method should be available in the associated payment module. The notification URL for payment providers is as follows:

http://www.example.com/shop/checkout.php?action=gateway_ping&provider=XX

Where XX is the ID of the checkout provider ($this->GetId()).

If this method is present and a payment pingback is sent from the provider, you should validate its authenticity to verify that the pingback is indeed an official payment notification.

ShowPaymentForm

If a payment gateway has it’s own page for collecting payment details, this method should exist and will automatically be called when the order has just been confirmed and the customer needs to pay for the order.

This method should output (by means of a template or just printing content out by itself) the payment form for the customer to pay for their order. The pending order details are available by calling LoadPendingOrder() which returns an array containing the order.

Included modules that display their own payment form include both Authorize.net and eWay.

ProcessPaymentForm

Returns: Boolean. True if the payment was processed successfully and the customer should see the “thank you for your order” page. False to display the “something went wrong with your order” page.

If a payment module has the above-mentioned ShowPaymentForm method, this method is called on completion of the payment form sent via ShowPaymentMethod. This method should validate the entered details, send the payment off to the provider (in the case of a module similar to Authorize.net or eWay) or update the order to reflect payment information.

DisplayPaymentDetails

Arguments:
  • Array containing a copy of the order as fetched from the database ($order)
Returns: String. Any content to be displayed under the order details in the control panel.

If a payment provider wishes to display it’s own custom information in the control panel when an order is expanded (to view the details of the order), this method should be present.

In the case of the manual credit card module, this method is used to display the customer’s credit card details for the order.

HandleStatusChange

Arguments:
  • The ID of the order that the status is being updated for. ($orderId)
  • The status that the order previously was before the update. ($existingStatus)
  • The status that the order is now being changed to. ($newStatus)

If a payment method implements the HandleStatusChange callback method, this event will be fired whenever the status of an order is changed that was processed through this payment provider either via the control panel or automatically by Interspire Shopping Cart.

GetCheckoutButton

Returns: String. The HTML for the checkout button to show.

This method allows a payment module to show it’s own “Proceed to Checkout” button on the View Cart page. Any HTML or content required for the checkout button to be displayed should be returned via this method.