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.
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.
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"
))
Put
The example below shows how to use the HTTP client service to make a PUT request to a third-party API with an element in the payload.
private val bt = BasisTheoryElements.builder()
.apiUrl(BuildConfig.BASIS_THEORY_API_URL)
.apiKey(BuildConfig.BASIS_THEORY_API_KEY)
.build()
...
bt.client.put("https://api.psp.com/v1/payment_methods/id",
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"
))
Patch
The example below shows how to use the HTTP client service to make a PATCH request to a third-party API with an element in the payload.
private val bt = BasisTheoryElements.builder()
.apiUrl(BuildConfig.BASIS_THEORY_API_URL)
.apiKey(BuildConfig.BASIS_THEORY_API_KEY)
.build()
...
bt.client.patch("https://api.psp.com/v1/payment_methods/id",
object {
val card = object {
val exp_month = binding.expirationDate.month()
val exp_year = binding.expirationDate.year()
}
},
mapOf(
"Authorization" to "Bearer ...",
"Content-Type" to "application/x-www-form-urlencoded"
))
Get
The example below shows how to use the HTTP client service to make a GET request to a third-party API.
private val bt = BasisTheoryElements.builder()
.apiUrl(BuildConfig.BASIS_THEORY_API_URL)
.apiKey(BuildConfig.BASIS_THEORY_API_KEY)
.build()
...
bt.client.get("https://api.psp.com/v1/payment_methods/id",
mapOf(
"Authorization" to "Bearer ...",
))
Delete
The example below shows how to use the HTTP client service to make a DELETE request to a third-party API.
private val bt = BasisTheoryElements.builder()
.apiUrl(BuildConfig.BASIS_THEORY_API_URL)
.apiKey(BuildConfig.BASIS_THEORY_API_KEY)
.build()
...
bt.client.delete("https://api.psp.com/v1/payment_methods/id",
mapOf(
"Authorization" to "Bearer ...",
"Accept" to "application/json",
))