Transactions, Reservations, & Payments

Overview
Architecture
Roadmap
API Example
Use & Best Practices
API Reference
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.

Roadmap

The following features are available in our test environment:

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

Upcoming features include

Creation and management of driver profiles, including vehicles and payment methods - Q3 of 2021
On-street parking support - Q3 of 2021
Notification improvements such as vehicle entry & exit, expiring session - Q4 of 2021
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.

Use & Best Practices

Usage is composed of 4 distinct types:

Setup, Login. or Access a Parking Account
Find Parking
Pay for Parking
Provide Evidence for Parking

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.

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.

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

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

Log in to a Parking Account
Retrieve Parking Session Information
Retrieve Parking Information at a Location
Quote Parking for a Location & Vehicle
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:

Driver username and password via basic HTTP AUTH

Example Result

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

{
  "userid": "{user id}" // Not available in TEST environment
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
}

userid Identifier for logged in user
token Authentication token

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 {token}

Call parameters:

user-id is the id of the user
?page=# is page number desired

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,
		  ...	    
		},

	    ...
    ]
}

id Record identifier
lot_id Parking lot identifier which can be used to retrieve specific lot details from Off-Street API
start_time Parking session start time
end_time When the parking session ended
duration Length of parking session in minutes
price_paid Amount paid in the indicated currency
currency Identifier for currency used
purchased_at When purchased, which could be in advance of start_time for reservations
count Number of pages
next and previous URLs for prior and subsequent page navigation
results Container for parking session objects when using paging

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}
Authorization: Bearer {token}

Call parameters:

lot-id is the id of the lot to quote parking for
entry-time the DateTime vehicle will enter lot, in local time
duration the maximum time the vehicle will be parked
vehicle-id the ID of the vehicle, related to the user account
user-id the ID of the user

Example Result

The result is one or more quotes or empty 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"
            }
         ]
      }
   ]
}

status Request success/failure
provider_id Parking supplier identifier
provider_name Parking supplier name
quote-ref Quote identifier
amount Pricing
currency Currency identifier for Pricing
start_time DateTime for parking session beginning, in ISO format
end_time DateTime for parking session ending, in ISO format
validation_steps Directions for entering/starting parking session, accompanied by a QR Code or similar validation instrument
_links HATEOS links

Purchase 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:

lot-id is the id of the lot to purchase parking
provider-id Parking supplier identifier
payment-id Payment type identifier, as associated with the user account
quote the quote being used, as previously retrieved via pay/v3/lots/{lot id}/quotes/
amount the parking cost
currency the currency type for the parking cost

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"
      },
   }
}

status Request success/failure
id Parking supplier identifier
start_time DateTime for parking session beginning, in ISO format
end_time DateTime for parking session ending, in ISO format
duration Parking time in minutes
price-paid Amount paid
currency Currency identifier for Pricing
purchased_at When purchased, in ISO format
external_id Parking payment ID at Parking Supplier
raw_json_response Information returned from Parking Supplier __not recommended to reference as may not be valid or consistently included __
validation Message to driver on how to gain entry to the lot
scan_code Raw QR Code identifier
_links HATEOS links

Release Notes

For Release v080221 in TEST environment

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

Documentation

PARKING