How to integrate your NetSuite with PencilPay

Prerequisites

1. You need a NetSuite account with:
   
   1. Integration User: This user must be a NetSuite Administrator user account.
   2. Note down your NetSuite ID, which is the numbers at the start of your URL.
2. Log in with your NetSuite Administrator user account and check the Web Services configuration:
   1. First we check the "REST Web Services". To do this, go to: Setup > Company > Enable Features > SuiteCloud > SuiteTalk (Web Services): REST Web Services needs to be checked
   2. Then we check the "Authentication". Go to: Setup > Company > Enable Features > SuiteCloud > Manage Authentication: TOKEN-BASED AUTHENTICATION needs to be checked
   3. Then check that "SuiteScript" is enabled. Go to Setup > Company > Enable Features > SuiteCloud > SuiteScript: check all 3 options.
      
3. Next, create ‘PencilPay API’ role with the below permissions at 'Full' level. This role will be used for the PencilPay API user that will be created in step 4 below.
   1. Go to: Setup > Users/Roles > Manage Roles > New
   2. Enter Name: PencilPay API
      
   3. In the Transactions tab select all the below options:
      1. Bills
      2. Credit Memo
      3. Customer Deposit
      4. Customer Payment
      5. Customer Refund
      6. Deposit
      7. Find Transaction
      8. Invoice
      9. Journal Approval
      10. Make Journal Entry
      11. Pay Bills
          
          
          
   4. Then click on Reports tab
      1. Select the "SuiteAnalytics Workbook" from the dropdown and click Add then Save.
         
         
         
   5. Click on the Lists tab and select all the below options:
      1. Accounts
      2. Contacts
      3. Currency
      4. Custom Record Entries
      5. Customers

      6. Documents and Files

      7. Locations
      8. Record Custom Field
      9. Subsidiaries
      10. Tax Records
      11. Vendors
          
          
          
   6. Click on the Setup tab and select all the below options:
      1. Access Token Management
      2. Accounting Lists
      3. Log in using Access Tokens
      4. REST Web Services

      5. SuiteScript

      6. User Access Tokens
      7. Click Save. 
         
4. Next we need to create the ‘PencilPay API’ account. If additional users will incur extra NetSuite licensing costs you can use an existing user that has Admin permissions and skip this step and go to Step 5 below.
   1. To do the go to: Lists > Employees > Employees > New
   2. In Name enter: PencilPay API
      
   3. Give access and Add the ‘PencilPay API’ role
      
   4. Click Save.
5. Now we need to register the ‘PencilPay API’ client in NetSuite.
   1. To do this, go to: Setup > Integration > Manage Integrations > New
   2. Enter Name: PencilPay API
   3. Under Token-based Authentication select: TOKEN-BASED AUTHENTICATION
   4. Please copy the CLIENT ID and CLIENT SECRET somewhere save as you will use this to enter into the PencilPay NetSuite integration page.
      
   5. Click Save. 
6. Now we need to create an Access Token
   1. To do this, go to: Setup > Users/Roles > Access Tokens > New
   2. Under APPLICATION NAME enter: 'PencilPay API'
   3. Select the USER: 'PencilPay API' user account
   4. Select the ROLE: 'PencilPay API' TOKEN-BASED AUTHENTICATION user role
   5. Please copy the TOKEN ID and TOKEN SECRET somewhere save as you will use this to enter into the PencilPay NetSuite integration page.
      
   6. Click Save.
7. How to set up the Customisation Scripts.
   
   There are two options:
   
   1. Option 1: Use Pencil's custom build script.

      1. To install Pencil's already defined bundle to your NETSUITE account, please follow these steps:

         1. In NetSuite go to: Customisation > SuiteBundler > Search & Install Bundles
            

         2. Click on 'Advanced' tab
            
            

         3. In the search box search for the following bundle in the Production Account ID: Pencil

         4. In the bundle: PencilPay Netsuite Bundle, click the "Install" button.
            

         5. Then click the "Install Bundle" button and Confirm
            
         6. Next scroll down to the very bottom of this page to "8. Final Steps to configure in PencilPay" and complete the last steps.
   2. Option 2: Manually create a RESTlet script.
      1. To do this, log into PencilPay and go to Integrations -> NetSuite -> scroll down the bottom of the configuration page and download this JS file: netsuite_pencil_restlet_script.js file
         
      2. Add the script file to the file cabinet
         1. To do this go to: Documents > Files > SuiteScripts > New
            
   3. Next you need to create the PencilPay RESTlet script record.
      1. To do this go to: Customisation > Scripting > Scripts > New
         
      2. Enter Name: PencilPay RESTlet
      3. ID: customscriptpencilpay_restlet
      4. Click Save.
   4. Create the script deployment record. To do this, on the Script review page, click on 'Deploy Script' to create script deployment record.
      
   5. Check the details:
      1. Title: PencilPay RESTlet
      2. ID: customdeploypencilpay_restlet
      3.  Status: Released
      4. Audience
         1. Roles: select All
         2. Employees: select All
   6. Click on Save. 
   7. Then we can update Deployments for this script: PencilPay RESTlet
      1. To do this go to: Customisation > Scripting > Scripts
         
      2. Search for: PencilPay RESTlet
         
      3. Click on View.
      4. In the top right corner click on: More -> View Deployments
         
         
      5. Click Edit.
         
      6. Update the Audience: 
         1. Select Role: All or ‘PencilPay API’ and any other roles you would like the users with these roles to push customer and invoice data from NetSuite to Pencil immediately via the web hook (otherwise you may wait up to 3 hours for the data to sync); OR
         2. Select Employees: All or ‘PencilPay API’ and any other Employees you would like the users with these roles to push customer and invoice data from NetSuite to Pencil immediately via the web hook (otherwise you may wait up to 3 hours for the data to sync); 
            
      7. Please copy down the External URL and save it securely as you will use it on the configuration page in PencilPay's NetSuite integration page.
   8. Now we need to create a User Event script 
      1. To do this log in to PencilPay and go to: Integrations -> NetSuite -> scroll down to the bottom and download this JS file: netsuite_pencil_webhooks_user_event_script.js
         
      2. Next we need to add the script file to file cabinet:
         1. To do this go to: Documents > Files > SuiteScripts > New
         2. Click "Add File" -> select the file and click the "Open" button to add the file.
            
         3. Click on Save.
      3. Then we need to create three script records; one each for the Create, Edit and Delete events:
         1. To set up the first "Create" script, go to: Customisation > Scripting > Scripts > New
         2. In the "File Name" field type: "netsuite_pencil_webhooks_user_event_js" or type the start of this file name and then select it.
            
         3. Click "Create Script Record"
         4. On the next page copy and paste these details:
            
            1. Name: PencilPay Webhooks Create
            2. ID: pp_whs_create
               1. Customer
                  1. ID: pp_whs_customer_create
                  2. Deployed: Yes
                  3. Status: Released
                  4. Event Type: Create
                  5. Log Level: Error
               2. Invoice
                  1. ID: pp_whs_invoice_create
                  2. Deployed: Yes
                  3. Status: Released
                  4. Event Type: Create
                  5. Log Level: Error

1. 1. 1. 1. 1. 
            2. Click Save.
         2. Then we need to create the 'Edit Event' script record. To do this go to: Customisation > Scripting > Scripts > New
            1.  In the "File Name" field type: "netsuite_pencil_webhooks_user_event_js" or type the start of this file name and then select it.
               
            2. Click "Create Script Record"
            3. On the next page copy and paste these details:

1. 1. 1. 1. 1. 1. Name: PencilPay Webhooks Edit
               2. ID: pp_whs_edit
                  
                  1. Customer
                     1. ID: pp_whs_customer_edit
                     2. Deployed: Yes
                     3. Status: Released
                     4. Event Type: Edit
                     5. Log Level: Error
                  2. Invoice
                     1. ID: pp_whs_invoice_edit
                     2. Deployed: Yes
                     3. Status: Released
                     4. Event Type: Edit
                     5. Log Level: Error
               3. 
            2. Click Save.
         2. The third one is the "Delete" script, go to: Customisation > Scripting > Scripts > New
            1. In the "File Name" field type: "netsuite_pencil_webhooks_user_event_js" or type the start of this file name and then select it.
               
            2. Click "Create Script Record"
            3. On the next page copy and paste these details:
               
               1. PencilPay Webhooks Delete
               2. ID: pp_whs_delete
                  
                  1. Customer
                     1. ID: pp_whs_customer_delete
                     2. Deployed: Yes
                     3. Status: Released
                     4. Event Type: Delete
                     5. Log Level: Error
                  2. Invoice
                     1. ID: pp_whs_invoice_delete
                     2. Deployed: Yes
                     3. Status: Released
                     4. Event Type: Delete
                     5. Log Level: Error
                  3. 
            4. Click Save.
      2. Then we need to update the 'Audience' for ALL all three script deployment records created above by following the steps below.
      3. To do this, go to: Customisation > Scripting > Scripts
         1. Then find the first script called: PencilPay Webhooks Create and click on the "View" link.
            
            
            1. On Script review page in the top right corner click on More > 'View Deployments' to update 'Audience' script deployment records.
               
            2. You will see two "Script Deployments".
               1. customdeploy_pp_whs_customer_create
                  1. Click on the Edit link.
                     
                  2. Update the Role to include: 'PencilPay API' and any other roles you would like the users with these roles to push customer and invoice data from NetSuite to Pencil immediately via the web hook (otherwise you may wait up to 3 hours for the data to sync); OR
                  3. Employee: 'PencilPay API' user account and any other roles you would like the users with these roles to push customer and invoice data from NetSuite to Pencil immediately via the web hook (otherwise you may wait up to 3 hours for the data to sync).
               2. customdeploy_pp_whs_invoice_create 
                  1. Click on the Edit link.
                     
                  2. Update the Role to include: 'PencilPay API' and any other roles you would like the users with these roles to push customer and invoice data from NetSuite to Pencil immediately via the web hook (otherwise you may wait up to 3 hours for the data to sync); OR
                  3. Employee: 'PencilPay API' user account and any other roles you would like the users with these roles to push customer and invoice data from NetSuite to Pencil immediately via the web hook (otherwise you may wait up to 3 hours for the data to sync).
         2. Then find the second script called: PencilPay Webhooks Edit and click on the "View" link.
            
            
            1. On Script review page in the top right corner click on More > 'View Deployments' to update 'Audience' script deployment records.
               
            2. You will see two "Script Deployments".
               1. customdeploy_pp_whs_customer_edit
                  1. Click on the Edit link.
                     
                  2. Update the Role to include: 'PencilPay API' and any other roles you would like the users with these roles to push customer and invoice data from NetSuite to Pencil immediately via the web hook (otherwise you may wait up to 3 hours for the data to sync); OR
                  3. Employee: 'PencilPay API' user account and any other roles you would like the users with these roles to push customer and invoice data from NetSuite to Pencil immediately via the web hook (otherwise you may wait up to 3 hours for the data to sync).
               2. customdeploy_pp_whs_invoice_edit
                  1. Click on the Edit link.
                     
                  2. Update the Role to include: 'PencilPay API' and any other roles you would like the users with these roles to push customer and invoice data from NetSuite to Pencil immediately via the web hook (otherwise you may wait up to 3 hours for the data to sync); OR
                  3. Employee: 'PencilPay API' user account and any other roles you would like the users with these roles to push customer and invoice data from NetSuite to Pencil immediately via the web hook (otherwise you may wait up to 3 hours for the data to sync).
                  4. Click Save.
         3. Then find the third script called: PencilPay Webhooks Delete and click on the "View" link. 
            
            
            1. On Script review page in the top right corner click on More > 'View Deployments' to update 'Audience' script deployment records.
               
            2. You will see two "Script Deployments".
               1. customdeploy_pp_whs_customer_delete  
                  1.  Click on the Edit link.
                     
                  2. Update the Role to include: 'PencilPay API' and any other roles you would like the users with these roles to push customer and invoice data from NetSuite to Pencil immediately via the web hook (otherwise you may wait up to 3 hours for the data to sync); OR
                  3. Employee: 'PencilPay API' user account and any other roles you would like the users with these roles to push customer and invoice data from NetSuite to Pencil immediately via the web hook (otherwise you may wait up to 3 hours for the data to sync).
                  4. Click Save.
               2. customdeploy_pp_whs_invoice_delete    
                  1. Click on the Edit link.
                     
                  2. Update the Role to include: 'PencilPay API' and any other roles you would like the users with these roles to push customer and invoice data from NetSuite to Pencil immediately via the web hook (otherwise you may wait up to 3 hours for the data to sync); OR
                  3. Employee: 'PencilPay API' user account and any other roles you would like the users with these roles to push customer and invoice data from NetSuite to Pencil immediately via the web hook (otherwise you may wait up to 3 hours for the data to sync).
                  4. Click Save.
         4. To do this, go to: Customisation > Scripting > Scripts
            
            
         5. Role: 'PencilPay API' and any other roles you would like the users with these roles to push customer and invoice data from NetSuite to Pencil immediately via the web hook (otherwise you may wait up to 3 hours for the data to sync); OR
         6. Employee: 'PencilPay API' user account and any other roles you would like the users with these roles to push customer and invoice data from NetSuite to Pencil immediately via the web hook (otherwise you may wait up to 3 hours for the data to sync).
            
   2. The last is to update or check the "PencilPay RESTlet" script. To do this follow these steps:

      1. Go to Customization -> Scripting -> Scripts.

      2. Find "PencilPay RESTlet" and click "View".
         

      3. In the top right corner of the newly loaded page click on: More -> View Deployments.
         

      4. You will see one entry, click on "Edit".
         

      5. You now need to add permissions to either the Roles or Employees to allow updates to push instantly from NetSuite to Pencil or wait for the 3 hour automated process.
         

         1. Under Roles, Select All.

            1. If you want to manage by Roles, select all the roles (you need to include the PencilPay API role) that you want to push data to Pencil from NetSuite if anyone in these roles updates Invoices/Customers.

         2. Under Employees, Select All.

            1. If you want to manage by Employees, select all the Employees that you want to push data to Pencil from NetSuite if anyone in these roles updates Invoices/Customers.

      6. Click Save.

1. 1. Log in to your PencilPay Account.
   2. Go to: Integrations -> NetSuite (if you have another accounting integration already connected you will need to disconnect)
   3. Then complete the following information:
      1. Enter your "NETSUITE Account ID"
      2. Enter your "Pencil Client ID" from step 5.d above
      3. Enter your "Pencil Client Secret" from step 5.d above
      4. Enter your "Token ID" from step 6.e above
      5. Enter your "Token Secret" from step 6.e above
      6. Enter your "Pencil RESTlet external URL" from step 7.c.iv above
      7. Click Authorise.
   4. In the "Reconcile configuration" page select your "Primary subsidiary" and click Next.
   5. Then select the following settings:
      1. Primary location
      2.  Bank account (set the bank account you want monies to be disbursed to)
      3.  Pencil clearing account (the integration will add this as part of the auto-reconciliation feature)
      4. Secondary Pencil clearing account (the integration will add this as part of the auto-reconciliation feature)
      5. Transaction fee account (select an account to assign the Pencil transaction fees).
      6. Pencil Vendor Tax Code.
      7. Customer Price Level.
      8. Customer Tax Item.
      9. Customer Category.
      10. Customer Status (This status will be applied to approved customers who on board through Pencil platform).
      11. Enable pushing payments as customer deposits (Toggle ON to allow Pencil push payments as customer deposits or toggle OFF to set as Disabled).
      12. Enable resyncing inactive customers (Toggle ON to allow Pencil resync customers and invoices that are set as Inactive in Pencil or toggle OFF to set as Disabled.)
      13. Enable pushing payments on checkout (Direct debit payments take 3 business days to process and sometimes they fail. This setting allows you to choose if you want to push the direct debit payment immediately to your accounting system (toggle this setting ON). If you run your business on statements and only want the payment to be updated in your accounting system on successful disbursement of the funds; then toggle this setting OFF).
   6. Click Save.