Paycoinly Wordpress Plugin Actions, Filters and Shortcode

The Paycoinly plugin provides several filters, actions and shortcode which allow you to extend and customize its payment processing functionality to meet your specific requirements.

Glossary

• Woocommerce payment refers to a payment initiated by clicking the Place Order button on the Woocommerce checkout page.
• Wordpress payment refers to a payment triggered via the paycoinly shortcode on Wordpress page other than the Woocommerce checkout page.

Actions

paycoinly_before_handle_wc_payment

This action is triggered just before your platform records customer's Paycoinly payment in the callback endpoint. It is used for Woocommerce payments only.

add_action('paycoinly_before_handle_wc_payment', 'before_handle_wc_payment');

function before_handle_wc_payment($payload) {
  // invoke your custom operation
  print_r($payload);
  echo $payload['order_id'];
  echo $payload['user_id'];
  echo 'woocommerce is going to record the payment';
}

Arg	Type	Description
payload	array('order_id' => string, 'user_id' => string)	Paycoinly invokes the callback endpoint, including the following data in the request body. order_id and user_id are corresponding values in your Woocommerce store

paycoinly_handle_payment

This action is triggered just after your platform records customer's Paycoinly payment in the callback endpoint. It is used for both Wordpress and Woocommerce payments.

add_action('paycoinly_handle_payment', 'after_handle_payment');

function after_handle_payment($payload, $mode) {
  // invoke your custom operation
  print_r($payload);
  echo $payload['order_id'];
  echo $payload['user_id'];

  if ($mode == 'wc') {
    echo 'woocommerce recorded a payment';
  } else {
    echo 'wordpress recorded a payment';
  }
}

Arg	Type	Description
payload	array('order_id' => string, 'user_id' => string)	Paycoinly invokes the callback endpoint, including the following data in the request body. order_id and user_id are corresponding values in your Woocommerce store
wc	string	wc if the payment is for Woocommerce, otherwise wp

Filters

paycoinly_order_price

This filter is used to calculate price of the order before Paycoinly shows payment UI to your customers. It is used for Wordpress payments only. Please refer to Wordpress Integration page to get more understanding and workflow of it.

Example

add_filter('paycoinly_order_price', 'get_order_price', $order_id);

function get_order_price($order_id) {
  // calculate the price based on $order_id
  if ($order_id == 'basic') {
    return 10;
  } else if ($order_id == 'pro') {
    return 30;
  } else if ($order_id == 'enterprise') {
    return 50;
  }
}

Arg	Type	Description
order_id	string	Data on which you want to calculate the price based. order_id is passed from shortcode

Shortcodes

paycoinly

You can place Paycoinly UI using paycoinly shortcode in any page. Here you can see arg details of the short code. All args are optional.

Arg	Default	Description
order_id	Empty string	The price is determined by order_id
on_complete	console.log(event.data.payload);	Javascript code which will be triggered on payment success in frontend. Premium subscription is required.
redirect	Empty string	Paycoinly payment UI will redirect to this URL after completion
html	<img src='https://app.paycoinly.xyz/logo/dark.svg' style='width: 5em;' />	Your custom HTML to render inside the button
class	Empty string	Your custom class name to render the button with
style	Empty string	Your custom style to render the button with

Success handler and redirection

By default, the Paycoinly UI launches the payment UI in a popup when triggered, and on_complete handler is executed on payment completion if you are subscribed to the Premium plan.

However, if the redirect argument is provided, the payment flow is handled via a full-page redirect instead. Upon successful completion of the payment, the user is then redirected to the URL specified in the redirect argument. Flow specified by on_complete argument is ignored in this case.

Price Determination

You need to decide price from order_id by hooking into paycoinly_order_price filter.

Security Tip

It is not safe to use order_id as direct price data when calling the shortcode, since a malicious user could manipulate it to pass any arbitrary amount. To ensure the integrity of your payments, always pass the order ID (or service ID) from the shortcode, and have your backend determine the correct price for that order by using the paycoinly_order_price filter.

You can see an example usage in the below.

[paycoinly order_id="premium" class="wp-element-button" redirect="/thank-you" html="<div>Pay in Paycoinly</div>" on_complete="console.log('hi');"]

info

The shortcode args should be called in one line.

Best practices

This section also describes best practices for hooking into the above actions and filters.