Services
Static Fields
You can set your API key globally for BasisTheoryElements
through the static apiKey
field.
BasisTheoryElements.apiKey = "<YOUR PUBLIC BT API KEY>"
All service method calls take an optional apiKey
should you need to override the globally set apiKey
.
apiKey
since its use case is different from the other services and requires a session API key for requests.Methods
tokenize
Elements' values can be securely tokenized utilizing our tokenize services. To accomplish this, simply pass the Element instance in the payload.
let body: [String: Any] = [
"data": [
"property": <BasisTheory Element instance>,
"myProp": "myValue"
],
"search_indexes": ["{{ data.property }}"],
"type": "token"
]
BasisTheoryElements.tokenize(body: body, apiKey: "<PUBLIC_API_KEY>")
{ data, error in ... }
tokenize
requires the use of a public API key (an API key issued to a public
Application). Click here to create one in the Basis Theory portal.The callback provided calls your function with a data
of type AnyCodable, and an error
of type Error.
createToken
Elements' values can be securely tokenized utilizing our createToken services. To accomplish this, simply pass the Element instance in the payload.
let body: CreateToken = CreateToken(type: "token", data: [
"property": <BasisTheory Element instance>,
"myProp": "myValue",
], searchIndexes: ["{{ data.property }}"])
BasisTheoryElements.createToken(body: body, apiKey: "<PUBLIC_API_KEY>")
{ data, error in ... }
createToken
requires the use of a public API key (an API key issued to a public
Application). Click here to create one in the Basis Theory portal.The callback provided calls your function with a data
of type CreateTokenResponse, and an error
of type Error.
encryptToken
This function encrypts sensitive data using a public key and Key ID created through Encryption Keys.
The encryptToken
method enables encryption of data payloads, transforming sensitive information into encrypted JSON Web Encryption (JWE) strings.
The encryptToken
method accepts data objects containing element instances and plaintext payloads. It also supports encrypting multiple nested token payloads within a single operation.
let cardTokenRequest: [String: Any] = [
"type": "card",
"data": [
"number": cardNumberElement, // an instance of CardNumberUITextField
"expiration_month": cardExpirationElement.month(), // using the data parsing method
"expiration_year": cardExpirationElement.year(),
"cvc": cardCvcElement // an instance of CardVerificationCodeUITextField
]
]
let encryptTokenRequest = EncryptTokenRequest(
tokenRequests: cardTokenRequest,
publicKey: "-----BEGIN PUBLIC KEY-----\nw6RFs74UmOcxjbWBSlZQ0...=\n-----END PUBLIC KEY-----",
keyId: "d6b86549-212f-4bdc-adeb-2f39902740f6"
)
let encryptResponse = try BasisTheoryElements.encryptToken(input: encryptTokenRequest)
// Response contains encrypted JWE string and type
print(encryptResponse.encrypted) // JWE encrypted payload
print(encryptResponse.type) // Token type
Encrypt Multiple Token Payloads
The encryptToken
method allows you to encrypt multiple token payloads in a single operation by nesting them under object keys:
let multipleTokenRequests: [String: [String: Any]] = [
"creditCard": [
"type": "card",
"data": [
"number": cardNumberElement, // an instance of CardNumberUITextField
"expiration_month": cardExpirationElement.month(),
"expiration_year": cardExpirationElement.year(),
"cvc": cardCvcElement
]
],
"bankAccount": [
"type": "bank",
"data": [
"routing_number": routingNumberElement, // an instance of TextElementUITextField
"account_number": accountNumberElement
]
],
"personalInfo": [
"type": "token",
"data": [
"name": nameElement, // an instance of TextElementUITextField
"email": emailElement
]
]
]
let encryptTokenRequest = EncryptTokenRequest(
tokenRequests: multipleTokenRequests,
publicKey: "-----BEGIN PUBLIC KEY-----\nw6RFs74UmOcxjbWBSlZQ0...=\n-----END PUBLIC KEY-----",
keyId: "d6b86549-212f-4bdc-adeb-2f39902740f6"
)
let encryptResponse = try BasisTheoryElements.encryptToken(input: encryptTokenRequest)
// Multiple encrypted payloads returned in the response
print(encryptResponse.creditCard.encrypted) // Encrypted card data
print(encryptResponse.bankAccount.encrypted) // Encrypted bank data
print(encryptResponse.personalInfo.encrypted) // Encrypted personal data
// Each response includes the token type
print(encryptResponse.creditCard.type) // "card"
print(encryptResponse.bankAccount.type) // "bank"
print(encryptResponse.personalInfo.type) // "token"
// Full response with all encrypted payloads
print(encryptResponse.description)
As you can see from these examples, the encryptToken
function is capable of resolving the raw data
from references to Element inputs and encrypting them securely. This enables your application to encrypt
sensitive data values without needing to touch the raw data directly. The response contains only the
encrypted JWE string and token type - no plaintext data is exposed.
createSession
To retrieve sensitive data on iOS, you'll need to create a session
and use its sessionKey
for making requests securely. To accomplish this, simply construct your createSession
request like this:
BasisTheoryElements.createSession(
apiKey: "<YOUR PUBLIC BT API KEY>"
) { data, error in ... }
The callback provided calls your function with a data
of type CreateSessionResponse, and an error
of type Error.
getTokenById
This function wraps the get a token API endpoint to retrieve a single strongly typed token. The token's data is transformed 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.
BasisTheoryElements.getTokenById(
id: "<YOUR TOKEN ID>",
apiKey: "<YOUR API KEY>",
) { data, error in ... }
The callback provided calls your function with a:
error
of type Errordata
of typeJSON
-JSON
is a data structure that has dynamic member lookup capabilities. This allows you to traverse atoken
without giving you access to read any sensitive values intoken.data
which means you stay compliant.
To show a value from the token data
, traverse the JSON using dot or bracket notation and retrieve the value using the elementValueReference
property.
Below is an example of how you do that and set the value reference into a Text Element.
@IBOutlet private weak var myTextElement: TextElementUITextField!
...
BasisTheoryElements.getTokenById(
id: "<YOUR TOKEN ID>",
apiKey: "<YOUR API KEY>",
) { data, error in
myTextElement.setValue(elementValueReference: data!.data!.nested!.property!.elementValueReference)
}
proxy
Proxy provides a simple way to send data securely using an element and/or retrieve data back into an element utilizing our proxy service. To accomplish this, simply construct your proxy
request like this:
@IBOutlet weak var testElement: TextElementUITextField!
let proxyHttpRequest = ProxyHttpRequest(method: .post, body: [
"testProp": "testValue",
"testElementPro": testElement,
"objProp": [
"nestedTestProp": "nestedTestValue"
]
], headers: [
"X-My-Custom-Header": "headerValue",
])
BasisTheoryElements.proxy(
apiKey: "<YOUR SESSION BT API KEY>",
proxyKey: "<YOUR PROXY KEY>",
proxyHttpRequest: proxyHttpRequest
) { response, data, error in ... }
The callback provided calls your function with a:
response
of type URLResponseerror
of type Errordata
of type JSON
Below is an example of how you can use a response from a proxy
with our elements.
@IBOutlet private weak var myTextElement: TextElementUITextField!
...
BasisTheoryElements.proxy(
apiKey: "<YOUR SESSION BT API KEY>",
proxyKey: "<YOUR PROXY KEY>",
proxyHttpRequest: proxyHttpRequest)
{ response, data, error in
myTextElement.setValue(elementValueReference: data.my?.nested?.property?.elementValueReference)
let body: CreateToken = CreateToken(type: "token", data: [
"myNestedProxyResponseProperty": myTextElement,
])
BasisTheoryElements.createToken(body: body, apiKey: "<PUBLIC_API_KEY>")
{ data, error in print(data) }
}
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 Services
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.
@IBOutlet private weak var myTextElement: TextElementUITextField!
let payload = [
"textElementProp": myTextElement,
"plainTextProp": "plaintext value",
"object" : [
"nestedProp": "nested value"
],
"array": [1, 2, 3]
] as [String : Any]
let config = Config(headers: [
"Content-Type": "application/json",
"Accept": "application/json",
"X-Test-Header": "test header value"
])
BasisTheoryElements.post(url: "https://www.api.thirdpartydomain.com/resources", payload: payload, config: config) { request, data, error in
print(data)
}
The callback provided calls your function with a:
response
of type URLResponseerror
of type Errordata
of type JSON
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.
@IBOutlet private weak var myTextElement: TextElementUITextField!
let payload = [
"textElementProp": myTextElement,
"plainTextProp": "plaintext value",
"object" : [
"nestedProp": "nested value"
],
"array": [1, 2, 3]
] as [String : Any]
let config = Config(headers: [
"Content-Type": "application/json",
"Accept": "application/json",
"X-Test-Header": "test header value"
])
BasisTheoryElements.put(url: "https://www.api.thirdpartydomain.com/resources/id", payload: payload, config: config) { request, data, error in
print(data)
}
The callback provided calls your function with a:
response
of type URLResponseerror
of type Errordata
of type JSON
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.
@IBOutlet private weak var myTextElement: TextElementUITextField!
let payload = [
"textElementProp": myTextElement,
"plainTextProp": "plaintext value",
"object" : [
"nestedProp": "nested value"
],
"array": [1, 2, 3]
] as [String : Any]
let config = Config(headers: [
"Content-Type": "application/json",
"Accept": "application/json",
"X-Test-Header": "test header value"
])
BasisTheoryElements.patch(url: "https://www.api.thirdpartydomain.com/resources/id", payload: payload, config: config) { request, data, error in
print(data)
}
The callback provided calls your function with a:
response
of type URLResponseerror
of type Errordata
of type JSON
get
The example below shows how to use the HTTP client service to make a GET request to a third-party API.
let config = Config(headers: [
"Content-Type": "application/json",
"Accept": "application/json",
"X-Test-Header": "test header value"
])
BasisTheoryElements.get(url: "https://www.api.thirdpartydomain.com/resources/id", config: config) { request, data, error in
print(data)
}
The callback provided calls your function with a:
response
of type URLResponseerror
of type Errordata
of type JSON
delete
The example below shows how to use the HTTP client service to make a DELETE request to a third-party API.
let config = Config(headers: [
"Content-Type": "application/json",
"Accept": "application/json",
"X-Test-Header": "test header value"
])
BasisTheoryElements.delete(url: "https://www.api.thirdpartydomain.com/resources/id", config: config) { request, data, error in
print(data)
}
The callback provided calls your function with a:
response
of type URLResponseerror
of type Errordata
of type JSON
JSON
JSON
is a data structure that has dynamic member lookup capabilities. This means that you can traverse a JSON
response using dot or bracket notation. Each property in a
JSON
struct returns a JSON
struct has the following properties to help read sensitive and non-sensitive properties:
elementValueReference
- This property is used to get the sensitive value of aJSON
property. It returns a value reference that can be used to set the value of an iOS Basis Theory element.rawValue
- This property is used to get the non-sensitive value of aJSON
property. It returns the plaintext value of the property.
Only numbers, booleans, and strings can be retrieved using this struct.
Errors
Error | Description |
---|---|
TokenizingError.applicationTypeNotPublic | The Application API key used is not of type public . Create a public API key through this link. |
TokenizingError.invalidInput | An element instance used in a tokenization request is invalid. Check the element events on each element to determine which one is invalid. |
ProxyError.invalidRequest | The proxy request is malformed. Revise the proxy request being attempted. |
ErrorResponse.error | An instance of ErrorResponse enum gets returned when there's an error from the BasisTheory API. |
ErrorResponse Enum
Order | Associated Value Name | Description |
---|---|---|
1 | status | An Int describing the response status code |
2 | data | A Data? instance describing the response body |
3 | urlResponse | The raw UrlResponse? instance |
4 | error | The raw Error instance |
ErrorResponse
enum can be imported from the BasisTheory Swift SDK through the BasisTheory
package, which is a dependency of the iOS BasisTheoryElements
package.