Custom Payment Gateway

There are few steps to integrate your payment gateway with WPSmartPay. Process of implementing payment gateway: 

First step is registering the gateway labels and icon. Here are two types of label is necessary. One is admin_label and another one is checkout_label. You can do that using a hook called ‘smartpay_gateways’. Let’s look an example:

add_filter(‘smartpay_gateways’, ‘register_gateway’, 110);



Callback function is look like:

function register_gateway(array $gateways = array()): array {     // check the gateway exist or not     $gateways[‘example’] = array(         ‘admin_label’       => ‘Example Gateway’,         ‘checkout_label’    => ‘Example Gateway’,         ‘gateway_icon’      =>  ‘example.png’,     );     return $gateways; }



Second one is to register your gateway to the available gateway list for selection to the users on SmartPay Payment Gateway settings. The process is the same as above method. Let’s look an example:

add_filter(‘smartpay_get_available_payment_gateways’,’register_to_available_gateway_on_setting’, 111);



function register_to_available_gateway_on_setting(array $availableGateways = array()): array {     $availableGateways[‘example’] = array(         ‘label’ => ‘Example Gateway’     );     return $availableGateways; }



Now it’s time to forward to the next step to process the payment. In the following process, you will be complete the payment.

All the steps will be done with the SmartPay hooks. So, let’s start

Register the payment gateway into Form or Payment Modal:

Add the ‘smartpay_settings_sections_gateways’ hook to add your payment gateway section on Form or Product Modal. Add your label on callback function like bellow’s example.

add_filter(‘smartpay_settings_sections_gateways’, ‘gateway_section’, 110);



function gateway_section(array $sections = array()): array {     $sections[‘example’] = __(‘Example Gateway’, ‘smartpay-example-gateway’);     return $sections; }



Then, you should create a necessary setting that will be needed to process the payment using your payment gateway such as, API keys, secret keys. So, let’s do it by a hook called ‘smartpay_settings_gateways’. Look an example:

add_filter(‘smartpay_settings_gateways’, ‘gateway_settings’, 110);



Your necessary setting will load from this callback function while user activate your payment gateway. Then, it will be shown on SmartPay setting page. Following example will make you more clear.

function gateway_settings(array $settings): array {     $gateway_settings = array(         array(             ‘id’    => ‘example_gateway_settings’,             ‘name’  => ‘<h4 class=”text-uppercase text-info my-1″>’ . __(‘Example Gateway Settings’, ‘smartpay-example-gateway’) . ‘</h4>’,             ‘desc’  => __(‘Configure your Example Payment Gateway Settings’, ‘smartpay-pro’),             ‘type’  => ‘header’         ),         array(             ‘id’   => ‘example_gateway_test_api_key’,             ‘name’  => __(‘Test Api Key’, ‘smartpay-example-gateway’),             ‘desc’  => __(‘Enter your test api key, found in your Developers > API keys’, ‘smartpay-example-gateway’),             ‘type’  => ‘text’,         ),         array(             ‘id’   => ‘example_gateway_live_api_key’,             ‘name’  => __(‘Live Api Key’, ‘smartpay-example-gateway’),             ‘desc’  => __(‘Enter your live api key, found in your Developers > API keys’, ‘smartpay-example-gateway’),             ‘type’  => ‘text’,         ),     );     return array_merge($settings, [‘example’ => $gateway_settings]); }



This is all about registering integration and settings. Let’s dive into processing the payment using your gateway integration.

Example:

In this section, we are going to discus about a few SmartPay action hooks to complete the payment using your payment gateway integration. Such as:

1. smartpay_custom_ajax_process_payment
2. smartpay_custom_subscription_process_payment
3. smartpay_update_payment_status
4. smartpay_update_subscription_status
5. init

WPSmartPay provides two types of payment support, which are Simple Payment and Recurring Payment. But before making a transaction, you should process the payment data according to your payment gateway. This hook will be called when user will choose to pay with you payment gateway using ajax. Let’s briefly discuss with this action with examples.

First invoke the action:

add_action(‘smartpay_example_ajax_process_payment’, ‘ajax_process_payment’);

[N. B] – ‘example’ is the gateway ID, which you have used on registering your gateway using a filter hook ‘smartpay_gateways‘.

In this action, you see the action name ‘smartpay_example_ajax_process_payment’. You should replace the ‘example’ with your gateway name, which name you have registered to the integration. For this case, we give the name is custom. Next, our call function named ‘ajax_process_payment’. In your case, it can be different.

function ajax_process_payment($payment_data)     {         // do staff to process the payment     }



In the above example, the method parameter is taken by ‘smartpay_example_ajax_process_payment’ hook. $payment_data will provide all the necessary information needed to process the payment. This is an array of contains a bunch of data:

• payment_type(string) – ‘form_payment’ or ‘product_payment’
• payment_data(array): 

• form_id(integer)
• total_amount(): price
• billing_type(string): ‘Subscription’ or ‘One Time‘

• date(string): current timestamp(ex: 2022-02-26 06:57:35)
• amount(): payable amount
• currency(string): selected currency(ex: USD)
• gateway(string): selected gateway name (ex: stripe)
• customer(array): customer information

• customer_id(integer)
• first_name(string): Customer first name
• last_name(string): Customer last name
• email(string): Customer email
• email(string): Payment email

In this method/function, you must store the payment information to the SmartPay payment records to update the payment status/information for future. 

You can do it by a function called ‘smartpay_insert_payment’. See an example:

smartpay_insert_payment($payment_data);



At the end of the docs, we will provide an example code that may help you to implement your integration in proper way.

Another important hook is called ‘smartpay_example_subscription_process_payment’ to process the recurring payment, or we can call the subscription payment which will be recurring on given period of time.

add_action(‘smartpay_example_subscription_process_payment’, ‘subscription_process_payment’, 10, 2);



As the same for ‘smartpay_example_ajax_process_payment‘ hook, you must change the ‘example’ with your registered gateway name, like

add_action(‘smartpay_example_subscription_process_payment’, ‘subscription_process_payment’, 10, 2);

[N. B] – ‘example’ is the gateway ID, which you have used on registering your gateway using a filter hook ‘smartpay_gateways‘.

Now look at the callback function:

function subscription_process_payment($payment, $paymentData)     {         // staff for subscription payment processing     }



You will get the created payment instance and paymentData(which was already discussed above). You should create a SmartPay subscription in this method. Like:

function subscription_process_payment($payment, $paymentData)     {         $subscription = new Subscription();         $subscription->period               = $paymentData[‘billing_period’];         $subscription->recurring_amount     = $paymentData[‘amount’];         $subscription->parent_payment_id    = $payment->id;         $subscription->status               = Subscription::STATUS_PENDING;         $subscription->save();     }



From the example, you can use Subscription model to store the subscription information, but for that you will need WPSmartPay Pro to get the subscription model. 

The next hook is responsible for updating payment status, which is ‘smartpay_update_payment_status’. 

add_action(‘smartpay_update_payment_status’, ‘payment_refund_and_subscription_cancel’, 10, 3);



function payment_refund_and_subscription_cancel($payment, $newStatus, $oldStatus)     {         // cancel the subscription and update     }



Let’s dive into updating payment status. Three parameters are available to update the status. 

• $payment(object) – Payment model
• $newStatus(string) – selected status or new status of payment
• $oldStatus(string) – old status of current payment instance

The another one is ‘smartpay_update_subscription_status’. using this hook you can update the subscription status as update status of payment.

add_action(‘smartpay_update_subscription_status’, ‘subscription_cancel’, 10, 3);



Callback action:

function subscription_cancel($subscription, $newStatus, $oldStatus)     {         // do staff of updating subscription status     }



Let’s dive into updating subscription status. Three parameters are available to update the status. 

• $subscription(object) – Subscription model
• $newStatus(string) – selected status or new status of subscription
• $oldStatus(string) – old status or new status of subscription

We have integrated the payment gateway integration. 🙂

For updating real-time payment, you should implement webhook by using ‘init’ hook. As an example:

add_action(‘init’, ‘process_webhooks’]);



Callback function for webhook:

function process_webhooks()     {         // process the webhook according to listener     }



This is a last section for the implementation of your payment gateway integration and you should need to know. We are going to discuss the payment status that SmartPay provides.

Available status of SmartPay Payment:

• pending – default status or webhook is not responded to update the status
• completed – If payment is completed by Payment gateway
• refunded – If payment is fully refunded
• failed – If the payment is not processed somehow
• abandoned – when payment is abandoned
• revoked – when payment is revoked 
• Processing – when payment is process, mostly happened while payment refund is called

Available status of SmartPay Payment:

• pending – default status or webhook is not responded to update the status
• active – recurring is activated, and it will charge given time period
• cancelled – subscription is cancelled and will no longer be continued
• expired – subscription is expired and will not charge anymore
• trialling – when subscription is on trial
• failing – subscription is failed with a valid reason
• completed – subscription is completed
• suspended – subscription

Subscription billing period that are available on WPSmartPay:

• Daily
• Weekly
• Monthly
• Every 3 Months
• Every 6 Months
• Yearly

We have another hooks available that may help you-

1. ‘smartpay_payment_completed’ – payload – $payment
2. ‘smartpay_payment_cancelled’ –  payload – $payment
3. ‘smartpay_before_payment_receipt_data’ – payload – $payment
4. ‘smartpay_before_payment_receipt_data’ – payload – $payment

[N. B: payload of $payment data is already described on above section]

After completing the setup correctly, you will get your payment gateway to make a payment.

You can follow the example code on Github

Currently, It is in beta stage. If you face any issue with the example code or documentation, please send your feedback to us. Your cooperation is highly appreciated.