Topics

Subscription payment methods (recurring) (since 4.2.0)

ImpressPages provides an abstract class Ip\SubscriptionPayment to make unified communication between checkout plugins and plugins who provide payment methods. You can implement your own subscription payment method for any existing checkout plugin. And vice versa - use any existing payment method on your checkout plugin.

Using subscription payment methods

If you write your own checkout script and want to use official ImpressPages subscription payment methods, use ipSubscriptionPaymentUrl function to get payment URL. Redirect the user to the given URL. If there are few payment methods installed, you will get a URL to the payment method selection page.

Example:

$options = array(
    'item' => 'Item name', //the ID of subscription. User will see if 'title' is missing
    'title' => 'The title of the subscription', //user will see while subscribing (optional)
    'period' => 1,
    'periodType' => 'day', //day, week, month, year
    'amount' => 9900, //in cents
    'currency' => 'USD',
    'successUrl' => 'http://example.com' //optional URL where user has to be redirected after successful subscription. By default user will get a subscription status page.
);
$subscriptionUrl = ipEcommerce()->subscriptionPaymentUrl($options);

Listen to ipSubscriptionSignup and ipSubscriptionExpired events and get notified when user signs up or cancels the subscription. Make sure to check if item in event info variable is the one related to your plugin as you will catch subscriptions made by other plugins too. 

You don't have to check the price of subscription. It has to be done by the payment method.

<?php
namespace Plugin\MyPlugin;
class Event
{
    public static function ipSubscriptionSignup($info)
    {
        //$info['item'] - subscription plan
        //$info['userId'] - user that has subscribed
        if ($info['item'] == 'Item name') {
            //supply the service
        }
    }

    public static function ipSubscriptionExpired($info)
    {
        //$info['item'] - subscription plan
        //$info['userId'] - user that has canceled the subscription
        if ($info['item'] == 'Item name') {
             //stop the service
        }
    }
}

To implement subscription cancellation button, use ipEcommerce()->subscriptionCancelUrl() method. Pass subscription name you want to be canceled.

<?php

$options = array(
    'item' => 'Item name' // used in ipEcommerce()->subscriptionPaymentUrl()
);
$cancelSubscriptionUrl = ipEcommerce()->subscriptionCancelUrl($options);

Implementing subscription payment method

If you want to build your own subscription payment method that integrates with other ImpressPages plugins, you have to catch ipPaymentMethods filter and add your own payment method.

<?php
namespace Plugin\PayPal;
class Filter
{
    public static function ipSubscriptionPaymentMethods($paymentMethods, $data)
    {
        $paymentMethod = new MyPaymentClass();
        $paymentMethods[] = $paymentMethod;
        return $paymentMethods;
    }
}

MyPaymentClass has to extend  \Ip\SubscriptionPayment class and implement three methods: name, icon, paymentUrl, html. Example payment class:

<?php
namespace Plugin\MyPayment;

class Payment extends \Ip\SubscriptionPayment
{
    public function name()
    {
        return 'My Custom Payment';
    }
    
    /**
     * try to provide the best fitting image to the given proportions   
     */
    public function icon($width = null, $height = null)
    {
        return ipFileUrl('Plugin/MyPayment/assets/Payment.svg');
    }

    /**
     * This method should generate payment URL.
     * Typical actions of this method:
     * 1 write down all passed data to the database table
     * 2 return URL which starts payment method execution
     *
     * @param array $data subscription data
     * @return string
     */
    public function paymentUrl($data)
    {
        //write down all $data variables
        //return URL which starts payment method execution
    }

    /**
     * HTML to be displayed in payment selection window.
     * Used only if there are more than one payment method installed.
     * All this HTML will be surrounded by A tag to be clickable.
     * @return string
     */
    public function html()
    {
        return '<img src="..." />';
    }
}

Subscription payment method should also implement a cancellation procedure.  To do so, catch ipSubscriptionCancelUrl job. Check if requested item was paid by your payment method and provide a cancellation URL.

<?php
namespace Plugin\MySubscription;
class Job
{
    public static function ipSubscriptionCancelUrl($info)
    {
        $item = $info['item'];
        $subscriptionsMadeByThisPayment = ...//it is up to you how and where do you store a list of active subscriptions
        if (in_array($item, $subscriptionsMadeByThisPayment)) {
            $cancelUrl = ipRouteUrl('MySubscription_cancel');
            return $cancelUrl;
        }
    }
}

See also


comments powered by Disqus