A plugin is a collection of PHP scripts that implements payment operations, configuration and information functions. The pattern of communication is given in the figure below:
The payment-sdk microservice is responsible for registering a plugin and make it available to the Billing system. The payment-sdk accomplishes it by exposing a Payment API to Billing, which calls the Payment API both to register and communicate with a plugin. Note that Billing does not call a plugin method directly, but through the Payment API.
The payment-sdk microservice is supported by a special instance of the Apache web server. Within this instance, a single index.php script receives HTTPS requests from Billing, detects, for each of those requests, which plugin and method Billing sent a request to, and dispatches that request to the detected pair plugin-method. The index.php script is also responsible to convert request and response data from JSON to PHP array, and vice-versa. The plug-in functions take an array of parameters and return an array with operation result data.
Each plugin is a folder that contains a special structure (see Location and Naming Convention). The plug-in script file (the one that has the same name as the folder) implements all required methods using the following method naming convention: $(PLUGIN_NAME)_$(METHOD_NAME). For example, the Stripe plugin must implement the GetConfig method in the Stripe.php script using the Stripe_GetConfig method name. The index.php script uses this convention to tell Billing all methods that could be called in a specific plugin. Failing to follow this convention causes Billing to not recognize some plug-in capabilities. For a list of methods that a plugin must implement, refer to Description of Methods .
Once a plugin receives a request from Billing, it can execute the PHP5 code needed to accomplish that request. If a communication with a Payment Gateway API is Mandatory to fulfill the request, the plugin can use whatever communication schema (for example, REST, SOAP) and data format (for example, JSON, XML) it finds convenient. The plug-in method response, however, must be an associative array and must contain some Mandatory keys (see each method description for further details).
Installing a new plugin is as simple as copying the plug-in folder to a special folder (that is, /custom) inside the payment-sdk microservice. For further details, check Plugin Installation.
A plug-in developer must be aware that:
-
Plugins are always passive in their communication with CloudBlue Commerce.
-
Plugins do not need to store any configuration parameters or transactional data themselves. CloudBlue Commerce provides all necessary means for this.
-
Plugins do not need to write logs to the file system directly; CloudBlue Commerce provides special utility functions for this.
Overall, the communication between Billing and a plugin happens as in the following diagram:
Plugin Registration
Billing starts the plugin registration when:
-
A provider logs in for the first time.
-
A provider accesses the Payment Gateways tab (Provider Control Panel > Billing > Settings > Payment Processing).
During the plug-in registration process, Billing calls the payment-sdk microservice and gets the list of all installed plugins. For each installed plugin, Billing registers the plugin and its capabilities (that is, the method it implements) in the Billing database. If Billing detects that the plugin is already registered, Billing checks its capacities and updates the Billing database accordingly. If the plugin implements:
-
Redirect method, Billing creates a new Payment System (
$(PLUGIN_NAME).Redirect) of the External Payment Site type. -
GoModal method, Billing creates a new Payment System (
$(PLUGIN_NAME).Modal) of the Modal Form type. -
Redirect or GoModal method and also Sell or Auth method (meaning that the plugin supports a token; see Tokenizing a Payment Method), Billing creates a new Payment System (
$(PLUGIN_NAME).Token) of the Custom type.
For each Payment System created and currency supported by the plugin (the GetSupportedCurrencies method), Billing registers a Feature (Provider Control Panel > Billing > Settings > Payment Processing > Plugin > Features).