Merchant Boarding API

Products
Merchant Boarding API Integration Guide
merchant-onboardingpostman

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 the User profile icon in the top right corner of the screen and selecting 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.

How to Create and Use a Plan ID

Before starting a new application, an application template must be created or the Plan ID of an existing template must be noted. The template defines the Equipment and Pricing options that will be applied to the application. Each template has a unique Template ID, referred to as planId in the API, which the user submits when using the API. Partner Portal’s Enrollment tool may be used to create a new template or to view an existing system template, as described in the following steps.

1. During development, login to the Sandbox Partner Portal using the same credentials you use for your Production Partner Portal account. Continue to the next step to create test templates in the Sandbox environment. Please note that after development, once your integration has been certified and you are ready to go live, you will login to your Production Partner Portal account and create templates to be used in Production.
2. Click Enrollment > Templates.
3. Either browse for an existing template and note the Template ID or select Start New Template.
4. Create a name for the template.
5. Set all necessary Equipment and Pricing fields. These must be finalized on the template, as Equipment and Pricing information will not be editable from the Merchant Boarding API.
6. On the template’s Validation page, navigate to any pages listed as “Not ready for use” and add the required content specified at the top of those pages.
7. At the bottom right corner of the Validation page, select Close to save the template.
8. When using the API to create a new merchant boarding application, the Template ID will be passed to the API in the the planId field to reference a template. A unique alphanumeric value must also be created each time a new application is started and passed in the API's externalKey field. The key refers to that particular application and allows the user to access it later. For example, when updating or submitting an application, a reference to an existing application should be made based on the external key.

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 the User profile icon in the top right corner of the screen and selecting 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.

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
   
   

Requirements for Custom Enrollment Integrations

• 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