| Environment | Base URL |
|---|---|
| Sandbox | https://merchant-management-api.sandbox.north.com |
| Production | https://merchant-management-api.north.com |
| Sandbox Authentication | https://api-auth.paymentshub.dev |
| Production Authentication | https://api-auth.paymentshub.com |
How To Start
- Sign up for a free North Developer account.
- Contact us to set up an Agent ID and get test credentials. Because this API can be used in different ways depending on your needs, our integration team will help identify the functions that fit your business case.
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 accounts associated with your ID.
- 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.
- 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 accounts associated with your Agent ID.
How To Authenticate
Authentication is required every time an API request is made. Authentication is granted through the use of a bearer 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 accounts boarded under that agent.
Underwriting Status Descriptions
| Underwriting Status Code | Underwriting Status Description |
|---|---|
| A | Approved: The account has been approved by Underwriting to process payments. |
| A | Approved - Conditional: The account has been approved by Underwriting to process payments with a funding reserve. |
| AC | Approved - Collections: The merchant has an unresolved collections balance and the account is being managed internally by the Collections department. |
| B1 | Enrollment: The application has not yet been submitted to Underwriting. |
| C | Closed: The merchant has closed their account and is no longer processing payments |
| CC | Closed - Collections: The merchant's prior collections balance has been satisfied and the account is closed. |
| CR | Closed - Risk: The account has been closed by Risk due to failure to process within the approved parameters of the merchant's agreement. |
| D | Declined: The account has gone through the Underwriting approval process and has been declined to process payments. |
| DX | Declined - Threatmatrix: The account was declined during the application process due to the use of an unaccepted IP address. |
| F | Fraud: The account has been closed due to fraudulent activity. |
| P | Pending: The application has been submitted and is under review by our Underwriting team. Merchant action may be required to bring the application to Approved status. |
| PM | Enrollment: The application has not yet been submitted to Underwriting. |
| PX | Pending: The application has been submitted and has not yet been reviewed by Underwriting. |
| W | Withdrawn: The merchant or sales agent has withdrawn the account prior to it being approved. |
Webhook Notifications
Webhook subscriptions allow your application to receive real-time, event-driven HTTP POST notifications when key activities occur within your merchant portfolio. Subscribe to specific events and automatically trigger internal workflows, update your database, or alert relevant teams.
To start receiving webhooks in the Sandbox and Production environments, please contact us to configure whitelisting for outbound and inbound communication:
- Your Endpoint Whitelisting: Provide your webhook destination's IP addresses, as well as the CNAMEs or URLs where you wish to receive notifications, so that our team can whitelist them for outbound communication.
- North Public IP Whitelisting: To ensure your servers can successfully receive inbound webhook requests from North, you may need to whitelist North's public IP ranges on your end. Our integration team will provide North's public outbound IP address ranges (for both Sandbox and Production environments) upon request.
The following webhook event types are available for subscription:
| Event Type | Display Name | Description & Common Use Cases |
|---|---|---|
merchant.status.changed | Merchant Status Change | Triggered when a merchant's underwriting, processing, or account status is updated (e.g., transitioning from Pending to Approved). Use Cases:
|
merchant.dispute.created | Dispute Created | Triggered when a cardholder files a new chargeback or dispute against a merchant transaction. Use Cases:
|