Merchant Boarding API Integration Guide

API Flow

1. An ISO or ISV presents their own merchant application in their web portal to collect some or all merchant information.
2. A new application is created and the ISO or ISV relays that to our systems via the Merchant Boarding API.
3. The ISO or ISV then triggers the application to be completed and signed by the merchant. This will send an email link to the merchant.
4. Once the application is completed and validated, the ISO or ISV triggers the application to be submitted to our Underwriting systems. After an application has been submitted to Underwriting, it cannot be modified.
5. The ISO or ISV can poll to check Underwriting status. Once approved, a Merchant ID (MID) will be provisioned which can be used for payment processing.
   
   

How To Start

1. Sign up for a free North Developer account.
2. Contact us to set up an Agent ID and get test credentials. Once test credentials are provisioned, they can be referenced when logged in by selecting "Dashboard" in the top navigation menu, then Credentials. The test credentials consist of a Client ID and Client Secret. The Client ID will be associated with your Agent ID, and using it will provide access to all merchant applications associated with your ID.
3. Use the API specification or the Postman Collection to build your app against the test environment. When logged in, you can use the Integration Tracker to view the status of your integration, notes from meetings with Integration Engineers, resources related to your solution, and more by clicking the User profile icon in the top right corner of the screen and selecting Integrations.
4. When development is complete, contact us and once we ensure things are working properly, you will receive Production credentials that will be associated with your Agent ID. Your Production credentials will provide access to all merchant applications associated with your Agent ID.

Managing Application Templates

Before initiating a new merchant application, you must identify which application template will govern the deal. The template defines the specific Equipment and Pricing options applied to the merchant application.

How to Select or Create a Template

Option 1: Use Standard System Templates

If your business model does not require specialized pricing or unique equipment bundles, you can use our pre-configured system templates. You can locate system template IDs through:

• Partner Portal: Log in to Partner Portal (Sandbox / Production) and navigate to the Templates section to view a list of global template IDs.
• API: Call the Get Application Plan Details by Agent endpoint to programmatically retrieve available system plans.
  
  

Option 2: Create Custom Templates

For partners offering tailored pricing and equipment packages, you must create unique templates within the Partner Portal.

1. Log in to Partner Portal (Sandbox / Production).
2. Navigate to Enrollment > Templates.
3. Select Start New Template.
4. Provide a clear, descriptive name for your template.
5. Configure all necessary Equipment and Pricing fields to match your offering.
6. On the Validation page, check for any sections marked "Not ready for use." Follow the prompts at the top of those pages to resolve missing requirements.
7. Click Close at the bottom right of the Validation page to save your template and generate the template ID, which you will use as the planId in the API.
   
   

Implementing a planId in Your API Call

When using the API to board a new merchant, you will use two primary identifiers:

• planId: Pass your chosen Template ID here to apply the correct business rules.
• externalKey: You must generate a unique alphanumeric value for every new application. This key serves as your unique reference for that specific application, allowing you to update, track, or submit it at a later time.

Note: Always reference the externalKey when making follow-up calls (such as updates or status checks) to ensure you are targeting the correct merchant record.

How To Test

Contact us for test credentials that can be used to try out the payment API in a test environment. Once test credentials are provisioned, they can be referenced when logged in by selecting "Dashboard" in the top navigation menu, then Credentials. The test credentials consist of a Client ID and Client Secret. The Client ID is associated with an Agent ID, and using it will provide access to all merchant applications under the associated agent.

How To Authenticate

Authentication is required every time an API request is made. Authentication is granted through the use of a token. A token is granted when a user calls the Authentication endpoint and submits a matching Client ID and Client Secret pair. A Client ID and Client Secret are provided when a user initially requests access to the API.

All requests must include the custom n-partner-identity-origin header that will be provisioned with your API credentials.

When calling any endpoint, first call the auth endpoint to obtain a bearer token which is valid for 5 minutes, and use that token in subsequent API calls within the timeframe. The header content should look like the following:

Authorization: Bearer Token

Each token is a signed JWT that expires 5 minutes after its creation. Each time a token is submitted with a call, it is verified to be valid and not expired. If the token expires, the user must retrieve a new token by calling the authentication endpoint and submitting a matching Client ID and Client Secret again. The same token can be used for all endpoints, until it expires. The Client ID is associated with an Agent ID and that API key will be able to access all merchant applications under that agent.

Pricing Field Conditions

There are two ways to change pricing values:

1. By updating the values within a template (in the Agent Portal)
2. By submitting updated values via the Update Application Pricing endpoint
   
   

Merchant Signature Requirements

Depending on your pre-approved partnership terms, you may fulfill signature requirements using one of the following two workflows:

1. Simplified Enrollment (Hosted Link): Use our hosted "Simplified Enrollment" link for the final merchant completion step. This allows the merchant to review terms and provide an e-signature directly within our secure environment.

2. External Signature Integration: If you prefer to have more control over the experience, you may integrate with one of the pre-approved electronic signature tools to send the application to the merchant yourself. Once executed, you must upload the signed document (via API or Partner Portal) prior to final submission to Underwriting.

• DocuSign
• RightSignature
• DropBox Sign
• PandaDocs
• AdobeSign
• Agreement Express

Additional Owner Requirements

Custom Enrollment Integration Requirements

Partners using a Custom Enrollment integration are required to use our Two-Factor Authentication (2FA) endpoints and provide a digital merchant e-signature certification sheet with every submission that includes:

• How the documents were sent to the signer
• The name of the person who sent the documents to the signer
• The IP address of the device where the application is being e-signed
• The device ID being used during the e-signing process
• The date and time of signature
• Verification of completion