Using the Jetpay for Bitrix CMS plug-in

Installing the plug-in

1. Download file with the Jetpay plug-in here.
2. Open Bitrix CMS.
3. Open the folder with Bitrix CMS modules in the following order:

   Select the Content tab, then select Site Explorer > Files and Folders and click the bitrix > modules.

4. Create the jetpay folder inside the bitrix/modules directory in the following order:

   Select Add > Add folder to open the following page:

   
   
   

   Copy the folder name—jetpay—into Section name and Folder name fields and make sure that Create index page for this section checkbox is cleared. Click Save.

5. Extract plug-in archive content into the bitrix/modules/jetpay folder following these steps:
   1. Click the jetpay folder
   2. Click Upload file.
   3. Click Add file on the page that opens.
   4. Select the archive with the plug-in, and then click Save button.
   5. Right-click the uploaded archive and select Extract files.
   6. Click Unpack button on the modal window that opens.

   Make sure that the structure of files and folders after archive unpacking looks like this:

   
   
   

   If the structure is different, move unpacked files and folders into the /bitrix/modules/jetpay folder.

6. Activate the installed plug-in in the following order:

   Select Settings tab, and then select System settings > Modules and click Install in the line with the Jetpay module.

   Once you complete these steps, the plug-in status will change to Installed.

Creating and setting up a payment handler

1. Create a new payment handler:

   To do this, select e-Store tab, and then select Settings > Payment systems and click New payment system.

2. Set up the new payment handler look-and-feel by entering the following parameters:
   • Handler—select Jetpay in the dropdown list
   • Payment system—handler title which will be shown to the customer on the page with payment methods
   • Description—description of the payment handler, optional

   If needed, you can upload a payment handler logo to show to the customer on the page with payment methods.

3. Configure the payment handler parameters:
   • Project ID—project ID you obtained from JetPay
   • Secret salt—value of the secret_key parameter you obtained from JetPay
   • Terminal language—language code according to ISO 639-1 alpha-2. If you leave this box empty, language of Payment Page is determined by customer's device IP address
   • Additional params—additional parameters according to Payment Page API. To specify two or more parameters, use "&" as separator. For more information about parameters supported by Payment Page, see Payment Page invocation parameters
   • Test mode—specify whether Payment Page to run in test mode. Possible options: Yes and No. If you leave this box empty, test mode will not be applied
   • Modal mode—specify whether to open Payment Page in a modal window. If you leave this box empty, Payment Page will be opened in an iframe
   • Display the page of selecting a payment method—specify whether to show the payment method selection screen. If you leave this parameter empty, customer will be asked to pay by a card
   • Pass customer ID—specify whether the plug-in will pass passes the customer ID in the payment request. You are required to select this checkbox for the plug-in to operate correctly.
     Note: If the payment is made by unauthorized customer, customer ID is not passed in the payment request.
4. Configure the parameters in the Status section. These parameters define how the status of the order in Bitrix CMS changes when the status of the corresponding payment in JetPay is updated.
   • Status "Paid" (one-stage payments)—use this parameter to select the status to automatically apply to the order after the payment is successfully completed, for example Paid.

     In other words, once the payment status changes to success, the status of the corresponding order in Bitrix CMS will change to the status specified in this parameter. This parameter is applicable only to one-step purchase.

   • Authorized payment status (two-stage payments)—use this parameter to select the status to automatically apply to the order in Bitrix CMS after the customer card is authorized in a two-step purchase process, for example Purchase authorized.

     Once the payment status changes to awaiting capture, the status of the corresponding order in Bitrix CMS will change to the status specified in this parameter. This parameter is applicable only to two-step purchase.

   • Payment authorization confirmation status (two-stage payments)—use this parameter to select the status to automatically apply to the order after the authorized amount is captured in a two-step payment procedure, for example Purchase captured.

     Once the payment status changes to success, the status of the corresponding order in Bitrix CMS will change to the status specified in this parameter. This parameter is applicable only to two-step purchase.

   • Authorized payment cancellation status (two-stage payments)—use this parameter to select the status to automatically apply to the order after the purchase is canceled in a two-step payment procedure, for example Purchase canceled.

     Once the payment status changes to canceled, the status of the corresponding order in Bitrix CMS will change to the status specified in this parameter. This parameter is applicable only to two-step purchase.

   • Payment error status (two-stage payments)—use this parameter to select the status to automatically apply to the order after the purchase is canceled in a two-step payment procedure, for example Error.

     Once the payment status changes to internal_error or external_error, the status of the corresponding order in Bitrix CMS will change to the status specified in this parameter. This parameter is applicable only to two-step purchase.

5. Click Save.

Configuring callback receiver

To automatically change the payment status of the order, you need to specify how to receive callbacks from Jetpay.

To configure callback receiver:

1. Open the tab Content, and then select Site Explorer > Files and Folders
2. Create the callback receiver file.

   To do so, select Add > Add file.

   Enter jetpay.php in the File name box and copy the following code into the text box:

   <?php
   require($_SERVER["DOCUMENT_ROOT"] . "/bitrix/modules/main/include/prolog_before.php");
    
   $APPLICATION->IncludeComponent(
       "bitrix:sale.order.payment.receive",
       "",
       Array(
           "PAY_SYSTEM_ID" => "22",
           "PAY_SYSTEM_ID_NEW" => "22"
       )
   );
    
   require($_SERVER["DOCUMENT_ROOT"] . "/bitrix/modules/main/include/epilog_after.php");
   ?>

   Set the PAY_SYSTEM_ID and PAY_SYSTEM_ID_NEW parameters to JetPay payment system ID. You can find the ID in the ID column on the corresponding row of the table in the following section: e-Store > Settings > Payment systems

3. Give the Jetpay technical support the URL you will use to receive callbacks.

   If you place the jetpay.php file into the root directory of your site, the URL for receiving callbacks will look like this:

   https://<full_domain_name>/jetpay.php

   If the jetpay.php file is located not in the root directory of your site, the URL for receiving callbacks will look like this:

   https://<full_domain_name>/<directory>/jetpay.php

Configuration

Making test orders

Once the parameters of the plug-in are configured, you can make test orders on the site and check the orders information in Bitrix CMS in the e-Store > Orders section.

Receiving the parameters for the production mode

To receive the parameters to integrate with the JetPay payment solutions, do the following:

1. Contact JetPay technical support and provide the following parameters:
   • The site name and site URL
   • The payment page currency
   • The URL to receive callbacks
2. Receive from JetPay technical support the following parameters:
   • Project ID—site identifier
   • Secret salt—secret key that is generated for a particular merchant in the JetPay processing system

Configuring the operational parameters

1. Open Bitrix CMS
2. Select e-Store > Settings > Payment systems
3. Select Jetpay and configure the operational parameters:
   • Select No in Test mode
   • Enter values for Project ID and Secret salt which you received from JetPay technical support
   • Make sure that the remaining parameters are set as required
   • Make sure that the Pass customer ID checkbox is selected
4. Click Save.