Introduction

Welcome to the Token Transit Payments API.

The Token Transit Payments API is a RESTful service that can be used as a drop-in Stripe replacement allowing roll-ups, custom receipts, and other useful payment functionality.

The payments API allows purchase of payments for authenticated users in third-party applications.

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

Headers

The Token Transit 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.

Cookies used are described in the Cookies section.

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.

`

Cookies

These are all of the cookies that are used in the API.

API Authentication

Token Transit 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 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 to provide us with a JWT that we can use to verify account credentials. You must have a user id (unique per user) for each of your users that you are willing to share with us and that you guarantee you can map back to a user for the duration of our integration with you.

The JWT should be specified according to IETF RFC 7519 and specify a number of claims and be signed using a key that is specified according to IETF RFC 7517 using an algorithm specified in IETF RFC 7518.

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

• Introduction to JWTs
• Description of JWKS
• Description of JWKS

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:

Sessions

In order to speed up calls and shrink the size of requests, we create a session id after every successful use of a JWT. The session id is returned in the user_session_id cookie and can be used in place of the normal JWT authentication. If both a session id and a JWT are included in a request, the JWT is ignored.

You may wish to use the endpoint /user/login to obtain a session id, as this endpoint has no further side effects. Any changes in a JWT will always result in a new session being created regardless of whether the JWT is for the same user on the same device.

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. This cookie may be used in place of a JWT authentication 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 failes 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 API using that session id to fail with an authorization error.

Versioning

The Token Transit 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.

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 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:

Developers

A developer is an entity that uses the Token Transit 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 yJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6InVzZXItY29udGFjdC1lbWFpbEB0aGlyZC1wYXJ0eS1zaXRlLmNvbSIsImF1ZCI6IlRva2VuVHJhbnNpdCIsImlzcyI6Imh0dHBzOi8vdGhpcmQtcGFydHktc2l0ZS5jb20vcHVibGljLWtleS1zaWduYXR1cmUiLCJzdWIiOiJ1bmlxdWVVc2VySUQxMjM0NTY3ODkwIiwiaWF0IjoxNTE2MjM5MDIyLCJleHAiOjE1NTk0MzAyMjR9.WRYRX2PYdUmouiQgG3r_KOTB7FRaW51YotR_YYuvnTCbymmlCP_I4-Di0QzvH096H7Mjh332JUp_Zx6P-TQt-iriEjCqKkZ8_WS9lc0TYClT5jL1cviS7yaZJgJfzakZL8nDtfseRMuXRNVy5nym87u_wZrZR20KpqlCSkhb-MI" \
  -H "Token-Transit-Api-Key: sk_fake_1234567890abcXYZ" \
  -H "Token-Transit-Api-Version: 2020-05-21" \
  -d include_stripe_customer_id=true \
  -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

{
  "stripe_customer_id": "cus_1234567890abdXYZ"
}

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

Query Parameters

HTTP 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/login

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.

Payments

A payment object is an updateable object that encompasses the entire flow for a single payment. Each payment has an id that is associated with the payment that can be used for retrieval and update.

Headers

The following headers are either required, strongly recommended, or specific to this set of endpoints.

Response Object

All responses in this section will return a response object with the following fields

Creating a Payment (User Authentication Required)

Creating a payment will always be the first thing that you do. If you supply enough information, this payment may be confirmed.

HTTP Request

POST /agency/{agency_id}/payment

Path components

Query Parameters

HTTP Response

A payment object.

Retrieving a Payment (User Authentication Required)

Retrieve an existing payment

HTTP Request

GET /agency/{agency_id}/payment/{payment_id}

Path components

Updating a Payment (User Authentication Required)

Update existing fields of a payment (e.g. payment_method, amount, currency, metadata, etc.)

This is optional if the original create request contained all of the necessary fields.

Path components

Query Parameters

HTTP Response

A payment object

Confirming a Purchase (User Authentication Required)

This endpoint is used to confirm a purchase. After submission, the payment will be executed.

HTTP Request

POST /agency/{agency_id}/payment/{payment_id}/confirm

Path components

Query Parameters

Cancelling a Purchase (User Authentication Required)

This endpoint is used to cancel a purchase. A purchase may be cancelled at any time, even after the purchase has already gone through.

HTTP Request

POST /agency/{agency_id}/payment/{payment_id}/cancel

Path components

Query Parameters

HTTP Response

A payment object (generally with the status set to cancelled. If a non-retryable error is received, it means the payment was not cancelled.