INRIX IQ logo

Contents

  1. Overview
  2. Architecture
  3. Roadmap
  4. API Example
  5. Use & Best Practices
  6. API Reference
  7. Release Notes

Overview

The Transaction API provides interfaces for securely reserving and initiating on-demand parking, managing driver and vehicle identity, and paying for parking. In conjunction with the Off-Street & On-street Parking APIs, a seamless parking experience of identifying a parking opportunity, paying, and parking can be accomplished.

Architecture

The APIs have a design goal of being straightforward to integrate with minimal overhead for edge cases. For example, a single endpoint’s available to pay for parking, covering both reservation and on-demand use cases. The differentiator being the parking start-time, with the present being on-demand and the future as a reservation. The same streamlined interaction exists for parking session information with a single endpoint providing both current and historic parking sessions.

The API uses HATEOS-style attributes to facilitate discovery and automatic incorporation of API changes. IANA relations are preferred with callers safely ignoring unexpected data. All bodies & responses are in JSON format (RFC 7159, ECMA-404).

The back-end design of these APIs is a proxying facade providing abstracted access to multiple parking and payment providers, alongside a secure, PCI & 3DS compliant payment store that is accessed directly.

Back-end Architecture

Roadmap

The following features are available in our test environment:

  1. Finding off-street parking, including rates, hours, amenities
  2. Quoting and paying for on-demand and reserved off-street parking
  3. Receiving lot-entry access, such as QR Code or license plate via LPR, if supported by lot

Upcoming features include

  1. Creation and management of driver profiles, including vehicles and payment methods - Q3 of 2021
  2. On-street parking support - Q3 of 2021
  3. Notification improvements such as vehicle entry & exit, expiring session - Q4 of 2021
  4. Extend existing parking session - Q4 of 2021

API Example

The following sequence diagram outlines a typical transaction API workflow. Note that it assumes a direct API call model to clarify demonstrated interactions.

Transaction Overview Workflow

Use & Best Practices

Usage is composed of 4 distinct types:

  1. Setup, Login. or Access a Parking Account
  2. Find Parking
  3. Pay for Parking
  4. Provide Evidence for Parking

Setup, Login, or Access to a Parking Account

All transactions: reservations and on-demand payments require a Parking account. An account is composed of an identifying email address, vehicle details such as license plate number and exhaust standard, and at least one payment method. All account details except payment methods are accomplished via direct API calls. Payment methods are collected via secure HTTPS form delivered from and posted to our PCI/3DS compliant payment store.

Authentication is via basic auth to facilitate integration with an existing driver authentication infrastructure.

Interactions include Account, Vehicle, and Payment Create/Update/Delete, Retrieve Account Parking Session History, and Account Login.

Best Practices Persist the authentication cookie to your driver’s session to enable future usage without logging in. Though cookies will expire, so prepare to renew if necessary. Session History is delivered in decreasing order of creation with date analysis used to determine current, future, and past parking sessions.

Transaction Overview Workflow

Find Parking

Find parking is via Off-Street & On-street Parking APIs. LotID and BlockID should be retained for transaction payment APIs.

Interactions include Finding parking supporting transactions near a specific lat/long.

Transaction Overview Workflow

Pay for Parking

Paying for parking is accomplished via the quoting and payment APIs.

Interactions include Creating a Parking Quote, Agreeing to Parking Facility Terms & Conditions, Creating a Parking Session - either in the present or future, Starting & Stopping a Parking session.

Best Practices Do not cache any aspect of the parking quote as pricing is volatile, changing on start-time, duration, and time of quote request. Quotes may not be possible for reasons such as availability at the desired time.

On Demand Payment Flow

On Demand Transaction Overview Workflow

Reservation Payment Flow

Reservation Transaction Overview Workflow

Provide Evidence for Parking

Retrieve explicit or confirm implicit evidence for parking facility or space entry.

Interactions include Confirm License Plate Number, Retrieve QR Code, or similar identifying credential.

Best Practices Deliver retrieved QR Code via email or mobile notification to ease driver usage for entry.

API Reference

Endpoints

  1. Log in to a Parking Account
  2. Retrieve Parking Session Information
  3. Retrieve Parking Information at a Location
  4. Quote Parking for a Location & Vehicle
  5. Purchase Parking for a Location & Vehicle

The URL for all Transaction API calls is https://txn1.parkme.com/

Log in to a Parking Account

The API endpoint /pay/v3/login is used for logging in an existing user via basic HTTP AUTH, returning an authentication token and a cookie that can be persisted to use across requests until expiration.

Example Call

GET https://txn1.parkme.com/pay/v3/login/

Call parameters:

Example Result

The result is a status, user id, token, and session cookie.

{
  "userid": "{user id}"
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
}

Returned token should be used for further requests.

Retrieve Parking Session Information

The API endpoint pay/v3/customers/{user-id}/transactions{?page=#} is used to retrieve a list of all parking sessions: past, present, and future created by the user, sorted by created date, descending. The API is paged with the optional argument used to retrieve a specific page, with page one being the first.

Best Practices Use paging whenever possible to manage data load with the first page containing the most recent, including current, parking sessions.

Example Call

GET https://txn1.parkme.com/pay/v3/customers/{user-id,: usr-1234}/transactions?page={page number: 1}
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...."

Call parameters:

Example Result

The result is a list of sessions, sorted by created date in descending order. If paging isn’t specified, then the entire history is returned.

{
  "result": [
    {
      "id": 1,
      "lot_id": "116156",
      "start_time": "2021-02-08T22:42:00Z",
      "end_time": "2021-02-09T02:00:00Z",
      "duration": 198,
      "price_paid": "15.00",
      "currency": "USD",
      "purchased_at": "2021-02-08T22:43:00.881000Z",
    },

    ...
}

If paging, such as with https://txn1.parkme.com/pay/v3/customers/{usr-1234}/transactions?page=3, the delivered sessions will be enclosed in a paging information envelope.

{
  "count": 5
  "next": "https://txn1.parkme.com/pay/v3/customers/{usr-1234}/transactions?page=4",
  "previous": "https://txn1.parkme.com/pay/v3/customers/{usr-1234}/transactions?page=2",
  "results": [
	    {
	      "id": 1,
		  ...	    
		},

	    ...
    ]
}

Retrieve Parking Information at a Location

The API endpoint is provided by the Off-Street and On-street Parking APIs with an additional flag directing the return of only reservable locations. The resulting location identifiers can then be used for a subsequent quote and purchase transaction API calls.

Example Call and Result

Refer to the Off-Street and On-street Parking API documentation for general usage and results. Adding the third_party_reservable=true parameter to the URL to retrieve only lots and blocks which support transactions.

The output will be the same as that achieved with the documented calls with all results supporting transaction-related functionality.

Quote Parking for a Location & Vehicle

The API endpoint pay/v3/lots/{lot id}/quotes/ is used to quote a parking time now, for on-demand, or in the future, a reservation. Lots have different requirements such as minimum time and payment, which will be reflected in the result, thus not necessarily aligning with the request. Multiple quotes could be returned for the lot, from different suppliers.

Best Practices Quoted rates and availability are dynamic and volatile, so quote should be promptly executed or requested again just prior to purchase. Quote should be stored, in given format, for inclusion in the follow-up purchase call.

Example Call

GET https://txn1.parkme.com/pay/v3/lots/{lot-id: 116156}/quotes/?entry_time={entry-time: 2021-08-28T11:00}&duration={duration: 120}&access_method_id={vehicle-id: PAI-1153}&customer_id={user-id: USR-1172}&format=json
Authorization: Bearer {token}"

Call parameters:

Example Result

The result is a quote or an error if not available at that DateTime and/or duration.

{
   "status":"ok",
   "quotes":[
      {
         "provider_id":777,
         "provider_name":"Parkwhiz",
         "quote_ref":"69f2f3a3-2a3c-4372-8f34-c6f9e944d23f",
         "quote_price":{
            "amount":"15.00",
            "currency":"USD"
         },
         "start_time":"2021-07-28T11:00:00.000-07:00",
         "end_time":"2021-07-28T13:00:00.000-07:00",
         "validation":{
            "validation_steps":[
               {
                  "instructions":"Upon arrival, show ParkWhiz Pass to the attendant for validation",
                  "icon":{
                     "path":"https://d2uqqhmijd5j2z.cloudfront.net/files/77185/original/validation-icons-24.png?1453405560"
                  }
               }
            ]
         },
         "_links":[
            {
               "rel":"item",
               "href":"/pay/v3/lots/116156/providers/777/",
               "type":"POST"
            }
         ]
      }
   ]
}

Quote Parking for a Location & Vehicle

The API endpoint https://txn1.parkme.com/pay/v3/lots/{lot ID}/providers/{provider ID}/ is used to purchase a parking quote, using stored payment details, associated with the user account.

Best Practices Purchases should be executed promptly after quotes as rates and availability are dynamic and volatile.

Example Call

POST https://txn1.parkme.com/pay/v3/lots/{lot-id: 116156}/providers/{provider-id: 777}/
Authorization: Bearer {token}
Payload: {"multipurpose_card_id":"{payment-id: PI-495}","quote_ref":"{quote}","quote_price":{"amount":"{quote-price:18.00}","currency":"{currency: USD}"}}

Call parameters:

Example Result

The result is a purchage validation or an error if not successful, such as for invalid or unsuccessful payment or quote is invalid, such as due to expiry. In many cases, additional detail provided by the parking supplier may be included in the purchase response, such as photos of the parking lot and listing of amenities. It is not recommended to reference these at their accuracy has not be verified.

{
"status":"ok",
   "id":155,
   "lot_id":"116156",
   "start_time":"2021-08-02T00:00:00Z",
   "end_time":"2021-08-02T06:30:00Z",
   "duration":390,
   "price_paid":"18.00",
   "currency":"USD",
   "purchased_at":"2021-08-01T23:25:18.906000Z",
   "external_id":"84262781",
   "raw_json_response": { ... }
   "validation":{
      "display_message":"Your validation method is your pass number.",
      "instructions":"Upon arrival, please show the ParkWhiz parking pass to the attendant for validation. The attendant will then instruct you where to park in the garage.",
      "scan_code":{
         "code":"84262781",
         "format":"QR",
         "qr_error_correction_level":"L"
      },
   }
}

Release Notes

For Release v080221 in TEST environment

  1. User, Driver, Vehicle, and Payment management is not available; use fixed user for testing with email updated via your Sales Engineer
  2. Terms & Conditions approval is not available; acceptance is assumed when testing