Introduction

Welcome to the Token Transit Bulk Purchase API.

The Token Transit Bulk Purchase API is a RESTful service that can be used to purchase transit passes for users to redeem in other apps. Where possible the API uses understandable resource identifiers, JSON-encoded responses, and well-known HTML response and error codes.

In addition to the live API, you may also access our test API by using an test API key.

Headers

The Token Transit Bulk Purchase API uses a number of common headers across the API. Some requests also require specific headers that will be mentioned separately. These should be included in each request.

List

This is a list of all headers and the endpoints for which they are useful.

Request Headers

These are all of the headers that you may need to include with requests

Response headers

This is a list of important headers that might be sent back across multiple API requests.

API Authentication

Token Transit Bulk Purchase API uses API keys for authentication of your service. If you are integrating with us, your secret and publishable test and live API keys will be sent to you during the integration process.

To authenticate with Token Transit, you must send your API key as the Token-Transit-API-Key HTTP header like the following example:

Token-Transit-API-Key: sk_fake_1234567890abcdef

API keys have two components: key type and environment.

Key Types

There are two types of keys: publishable (publishable) and secret (secret). Publishable keys may be freely used in your app. Publishable API keys are indicated with a pk prefix to all keys. An API key has

If an endpoint restricts only certain information or is only available for use with a secret key, it will be marked as "(Requires Secret Key)".

Environments

There are three environments available as part of the Token Transit Ticketing API: fake, test, and live.

Code examples in this doc exclusively use the fake environment.

Distribution

During your integration, we will ask you to provide us with a public RSA key. We we sign your API keys and distribute them to you over e-mail or your preferred method of contact.

Retrieval and Invalidation

Once we send you a copy of your API key, it is impossible for us to re-send you your key. If you suspect a key has been compromised or you lose your API key, we will have to send you new key(s) and invalidate the old one(s).

Protocol

All calls must be made over HTTPS and include API key authentication or they will fail.

User Credentials

In addition to API keys, some endpoints also require you also create an administrative user session. User sessions are long-lasting sessions created using the Token Transit API. User sessions are returned as cookies and are created by sending a signed JWT that we can use to verify account credentials. You should use a user id (unique per user) for each of your users and that you guarantee you can map back to a user for the duration of our integration with you to used as the sub claim in your JWT.

Token Transit uses standardized JWK tools to accept and verify your JWT. The standards for this interaction are:

• JSON Web Token (JWT) IETF RFC 7519: JWTs are a standardized way of sending publicly verififiable user tokens securely to Token Transit so that we can accept your user credentials in our app.
• JSON Web Key (JWK) IETF RFC 7517: JWKs are a standardized way of providing the public key component of a public/private key pair used to sign your JWTs.
• JSON Web Algorithms (JWA) IETF RFC 7518: JWAs are a set of predetermined secure algorithms for public/private key signing. Token Transit expects either RSA (RS256, RS384, or RS512) or EC (ES256, ES384, ES512) to be used as algorithms for your JWK and JWT. If you are unsure of what option to choose when setting up your service, RS256 is widely supported and will work well with Token Transit.

Token Transit requires that you send a signed JWT to create Token Transit account credentials. We will use a URL that you provide us separately to fetch your JWKs and verify the signature on each JWT we are provided.

We expect your JWTs to be short-lived (less than 10 minutes will work well with Token Transit infrastructure). We expect your JWKs to be publicly accessible at a URL that you provide us, served over HTTPS, as a JSON Web Key Set (JWKS).

Here is a list of useful Links if you are not experienced with JWTs:

• Wikipedia
• Introduction to JWTs
• Description of JWKS

Setting up your own internal tooling to support JWT and JWKS is not difficult. There are also many third party services that will assist with this such as Auth0 and AWS Cognito.

Authorization Header

User credentials should be sent using the Authorization header specifying the Bearer type. Example:

Authorization: Bearer JWTHeader.JWTClaims.JWTSignature

JWT Specification

We use the following standard claims:

We also use the following custom claims:

Versioning

The Token Transit Ticketing API uses a versioning system to separate breaking API changes. The Token-Transit-Api-Version header should always be set to ensure that the correct version of the API is used.

All version ids look like date strings in the format YYYY-MM-DD.

This version of the API is 2020-05-21.

JWKS Server

API implementors must provide a JWKS server endpoint that is publicly accessible. We will occasionally fetch your JWKS when neccessary or when signature verification fails. Token Transit provides an example endpoint that meets our specification and can be used for verification.

curl "https://api.tokentransit.com/testing/jwks.json"

The above command returns the following valid JWKS:

{
  "keys": [
    {
      "kty": "RSA",
      "alg": "RS256",
      "kid": "0c2c5382-cef8-4c60-bda8-16bb0771c3bc",
      "use": "sig",
      "e": "AQAB",
      "n": "odw6amrOS58r3APO4V90Rv_qS4FKn1Ri9MD6vjpFNJcQKfLeJLIdLhBPr_rUY0O5dyOd2xvv8Zc4yd4G8iWpDtO-1ShwigMARg6mlY0iHZH9l-hUKsm1x_cg3L4Tovp2SIEidhJp5MvpTodKJAtBADs6-s-YVokS3R5dQLnUy9MWpB9o_YvexR8slMzyb9wwcIJaLcFOFiJ59yRxGRfuRDn4yOttdqaKU4c8yjqbknwPPrkHGvsJHTrTgFBy2kU_vilWLKdizhfJc3xxj7GibryNclrGW7TiLy_DoRuwPf4mtfsN6RH6zZdmqISkps--j6T7lByl2thm2iw2J05Epw"
    }
  ]
}

JWT Generation

API implementors must generate signed JWTs for each user authentication. We will verify the signature of the JWT is valid and matches a key in you JWKS. Token Transit provides an example endpoint that meets our specification that can be used for verification. Note that this endpoint requires a valid public testing key to function, and will not accept live or fake keys.

curl "https://api.tokentransit.com/auth/testing/jwt" \
  -H "Token-Transit-Api-Key: sk_fake_1234567890abcXYZ" \
  -H "Token-Transit-Api-Version: 2020-05-21" \
  --data-urlencode "sub=bcfad41f" \
  --data-urlencode "email=user@example.com" \
  --data-urlencode "phone_number=+14155550123" \
  --data-urlencode "device_id=d8a942c5-a700-450d-977d-b3935ab0ea87"

The above command returns the following valid JWT:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsidG9rZW50cmFuc2l0LmNvbSJdLCJleHAiOjE1NzY3MjM4ODAsImlhdCI6MTU3NjcyMzU4MCwiaXNzIjoiaHR0cHM6Ly9hcGkudGVzdC50b2tlbnBsZXguY29tL3Rlc3RpbmcvIiwic3ViIjoiYmNmYWQ0MWYiLCJkZXZpY2VfaWQiOiJkOGE5NDJjNS1hNzAwLTQ1MGQtOTc3ZC1iMzkzNWFiMGVhODciLCJlbWFpbCI6InVzZXJAZXhhbXBsZS5jb20ifQ.SMt7c2eWSmeeWBZ1yQWoCb2noDKT9vFXuJe4e5ZnKcpyDd0Cu1jSDOLk37vnhKoBrTHOlW5FHJokKX6FpHOq8MREZQw0O1lRwC7px6nqHqDgv3nDgY68kEGnLDSwUoBNwv81_qIGFhJTasFKLzVYNGeZnp4SWN6Z4SnF6rkDeidAQSHIgOSEQ78OPM_5t-0L1DXaemaaj1e7VjSCpilLP-a62sBH-soXHQQVjx6y54ew0e1HFq2I4wSNc2fAXibIrfSL3FE4zXwcXZaUmoWk08-MqnhyExjKPKvmbFdC6oEsKIWE1an7D5p4USCUUXT0QFohEHQbr87ymY1WYkSKVg

Sessions

Requests to Token Transit API endpoints that require a user session will return an error with a 401 Authorization Error status code if no session cookie or valid authorization bearer token is provided. If an authorization bearer token is provided, a user_session_id cookie will be set in the response.

You may wish to use the endpoint /user/login to obtain a session id, as this endpoint has no further side effects.

Any successful request sent with a JWT (except those sent to the /user/logout endpoint) will result in the user_session_id cookie being set. The cookie may be used until the session expires. The session may expire at any time, so you should always first try a call with the user_session_id and fall back to using a JWT if the request fails with a 401 Authorization Error status code.

If you would like to forcibly destroy a session, please call /user/logout. This will block all further calls to the Token Transit Ticketing API using that session id to fail with an authorization error.

Idempotency

All requests that have the ability to modify state will be PUT, POST, DELETE, or PATCH requests. Any of these requests can include an Idempotency-Key header. The idempotency key allows for requests to be retried without duplication of side-effects. All results whether successful or not will be saved server-side allowing a later request including an Idempotency-Key to be retried. These requests will always return the same result.

If an idempotency key is included in a request then the parameters of the request must match all previous requests with that key.

You may use any UUID suitable to yourself, but we strongly recommend generating UUIDs using UUID version 4 as specified in by IETF RFC 4122. Your UUID must be no longer than 128 bytes long and must be encoded in UTF8 format. We recommend either encoding the bytes using URL-safe base 64 encoding or the standard hexadecimal format specified in IETF RFC 4122.

Because GET requests are inherently idempotent (they do not modify state), the Idempotency-Key will be ignored on all GET requests.

Errors

Token Transit uses standard HTTP codes to indicate success or failure as well as a JSON-encoded response for each error as well as a JSON response with more details.

Status Codes

Token Transit Ticketing API uses a set of standard error codes.

JSON Error Response

In addition to the status code, we also return a response with the following fields:

Error Codes

Most errors have a specific error code (set in the code field) that can be used to identify the error. Below is a table of all error codes and their meanings:

Developers

A developer is an entity that uses the Token Transit Ticketing API. Generally your integration will have two developers: test and live. We provide a few endpoints to allow you to verify that your API keys work properly.

Retrieving Developer Info

Retrieves key type and developer id to verify that your key is working. Your API key uniquely identifies what partner is making the request, the environment, and what permissions may be accessed.

HTTP Request

curl "https://api.tokentransit.com/developer" \
  -H "Token-Transit-Api-Key: sk_fake_1234567890abcXYZ" \
  -H "Token-Transit-Api-Version: 2020-05-21"

The above command returns JSON structured like this

{
  "platform_id": "plat_1234567890abcXYZ",
  "platform_name": "Fake Platform",
  "owner_entity_kind": "Platform",
  "developer_id": "dev_1234567890abcXYZ",
  "api_key_type": "secret",
  "env": "fake"
}

GET /developer

HTTP Response

Testing a Secret Key (Requires Secret Key)

This endpoint will return success if you are using a secret key and fail if you are using a publishable key.

HTTP Requst

curl "https://api.tokentransit.com/developer/private" \
  -H "Token-Transit-Api-Key: sk_fake_1234567890abcXYZ" \
  -H "Token-Transit-Api-Version: 2020-05-21"

The above command returns JSON structured like this

{
  "platform_id": "plat_1234567890abcXYZ",
  "platform_name": "Fake Platform",
  "owner_entity_kind": "Platform",
  "developer_id": "dev_1234567890abcXYZ",
  "api_key_type": "secret",
  "env": "fake"
}

GET /developer/private

HTTP Response

Users

A user is the Token Transit representation of an account on your system. Users must be authenticated using JWTs that are signed by your service and returned to our service. We provide endpoints to fetch information about a user, generate a user session, and destroy a user session.

Generating a New User Session (Logging in) (User Authentication Required)

To obtain a user session, make a request to the login endpoint for the user and specify a signed JWT. The session ID returned in the cookie can be used in place of a JWT in any requests requiring User Authentication.

HTTP Request

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6InVzZXItY29udGFjdC1lbWFpbEB0aGlyZC1wYXJ0eS1zaXRlLmNvbSIsImF1ZCI6IlRva2VuVHJhbnNpdCIsImlzcyI6Imh0dHBzOi8vdGhpcmQtcGFydHktc2l0ZS5jb20vcHVibGljLWtleS1zaWduYXR1cmUiLCJzdWIiOiJ1bmlxdWVVc2VySUQxMjM0NTY3ODkwIiwiaWF0IjoxNTE2MjM5MDIyLCJleHAiOjE1NTk0MzAyMjR9.WRYRX2PYdUmouiQgG3r_KOTB7FRaW51YotR_YYuvnTCbymmlCP_I4-Di0QzvH096H7Mjh332JUp_Zx6P-TQt-iriEjCqKkZ8_WS9lc0TYClT5jL1cviS7yaZJgJ" \
  -H "Token-Transit-Api-Key: sk_fake_1234567890abcXYZ" \
  -H "Token-Transit-Api-Version: 2020-05-21" \
  -b /tmp/tt_fake_api_cookies \
  -c /tmp/tt_fake_api_cookies \
  -X POST \
  "https://api.tokentransit.com/user/login"

The above command returns JSON structured like this

{}

POST https://api.tokentransit.com/user/login

HTTP Response

This endpoint responds with an empty JSON object response

Destroying an Existing User Session (Logging out) (User Authentication Required)

To destroy an existing user session, make a request to the logout endpoint and specify the session id.

HTTP Request

The following command assumes you have already sent a login request and saved cookies in

/tmp/tt_fake_api_cookies

curl -H "Token-Transit-Api-Key: sk_fake_1234567890abcXYZ" \
  -H "Token-Transit-Api-Version: 2020-05-21" \

  -b /tmp/tt_fake_api_cookies \
  -c /tmp/tt_fake_api_cookies \
  -X POST \
  "https://api.tokentransit.com/user/logout"

The above command returns JSON structured like this

{}

POST https://api.tokentransit.com/user/logout

Cookies

HTTP Response

The response will always be an empty JSON response upon success with a cookie set to delete the user_session_id cookie.

Agencies

An agency is the issuer of a pass. Fetching an agency will return the location, name, and logo of the agency.

Agency object

All endpoints in this section either return an Agency object or a list of Agency objects.

The Agency object response is defined as follows:

Service Alert effects

A service alert may have one of a number of effects. The effect type may be used to change app behaviour. New effects may be added over time; you should treat unknown effect types the same as OTHER_EFFECT.

Retrieving information about an agency

This endpoint fetches an Agency object using the provided agency id.

HTTP Request

curl "https://api.tokentransit.com/agency/bigbluebus" \
  -H "Token-Transit-Api-Key: sk_fake_1234567890abcXYZ" \
  -H "Token-Transit-Api-Version: 2019-05-01"

The above command returns JSON structured like this

{
  "agency_id": "bigbluebus",
  "agency_name": "Big Blue Bus",
  "location": {
    "latitude": 34.028189,
    "longitude": -118.489176
  },
  "logo_url": "https://storage.googleapis.com/token-transit.appspot.com/myzToIABwReXJuY3z6e4KEGPXx1vOEAP3ZbYD9isQlE-logo.png",
  "region": "Santa Monica, CA",
  "timezone": "America/Los_Angeles",
  "website": "https://www.bigbluebus.com"
}

GET https://api.tokentransit.com/agency/{agency_id}

Path components

Optional Headers

HTTP Response

This endpoint will return an Agency object.

Listing all agencies

All agencies may be retrieved in one RPC.

HTTP Request

curl "https://api.tokentransit.com/agency" \
  -H "Token-Transit-Api-Key: sk_fake_1234567890abcXYZ" \
  -H "Token-Transit-Api-Version: 2019-05-01"

The above command returns JSON structured like this

{
  "agencies": [
    {
      "agency_id": "bigbluebus",
      "agency_name": "Big Blue Bus",
      "location": {
        "latitude": 34.028189,
        "longitude": -118.489176
      },
      "logo_url": "https://storage.googleapis.com/token-transit.appspot.com/myzToIABwReXJuY3z6e4KEGPXx1vOEAP3ZbYD9isQlE-logo.png",
      "region": "Santa Monica, CA",
      "timezone": "America/Los_Angeles",
      "website": "https://www.bigbluebus.com"
    }
  ]
}

GET https://api.tokentransit.com/agency

Optional Headers

HTTP Response

Fares

A fare corresponds to a specific type of pass that a user can buy through token transit. Each fare has a price, a name, and a description. Fare ids are unique per agency.

Fare object

All endpoints in this section either return an Fare object or a list of Fare objects.

The Fare object response is defined as follows:

ProductType is an enum type (represented as a string) that can contain the following values:

Fare Options

Each Fare object will contain a list of option ids. These options help organize the fares into a user-friendly display. Each fare will have a number of options: a rider type, a fare type, and (sometimes) a zone. Although these are the current options that are part of fares, we may add options at any point in the future, and thus listing options is an extensible way to describe the different types.

A FareOption will describe one type of option and all of the available values. Because they are only useful when organizing fares and passes in different ways, the FareOption objects will only be present in API calls that list all fares or passes. In API calls that only return a single Pass or Fare, only the option ids will be included.

A FareOption can be described as follows.

The label should be shown to the user as a label for the category, while the value.name field should be used as the display text to the user and the value.id should be used to uniquely reference the id.

A FareOptionValue object lists the id, user-displayable name, and potentially other information in future versions. The object can be described as follows.

When all of the fares are listed, a complete structure of the fares can be obtained broken down into different categories.

The FareOptions are listed in the order that they should be used for selection.

Selecting fare options

In order to display different fare options, FareOptions may be used to break the list of fares into different categories that can be shown to the user. A selector choosing from amongst all the FareOptionValues of the first type should be shown first. Next, the user should select among all of the FareOptionValue in the second category, but only for fares that already match the first category. In the case that a fare does not have a FareOptionValue of a particular type, this selector should be marked as inactive in the UI, as not having a category indicates that the pass cannot be broken down by this particular FareOption.

You can see how passes are selected in the Token Transit to get a feel for how we use the FareOptions in our app.

Retrieving information about a fare

To retrieve information about a type of pass, a request for a Fare object should be made. Generally, it is better to just list all of the fares at once using the list fares endpoint because it also includes the FareOption list.

HTTP Request

curl "https://api.tokentransit.com/agency/bigbluebus/fare/regular_single_ride" \
  -H "Token-Transit-Api-Key: sk_fake_1234567890abcXYZ" \
  -H "Token-Transit-Api-Version: 2019-05-01"

The above command returns JSON structured like this

{
  "agency_id": "bigbluebus",
  "agency_name": "Big Blue Bus",
  "description": "Valid on all local Big Blue Bus routes. Single ride is valid for 30 minutes after use.",
  "fare_id": "regular_single_ride",
  "fare_name": "Regular Single Ride",
  "options": [
    {
      "id": "rider_regular",
      "type": "rider"
    },
    {
      "id": "fare_single_ride",
      "type": "fare"
    }
  ],
  "price": {
    "amount": 125,
    "currency": "USD"
  },
  "product_type": "single_pass"
}

GET https://api.tokentransit.com/agency/{agency_id}/fare/{fare_id}

Path components

Optional Headers

HTTP Response

A Fare object with the information about the fare with be returned.

Listing all fares

All fares for a provided agency may be retrieved in a single call.

HTTP Request

curl "https://api.tokentransit.com/agency/bigbluebus/fare" \
  -H "Token-Transit-Api-Key: sk_fake_1234567890abcXYZ" \
  -H "Token-Transit-Api-Version: 2019-05-01"

The above command returns JSON structured like this

{
  "fare_options": [
    {
      "label": "Rider",
      "type": "rider",
      "value": [
        {
          "id": "rider_regular",
          "name": "Regular"
        },
        {
          "id": "rider_reduced",
          "name": "S/D/M"
        }
      ]
    },
    {
      "label": "Fare",
      "type": "fare",
      "value": [
        {
          "id": "fare_single_ride",
          "name": "Single Ride"
        },
        {
          "id": "fare_3_ride",
          "name": "3 Ride"
        }
      ]
    }
  ],
  "fares": [
    {
      "agency_id": "bigbluebus",
      "agency_name": "Big Blue Bus",
      "description": "Valid on all local Big Blue Bus routes. Single ride is valid for 30 minutes after use.",
      "fare_id": "regular_single_ride",
      "fare_name": "Regular Single Ride",
      "options": [
        {
          "id": "rider_regular",
          "type": "rider"
        },
        {
          "id": "fare_single_ride",
          "type": "fare"
        }
      ],
      "price": {
        "amount": 125,
        "currency": "USD"
      },
      "product_type": "single_pass"
    },
    {
      "agency_id": "bigbluebus",
      "agency_name": "Big Blue Bus",
      "description": "Valid on all local Big Blue Bus routes. Single ride is valid for 30 minutes after use.",
      "fare_id": "reduced_single_ride",
      "fare_name": "S/D/M Single Ride",
      "options": [
        {
          "id": "rider_reduced",
          "type": "rider"
        },
        {
          "id": "fare_single_ride",
          "type": "fare"
        }
      ],
      "price": {
        "amount": 50,
        "currency": "USD"
      },
      "product_type": "single_pass",
      "restricted_purchase": true,
      "restricted_purchase_text": "This pass is restricted. Riders must be pre-authorized by the transit agency to purchase it. For more information, please contact the transit agency."
    },
    {
      "agency_id": "bigbluebus",
      "agency_name": "Big Blue Bus",
      "description": "Valid on all local Big Blue Bus routes. Single ride is valid for 30 minutes after use.",
      "fare_id": "regular_3_ride",
      "fare_name": "Regular 3 Ride",
      "options": [
        {
          "id": "rider_regular",
          "type": "rider"
        },
        {
          "id": "fare_3_ride",
          "type": "fare"
        }
      ],
      "passes_count": 3,
      "price": {
        "amount": 350,
        "currency": "USD"
      },
      "product_type": "pass_book"
    },
    {
      "agency_id": "bigbluebus",
      "agency_name": "Big Blue Bus",
      "description": "Valid on all local Big Blue Bus routes. Single ride is valid for 30 minutes after use.",
      "fare_id": "reduced_3_ride",
      "fare_name": "S/D/M 3 Ride",
      "options": [
        {
          "id": "rider_reduced",
          "type": "rider"
        },
        {
          "id": "fare_13_ride",
          "type": "fare"
        }
      ],
      "passes_count": 3,
      "price": {
        "amount": 140,
        "currency": "USD"
      },
      "product_type": "pass_book",
      "restricted_purchase": true,
      "restricted_purchase_text": "This pass is restricted. Riders must be pre-authorized by the transit agency to purchase it. For more information, please contact the transit agency."
    }
  ]
}

GET https://api.tokentransit.com/agency/{agency_id}/fare

Path components

Optional Headers

HTTP Response

Passes

Passes are the actual digital product sold by Token Transit. Possession of an active pass shows proof of purchase and can be used to board an appropriate bus for the transit agency. Passes start out as unredeemed and must be redeemed by a user.

Pass Object

All of the endpoints in the the passes section all return a Pass object or a list of Pass and PassBook objects.

The Pass object response is defined as follows:

Pass Statuses

A pass may have a number of statuses. These statuses indicate the state of a pass and whether the pass is usable for boarding, can be activated, and is valid for later use.

PassBook Object

Pass books are a sets of passes that can be used individually but are purchased as one item.

The PassBook object is defined as follows:

PassTransfer Object

Pass transfers correspond to the transfer of a pass from one account to another (usually from your administrative account to a new account).

The PassTransfer object is defined as follows:

PassTransferItem Object

A PassTransferItem corresponds to either a Pass or PassBook that is an item in the user's account.

The PassTransferItem object is defined as follows:

Purchasing fares for redemption (User Authentication Required)

To purchase passes or pass bookes for a user to redeem, a POST request supplying a valid fare_ids[] and agency id (via the a param) should be sent to the pass purchase endpoint.

HTTP Request

curl -X POST \
  -H "Token-Transit-Api-Key: sk_fake_1234567890admin1" \
  -H "Token-Transit-Api-Version: 2019-05-01" \
  -d a=bigbluebus \
  -d fare_ids[]=regular_single_ride \
  -b /tmp/tt_fake_api_cookies \
  -c /tmp/tt_fake_api_cookies \
  "https://api.tokentransit.com/purchase/bulk"

The above command returns JSON structured like this:

{
  "pass_books": null,
  "passes": [
    {
      "agency_id": "bigbluebus",
      "details": {
        "agency_name": "Big Blue Bus",
        "description": "Valid on all local Big Blue Bus routes. Single ride is valid for 30 minutes after use.",
        "name": "Regular Single Ride"
      },
      "fare": {
        "agency_id": "bigbluebus",
        "agency_name": "Big Blue Bus",
        "description": "Valid on all local Big Blue Bus routes. Single ride is valid for 30 minutes after use.",
        "fare_id": "regular_single_ride",
        "fare_name": "Regular Single Ride",
        "price": {
          "amount": 100,
          "currency": "USD"
        }
        "product_type": "single_pass",
      },
      "pass_id": "pass_unactivated",
      "payment_processor": "Stripe",
      "purchase_timestamp": "2020-03-13T16:39:29.988256565-07:00",
      "status": "awaiting_transfer",
    }
  ],
  "pass_transfers": [
    {
      "id": "ptfr_1234567890abcXYZ",
      "items": [{
        "fare": {
          "agency_id": "bigbluebus",
          "agency_name": "Big Blue Bus",
          "fare_id": "regular_single_ride",
          "fare_name": "Regular Single Ride",
          "product_type": "single_pass"
        },
        "id": "pass_unactivated",
        "purchase_timestamp": "2020-03-13T16:39:29.988256565-07:00",
        "status": "awaiting_transfer",
      }],
      "redemption": {
        "url": "https://app.tokentransit.com/redeem/rdm_1234567890abcXYZ",
      },
      "metadata": {
        "invoice_id": 123,
      },
      "status": "awaiting_transfer",
    }
  ],
}

POST https://api.tokentransit.com/purchase/bulk

Query Parameters

HTTP Response

Listing all passes and pass transfers (User Authentication Required)

Existing passes and pass transfers may be retrieved for a user. omit_unusable_passes may not be set to false unless pass_transfer_id is specified. If pass_transfer_id is specified, then only passes related to the specified id will be returned.

HTTP Request

curl "https://api.tokentransit.com/pass?omit_unsuable_passes=false&pass_transfer_id=ptfr_1234567890abcXYZ" \
  -H "Token-Transit-Api-Key: sk_fake_1234567890admin1" \
  -H "Token-Transit-Api-Version: 2020-05-21"

The above command returns JSON structured like this:

{
  "pass_books": null,
  "passes": [
    {
      "agency_id": "bigbluebus",
      "details": {
        "agency_name": "Big Blue Bus",
        "description": "Valid on all local Big Blue Bus routes. Single ride is valid for 30 minutes after use.",
        "name": "Regular Single Ride"
      },
      "fare": {
        "agency_id": "bigbluebus",
        "agency_name": "Big Blue Bus",
        "description": "Valid on all local Big Blue Bus routes. Single ride is valid for 30 minutes after use.",
        "fare_id": "regular_single_ride",
        "fare_name": "Regular Single Ride",
        "product_type": "single_pass"
      },
      "pass_id": "pass_unactivated",
      "payment_processor": "Stripe",
      "purchase_timestamp": "2020-03-13T16:39:29.988256565-07:00",
      "status": "awaiting_transfer"
    }
  ],
  "pass_transfers": [
    {
      "id": "ptfr_1234567890abcXYZ",
      "items": [
        {
          "fare": {
            "agency_id": "bigbluebus",
            "agency_name": "Big Blue Bus",
            "fare_id": "regular_single_ride",
            "fare_name": "Regular Single Ride",
            "product_type": "single_pass"
          },
          "id": "pass_unactivated",
          "purchase_timestamp": "2020-03-13T16:39:29.988256565-07:00",
          "status": "awaiting_transfer",
          "type": "pass"
        }
      ],
      "redemption": {
        "url": "https://app.tokentransit.com/redeem/rdm_1234567890abcXYZ"
      },
      "metadata": {
        "invoice_id": 123
      },
      "status": "awaiting_transfer"
    }
  ]
}

GET https://api.tokentransit.com/pass

Query Parameters

HTTP Response

Refunding a Pass, Pass Book, or Pass Transfer

As long as a pass or pass book has not been transferred and activated, it may refunded. Pass transfers may be refunded as well.

Semantics for refunding pass transfers:

Semantics for refunding individual passes or pass books:

HTTP Request

curl -X POST \
  -H "Token-Transit-Api-Key: sk_fake_1234567890admin1" \
  -H "Token-Transit-Api-Version: 2019-05-01" \
  -d id="pass_unactivated" \
  -b /tmp/tt_fake_api_cookies \
  -c /tmp/tt_fake_api_cookies \
  "https://api.tokentransit.com/refund"

The above command returns JSON structured like this:

{
  "pass_books": null,
  "passes": [
    {
      "agency_id": "bigbluebus",
      "details": {
        "agency_name": "Big Blue Bus",
        "description": "Valid on all local Big Blue Bus routes. Single ride is valid for 30 minutes after use.",
        "name": "Regular Single Ride",
        "type": "pass"
      },
      "fare": {
        "agency_id": "bigbluebus",
        "agency_name": "Big Blue Bus",
        "description": "Valid on all local Big Blue Bus routes. Single ride is valid for 30 minutes after use.",
        "fare_id": "regular_single_ride",
        "fare_name": "Regular Single Ride",
        "product_type": "single_pass"
      },
      "pass_id": "pass_unactivated",
      "payment_processor": "Stripe",
      "purchase_timestamp": "2020-03-13T16:39:29.988256565-07:00",
      "refund_timestamp": "2020-03-13T16:39:29.988256565-07:00",
      "status": "refunded"
    }
  ],
  "pass_transfers": [
    {
      "id": "ptfr_1234567890abcXYZ",
      "creation_timestatmp": "2020-03-13T16:39:29.988256565-07:00",
      "items": [
        {
          "fare": {
            "agency_id": "bigbluebus",
            "agency_name": "Big Blue Bus",
            "fare_id": "regular_single_ride",
            "fare_name": "Regular Single Ride",
            "product_type": "single_pass"
          },
          "id": "pass_unactivated",
          "type": "pass",
          "purchase_timestamp": "2020-03-13T16:39:29.988256565-07:00",
          "refund_timestamp": "2020-03-13T16:39:29.988256565-07:00"
        }
      ],
      "metadata": {
        "invoice_id": 123
      },
      "refund_timestamp": "2020-03-13T16:39:29.988256565-07:00",
      "status": "cancelled"
    }
  ]
}

POST https://api.tokentransit.com/refund

Query Parameters

Headers

The following headers are either required, strongly recommended, or specific to this endpoint.

HTTP Response