Exposing Payment Options in the Checkout Block

A while ago, we announced the public availability of developer documentation covering the integration of payment methods with the Cart and Checkout Blocks. This time, we will show you an example that includes the necessary client side (JS) and server side (PHP) components involved in exposing a payment gateway in the new Checkout Block. 

Note: If this is the first time you are developing a payment gateway plugin for WooCommerce, please start with this guide.

Getting Started

To make this guide easier to follow, we have created a “dummy” payment gateway that allows you to place orders without paying. When you activate the plugin, a new gateway called “Dummy Payment“ will be added to your store. The plugin works both with the Checkout Block and the checkout shortcode.

Before diving into the code:

1. Ensure that the WooCommerce Blocks plugin is installed and activated on your site.
2. Clone our plugin’s GitHub repository inside the /wp-content/plugins directory of your WordPress installation.
3. Log into your WordPress dashboard.
4. Under the Plugins menu, locate and activate the WooCommerce Dummy Payments Gateway plugin that you just cloned.
5. Navigate to WooCommerce > Settings > Payments and confirm that the Dummy Payment gateway is activated.

Note: The Dummy Payment gateway provides a Payment result option that you can use to control if the payment gateway will be able to process your test payments successfully, or not.

Server-side Integration

Enqueuing Scripts

To integrate our payment gateway with the block-based checkout, we created this class that extends Automattic\WooCommerce\Blocks\Payments\Integration\AbstractPaymentMethodType.

This ensures that you can register any assets and data to pass along to your client side payment method from the server and handles the correct loading order of those assets.

Class Properties

• name — holds the name of our payment gateway.
• gateway — stores an instance of the payment gateway object.

Class Methods

• initialize() — populates the gateway settings and initializes the gateway property. 
• is_active() — determines if the gateway is active or not. 
• get_payment_method_script_handles() — calls wp_register_script() to register the payment gateway scripts.
• get_payment_method_data() — returns an associative array with all the data we want to use in the front end.

Processing Payments

The Checkout Block was built to provide legacy handling for payment processing: It converts incoming payment_data provided by the client-side payment method to $_POST and calls the payment gateway’s process_payment function. 

If you already have a payment method extension integrated with the existing shortcode checkout flow, the Checkout Block will take care of processing your payment for you on the server side. However, If your payment method hooks into the core checkout process_checkout function in any way, you will need to make some adjustments. 

Registering our Integration

Time to register our integration. To do this, we hooked a callback on the woocommerce_blocks_payment_method_type_registration action. This callback receives an instance of Automattic\WooCommerce\Blocks\Payments\PaymentMethodRegistry which provides a register() method for registering an instance of the AbstractPaymentMethodType class that we created earlier.

Front-end Integration

At this point, we can go ahead and implement our front-end code. This script should register a JavaScript object with options specific to the payment gateway using the registerPaymentMethod function. For more details about this, please refer to this document from the WooCommerce Blocks repository.

If you take a closer look at our payment gateway configuration object, you will notice that it contains:

• a Label component, which is used to display the gateway name, 
• a Content component, which is used to display the gateway description, 
• a callback to determine whether the payment method should be available as an option;
• a list of supported features.  

Here’s how we accessed the data that we previously exposed to the front end:

import { getSetting } from '@woocommerce/settings';
const settings = getSetting( 'dummy_data', {} );

Or, if your integration does not require you to write ES6 or React, you could also write:

var settings = wc.wcSettings.getSetting( 'dummy_data' )

Note: In your own integration, replace dummy with the value of the name property, as defined in the PHP class.

This example demonstrates how you can use the canMakePayment() callback to control the availability of your payment method in the Checkout Block. In this example, “Cash on Delivery” excludes itself when the order contains virtual products. 

Note: The Checkout Block also allows plugins to conditionally exclude payment options. To learn more, have a look at this guide.

Building our JavaScript Code

To build the plugin you just cloned and activated:

1. Ensure that you are using node version 14.18+ with npm version 6.14.
2. Run npm install followed by npm run build.

Note: The build tools included in the Dummy Payments Gateway repository assume that your script will include some ES6 or React. However, this is not necessary.

Note: If you are already using a task runner to build your plugin’s assets, and want to build upon what you already have, check out this example. This demonstrates how you can use wp-scripts to build modern JavaScript as part of an existing build process based on Grunt.

Next steps

In this example, we covered the basic scaffolding involved in exposing a payment method such as cheque, PayPal Standard, or Stripe Credit Card in the Checkout Block. In addition to this, the payment method integration API also allows you to register express payment methods that consist of a one-button payment process initiated by the shopper, such as Stripe, ApplePay, or GooglePay.

If you haven’t done so already, this is a great time to start integrating your payment gateways with the Cart and Checkout Blocks: Store owners using WooCommerce for the first time will soon have the block-based checkout installed as part of our guided store setup experience.

Already started, but are having trouble integrating your payment method? Our engineers are available for technical guidance in the WooCommerce Blocks repository. Feel free to open an issue to ask for assistance, or share your findings and feedback.