North Semi-Integrated Cloud API

Products
North SI Cloud API Integration Guide
semi-integratedpostman

How To Start

1. Sign up for a free North Developer account.
2. Contact us for Sandbox credentials that can be used to try out this product in a test environment.
3. Use the guide below or the Postman Collection to build your app. Resources to assist with development are provided here.
4. 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.
5. When development is complete, contact us to certify your integration. Once certified, the merchant or an authorized contact will be able to retrieve Production credentials from the API Access page of your Production Payments Hub account. For more information about using Payments Hub, visit the Help Center.

How To Test

1. Order a compatible PAX smart terminal.
2. When you receive the terminal, the North Sandbox App will be preinstalled. If two Sandbox apps are installed on your device, use the app named “North.” You won’t need to do anything with the app named “North Sandbox Installer” at this time.
3. Connect the terminal to the internet, launch the North Sandbox App and login with your Payments Hub username and password.
4. Test transactions can be submitted to the terminal, and the test card data below can be keyed in on the terminal’s keypad to complete transactions in the Sandbox environment:
   • Card #: 4000000000000002
   • Exp: 12/25
   • Zip: 12345
   • CVV: 123
5. You will receive mocked responses that match the responses returned by the payment processor in the Production environment. A complete list of transaction response codes can be viewed here.

Introduction

The North Semi-Integrated API can be used to send Sale and Pre-auth transaction requests from a partner’s cloud-based software to supported physical card readers/terminals paired with the “North - Point of Sale" mobile app, allowing partners to accept card-present payments.

This API leverages the "North - Point of Sale" mobile app (available on iOS, Android, and PAX), which has geo-location restrictions that limit usage to the United States. Compatible hardware includes devices the "North - Point of Sale" mobile app currently supports, such as PAX smart terminals.

Process Flow

1. The partner’s software initiates the transaction request via RESTful API to the North server.
2. North's server sends a push notification to the “North" app installed on the mobile device, prompting the customer for payment on the terminal/card reader.
3. The customer completes the transaction with their card on the terminal/card reader.
4. The transaction is processed through North and North's in-house processor, EPX.
5. The “North" app receives and displays a generic transaction response, including a transaction approved or declined message.
6. Optionally, the partner’s software can receive a detailed transaction response via the North Webhook. This response contains non-sensitive transaction information including a transaction ID, which can be used for subsequent card-not-present transactions, such as refunds and voids, preauthorization adjustments, and captures. This custom webhook configuration is required for the partner’s application to receive the real-time transaction responses.

Setup

1. Login to the “North” sandbox application with your Payments Hub merchant username and password.
2. To initiate the transaction request, you will need to make calls to two API endpoints.
   
   a. The first call is to authenticate. You can make this call using a variety of server-side languages or libraries of your choice. Here are the details for this request:
   
   Method: POST
   Request URL: https://proxy.payanywhere.dev/auth
   Headers:

{
  "mid": "Your MID",
  "developerKey": "Your Developer Key",
  "password": "Your Auth Password"
}

{
  "accountId": "Account ID",
  "mid": "Your MID",
  "token": "JWT"
}

{
  "type": "sales",
  "amount": "2.00",
  "email": "email@address.com"
}

{
    "type": "pap",
    "amount": "2.00",
    "email": "email@address.com"
}

{
    "id": "18",
    "devices": [
        {
            "token": "e01010dbdb67196ac37da3992e89896216968a5199da367361937dac114a4b62",
            "sent": true,
            "type": "ios"
        },
        {
            "token": "dD9f-wtD4kY:APA91bHp4m-OaWDlqvKuaNWC9jGh5J3CEruAnXO7qOpkmfcvDvjwyk0mCztT0Oeqlhlcm240EGCHbkUcdJqES1ytczmJtzEeBhzN4thdRrU6xnccDllPZGyfJnv36gR5FEdHm3VWqB2N",
            "sent": false,
            "reason":"BadDeviceToken",
            "type": "android"
        }
    ]
}

4. Optionally, build a page to receive the webhook response with details of the attempted payment. The address of this page must match the webhook URL you entered in your Payments Hub API Access page. The response will look similar to the following:

{
    "unique_id":"ccs_123456789",
    "auth_code":"01234A",
    "amount":2.00,
    "status":"APPROVED",
    "is_partial_auth":false,
    "requested_amount":2.00,
    "parent_id":"",
    "receipt_id":123456789,
    "bric":"",
    "signature_id":null,
    "invoice_number":"12345",
    "extra":
        {
            "invoice":"12345",
            "tokenized_card":null
        },
    "mid":"9999999999999"
}