Documentation

# Overview

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.

# Getting started

# Create cloud app

To consume Poynt APIs you must:

  1. Signup on Poynt Developer Portal (opens new window)

  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". "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"

DANGER

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

  1. You should now be able to see the newly created application. "Create new application"

  2. Complete the application information by clicking on "Edit app details" and filling the required fields. Click on "Save" button. "Create new application"

  3. Click on "Cloud Permissions", enter the OAuth callback URL and edit the permissions. Click on "Save" button. "Create new application"

# Merchant authorization

  1. 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.

    TIP

    Note for development you can use your own test merchant account to give permission and experiment with the APIs.

    "Create new application"

  2. 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.

    TIP

    Note for developers, you need to login with your developer account credentials to see the next steps.

    • Select the test merchant
      "Create new application"

    • Authorize by clicking on "Authorize Access"
      "Create new application"

  3. Merchant gets redirected back to your redirect_uri with code, status, context (optional) and merchant's businessId.

    WARNING

    businessId is a deprecated parameter that has been temporarily kept for backwards compatibility.
    Use the poynt.biz property inside the jwt

    • status provides you info on whether your request has been authorized by the merchant or not.
    • code jwt with additonal information

    Decode the code to get the businessId.
    Sample code

    eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL3BveW50Lm5ldCIsImlhdCI6MTU4NTY4OTgxNiwiZXhwIjoxNTg1NjkwNzE2LCJzdWIiOiJ1cm46YWlkOjFiMDNhZWQzLTU4MjYtNDE2My05ZDA3LWFhOWFkY2I5NGZlOSIsInBveW50LmJpeiI6ImM5NTgwYzI0LWI2MWUtNGUwZC1hZDI2LTFkZDFkMzk0M2QyYyIsInBveW50LnVpZCI6MzQ0MTUwODN9.gPq58I7MEbOhqoZiQIWHE2GHQTUiKlGmDQ--RpgGgAU4blPXRZgOLLzs5CpiF3-5GIdhJ7nxmBdv_-24s1HRqXS9WmBvKV_ZV0W0gzq5GDtIfuYcxfjVQirzPcXWYaCrGmkJ_yOUH0t4UXKEmyu9CQaVKunAT8sipZFS43rO5yTA6CsNMzse7KIdJo92fe0NVb7OVVHxZk0Jknvs-KlFbA0aCsCa1fBnr_gsf3KgHUnYDdlQ7WcvfpdioGGwlDIXBjlhOa4WtqpeJsQt_vrA7Yph9tJpCrl3V951gloWGp1WjEhJfCdwbFJ-SROWnqRl3A3E-5ojG-7TOj1DlT-Gpg

    Decoded JWT

    {
     "iss": "https://poynt.net",
     "iat": 1585689816,
     "exp": 1585690716,
     "sub": "urn:aid:1b03aed3-5826-4163-9d07-aa9adcb94fe9",
     "poynt.biz": "c9580c24-b61e-4e0d-ad26-1dd1d3943d2c",
     "poynt.uid": 34415083
 }

    The JWT is signed and issued by "https://poynt.net" (opens new window), you can check the authenticity by verifying the signature using "https://poynt.net" (opens new window) public key

     -----BEGIN PUBLIC KEY-----
 MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA5IF70K9Hc16ZxVWGBmWp
 XBbYSzVqL3TkpIuEiUK+5Rrz1S1Uojf1hHtIxNDPXu7FcnNm2QvX3ibTClkgXHsP
 y71O/O/bjBWo1EcwjhxN03GKa/WmZMM5E8LIpb9X+D5yKX2jZYPM9wNhpUVMLhUO
 fdmS5vb1ihklnPo2lKaochS6aLvDpH5A+frQZ6DS2jGp+hvbcXkof+o8wivYmofR
 rIy/heS8RnFIVB+P5sNK4QuxwycYv77weVZIMhjrDf/nxbD5laDzisjDACvi9dw/
 n9Rp4Djor5QkMEBITU52SKs9hgIOkM1oEbYHtxrmG/yYDG9bBV04WXKtfgFF2eK+
 BwIDAQAB
 -----END PUBLIC KEY——

    TIP

    Use this command to get the current public key

    openssl s_client -connect poynt.net:443 | openssl x509 -pubkey -noout

    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.

# Requesting merchant specific access token

The following steps show how to get the access token for the merchant after Oauth From your server make a HTTP POST request to https://services.poynt.net/token and include the following headers and arguments:

Headers:

  • Accept: application/json
  • api-version: 1.2
  • Authorization: Bearer {self-signed-jwt}

Query Params:

  • grant_type=authorization_code
  • redirect_uri={redirect_uri}
  • client_id={appId}
  • 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:

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

The access token has the following claims,

{
  "poynt.uid": 1526378,
  "sub": "{YOUR_APP_ID}",
  "aud": "{YOUR_APP_ID}",
  "poynt.aur": "{APP_PACKAGE_NAME}",
  "poynt.sct": "J",
  "poynt.biz": "{MERCHANT_BUSINESS_ID}",
  "poynt.org": "69f1712e-e8f1-4c44-9ec8-6f15a5beecb1",
  "iss": "https://services.poynt.net",
  "poynt.kid": 6957716317166682000,
  "exp": 1463519061,
  "iat": 1463432661,
  "jti": "c374c9f8-87bd-4705-b3d0-e6d078fd17af",
}

# Requesting access token

From your server make a HTTP POST request to https://services.poynt.net/token and include the following headers and arguments:

Headers:

  • Accept: application/json
  • api-version: 1.2
  • Content-Type: application/x-www-form-urlencoded

HTTP body: 

    {
        "grantType": "urn:ietf:params:oauth:grant-type:jwt-bearer",
        "assertion"  : "{SELF_SIGNED_JWT}"
    }

# Example request:

Make sure to replace {SELF_SIGNED_JWT} with a jwt signed with your private key The payload for the jwt should contain the following parameters

    {
        "exp": 1585694203,
        "iat": 1585691303,
        "iss": "urn:aid:43d223e7-0783-4889-822a-b1df827352c2",
        "sub": "urn:aid:43d223e7-0783-4889-822a-b1df827352c2",
        "aud": "https://services.poynt.net",
        "jti": "f3d223e7-0783-4889-822a-b1df827352c6"
    }

Claims explained:

  • exp: Expiry time for the self generated jwt
  • iat: Time the jwt is issued/created
  • iss: Issuer of the jwt (your appId)
  • sub: Subject of the jwt (your appId)
  • aud: Audience the jwt is intented for ("https://services.poynt.net or "https://services-eu.poynt.net" for EU)
  • jti: Unique identifier for the jwt

TIP

The payload shown in the json code block above needs to be encoded with the private key of your application.




 

    curl -XPOST 'https://services.poynt.net/token' \
    -H "Accept: application/json" \
    -H "api-version: 1.2" \
    -d "grantType=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={SELF_SIGNED_JWT}"

# Example response:

{
    "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 the claims.


{
  "aud": "urn:aid:43d223e7-0783-4889-822a-b1df827352c2",
  "sub": "urn:aid:43d223e7-0783-4889-822a-b1df827352c2",
  "poynt.aur": "co.poynt.posapp",
  "poynt.sct": "J",
  "poynt.org": "69f1712e-e8f1-4c44-9ec8-6f15a5beecb1",
  "iss": "https://services.poynt.net",
  "poynt.kid": 13316956343565198000,
  "poynt.aty": "S",
  "exp": 1585717703,
  "iat": 1585591303,
  "jti": "68c64659-dcba-44f7-8515-33117294411e"
}

# Making Your first API call

GoDaddy Poynt APIs allow you to bring and merge essential information into your application. All Poynt APIs are secured with the OAuth2.0 authentication and authorization framework.

Before you can make an API call on behalf of a merchant, the are a series of steps to follow:

  1. Generate a self-signed JWT using the public-private keypair for your cloud app obtained from the Poynt Developer Portal.

  2. Post the self-signed JWT to Token API to obtain the Poynt granted AccessToken, TokenType and RefreshToken.

  3. Obtain the merchant's permission to access their data and call Poynt APIs.

NOTE

The algorithms supported to generate the JWT are RS256, RS384, RS512, PS256, PS384 or PS512 to generate the JWT.

Below is a section from our Python Sample (opens new window) hosted on GitHub.


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 code will generate an 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...
  1. 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"
}

At this point you can make any Poynt API calls by passing the access token as part of the authorization header.

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

TIP

Note that the Authorization header consists of the token type BEARER and the actual token value.

A functional Python Sample (opens new window) has been provided on GitHub as a reference. Make sure to check it out as it will help you understand API calls and their behavior.

You can also refer to the Poynt API Reference (opens new window) for more information about the available API resources.

Last Updated: 4/13/2022, 3:57:15 PM

← Webhooks →