API Integration with NetPayDue
Introduction
Welcome to the comprehensive guide for integrating with NetPayDue APIs using OpenID and OAuth2 technologies. This guide is meticulously designed to walk you through every phase of the process, from your initial registration to deploying advanced API functionalities, ensuring a secure and efficient setup.
For more detailed information, please click on the headers above or simply scroll down.
PI) Partner API Creation and Management
PI1) Introduction
Begin your journey with NetPayDue by registering for a partner account using a straightforward process:
- Access the Registration Page: Visit the NetPayDue platform's signup page.
- Enter Your Details: Provide your details including email and password. This step is open to all prospective partners, regardless of their current setup.
- Submission: Submit your registration form and then you can start signing in.
- Static IP Requirement: To access our API, a static IP address is mandatory. Access is granted only from specified static IPs to ensure security. Our system supports up to 5 static IP addresses as origins for API access.
PI2) Mandatory Data
After logging in to your newly created account, prepare to provide detailed information to proceed with the API onboarding:
- Company Name: The legal name of your company.
- Messaging Name: A preferred name for communications.
- Company URL: The URL of your company's official website.
- Contingency Email: An email address for backup communication purposes.
- Company Phone 1: The primary phone number for contact.
- System Admin Email: The email of the individual who will manage the system.
- Year of Establishment: The year your company was founded.
- Number of Employees: How many employees work in your company.
- Service Required: The specific APIs or services you intend to use.
- Static IPs: A list of static IP addresses that will be used to access the APIs; essential for securing your API usage.
PI3) Sign Up for Partner API
To successfully request and gain access to our APIs, follow these detailed steps after logging into your NetPayDue partner account:
- Navigate to Onboarding Form: Go to the Hamburger Menu, select View/Edit Account, then navigate to API/SFTP/CSV/Dropbox Integration Setup. Here, click on the API Integration Setup button to access the onboarding request form.
- Complete the Onboarding Form: Fill in all the mandatory data you collected earlier (e.g., company name, static IPs). Ensure all information is accurate to facilitate a smooth approval process.
- Submit the Onboarding Request: After verifying the information, submit the form. This action will send your onboarding request to the NetPayDue system administrator for review.
- Review by System Administrator: The system administrator will review your submitted details to verify the adequacy and security measures of the provided data. This step is crucial for ensuring that all potential API users meet our security standards.
- Initial Approval or Inquiry for More Information:
- If the administrator determines that your application meets all requirements, they will approve your API access, and you will receive an email confirming this approval.
- If the administrator needs more information or clarifications, they will reach out to you. You will need to respond promptly to any queries to proceed.
- Accept the API User Agreement: Upon receiving approval, return to the API Integration Setup via the Hamburger Menu. Here, you will be prompted to review and accept our "API User Agreement." This agreement outlines the terms and conditions under which you can use our APIs.
- Access API Credentials: After accepting the user agreement, navigate to API Credentials by following: Hamburger Menu → View/Edit Account → API/SFTP/CSV/Dropbox Integration Setup → API Integration Setup → API Credentials button. This page will display your OpenID setup details, including clientId, clientSecret, tokenEndpoint, and grantType.
- Secure Storage of API Credentials: It's important to securely store the clientId and clientSecret provided. These credentials are essential for obtaining access tokens needed for API consumption. If you encounter any issues or have questions about storing these credentials, do not hesitate to contact our support for assistance.
PI4) Installing OpenID
Set up your OpenID configuration with ease:
- Choose an OpenID Provider: Decide between options like Azure, Keycloak, etc., based on what best suits your system architecture.
- Configure Client ID and Client Secret: Enter the credentials provided by NetPayDue into your OpenID provider’s configuration settings.
- Test Connection: Ensure that the connection between your OpenID provider and NetPayDue is active and secure.
- Support: If you face any difficulties during setup, our dedicated support team is ready to assist you with any technical issues.
PI5) Test API Integration
Testing the API integration ensures that your application can securely and efficiently communicate with NetPayDue APIs. Follow these detailed steps to validate your API setup:
- Obtain Access Token:
- Start by using the clientId, clientSecret, grantType, and tokenEndpoint obtained from the API Credential Details page.
- Send a request to the tokenEndpoint to obtain an access token. This token is crucial as it authenticates your requests to the NetPayDue APIs.
- Access the Demo Application:
- Utilize our demo application, which is specifically designed to help you test basic API connectivity. This application will guide you through using your access token in a controlled environment.
- Select an API:
- Choose an appropriate business API based on your integration needs. We offer various business APIs, including:
- Payroll API: For handling and processing pay calculations.
- Grant Authorization API: For managing OAuth flows, crucial for operations requiring permissions and user consents.
- For a complete list of all business APIs please click here
- Choose an appropriate business API based on your integration needs. We offer various business APIs, including:
- Invoke the API:
- Using the access token, invoke the selected API. It's critical to make these requests from one of the pre-arranged static IPs as configured in your NetPayDue settings.
- Note: Access from non-configured IPs will result in an error, regardless of the API being invoked.
- Analyze Results:
- Analyze the responses from the API. Successful responses indicate that your API setup is correctly configured and operational.
- If you receive errors, carefully review the error messages provided. These messages will help you identify and resolve configuration issues or other integration problems.
- Troubleshooting and Corrections:
- For any issues encountered during testing, adjust your API configurations or consult the error guides provided by NetPayDue. Common adjustments include updating static IPs, revising token permissions, or re-authenticating your client credentials.
- Repeat Testing if Necessary:
- If corrections are made, repeat the testing process to confirm that all issues have been resolved and your application can now fully integrate with NetPayDue APIs without any errors.
PI6) Updating Partner API
Maintain and update your API settings regularly:
- Review Current Settings: Regularly check and review your system administrator details and IP addresses.
- Make Necessary Changes: Update any details that have changed to ensure ongoing security and functionality.
- Confirm Updates: Save changes and confirm that they are correctly applied across all systems.
CA) Partner Client Creation
CA1) Introduction
NetPayDue simplifies the management of client details through its business APIs, integrating client setup and updates directly into API transactions. This streamlined approach ensures that client records are created or updated in real-time, based on the transactions initiated by partners.
CA2) Creating Partner Client
When using NetPayDue business APIs to process transactions like VAT returns, partners are required to include specific client details in the API request. Here’s how to handle client data during API interactions:
- Include Client Details in API Headers:
- For each API call, include mandatory header fields that identify the client:
- DocumentID: A unique identifier for the transaction document.
- UniqueClientID: A unique identifier for the client which is used to check for existing records.
- ClientName: The name of the client.
- ClientEmail: The client’s email address.
- ClientMobile: The client’s mobile phone number.
- Attach Business-Specific Data:
- Along with the client information, include business-specific fields relevant to the transaction, such as:
- NetVAT: Net VAT amount to be filed.
- TotalVAT: Total VAT amount relevant to the transaction.
- API Processing of Client Records:
- When an API call is made, NetPayDue’s system checks if a record exists for the given UniqueClientID:
- If a record exists: The system will update the existing client record with the new details and transaction data provided.
- If no record exists: A new client record is created using the details provided in the API call.
- Confirmation and Error Handling:
- After processing the API call, the system will return a confirmation if the transaction and client update or creation were successful. If there are any issues, such as missing data or formatting errors, an error response will be generated, detailing the nature of the issue for correction and resubmission.
- Seamless Integration:
- This approach allows for seamless integration of client management into routine business processes, eliminating the need for separate client setup steps and reducing the overhead of managing client data manually.
BA) Business API
BA1) Test Payroll API
The Test Payroll API is a critical first step to ensure that your partner application is properly configured to interact with NetPayDue's business APIs. This test is designed to validate that your application can securely access our services from prearranged static IP addresses, enhancing overall security. Here’s how to conduct this test effectively:
- Obtain Access Token:
- First, retrieve an access token using your clientId and clientSecret. This token is crucial as it authenticates and authorizes your access to the API.
- Initiate Test Payroll API:
- Use the access token to initiate the Test Payroll API. This API allows you to calculate net pay by inputting various payment amounts and deductions, simulating a real-world payroll calculation.
- Verify IP Address Security:
- The Test Payroll API checks whether the access request comes from one of your prearranged static IPs. This step is vital for security, ensuring that only authorized locations can access the API.
- Handle API IP Check Errors:
- If the request does not originate from a prearranged IP, the API will return an "API IP check failed" error. This error indicates that the access attempt was from an unauthorized IP address.
- Successful Connection Confirmation:
- A successful test confirms that your application can connect to and communicate with NetPayDue’s APIs under the correct security conditions. This confirmation is essential before proceeding to more complex API functionalities.
- Access Further Business APIs:
- Once you’ve successfully established a connection with the Test Payroll API, your application is cleared to access additional business APIs offered by NetPayDue, such as the MTD VAT API and the HMRC Grant Authorization API.
BA2) Grant Authorization API
The HMRC Grant Authorization API offers a distinct testing approach by integrating authorization procedures directly with HMRC. This process not only tests the API integration but also confirms the ability of your application to handle sensitive authorization workflows securely. Here’s how to conduct this alternative test:
- Initiate Authorization Request:
- Begin by using the Grant Authorization API to retrieve a unique grant authorization token request URL. This URL is specifically generated for your application.
- Redirect to HMRC Site:
- Upon invoking the URL, your application will be redirected to the official HMRC site. This is where the authorization process gets handled externally by HMRC’s own systems.
- Enter HMRC Credentials:
- At the HMRC site, input the specific user ID and password associated with your HMRC account. These credentials are crucial for verifying the identity and authorization permissions of your application.
- Approve OAuth Request:
- Once logged in, you will be prompted to approve an OAuth request. This approval allows NetPayDue to electronically file returns, such as MTD VAT, on your behalf without manual intervention. Confirming this request is pivotal as it grants necessary permissions to NetPayDue.
- HMRC Redirects Control:
- After approval, HMRC will redirect control back to the NetPayDue server. During this redirect, HMRC sends back a unique authorization token to NetPayDue.
- Token Storage and Confirmation:
- NetPayDue captures and securely stores the authorization token received from HMRC. This token is essential for future API calls that require HMRC interaction and confirms that your setup is capable of handling sensitive authorization processes.
BA3) Test MTD VAT API
Once you have confirmed that your application's integration with the test APIs is functioning correctly, you are ready to proceed with e-filing MTD VAT returns through HMRC. Here's how to utilize the NetPayDue API for this purpose:
- Prepare E-filing Data:
- Gather all necessary information required for MTD VAT returns. This includes both header values, which dictate the type of filing and associated metadata, and actual data values, which contain the detailed tax information.
- Initiate E-filing Process:
- Access the specified NetPayDue API endpoint designed for MTD VAT e-filing. Ensure your application is set up to send data securely and in compliance with HMRC's formatting requirements.
- Transmit Data to HMRC:
- Send the prepared header and data values via the NetPayDue API. The API will process these inputs and forward them to HMRC’s systems for e-filing.
- Confirmation of Submission:
- After submitting the data, monitor for a confirmation response from HMRC through the NetPayDue API. This response will indicate whether the submission was successful or if further action is required.
- Error Handling:
- In case of errors or issues in the submission, the API will provide error messages detailing what went wrong. Use these messages to troubleshoot and correct any issues, then resubmit the data as necessary.
- Record Keeping:
- Once the filing is successfully processed, ensure to log and store the confirmation details and any reference numbers provided by HMRC. This documentation will be crucial for future reference and compliance audits.