Mobile Ticketing API Guidelines

This page describes how a mobile ticketing partner can be integrated with Transit through an API. This list of requirements isn’t meant to be exhaustive, but should help the partner identify the minimum level of commitment needed for an integration. Transit prefers RESTful APIs.

This page describes a standard mobile ticketing integration. Transit also supports other scenarios not described here, including stored value wallets, scan-to-ride, fare capping, cash digitization, and smart cards.

On this page:

• Orders
• Payment Methods
• User Management
• Ticket Management
• Other Requirements

Orders

Fares

Purpose: List all available fares.
Returns: Fare ID, fare type, cost by traveler type (adult, student, etc), short description, longer description, regulations for the ticket, minimum/maximum quantity, origins/destinations, duration.

Order creation

Purpose: Add a ticket for a specific fare to the current order, create an order if there isn’t one, remove an item, list an order’s contents.
Request: Fare ID, traveler type, origin, destination and quantity.
Response: An order’s ID, line items with their price, the order’s subtotal, taxes and total price.

Order completion

Purpose: Process a payment for an order.
Request: An order ID or a list of items, a payment method ID.
Response: The completed order details or an error describing what went wrong.

Payment Methods

List available payment methods

Purpose: List a user's available payment methods.
Response: Payment method IDs, name, brand, last 4 digits and expiration.

Add a new payment method

Purpose: Used when a user wants to add a new payment method to their account. Transit can deliver the payment method to the partner in multiple ways: the complete PAN can be sent or a third party payment services provider (Stripe, Braintree, etc.) can be used. This requires the partner to provide their PCI compliance documents. The partner should then tokenize the payment method on their end so the user can purchase later without sending it again.

Request: Name on the card, PAN, expiration, CVV.
Response: Payment method ID, name, brand, last 4 digits and expiration.

Remove a payment method

Purpose: Used when a user wants to remove a tokenized payment method.

User Management

Authentication

Transit supports various OpenID scenarios. Conceptually, Transit should act as an external authentication provider for the partner. The preferred way to attain that is by honoring JSON Web Tokens (JWTs) generated by Transit to sign up and sign in a user.

These tokens provide the user's email (and other claims needed by the partner) and an identifier that uniquely identifies the user. The JWTs can be validated using a public JSON Web Key Set provided by Transit.

The JWT should then be exchanged for an authentication token that Transit will use in all subsequent API calls made on behalf of the user.

We can also support other authentication schemes: username/password, sign in with a text message, sign in with a link sent via an email, etc.

Purpose: Create new account, or sign a user in and out using a JWT from Transit. Details: Email, account details, access token.

Get Profile

Purpose: Get a user’s profile with their current tickets and their current payment methods.
Response: List of tickets, with ticket IDs, type, name, traveler type. List of payment available methods with IDs, names, last 4 digits and expiration.

Get Past Tickets

Purpose: Get a user’s ticket history.
Request: A time interval for which to return the tickets.
Response: A list of tickets, their order ID, the cost of the ticket, the status of the ticket (activated, expired, ready to use, etc.).

Ticket Management

Activate a Ticket

Transit can build the ticket screen to the partner's specifications to ensure that tickets in Transit look exactly the same as in the partner's app.

Purpose: Mark a ticket as being used right now. Get its image to be shown to a driver. Could also be a QR code.
Request: A ticket ID.
Response: An image URL, a QR code image, or a QR code payload with a symbology.

Other Requirements

• Up to date API documentation.
• API endpoints and API keys for staging/QA and production environments. Payments should also be testable in the staging/QA environment.
• Technical contact to whom Transit can ask questions regarding the integration.
• Agreement to allow Transit to integrate the ticketing API with Transit accounts
• Test accounts for the production environment (with vouchers for free orders).
• PCI attestation of compliance (AOC) and results for a recent scan done by an approved scanning vendor (ASV).