Contents
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 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.
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
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 forentry-time
the DateTime vehicle will enter lot, in local timeduration
the maximum time the vehicle will be parkedvehicle-id
the ID of the vehicle, related to the user accountuser-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 parkingprovider-id
Parking supplier identifierpayment-id
Payment type identifier, as associated with the user accountquote
the quote being used, as previously retrieved viapay/v3/lots/{lot id}/quotes/
amount
the parking costcurrency
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