--- url: >- https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/integrate/zenCart/index.md description: >- ZenCart-PPPay Plugin Installation Guide provides detailed steps for integrating PPPay payment plugin on ZenCart platform. Compatible with ZenCart 1.7 and above versions, requires PHP 7.1 and its extensions. The document covers the entire process from file upload to environment parameter configuration, emphasizing the importance of order number uniqueness and monotonic increment. --- # ZenCart-PPPay Plugin Installation Guide ### Installation Prerequisites > - ZenCart version>=1.7 > - php version >=7.1 > - php Extensions:curl bcmath > - chmod 777 /zenCartRoot/logs --- The following are non-essential settings, if 504 error occurs, you can check the following options - [ ] php ini execution timeout - [ ] nginx or apache execution timeout settings --- ::: danger 1. Order numbers under the same accId cannot be duplicated, must be monotonically increasing, otherwise will cause order status issues; 2. Orders from different databases cannot share the same accId; 3. If there have been transactions under accId, before installing the plugin, the id start value should be set to greater than the current maximum order id; 4. After resetting database, store, or migrating accId to another store, you should check the maximum order number under accId. ::: ### ### ZenCart Installation Path Rules #### Extract Files After extraction, the directory structure is as follows. These four directories correspond to the directories under zenCart/inclues. ![image.png](/zencart/1629463595657-e90b21d9-ff38-4fe4-8a28-b1941f5be7df.png) ### Installation Process #### Login to FTP Use FTP tool to connect to server, upload plugin zip package. If no FTP tool available, you can use command line, use powershell under windows. SFTP command - connect to remote server: ```shell:line-numbers title="terminal" sftp username@ip # [!code focus] ``` #### File Upload If no FTP tool available, use SFTP command - upload files to server: ```shell:line-numbers title="terminal" put [local file path] [server file storage location] # [!code focus] ``` #### File Extraction Use unzip command ZenCart-PPPay comes with complete directory structure, the plugin after extraction contains inclues/ directory, after extracting in zenCart root directory, plugin files will automatically merge to existing files. ### Configuration Process #### Login to Website Backend Go to page `Modules->Payments->PingPongCheckout` ![image.png](/zencart/1629465534493-004c763c-8f10-4b14-b668-fb1ffcd7d3fa.png) #### Install and Enable Module Select module `PingPongCheckout`, and click install ![image.png](/zencart/1629465589636-05ede39b-fb30-4200-850c-042ce15b678f.png) #### Configure Environment Configure payment environment parameters as shown in the image below. ![image.png](/zencart/1629465797236-c80930dd-85e0-4550-9aed-e502bcb2e4c5.png) #### Save Configuration ![image.png](/zencart/1629465944926-5bb4e5c2-cfa4-4b82-8b72-656d4a963a86.png) ### Environment Parameters #### Sandbox Environment Store Parameters ```ini:line-numbers title="config/sandbox.ini" clientId: 2018092714313010016 # [!code focus] accId: 2018092714313010016291 # [!code focus] salt: F78BC96A55548B2319EE68E0 # [!code focus] ``` #### Sandbox Environment Test Card Numbers ```text:line-numbers title="config/test-cards.txt" Card Number: 4200000000000000 Expiry: 12/22 cvv: 123 cvv must be 3-digit pure numbers 3DS transaction card: 4711100000000000 ``` #### Environment URLs ```text:line-numbers title="config/environment-urls.txt" Sandbox Environment https://sandbox-acquirer-payment.pingpongx.com Production Environment https://acquirer-payment.pingpongx.com ``` ### Integration Process #### Sandbox Environment Integration 1. Install plugin according to file instructions. 1. After plugin installation is complete, payment self-testing is required, and complete the following items: - [ ] Screenshot of card number input page - [ ] Screenshot of final redirect page after payment completion - [ ] Send screenshots to integration group and notify technical support If any issues occur during installation process, you can seek technical support in the integration group. --- Notes: > In sandbox environment, no deduction will be initiated from cardholders, shipping after payment will cause losses, not shipping may result in complaints from cardholders. Therefore during integration, operations need to be cautious, after integration testing is passed, immediately close payment channel, wait for production environment launch before opening. --- #### Production Environment Integration 1. After the plugin completes the first round of sandbox environment integration under technical support, it will enter the website information and account review stage, after passing, production environment parameters will be issued. 1. After obtaining production parameters, complete the following items - [ ] Replace sandbox environment parameters with production parameters. - [ ] Self-test payment and complete screenshots - [ ] Prepare a $1 product link. 3. Send screenshots and product link, and notify technical support, customer/technical support will initiate real transaction test on this product link to verify integration results and website payment availability. 3. After completing real transaction test, merchant needs to initiate refund to verify refund process. 3. After completing above process, website integration ends, payment channel officially launches, payment becomes available. ### Production Environment Configuration #### Review Process Get notification from integration group or business/customer that review is passed. Login to [Merchant Backend](https://pay.pingpongx.com/aq/websiteList) ```text:line-numbers title="urls/merchant-backend.txt" https://pay.pingpongx.com/aq/websiteList ``` #### Go to Website List As shown in the figure, go to Group Management->View Details->Website List #### Group Management > - ⚫ Select from menu bar 【Website Management】-【Group Management】to enter group management page > - ⚫ This function allows current merchant to click "Create Group" to create new group; system will provide a default group by default > - ⚫ Websites are under groups. > - ⚫ Click "View Details" to enter group details page, can modify group name, view and copy ID number, view websites under group. ![image.png](/zencart/1629468866673-c4edef47-9708-4141-959c-feab1b3f6c26-20210821003240351.png) #### Select Website Based on current integration website domain name, select corresponding website from the list ![image.png](/zencart/1629468928427-be88d189-e850-4479-a279-f853446fc371-20210821003248766.png) #### Get accId for corresponding domain website ![image.png](/zencart/1629468994781-7e5ba639-38ca-4593-a6cb-a3d213d71bb0-20210821003259460.png) #### Get Secret Key > Select from menu bar 【System Management】-【Secret Key Management】to enter secret key management page by default, can view website secret key on this page. After entering secret key management, can view secret keys corresponding to all websites, click "Secret Key Details" to view specific > secret key fields. > Secret keys with status "Normal" can be used, when status is "Abnormal", they cannot be used and can contact relevant business personnel for handling. ![image.png](/zencart/1629469253929-79e2ba85-c8c9-460f-bb79-e6b9301ae557-20210821003307842.png)