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 Element, object, array, or any primitive type such as an integer, boolean, or string

Access non-sensitive responses from Proxy calls
Beta

Our Elements enable you to convert proxy responses into plain text, which is ideal for non-sensitive data handling. This enhancement streamlines your data processing workflows and facilitates an easier understanding of the returned data, bypassing decryption or tokenization.

This feature is currently invite-only. If you're interested, please get in touch for an invitation.

You can capture values from any of our Elements; hence we strongly recommend only using this feature for non-sensitive data. Converting proxy responses to plain text can expose the underlying data to risks, such as unauthorized access or leakage. Ensure the plain-text proxy responses align with your data security policy, data handling practices, and compliance obligations. If you're unsure, please get in touch for guidance at www.basistheory.com/contact

HTTP Client

Element values can be used in a request to a third-party API using our HTTP client service.

Post

The example below shows how to use the HTTP client service to make a POST request to a third-party API with an element in the payload.

Invoking HTTP Client Service w/ POST
private val bt = BasisTheoryElements.builder()
    .apiUrl(BuildConfig.BASIS_THEORY_API_URL)
    .apiKey(BuildConfig.BASIS_THEORY_API_KEY)
    .build()
...

bt.client.post("https://api.psp.com/v1/payment_methods",
    object {
        val type = "card"
        val billing_details = object {
            val name =  "Peter Panda"
        }
        val card = object {
            val number = binding.cardNumber
            val exp_month = binding.expirationDate.month()
            val exp_year = binding.expirationDate.year()
            val cvc = binding.cvc
        }
    },
    mapOf(
        "Authorization" to "Bearer ...",
        "Content-Type" to "application/x-www-form-urlencoded"
    ))