API Information

Last updated: July 2, 2025

Creating a new Receivable

POST/v1/clients/{clientId}/receivables
This endpoint allows users to submit a new Parking Receivable to be invoiced.

Request Body Parameters

invoicingScheme (object): Contains the following invoicing options:

◦ direct (boolean): true = invoices should be created asap, currently the only supported option

◦ addConfiguredFee (boolean): If true configured fees will be added to the invoice. See the POST /v1/clients/{clientId}/merchantfees endpoint documentation for more information.

• Default is false

sessions (array of Session): List of parking sessions to be payed. Currently allowed only one parking Session per Receivable. Contains the following session details:

◦ externalReference (string): merchant's own reference

◦ actualStart (string): parking session start date and time. Accepted formats:

• 1985-04-12T23:02:50
• 1985-04-12T23:02:50Z
• 1985-04-12T23:02:50-04:00

◦ actualEnd (string): parking session end date and time. Accepted formats:

• 1985-04-12T23:02:50
• 1985-04-12T23:02:50Z
• 1985-04-12T23:02:50-04:00

◦ identifiedCredentials (array): currently only one credential is allowed. Contains the following credential details:

• type (string): licensePlate

• identifier (object):
  ▪ id (string): license plate number of the car
  ▪ country (string): ISO 3166-1 alpha-2 or alpha-3 country code of the car

◦ element (object): Parking space location

• id (string): facility ID
• name (array of MultiLingualString): facility name:
  ▪ languageCode (string): ISO language code
  ▪ value (string): localized facility name

◦ initiator (object):

• id (string): ID of current receivable owner

◦ segments (array): Time periods to be payed

• actualStart (string): start date and time of the segment. Accepted formats:
  ▪ 1985-04-12T23:02:50
  ▪ 1985-04-12T23:02:50Z
  ▪ 1985-04-12T23:02:50-04:00

• actualEnd (string): end date and time of the segment. Accepted formats:
  ▪ 1985-04-12T23:02:50
  ▪ 1985-04-12T23:02:50Z
  ▪ 1985-04-12T23:02:50-04:00

◦ assignedRight (object): Descriptor for parking activity and segment cost

• id (string)
• name (array):
  ▪ languageCode (string): ISO language code
  ▪ value (string): localized parking activity name
• zoneName (string) (Length ≤ 20)
• zoneCode (string) (Length ≤ 20)
• FacilityCode (string) (Length ≤ 20)
• FacilityName (string) (Length ≤ 20)

◦ monetaryValue (object): Descriptor for segment fee

• value (object):
  ▪ currencyValue (string): decimal with period as a separator
  ▪ currencyType (string): 3-letter currency code
  ▪ taxIncluded (boolean): value contains gross amount if true, net amount if false

• taxLines (array): Tax information for the segment
  ▪ taxLabel (array of MultiLingualString):
  • languageCode (string): ISO language code
  • value (string): localized tax label
  ▪ taxRate (string): decimal with period as a separator. Tax rate as ratio of 1
  ▪ taxAmount (string): decimal with period as a separator. Tax amount in currency

◦ feeType (string): Normally can be SEGMENT or PENALTY. Default is SEGMENT

• SEGMENT - parking fee
• PENALTY - parking penalty
  -- INVOICE - fee for invoicing service (returned by the system when configured fee is added). See the POST /v1/clients/{clientId}/merchantfees endpoint documentation for more information
• REMINDER, LOOKUP - reserved for other types of automated fees

Responses

Code	Description
200	OK
400	Bad Request
401	Missing or invalid "Authorization" header
403	Lacking permissions
404	Resource not found
409	Invoice already exists
422	Unprocessable Content
500	Unexpected internal server error

Upload Receivable Picture

This endpoint allows users to upload pictures to the Receivable in a form of a binary file.

When creating the invoice, attached pictures will be uploaded to the invoicing platform. Delivering images to customers is a subject for future development.

Request Form parts

binaryFile (file):

Picture file to upload. Currently supported only data of types image/jpeg, image/png. File size should not exceed 5MB.

MetaData (object):

Metadata for the uploaded file.

• description (string): picture description

• exposeToCustomer (boolean): default is false. Alternative functionality is not supported yet.

Responses

Code	Description
200	OK
400	Bad request
401	Missing or invalid "Authorization" header
403	Lacking permissions
404	Resource not found
422	Unprocessable Content
500	Unexpected internal server error

Process Flow

POST/v1/clients/{clientId}/receivables/{receivableId}/picturesurl
This endpoint allows users to attach a picture to the Receivable in a form of URL or Base64 data.
When creating the invoice, attached pictures will be uploaded to the invoicing platform. Delivering images to customers is a subject for future development.

Request Body Parameters

• type (string): type of the value: [URL, BASE64]. Default is URL.

• value (string): picture base64 source or link to the image file. Currently supported only data of content types image/jpeg, image/png. Image size should not exceed 5MB.

• description (string): picture (license plate) description

• exposeToCustomer (boolean): default is false. Alternative functionality is not supported yet.

Example of a valid URL attachment

{
  "value": "https://collect.mobility-hub.com/pictures/some_photo_of_B-MK58.jpg",
  "description": "B  MK  58"
}

Example of a valid BASE64 data attachment

{
 "type": "BASE64",
  "value": "iVBORw0KGgoAAAANSUhEUgAAA…",
  "description": "BASE64 data for license plate photo"
} 

Code	Description
200	OK —
400	Bad request
401	Missing or invalid "Authorization" header
403	Lacking permissions
404	Resource not found
422	Unprocessable Content
500	Unexpected internal server error

Crediting a Receivable

POST/v1/clients/{clientId}/receivables/{receivableId}/credit

This endpoint allows users to refund an invoiced Receivable. Currently only full refunds are supported.

To view the status of the refund, refer to the GET
/v1/clients/{clientId}/receivables/{receivableId} endpoint documentation.

Request Body Parameters

RefundType (string): The type of refund. One value must to be assigned: [FULL].

Tax Calculations

For credit requests, the tax calculations must follow specific rules based on the taxIncluded flag:
When taxIncluded = true

• GrossAmount = currencyValue
• NetAmount = currencyValue - taxAmount
• VatPercentage = taxRate

Example of valid values:

{
  "currencyValue": "100",
  "taxAmount": "20",
  "taxRate": "0.25"
}

Results in:

• GrossAmount: 100.0
• NetAmount: 80.0
• VatPercentage: 25.0

When taxIncluded = false

• GrossAmount = currencyValue + taxAmount
• NetAmount = currencyValue
• VatPercentage = taxRate

Example of valid values:

{
  "currencyValue": "100",
  "taxAmount": "25",
  "taxRate": "0.25"
}

Results in:

• GrossAmount: 125.0
• NetAmount: 100.0
• VatPercentage: 25.0

Merchant Fees

For configured MerchantFees, values are always treated as if taxIncluded = true:

• GrossAmount = currencyValue
• NetAmount = currencyValue - taxAmount
• VatPercentage = taxRate

Example of a valid full refund credit request

{
  "RefundType": "FULL"
}

Responses

Code	Description
200	OK —
400	Bad request
401	Missing or invalid "Authorization" header
403	Lacking permissions
404	Resource not found
409	Invoice already exists
422	Unprocessable Content
500	Unexpected internal server error

Get a Receivable by its ID

GET/v1/clients/{clientId}/receivables/

Responses

200 OK
The request was successful. The response includes the full receivable object with fields like id, status, invoicingScheme, and a list of sessions including parking data, vehicle identifiers, and payment segments.

Search Receivable

GET/v1/clients/{clientId}/receivables/search

This endpoint allows for searching of receivables using various filtering criteria. Date and time parameters are expected in the ISO 8601 format without timezone details. Here are examples of parameters you might use:

• externalReference (string): The external identifier, which may include spaces and should be URL-encoded as needed. Example: externalReference=City%20Park.
• startDate (dateTime): The start date and time for the search, inclusive. Expects ISO 8601 format without timezone (YYYY-MM-DDTHH:MM:SS). Example: startDate=2024-01-01T00:00:00.
• endDate (dateTime): The end date and time for the search, inclusive. Expects ISO 8601 format without timezone (YYYY-MM-DDTHH:MM:SS). Example: endDate=2024-01-31T23:59:59 .
• sortBy (string): The field name to sort by. Default is date (only supported). Example: sortBy=date .
• sortDirection (string): The sorting direction, either asc for ascending or desc for descending. Default is asc. Example: sortDirection=desc .
• pageNumber (integer): The page number for pagination, with a default of 1. Example: pageNumber=2 .
• pageSize (integer): The number of records per page for pagination, with a default of 1000. Example: pageSize=500.

Using Direct Query Parameters

You can pass the parameters directly in the query string. For example:

/v1/clients/{clientId}/receivables/search?externalReference=City%20Park&startDate=2024-01-01T00:00:00&endDate=2024-01-31T23:59:59&sortBy=date&sortDirection=desc&pageNumber=1&pageSize=500.

By default, the endpoint returns the first 1000 receivables ordered in ascending order for the first page.

Response

200 OK
A list of receivables matching the query criteria

Contract Parking

POST/v1/clients/{clientId}/receivables/{receivableId}/invoicerecipient
Contract Parking enables API users to bypass the car owner lookup by license plate and instead directly provide the contract payer's details.
The submitted details are automatically used to generate and send an invoice to the specified contract payer's address.

Process Flow

1.Create a Receivable with customerDataDeferred = true

• For more information on Receivables, refer to the
  POST /v1/clients/{clientId}/receivables endpoint

• Status is set to WAITING_CONTRACT_DATA

• Note the Receivable ID from the response

2.Submit contract payer details using this endpoint

• Use the Receivable ID from step 1

• Status changes to PENDING upon successful submission

3.Automatic processing begins

• Normal flow: PENDING -> INVOICE_REQUESTED -> INVOICE_CREATED

• Error flow: CARHOLDER_RESOLUTION_FAILED

Important Notes

-Only Receivables with status WAITING_CONTRACT_DATA can receive contract payer details

-Attempting to submit details for a Receivable in any other status will result in an error

-Once details are submitted and status changes to PENDING , the process cannot be reversed

Request Body Parameters

• CustomerType (string): The type of contract payer. One value must to be assigned: [Company, Person].

• SSN (string): The Social Security Number of the contract payer. (Optional)

• OrganizationNumber (string): The Organization Number of the contract payer. Required if the CustomerType is Company.

• FirstName (string): The first name of the contract payer. Not required if CustomerType is a Company.

• LastName (string): The last name of the contract payer. If the CustomerType is a Company, the organization name should be used here.

• PhoneNumber (string): The landline phone number of the contract payer.

• Mobile (string): The mobile phone number of the contract payer.

• Email (string): The email address of the contract payer.

• CountryCode (string): The country code of the contract payer. Formatted to ISO 3166-1 alpha-2.

• PostalCode (string): The postal code of the contract payer.

• PostalPlace (string): The postal place of the contract payer.

• AddressLine (string): The address line of the contract payer.

• OCR (string): The Optical Character Recognition number of the contract payer.

Responses

Code	Description
200	Send contract payer data.
400	Bad request.
401	Missing or invalid "Authorization" header.
403	Lacking permissions.
422	Unprocessable Content.
500	Unexpected internal server error.

Invoice Statues

Invoice Status	Endpoint	Action	Previous Status	Waiting Action From	Next Possible Status
Pending	/v1/clients/{clientId}/receivables	post	—	waiting to send request to Look-up Provider	Carholder Look-up Requested
Carholder Look-up Requested	/v1/licence-plate/	post	Pending	Waiting response from LookUp provider	- Whitelisted - Car Holder Resolution Failed - Pending - Invoice Requested
Whitelisted	/v1/licence-plate/	response	Carholder Look-up Requested	N/A	Final Status
Car Holder Resolution Failed	/v1/licence-plate/	response	Carholder Look-up Requested	Look-up Provider couldn’t find owner	Final Status
Pending	/v1/licence-plate/	response	Carholder Look-up Requested	Invoices waiting to send to Phx.	Invoice Requested
Invoice Requested	/v1/clients/{clientId}/invoices (message queues)	post	Carholder Look-up Requested / Pending	Invoice API (Phx)	Invoice Created
Invoice Created	/v1/clients/{clientId}/invoices	response	Invoice Requested	N/A	Final Status
Waiting Contract Data	/v1/clients/{clientId}/receivables	response	—	First request for Contract Parking clients	Pending / Invoice Requested
Credit Note Pending	/v1/clients/{clientId}/receivables/{receivableId}/credit	post	—	Invoicing API for Credit request	Credited Notes Failed / Credited Notes Succeed
Credited Notes Failed	/v1/clients/{clientId}/invoices/{invoiceNumber}/credit	response	Credit Note Pending	Request failed	Final Status
Credited Notes Succeed	/v1/clients/{clientId}/invoices/{invoiceNumber}/credit	response	Credit Note Pending	Crediting succeed	Final Status