Using Modal Forms in Checkout

Some payment vendors provide the API to embed checkout forms by integrating JavaScript files into merchants' pages. There are some notes on how to build a plug-in with an integrated JS file:

1. For Billing to recognize that a plug-in supports embedding, the %PluginName%_GoModal() function must be present in the plug-in code. When called, this function returns an array that contains:
   • status MODAL, and
   • array MODAL_FORM array that contains the values of the checkout_script_section, checkout_script_src, checkout_script_handler, and checkout_script_htmlparameters (the last parameter is optional).

2. The values from the MODAL_FORM array are used when opening a modal form. They are injected into HTML code on the front-end as a hidden HTML <div> element. An example of such a <div> element is:

   <div id="{checkout_script_section}" style="display:none">
   <script src="{checkout_script_src}"></script>
   <script>
   function completion_handler() {
   // some cleanup code here
   }
   {checkout_script_handler}
   </script>
   {checkout_script_html}
   </div>

3. The original - provided by payment gateway vendors - template forms must be used for integration with checkout (e.g., https://online.worldpay.com/docs/template-form).
4. In Billing UI, a dynamic code generation is used, and the content is almost never refreshed. Thereby, it is REQUIRED that checkout_script_handler perform the cleanup on the modal form close: specifically, the data contained in the injected HTML code in <div> by id="checkout_script_section".

5. The workflow of a payment for a modal form plug-in:

   

6. After a payment is submitted, the data that received in the callback from a payment system can be passed to the plug-in by a POST or GET request to the notify_url parameter of the %PluginName%_GoModal() function.
7. After a successful payment submission, the completion_handler() function must be called to close the order confirmation pop-up. Do not call this function in case of a failed submission or closed form, in order to allow repeat submission or change a payment method.
8. Only the "application/x-www-form-urlencoded" content type is currently supported for POST requests.
9. For the comments in checkout_script_handler code, the /* */ must be used.