Partner OAuth Workflow – Doshii Guide

For POS and Apps that support OAuth 2.0, it is possible to auto-provision using the workflow described below.

Partner Workflow

Doshii OAuth Provisioning.png

Required Configuration

The following table lists the information that Doshii requires to support the OAuth provisioning process:

Property	Value
clientId	Client ID value that is required for Doshii to invoke the OAuth endpoints
clientSecret	Client Secret value that is required for Doshii to invoke the OAuth endpoints
authoriseUrl	The URL (including any query parameters) that should be invoked when attempting to authorise a merchant via OAuth. e.g. https://my.partner.com/authorize?client_id={{clientId}}&redirect_uri={{redirectUrl}}&state={{state}}&response_type=code
tokensUrl	The URL that is invoked via POST to retrieve the OAuth access tokens. e.g. https://api.partner.com/tokens.
revokeUrl	The URL that is invoked via POST to revoke OAuth access tokens for a given customer. e.g. https://api.partner.com/revoke.
locationsUrl	The URL that is invoked via GET to retrieve locations associated to a given account. e.g. https://api.partner.com/doshii/locations.
provisionUrl	The URL that is invoked via GET to retrieve more detailed information for a specified location in the Partner for the purposes of provisioning. e.g. https://api.partner.com/doshii/provision.

Workflow

Request Authorisation

The OAuth workflow will be initiated by Doshii. The process will then redirect to the Partner's OAuth authorisation form where the merchant will be required to accept or deny the request to allow Doshii to access their Partner account.

In either case (accept/deny), it is expected that the Partner will then invoke the configured redirect URL.

Redirect and Retrieve Tokens

The initial request should find its way to the redirect URL, which, depending on the outcome (accept/deny) will retrieve the merchant’s OAuth tokens using the authorisation code in the request against the Partner’s tokensUrl via a POST request. Once the tokens are retrieved, they will be stored securely against the organisation and will be used in subsequent calls.

In the case where the authorisation request was denied, the Partner will include the error and error_description query parameters. These parameters will be passed back to Doshii’s provisioning platform.

Retrieve Locations

To allow merchant’s to then specify which location they would like to have provisioned in Doshii, it is necessary to retrieve a list of locations from the partner. The custom API endpoint that the Partner will need to implement as part of the Doshii certification will be invoked via GET and is expected to return a list of locations (with optional address information) associated to the given organisation. The response to this request will be of the form:

[
  {
  "id": "<PartnerLocation ID>",
  "name": "<PartnerLocation Name>",
  "doshiiId": "<Doshii Location ID>",
  "address": {
    "addressLine1": "<Location Address Line 1>",
    "addressLine2": "<Location Address Line 2>",
    "city": "<Location Address City>",
    "country": "<Location Address Country>",
    "postalCode": "<Location Address Post Code>",
    "state": "<Location Address State/Territory>"
   }
  },  
  { 
     "id": "<PartnerLocation ID>",  
     "name": "<PartnerLocation Name>"  
  }
]

The organisation is identified by the fact that this endpoint uses the organisation’s OAuth access tokens as the Authorisation header.

The doshiiId property in the response indicates that the location has already been provisioned in Doshii. For a completely new customer, there would be no locations in the list with this property set.

Provision a Location

Once the merchant has nominated the location from the list in the previous step, Doshii would then issue a GET request to a custom API endpoint that the Partner will need to implement as part of the Doshii certification, which, using the supplied partnerLocationId query parameter, will then collate the internal location information and return it in the standard Doshii Location schema, described in Doshii’s PartnerAPI endpoint to create a location.

The endpoint will then return the a payload similar to below:

{
  "name": "Chicken's R Us",
  "partnerLocationId": "<partnerLocationId>",
  "addressLine1": "520 Bourke St",
  "addressLine2": "Level 1",
  "city": "Melbourne",
  "state": "VIC",
  "country": "AU",
  "postalCode": "3000",
  "timezone": "Australia/Melbourne",
  "phoneNumber": "+61415123456",
  "email": "info@therestaurant.org",
  "publicWebsiteUrl": "https://therestaurant.com.au",
  "latitude": "123",
  "longitude": "456",
  "classification": "Accommodation",
  "operatingHours": [
      {
        "standard": true,
        "status": "open",
        "dates": [
           {
            "day": 31,
            "month": 1,
            "year": 2019
           }
      ],
  "time": {
     "from": "13:00",
     "to": "23:00"
      },
  "daysOfWeek": [
    "mon"
   ],
  "effective": {
     "from": "string",
     "to": "string"
       }
    }
  ]
}

The organisation at the Partners end is identified by the fact that this endpoint uses the organisation’s OAuth access tokens as the Authorisation header.

Doshii would then use this information to provision the location.

App Provisioning

If it is an App (rather than a POS), it is the Apps responsibility to complete the subscription using:
https://dashboard.sandbox.doshii.io/docs/api/app#/Onboarding/subscribeLocation

Where the App is also implementing de-provisioning they would also need to call:
https://dashboard.sandbox.doshii.io/docs/api/app#/Onboarding/unsubscribeLocation

Note: The mapped location id must be globally unique within their system. If it is not the App will need to prefix the location id to make it unique.