Payment methods (since 4.2.0)
ImpressPages provides abstract class Ip\Payment to make unified communication between checkout plugins and plugins who provide payment methods. You can implement your own payment method for any existing checkout plugin. And vice versa - use any existing payment method on your checkout plugin.
Using payment methods
If you write your own checkout script and want to use official ImpressPages payment methods, use ipPaymentUrl function in your PHP code. This function will return an URL where the user has to be redirected to proceed to the installed payment method. If there are several payment methods installed, you will get a URL to the payment method selection page.
Example:
$paymentOptions = array (
'id' => 'AnyStringUniquelyIdentifyingThePayment', //required
'price' => $paymentAmountInCents, //required
'currency' => 'USD', //required
'title' => 'Title to be displayed during the payment',
'successUrl' => $successUrl,
'cancelUrl' => $cancelUrl
);
$paymentUrl = ipEcommerce()->paymentUrl($paymentOptions);
Listen to ipPaymentReceived event and get notified when payment will be completed. Make sure to check if id in event $info variable is one of your plugins generated IDs.
<?php
namespace Plugin\MyPlugin;
class Event
{
public static function ipPaymentReceived($info)
{
if ($info['id'] == 'AnyStringUniquelyIdentifyingThePayment') {
//process the order
}
}
}
Implementing your own payment method
If you want to build your own 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 ipPaymentMethods($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\Payment
{
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 information provided by other plugin executing ipEcommerce()->paymentUrl($data) function (read above)
* @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="..." />';
}
}
The actual payment will be initialized redirecting the visitor to the paymentUrl provided by your payment class. It is up to you where the user goes afterwards, but when the payment is complete, your plugin has to throw and event ipPaymentReceived with information about received payment. This way the plugin that has issued the payment request will know that the payment has succeeded.
$info = array(
'id' => '123xyz', //id attribute from $data array in paymentUrl method
'paymentMethod' => 'Your payment name',
'title' => 'payment title , //id attribute from $data array in paymentUrl method
);
ipEvent('ipPaymentReceived', $info);
There is basically the same data you get in paymentUrl method of your payment class. So you have to store all that data during the payment so that you know it at the time user completes the payment. The most important bit is id. This is the field that will be used by the third party plugin to recognize which order has been paid. Please pay attention, that id is string and in theory may contain letters. title may be missing in $data variable of paymentUrl method. In that case return id value as a title.
You can provide any additional data your payment method may dispose. The most common value is userId. If user completed the payment while being logged in, please add userId to the event. Otherwise other plugins can't know which user actually finished the payment.