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.

The proxy service call does not use this globally set 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 ... }

Note that 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 ... }

Note that 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.

createTokenIntent

Token Intents provide a secure mechanism to collect and validate sensitive information, like card details, before converting it into a long-lived token. Using the Basis Theory iOS SDK, you can initiate a token intent request with minimal client-side code:

let request = CreateTokenIntentRequest(
    type: "card",
    data: [
        "number": cardNumberTextField.text ?? "",
        "expiration_month": expirationDateTextField.month(),
        "expiration_year": expirationDateTextField.year(),
        "cvc": cvcTextField.text ?? ""
    ]
)

BasisTheoryElements.createTokenIntent(request: request) { result in
    switch result {
    case .success(let tokenIntent):
        print("Token Intent created: \(tokenIntent.id)")
    case .failure(let error):
        print("Failed to create Token Intent: \(error)")
    }
}

This initiates a card Token Intent, which can then be used for authentication, 3DS, or converted into a permanent token depending on your use case.

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 Error
data of type JSON - JSON is a data structure that has dynamic member lookup capabilities. This allows you to traverse a token without giving you access to read any sensitive values in token.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 ... }

Note that proxy requires the use of a sessionKey (an API key issued via createSession).

The callback provided calls your function with a:

response of type URLResponse
error of type Error
data 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.

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

Invoking HTTP Client Service w/ POST
@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 response from this service is the actual plaintext data. It may contain sensitive data depending on the third-party API response.

The callback provided calls your function with a:

response of type URLResponse
error of type Error
data 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.

Invoking HTTP Client Service w/ PUT
@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 response from this service is the actual plaintext data. It may contain sensitive data depending on the third-party API response.

The callback provided calls your function with a:

response of type URLResponse
error of type Error
data 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.

Invoking HTTP Client Service w/ PATCH
@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 response from this service is the actual plaintext data. It may contain sensitive data depending on the third-party API response.

The callback provided calls your function with a:

response of type URLResponse
error of type Error
data 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.

Invoking HTTP Client Service w/ GET
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 response from this service is the actual plaintext data. It may contain sensitive data depending on the third-party API response.

The callback provided calls your function with a:

response of type URLResponse
error of type Error
data 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.

Invoking HTTP Client Service w/ DELETE
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 response from this service is the actual plaintext data. It may contain sensitive data depending on the third-party API response.

The callback provided calls your function with a:

response of type URLResponse
error of type Error
data 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 a JSON 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 a JSON 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

The ErrorResponse enum can be imported from the BasisTheory Swift SDK through the BasisTheory package, which is a dependency of the iOS BasisTheoryElements package.

Static Fields​

Methods​

tokenize​

createToken​

createTokenIntent​

encryptToken​

Encrypt Multiple Token Payloads​

createSession​

getTokenById​

proxy​

Access non-sensitive responses from Proxy calls Beta​

HTTP Client Services​

post​

put​

patch​

get​

delete​

JSON​

Errors​

ErrorResponse Enum​

Static Fields

Methods

tokenize

createToken

createTokenIntent

encryptToken

Encrypt Multiple Token Payloads

createSession

getTokenById

proxy

Access non-sensitive responses from Proxy calls
Beta

HTTP Client Services

post

put

patch

get

delete

JSON

Errors

ErrorResponse Enum