Services

BasisTheoryElements

The BasisTheoryElements class contains methods for interacting with the Basis Theory API using element references.

Initialization

A new instance of the BasisTheoryElements service can be configured using the builder pattern:

val bt = BasisTheoryElements.builder()
    .apiUrl("https://api.basistheory.com") // optional
    .apiKey(myApiKey)
    .dispatcher(myDispatcher) // optional
    .build()

The following values are used by default if not specified when constructing an instance of the service:

• apiUrl: https://api.basistheory.com
• apiKey: null
• ioDispatcher: Dispatchers.IO

Note that BasisTheoryElements requires the use of a public API key during initialization (an API key issued to a public Application). Click here to create one in the Basis Theory portal.

tokenize

This function wraps the tokenize API endpoint providing added support for referencing instances of elements within your request payload.

val tokenizeResponse = bt.tokenize(object {
    val type = "token"
    val data = object {
        val name = nameElement // an instance of TextElement
        val phoneNumber = phoneNumberElement // an instance of TextElement
        val note = "Non sensitive value" // plaintext strings can also be included in the token body
    }
    val expires_at = "2022-11-03T19:14:21.4333333Z" // all standard token attributes are supported
})

As you can see from this example, the tokenize function is capable of resolving the raw data from references to Element inputs. This enables your application to tokenize sensitive data values without needing to touch the raw data directly.

createToken

This function wraps the create token API endpoint to create a single strongly typed token. It also provides added support for referencing instances of Elements within your request payload.

val createTokenResponse = bt.createToken(CreateTokenRequest().apply {
    this.type = "token"
    this.data = object {
        val name = nameElement // an instance of TextElement
        val phoneNumber = phoneNumberElement // an instance of TextElement
        val note = "Non sensitive value" // plaintext strings can also be included in the token body
    }
    this.expires_at = "2022-11-03T19:14:21.4333333Z" // all standard token attributes are supported
})

As you can see from this example, the createToken function is capable of resolving the raw data from references to Element inputs. This enables your application to tokenize sensitive data values without needing to touch the raw data directly.

createSession

To retrieve sensitive data on Android, you'll need to create a session and use its sessionKey for making requests securely. To accomplish this, simply call the createSession function like this:

val session = bt.createSession()

This returns a CreateSessionResponse which contains a nonce that needs to be used to authorize the session before using it.

To learn more about how to authorize a session, read our guide Access Data Using Sessions.

getToken

This function wraps the get a token API endpoint to retrieve a single strongly typed token. It then transforms the token's data to value references which you can use to set the value of your elements without touching the plaintext value and pulling your application into compliance scope.

val getTokenResponse = bt.getToken("<tokenId>")

proxy

This function receives a ProxyRequest and wraps the proxy API endpoint to proxy a request to a third party API. It then transforms the response to value references which you can then use to set the value of your elements without touching the plaintext value and pulling your application into compliance scope.

val proxyResponse = bt.proxy.post(proxyRequest)

Methods Supported

Signature	Description
get(proxyRequest: ProxyRequest, apiKeyOverride: String? = null): Any?	Performs a proxy GET request.
post(proxyRequest: ProxyRequest, apiKeyOverride: String? = null): Any?	Performs a proxy POST request.
put(proxyRequest: ProxyRequest, apiKeyOverride: String? = null): Any?	Performs a proxy PUT request.
patch(proxyRequest: ProxyRequest, apiKeyOverride: String? = null): Any?	Performs a proxy PATCH request.
delete(proxyRequest: ProxyRequest, apiKeyOverride: String? = null): Any?	Performs a proxy DELETE request.

ProxyRequest

Attribute	Required	Type	Default	Description
path	false	String?	null	The sub-path of the HTTP URL.
queryParams	false	Map<String, String>?	emptyMap()	Map of query parameters to include in the request.
headers	false	Map<String, String>?	emptyMap()	Map of headers to include in the request.
body	false	Any?	null	The request body. Can be an object, array, or any primitive type such as an integer, boolean, or string