Poynt Cloud APIs can be used to build applications in the cloud that can sync or process data, create and manage various resources (orders, customers, products, etc.) on-behalf of the merchant, build mobile applications for consumers that connect back to the merchant’s Poynt Terminal, and many more.

All Poynt APIs are built with commonly used RESTful design patterns in the industry. All APIs using the standard OAuth2.0 authentication & authorization framework and uses Json Web Tokens (aka JWTs) as bearer tokens.

Note: If you already have an on-terminal app you can use it's appId to make cloud API calls without additional authorization from the merchant as long as the app is installed on their terminal.

To consume Poynt APIs you must:

  1. Signup on Poynt Developer Portal
  2. After you’re registered, you will see Poynt Developer dashboard.
    • All developers by default are assigned their default developer organization so they can invite other teammates to join and access the same applications. You can try this out later after setting up your device.
  3. On the dashboard, click on “MERCHANTS” tab. To create a test merchant for your development activity, enter the Merchant Name and Bank and click “Submit”.
    Create Test Merchant

  4. Once a test merchant is created, go to “DEVELOPMENT” -> click on “Create an app”.
    Create New Application

  5. Enter the App name and click on “Submit” button.
    Create New Application

  6. Click on “Download keypair” to save your newly created application credentials and click on “Go to app”.
    Create New Application

    Warning: Your private key cannot be recovered, so please save them it a safe location. If you lose your private key you will be able to reset the public/private keypair for your appId

     

  7. You should now be able to see the newly created application.
    New Application Created

  8. Complete the application information by clicking on “Edit app details” and filling the required fields. Click on “Save” button.
    Fill Application Info

  9. Click on “Cloud Permissions”, enter the OAuth callback URL and edit the permissions. Click on “Save” button.
    Fill Application Info

  10. Obtain merchant’s permission to access Poynt APIs on behalf of them (access their data)
    1. Construct Poynt Authorization url to redirect the merchant to:
    2. Redirect the merchant to Poynt Authorization url to obtain the necessary permission. The merchant needs to login to authorize.
    Note for development you can use your own test merchant account to give permission and experiment with the APIs.

    Merchant Sign In

  11. The merchant will be prompted to allow access to the resources you specified for your app. If the merchant has already given you permission, the page will automatically redirect to the next step.
    Note for developers, you need to login with your developer account credentials to see the next steps.
    1. Select the test merchant
      Authorization Page

    2. Authorize by clicking on “Authorize Access”
      Authorization Page

  12. Merchant gets redirected back to your redirect_uri with code, status, context (optional) and merchant’s businessId.
    • Note that businessId is a deprecated parameter that has been temporarily kept for backwards compatibility.
    • status provides you info on whether your request has been authorized by the merchant or not.
  13. From your server make a HTTP POST request to https://services.poynt.net/token and include the following headers and arguments:
    • Header: Accept: application/json
    • Header: Authorization: Bearer {self-signed-JWT}
    • HTTP param: grant_type=authorization_code
    • HTTP param: redirect_uri={redirect_uri}
    • HTTP param: client_id={appId}
    • HTTP param: code={code}

Example request:

    curl -XPOST 'https://services.poynt.net/token' \
    -H "Accept: application/json" \
    -H "Authorization: Bearer  <self-signed-jwt>  \
    -d 'grant_type=authorization_code&code={CODE}&client_id={APP_ID}&redirect_uri={OAUTH CALLBACK URL}'
    

Example response:

1
2
3
4
5
6
7
{
    "expiresIn": 86400,
    "accessToken": "eyJhbGciOiJSUzI1NiJ9.eyJwb3ludC51aWQiOjE1MjYzNzgsInN1YiI6InVy...",
    "refreshToken": "1:1:1:2:emjXrINpTMI7aLvMZfdPHEH/OTtSZlI+BqfmBi+iJ0aRS40BJrYWvqU04I...",
    "scope": "ALL",
    "tokenType": "BEARER"
}

The accessToken is an encoded JWT (https://jwt.io) containing a poynt.biz attribute representing the authenticated merchant’s business ID:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "poynt.uid": 1526378,
  "sub": "{YOUR_APP_ID}",
  "aud": "{YOUR_APP_ID}",
  "poynt.aur": "{APP_PACKAGE_NAME}",
  "poynt.sct": "J",
  "poynt.org": "c4f29c0d-f818-4521-9ae1-21f385628c25",
  "poynt.biz": "{MERCHANT_BUSINESS_ID}",
  "iss": "https://services.poynt.net",
  "poynt.kid": 6957716317166682000,
  "exp": 1463519061,
  "iat": 1463432661,
  "jti": "c374c9f8-87bd-4705-b3d0-e6d078fd17af"
}
  1. To terminate merchant’s poynt.net session redirect them to https://services.poynt.net/auth/signout?redirect={REDIRECT_URL}

At this point your app has all the necessary permissions to make API calls on behalf of the merchant.

Making the first API call

As mentioned above, all Poynt APIs are secured with OAuth2.0 authentication and authorization framework. Before you make an API call on-behalf of a merchant, you must obtain the merchant’s permission to access their data and call Poynt APIs on their behalf as mentioned in the section above. Once you’ve obtain the merchant’s permission, follow the steps below to make your first API call:

Step 1

The first and foremost thing we need to do is to obtain an access token. We do that by generating a self-signed JWT using the private-key obtained from the Poynt Developer Portal and POST it to token API to obtain Poynt granted AccessToken, TokenType and RefreshToken. Below is a snippet from our python sample hosted on github.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
  def getAccessToken(self):
          poyntTokenUrl = self.apiHost + "/token"
          currentDatetime = datetime.utcnow()
          expiryDatetime = datetime.utcnow() + timedelta(seconds=300)
          payload = {
              'exp': expiryDatetime,
              'iat': currentDatetime,
              'iss': self.applicationId,
              'sub': self.applicationId,
              'aud': 'https://services.poynt.net',
              'jti': str(uuid.uuid4())
          }
          encodedJWT = jwt.encode(payload, self.rsaPrivateKey, algorithm='RS256')
          payload = {'grantType':'urn:ietf:params:oauth:grant-type:jwt-bearer', 'assertion':encodedJWT}
          print "Obtaining AccessToken using self-signed JWT:"
          code, jsonObj = self._sendFormPostRequest(poyntTokenUrl, payload, {})
          if code == requests.codes.ok:
              self.accessToken = jsonObj['accessToken']
              self.tokenType = jsonObj['tokenType']
              self.refreshToken = jsonObj['refreshToken']
              return True
          else:
              print "*** FAILED TO OBTAIN ACCESS TOKEN ***"
              return False
  

This will generate a HTTP POST API call to /token API to obtain an Access Token (JWT). Below is a sample raw HTTP request - note that your self-signed JWT must be passed as the ‘assertion’ parameter:

  POST https://services.poynt.net/token
  api-version: 1.2
  Content-Type: application/x-www-form-urlencoded
  Content-Length: 749
  Poynt-Request-Id: 54d6c99a-7520-46dc-814d-1793c086bc5c
  grantType=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI...
  

Step 2

Retrieve the access and refresh tokens from the Poynt’s /token API response. Sample response:

{
    "accessToken": "eyJhbGciOiJSUzI1NiJ9.eyJleHA...",
    "expiresIn": 86400,
    "refreshToken": "1:1:1:1:+XSWRztWqmZP7AC55IK...",
    "scope": "ALL",
    "tokenType": "BEARER"
}

Step 3

At this point you can make any Poynt API calls by passing the access token as part of the Authorization header. Note that the ‘Authorization’ header consists of token type ‘BEARER’ and the the actual token value.

GET https://services.poynt.net/businesses/411c9612-2079-45ba-9a9d-a7b36140b0f1/catalogs
api-version: 1.2
Authorization: BEARER eyJhbGciOiJSUzI1NiJ9.eyJl...

A functional sample in Python has been provided on github as a reference. Please give it a try to understand how to make API calls and their behavior. Please refer to the Poynt API reference for more information on the API resources available.