Overview

The transaction API provides a generic interface for paying for parking, creating reservations for parking in the near future, and other transactions.
Our service interfaces with multiple providers of parking spaces to create a seamless experience for the driver. Parking providers can interface with us with minimal effort, benefit from our reach, and maintain the ability to create their own relationship with the driver.

The API uses HATEOS-style attributes to facilitate discovery and automatic reconfiguration on API changes. We prefer to use the IANA list of relations over custom-made relations.

Setup

• Driver registers with INRIX Parking Transactions.
• Driver adds car details (such as license plate and exhaust standard).

Payment

• Driver initiates payment flow by indicating how long they want to park for.
• Driver reviews a list of reservable parking spaces nearby, with price indicators.
• Driver picks a space and is shown a quote for their payment.
• Option 1: The parking space is marked ‘pay by time’: Driver agrees to payment of the estimated charges (the quote). When the driver leaves the space, payment is finalized for the actual time used. This may be more or less than the quote provided.
• Option 2: Driver agrees to payment and a transaction is made for the amount quoted.

Additional steps for new providers:

• If the driver has not used the provider before, an additional Terms and Conditions screen is shown.
• After driver agrees, payment is taken and the transaction is confirmed.

While parking:

• In a parking structure, access may be provided by license plate recognition, RFID reader, or via a QR code at the entrance and exit barrier.
• For on-street parking, the driver’s license plate or RFID is logged with the parking provider or enforcing agency.

Optional Notifications

The driver receives notifications on the Head Unit or configured mobile device when:

• A major account change has been made, such as a credit card change.
• A payment has been confirmed and an on-device entry method (such as a QR code) has been chosen.
• A payment has been recognized by a parking structure entry system.
• A payment has been ended by leaving the parking spot. This notification includes a transaction summary.
• A payment is about to expire.

Payment States

A payment can be immediate, for example, when a customer identifies at the entrance barrier of a parking structure. A payment can also be in the future, if the driver makes an reservation for a parking structure in advance.

A payment has the following states, that must be traversed from top to bottom. States can be skipped but the flow cannot be reversed.

• pending: A payment has been made, but the car has not reached the parking site yet. Example: The driver made a reservation ahead of time.
• canceled: A payment has been canceled before it was effective.
  The provider may refund the driver depending on their T&C.
  No state changes are allowed after this state.
• started: The car has reached the parking site and the payment has started to take effect. Example: The car was recognized at the entrance barrier.
• completed: The car has left the parking site and the transaction has completed. If parking was paid for by time, the time paid for will be the interval between started and completed. No state changes are allowed after this state.

/pay/v3/customers

POST Create a new transaction customer

Parameters

  = required

Name	Located In	Type	Description
firstName	Body	String	First name of customer
lastName	Body	String	Last name of customer.
address1	Body	String	Address line 1, should correspond with customer billing address
address2	Body	String	Address line 2, should correspond with customer billing address
address3	Body	String	Address line 3, should correspond with customer billing address
country	Body	String	Country of residence

Responses

200 Customer created successfully, userid and password are returned. The receiving unit must store the password for future authentication.

{
    "status": "ok",
    "userID": "user1234",
    "password": "some-secret-string",
    "_links": [
       { "rel": "current", "href": "/pay/v3/customer/user1234", "type": "GET"},
       { "rel": "edit", "href": "/pay/v3/customer/user1234", "type": "PUT"}
    ]
}

400 Failed to create customer, user readable explanation in 'message' field

{
  "status": "failed",
  "errorCode": 11,
  "message": "Country of residence not specified"
}

/pay/v3/customers/userID

GET Get customer details

Parameters

  = required

Name	Located In	Type	Description
token	Header	String	Authentication token

Responses

200 Customer record

{
    "status": "ok",
    "userID": "user1234",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "address1": "1 Love Lane",
    "address2": "Kirkby Mallory, LE9 7QF",
    "country": "United Kingdom",
    "_links": [
       { "rel": "current", "href": "/pay/v3/customer/user1234", "type": "GET"},
       { "rel": "edit", "href": "/pay/v3/customer/user1234", "type": "PUT"}
    ]
}

400 Failed to list customer, user readable explanation in 'message' field

{
  "status": "failed",
  "errorCode": 12,
  "message": "Country of residence not specified",
  "_links": [
   { "rel": "current", "href": "/pay/v3/customer/user1234", "type": "GET"},
   { "rel": "edit", "href": "/pay/v3/customer/user1234", "type": "PUT"}
   ]
}

PUT Adjust customer details

Parameters

  = required

Name	Located In	Type	Description
token	Header	String	Authentication token
firstName	Body	String	First name of customer
lastName	Body	String	Last name of customer
address1	Body	String	Address line 1, should correspond with customer billing address
address2	Body	String	Address line 2, should correspond with customer billing address
address3	Body	String	Address line 3, should correspond with customer billing address
country	Body	String	Country of residence

Responses

200 Success

{
    "status": "ok",
    "_links": [
       { "rel": "current", "href": "/pay/v3/customer/user1234", "type": "GET"},
       { "rel": "edit", "href": "/pay/v3/customer/user1234", "type": "PUT"}
    ]
}

400 Failed to modify customer, user readable explanation in 'message' field

{
  "status": "failed",
  "errorCode": 12,
  "message": "Country of residence not specified",
  "_links": [
   { "rel": "current", "href": "/pay/v3/customer/user1234", "type": "GET"},
   { "rel": "edit", "href": "/pay/v3/customer/user1234", "type": "PUT"}
   ]
}

/pay/v3/customers/userID/paymentmethod

POST Add a payment method

Parameters

  = required

Name	Located In	Type	Description
token	Header	String	Authentication token
userID	Path	String
paymentType	Body	String	List a supported payment type, currently only 'creditcard'
creditcardNumber	Body	String
creditcardExpiration	Body	String
creditcardCCV	Body	String

Responses

200 Success, returns the user-readable payment identifier.

{
    "status": "ok",
    "userPaymentIdentifier": "Visa 7890",
    "_links": [
       { "rel": "current", "href": "/pay/v3/customer/user1234/paymentmethod/1", "type": "GET"},
       { "rel": "edit", "href": "/pay/v3/customer/user1234/paymentmethod/1", "type": "PUT"}
    ]
}

400 Failed to create payment method, user readable explanation in 'message' field

{
  "status": "failed",
  "errorCode": 17,
  "message": "Card not valid",
}

GET List all payment methods for customer

Parameters

  = required

Name	Located In	Type	Description
token	Header	String	Authentication token
userID	Path	String

Responses

200 List of payment methods with identifiers

{
    "status": "ok",
    "paymentMethods": [
      {
        "userPaymentIdentifier": "Visa 7890",
        "paymentType": "creditcard",
        "state": "active",
        "_links": [
           { "rel": "current", "href": "/pay/v3/customer/user1234/paymentmethod/1", "type": "GET"},
           { "rel": "edit", "href": "/pay/v3/customer/user1234/paymentmethod/1", "type": "PUT"}
        ]},
      {
        "userPaymentIdentifier": "Amex 7887",
        "paymentType": "creditcard",
        "state": "active",
        "_links": [
           { "rel": "current", "href": "/pay/v3/customer/user1234/paymentmethod/2", "type": "GET"},
           { "rel": "edit", "href": "/pay/v3/customer/user1234/paymentmethod/2", "type": "PUT"}
        ]}
    ]
}

/pay/v3/customers/userID/vehicle

POST Add a vehicle

Parameters

  = required

Name	Located In	Type	Description
userID	Path	String
token	Header	String	Authentication token
userVehicleIdentifier	Body	String	Identifier for vehicle as used in the User Interface
licensePlate	Body	String
RFID	Body	String	RFID code if vehicle is equiped with an RFID device
exhaustStandard	Body	String
heightCm	Body	Number
widthCm	Body	Number
lengthCm	Body	Number

Responses

200 Vehicle added

{
    "status": "ok",
    "userVehcileIdentifier": "Red Prius",
    "_links": [
       { "rel": "current", "href": "/pay/v3/customer/user1234/vehicle/1", "type": "GET"},
       { "rel": "edit", "href": "/pay/v3/customer/user1234/vehicle/1", "type": "PUT"}
    ]
}

/pay/v3/customer/userID/payments/

GET Show status and summary information of all payments

Parameters

  = required

Name	Located In	Type	Description
token	Header	String	Authentication token

Responses

200

{
  "next": "/pay/v3/payment/?page=3",
  "previous": "/pay/v3/payment/?page=1",
  "count": 200,
  "results": [
    { "_links": { "rel": "current", "href": "/pay/v3/payments/44556645", "type": "GET"},
      "fullAddress": "501 Santa Monica Blvd, Santa Monica, CA 90401",
      "state": "pending",
      "entrytime": "2020-10-19T12:34:00-07:00"
    },
    { "_links": { "rel": "current", "href": "/pay/v3/payments/44556235", "type": "GET"},
      "fullAddress": "501 Santa Monica Blvd, Santa Monica, CA 90401",
      "state": "pending",
      "entrytime": "2020-10-21T12:00:00-07:00"
    }
  ]
}

/pay/v3/lot/search

POST List providers and quotes for parking, using a variety of search options.

Parameters

  = required

Name	Located In	Type	Description
token	Header	String	Authentication token
userid	Body	String	customerID
lotID	Body	String	LotID to query. Parameters 'lotID', lotArray' and 'geo' are mutually exclusive. Only 'lotID' is currently implemented.
lotArray	Body	Array	Array of lotIDs to query. Parameters 'lotID', lotArray' and 'geo' are mutually exclusive.
geo	Body	Object	Geo object with lat, long and radius. Quotes for lots within this circle will be returned. Parameters 'lotID', lotArray' and 'geo' are mutually exclusive.
entryTime	Body	String	when to start parking (approximately), an ISO date time string. Defaults to current time.
duration	Body	String	Parking duration in minutes, the quote will be based on this time
vehicleID	Body	String	vehicleID of customer

Responses

200 List of providers and quotes. A provider can set the 'payByTime' flag to indicate that actual charges will be computed at vehicle exit. The 'quoteReference' can be used to expire the quoted amount. An empty list will be returned if no payment-supported parking is available.

{
   "providers": [
      {
        "providerID": "ParkingFoo",
        "quote": "$10",
        "quoteReference": "a324ef8",
        "isCustomer": true,
        "payByTime": true,
        "_links": [
          { "rel": "item", "href": "/pay/v3/pay/lot/33344/provider/parkingFoo", "type": "POST" }
        ]
      }
   ]
}

/pay/v3/lot/lotID/provider/providerID

POST Create a payment for a parking lot

Parameters

  = required

Name	Located In	Type	Description
lotID	Path	String
providerID	Path	String
token	Header	String	Authentication token
entrytime	Body	String	When to start parking (approximately), an ISO date time string. Defaults to the current time.
duration	Body	String	Parking duration in minutes. If the provider uses 'payByTime', this field will be used for indicative charges.
vehicleID	Body	String	vehicleID of customer
userPaymentIdentifier	Body	String	Identifier for the payment method to use
quoteReference	Body	String	ReferenceID for the quote provided by the provider previously. If the provider uses 'payByTime', this field is optional.
quote	Body	String	Quote as received from provider previously, this is the amount payable. If the provider uses 'payByTime', this field is optional.

Responses

200 returns a payment code

{
    "status": "ok",
    "paymentCode": "RES44556645",
    "_links": [
       { "rel": "current", "href": "/pay/v3/payments/44556645?readonly=12312312", "type": "GET"},
       { "rel": "edit", "href": "/pay/v3/payments/44556645", "type": "PUT"}
    ]
}

401 Access Denied. Make a t&c call first, and the provider ID

{
  "status": "failed",
  "message": "User must accept terms and conditions",
  "_links": [
     { "rel": "next", "href": "/pay/v3/provider/parkingFoo/tandc", "type": "GET"},
  ]}

400 Any field errors are listed under the 'messageObject'

{ "status": "failed",
  "messageObject": {
    "entrytime": [
        "This field is required."
    ],
    "duration": [
        "Value has to be an integer",
        "Value must be positive"
    ]
  },
}

409 The quote is no longer valid or the requested space is no longer available.

{ "status": "failed",
  "message": "The quote is no longer valid"
}          

/pay/v3/payments/paymentID

GET Retrieve all details of a payment

Parameters

  = required

Name	Located In	Type	Description
paymentID	Path	String	Which payment to retrieve
authToken	Header	String
userID	Body	String
readonly	Query	String	Provides read-only access to (selected) reservation details. If specified, the 'userID' and 'authToken' fields are not required. This can be used to generate a QR code or similar.

Responses

200

{
  "state": "pending",
  "timestampStart": "2020-10-19T06:23:00Z",
  "timestampEnd": "2020-10-19T08:49:00Z",
  "price": "$14.22",
  "facility": {
    "providerID": "ParkingFoo",
    "fullAddress": "501 Santa Monica Blvd, Santa Monica, CA 90401",
    "entrypoint": {"lat": 34.01753357460263, "lon": -118.49451184272766 },
    "hours": "Open Monday-Friday: 7:00AM to 8:00PM"
    },
  "customer": {
    "entryMethod": {
      "type": "license plate",
      "value": "8EXAMPLE",
      "state": "California"
    },
    "userID": "4453453"
  }
  "_links": [
     { "rel": "current", "href": "/pay/v3/payments/44556645?readonly=12312312", "type": "GET"},
     { "rel": "edit", "href": "/pay/v3/payments/44556645", "type": "PUT"}
  ]
}

PUT Adjust status of payment

Parameters

  = required

Name	Located In	Type	Description
paymentID	Path	String	Which payment to modify
authToken	Header	String
userID	Body	String
state	Body	String	Valid values are `pending`, `canceled`, `started`, `completed`.

Responses

200

{
  "state": "canceled",
  "_links": [
     { "rel": "current", "href": "/pay/v3/payments/44556645?readonly=12312312", "type": "GET"},
     { "rel": "edit", "href": "/pay/v3/payments/44556645", "type": "PUT"}
      ]
}

/pay/v3/providers/providerID/tandc

GET Return full text of Terms and Conditions of this provider

Parameters

  = required

Name	Located In	Type	Description
providerID	Path	String	Provider ID, which is the userID of the provider customer.
token	Header	String	Authentication token
userid	Body	String	customerID

Responses

200 returns full terms and condition text, version number, and links to accept/reject

{
    "status": "ok",
    "text": "You are agreeing to all terms and conditions.",
    "version": "2020-09-16",
    "_links": [
       { "rel": "accept", "href": "/pay/v3/providers/providerID/tandc/customers/userID/version/2020-09-16/accept", "type": "POST"},
       { "rel": "decline", "href": "/pay/v3/providers/providerID/tandc/customers/userID/version/2020-09-16/decline", "type": "POST"}
    ]
}