North SI Cloud API Specification

North Semi-Integrated Cloud API

Authentication

post /auth

This endpoint will return a JSON Web Token (JWT) that should be used with the Authorization header when sending requests that require authorization. This endpoint will also return an account ID that should be used as a request parameter when sending account-related requests. The following headers are required:

Content-Type: <application/json>
Content type of message. For most messages, this will be the default.
Content-Length: <1234>
This value should be set to the exact length of the message body you are sending.
x-nabwss-appsource: <pa_isv_1234567890abc>
This value is specific to each individual API account.

Request Schema

mid required

string

Example:

9999999999999

developerKey required

string

Example:

12345

password required

string

Example:

Password

Example Request

{
  "mid": "9999999999999",
  "developerKey": "12345",
  "password": "Password"
}

Example Response

200 Request Authorized

400 Invalid Post Data

404 Unauthorized Request

Send Push Notification

post /accounts/{accountId}/notification

This endpoint sends a transaction request through a push notification to the Payanywhere mobile application paired with a supported physical terminal or card reader to accept a card-present payment from the card holder. The following parameter is required:

Account ID: Your Account ID will be returned from the /auth request and is required to be inserted into this URL endpoint.

The following headers are required:

Authorization: Bearer JWT
Send a valid JWT through the Authorization header. Use the JWT returned from the Authentication request. Invalid or expired JWTs are unauthorized and will return as such.
x-nabwss-appsource: <pa_isv_1234567890abc>
This value is specific to each individual API account.

Request Schema

type required

string

Minimum:

Example:

sales

invoice

string

Minimum:

Example:

123abc

amount required

string

Minimum:

Example:

2.00

email required

string

Minimum:

Example:

email@address.com

tokenization

boolean

Minimum:

Example:

true

Example Request

Sale

{
  "type": "sales",
  "amount": "2.00",
  "email": "email@address.com",
  "invoice": "123abc",
  "tokenization": false
}

Example Response

201 Authorized

401 Unauthorized

Submit Subsequent Sale

post /mids/{mid}/gateways/payment

This endpoint is used to submit a card-not-present Sale payment. Pass in the 'tokenized_card' property received from the webhook JSON payload's extra section. The following parameter is required:

MID: Your merchant ID is required to be inserted into this URL endpoint.

The following headers are required:

Authorization: Bearer JWT
Send a valid JWT through the Authorization header. Use the JWT returned from the Authentication request. Invalid or expired JWTs are unauthorized and will return as such.
x-nabwss-appsource: <pa_isv_1234567890abc>
This value is specific to each individual API account.

Request Schema

token required

string

amount required

string

gateway_public_key required

string

Example:

Your Gateway Public Key

transaction_source

string

Example:

PA-JS-SDK

Example Request

{
  "token": "<tokenized_card value>",
  "amount": "1.26",
  "gateway_public_key": "<your gateway_public_key>",
  "transaction_source": "<optional>"
}

Example Response

201 Success

401 Unauthorized. New JWT needed

Submit Subsequent Transaction

post /accounts/{accountId}/transactions

This endpoint can be used to perform subsequent actions on an existing pre-authorization or captured transaction. Depending on the values passed in the request body, this endpoint can send the following types of requests:

Pre-authorization adjustment: adjusts the amount of an existing pre-authorization transaction
Pre-authorization capture: captures the amount of an existing pre-authorization transaction
Void: voids a transaction before settlement occurs
Refund: refunds the full amount of the transaction or any amount less than the transaction amount after settlement has occurred

For all transactions sent through the North SI Cloud API, the webhook response will include the parameter 'unique_id.' The 'unique_id' has the format of 'ccs_' followed by several numerical characters. For this request, you will need to parse the 'unique_id' returned by North, removing the 'ccs_' portion of that string, and submit the remaining numerical value in the 'transaction_id' field for Voids, or the 'ccs_pk' field for Refunds. For example, if Payanywhere returns 'unique_id=ccs_87654321' then the 'transaction_id' or 'ccs_pk' for this request would equal '87654321'. The following parameter is required:

Account ID: Your Account ID will be returned from the /auth request and is required to be inserted into this URL endpoint.

The following headers are required:

Authorization: Bearer JWT
Send a valid JWT through the Authorization header. Use the JWT returned from the Authentication request. Invalid or expired JWTs are unauthorized and will return as such.
x-nabwss-appsource: <pa_isv_1234567890abc>
This value is specific to each individual API account.

Request Schema

type required

string

Example:

capture

transaction_id required

number

Example:

87654321

amount required

string

Example:

2.00

username

string

Example:

email@address.com

string

Example:

email@address.com

comment

string

Example:

ccs_pk

string

Example:

87654321

transaction_source

string

Example:

PA-iOS-SDK|5.10.0-x86_64-12.2

longitude

number

Example:

-83.127797000000001

latitude

number

Example:

42.564374000000001

Example Request

Pre-authorization Adjustment

{
  "type": "pap_adjust",
  "transaction_data": {
    "transaction_id": "<INITIAL_PREAUTH_TRANSACTION_ID>",
    "amount": 5
  }
}

Example Response

201 Authorized

400 Invalid Request

401 Unauthorized Request

404 Transaction_id not found

Refresh Session

post /auth/refreshSession

This endpoint takes a previously-authorized JWT and creates a new JWT with an extended expiration date. Data stored within the token will stay the same and the user will still have access to the endpoints. To use this function, send a valid JWT through the Authorization header and replace your stored JWT with the token response upon success. This endpoint can only refresh valid JWTs signed by this application. Invalid or expired JWTs are unauthorized and will return as such.

Example Response

200 Valid Token

401 Unauthorized

End Session

get /auth/expireToken

This endpoint logs out of and expires a JWT. This requires a previously-authorized JWT. See the /auth endpoint for more information on obtaining a JWT.

Example Response

200 Request Authorized

401 Unauthorized