SDKs
iOS SDK
You can use our iOS SDK to:
- Encrypt data
- Embed UI Components
- Attest Enclaves
- Support Apple Pay
Supported Platforms
- iOS 15+
- macOS 12+
Quickstart
Install SDK
The Evervault iOS SDK can be installed using the Swift Package Manager.
- Open your Xcode project.
- Navigate to File > Swift Packages > Add Package Dependency.
- Enter the repository URL for the Evervault iOS SDK:
https://github.com/evervault/evervault-ios.git
. - Choose the latest available version or specify a version rule.
- Click Next and follow the instructions to integrate the package into your project.
Initialize SDK
Now, let's initialize the SDK using our App and Team ID. If you don't have one yet, you can get one by creating an App in the Evervault Dashboard.
If you need multiple instances of the Evervault SDK you can use the initializer as follows:
Encrypting Data
Once the SDK is configured, you can use the encrypt
method to encrypt your sensitive data. The encrypt
method accepts various data types, including Boolean, Numerics, Strings, Arrays, Dictionaries, and Data.
Here's an example of encrypting a password:
Or using a dedicated instance:
The encrypt
method returns an Any
type, so you will need to safely cast the result based on the data type you provided. For Boolean, Numerics, and Strings, the encrypted data is returned as a String. For Arrays and Dictionaries, the encrypted data maintains the same structure but is encrypted. For Data, the encrypted data is returned as encrypted Data, which can be useful for encrypting files.
Decrypting Data
Decrypts data previously encrypted with the encrypt()
function or through Relay.
The decrypt()
method allows you to decrypt previously encrypted data using a token.
The token is a time bound token for decrypting data. The token can be generated using our backend SDKs or through our REST API.
The payload must be the same payload that was used to create the token and expires in a maximum of 10 minutes depending on the expiry set when creating the token.
Inputs
The Evervault iOS SDK also includes the EvervaultInputs
module, which provides a SwiftUI view called PaymentCardInput
. This view is designed for capturing credit card information and automatically encrypts the credit card number and CVC without exposing the unencrypted data. The PaymentCardInput
view can be customized to fit your application's design.
To use PaymentCardInput
, make sure you have imported the EvervaultInputs
module in your file, and then simply add the view to your SwiftUI hierarchy:
Fields can be optionally displayed by passing in the enabledFields struct. For example if you with to only render the Card Number field use the following code.
The encrypted credit card number and CVC are captured in the PaymentCardData
Binding, as well as the expiry month and year and validation fields.
Styling
Internally, the PaymentCardInput
view uses SwiftUI TextField
s. These can be customized using SwiftUI modifiers like any other TextField
s in your application:
To provide more customization options, the PaymentCardInput
can be styled using a PaymentCardInputStyle
. There are two build-in styles:
InlinePaymentCardInputView
(the default style) - puts the credit card number, expiry and cvc fields all on a single row.
To explicitly use this style:
RowsPaymentCardInputStyle
- puts the credit card number on a single row. Below it, places the expiry and cvc fields next to each other.
To use this style:
If these two styles do not match your use case, you can create your own style:
Attest Enclaves
The Evervault iOS SDK includes the ability to attest connections to Enclaves.
To attest your Enclave, you need to provide the expected PCRs to a Enclave session.
Apple Pay®
Evervault Apple Pay for iOS is currently in Beta. Please contact support@evervault.com for more information.
The Evervault iOS SDK provides support for Apple Pay on iOS, enabling secure handling of card data during mobile transaction flows. When a customer taps the Apple Pay button in your app, our SDK will give you the Apple Pay card token (DPAN) from the user's device.
Instead of using Apple's default encryption, the SDK extracts the customer's card details, including the card token and “cryptogram”, and returns them in an Evervault-encrypted payload. This allows you to securely access sensitive values while ensuring they remain protected through Evervault's encryption infrastructure.
The encrypted payload can then be safely passed to any downstream system or payment processor for transaction authorization using our proxy, Evervault Relay.
Prerequisites
You must have an individual or organisational Apple Developer account.
All users of Apple Pay agree to adhere to the Apple Pay Terms and Conditions.
Register for an Apple Merchant ID
Before you can use Apple Pay for iOS with Evervault you need to obtain an Apple Merchant ID by registering for a new identifier on the Apple Developer portal. Fill out the description and identifier. We recommend you use the name of your app as the identifier e.g. merchant.com.<YOUR_APPS_NAME>
Create a new Apple Pay Payment Processing Certificate
Apple Pay needs to encrypt payment data such as card details. You will need a payment processing certificate for your app to allow Apple Pay to encrypt those details within your app.
In the Evervault dashboard, click the Payments
tab at the top of the page. Then, on the left-hand side of the page click Apple Pay
and at the bottom of the page under Certificates
, click Add certificate
. Follow the on screen instructions.
As part of this flow, Evervault will provide you with a certificate signing request that you must download.
Then, in a new tab, in the Apple Developer portal, under Certificates, create an Apple Pay Payment Processing Certificate
, select the Merchant ID that you created in the previous step and click Continue
. Under the Apple Pay Payment Processing Certificate
section, click Create Certificate
and upload the certificate signing request you downloaded from the Evervault dashboard.
Download the Apple certificate you just created and go back to the Evervault dashboard and in the certificate set up dialog, upload the certificate you just downloaded from Apple.
Setting up Xcode
Once you have created your merchant identifier and payment processing certificate, you need to add the Apple Pay capability to your app in Xcode.
Open your project settings, click the Signing & Capabilities
tab, and add the Apple Pay capability. You might be prompted to sign in to your developer account. Select the merchant ID you created earlier, and now your app is ready to accept Apple Pay.
Create a Transaction
Next you will need to create a transaction to describe the payment you want to process. You will need to provide the country, currency, and line items for the transaction. The last item is the total for the transaction.
If the transaction is not constructed correctly e.g country or currency fields aren’t correct or there are no summary items then an EvervaultError.InvalidTransaction
error will be thrown.
Please refer to Apple’s documentation on requirements for country and currency and amount
fields.
Check if Apple Pay is supported
Before displaying Apple Pay as a payment option, determine if the user’s device supports Apple Pay and that they have a card added to their wallet by calling the isAvailable()
method.
Render the Apple Pay button
Next you can render the Apple Pay button. When you do this, you will need to pass in your Evervault App ID, your Apple Merchant Identifier, the transaction object, the card networks you support, any custom butter styles, and a callback closure:
authorizedResponse
:- Whenever the user successfully authorizes the payment, the decrypted
ApplePayResponse
(containing token, card info, cryptogram, etc.) will be written into yourauthorizedResponse
variable. You can react to that state change however you like — navigate onward, show a confirmation screen, or send it off to your own backend to be sent via an Evervault Relay to your PSP. Refer to this section for the structure of the response.
- Whenever the user successfully authorizes the payment, the decrypted
onResult
:- Use this callback to reset UI state or advance your checkout flow once the sheet closes. It's triggered whether the transaction succeeds or fails—for example, if Apple Pay is unavailable, the transaction is invalid, presentation fails, or Evervault cannot decrypt the payment. The callback returns a
Result<Void, EvervaultError>
. TheEvervaultError
includes a localizedDescription you can display in an alert, log for diagnostics, or present however appropriate.
- Use this callback to reset UI state or advance your checkout flow once the sheet closes. It's triggered whether the transaction succeeds or fails—for example, if Apple Pay is unavailable, the transaction is invalid, presentation fails, or Evervault cannot decrypt the payment. The callback returns a
Processing the Payment
If the payment is handled successfully, the Evervault encrypted payment method is available in $applePayResponse
(in the example above). The authorizedResponse
is an ApplePayResponse
object containing the payment method details encrypted with the Evervault public key. You can send this encrypted payment method to your server and use Evervault Relay to decrypt the payment details when you send them to your PSP.
The ApplePayResponse
object represented as JSON contains the following fields:
Complete example
Below is a complete example of Evervault Apple Pay in action:
Customise the Apple Pay button
When initialising the EvervaultPaymentViewRepresentable
you can pass two optional parameters — buttonType
and buttonStyle
.
Please refer to the Apple PassKit documentation on what preset button styles and types are available.
Error Handling
All errors from creating the Transaction
object and the errors surfaced in the onResult
callback are of type EvervaultError
There are four error types:
InvalidTransactionError
- This error is thrown when there is an with the transaction. As a guideline to help prevent encountering this error:amount
: The format of this value depends on thecurrency
. It follows ISO 4217 and depends on the minor unit of the currency e.g the number of decimal points forUSD
is 2, so the amount must be formatted as"50.00"
. This error will be thrown if you try to format theamount
as"50.0"
. As another example,JPY
has no minor unit so theamount
must be formatted as"1000"
.
InvalidCurrencyError
- The currency is the three-letter ISO 4217 currency code that determines the currency the payment request uses. This error is thrown if the currency does not match this spec.InvalidCountryError
- The country is the two-letter ISO 3166 country code. This error is thrown if the country does not match this spec.EmptyTransactionError
- This error is thrown when a transaction has no summary items. The transaction must have at least 1 summary items, and the final item is the total.ApplePayUnavailableError
- This error is thrown when Apple Pay is not available on the deviceApplePayPaymentSheetError
- This error is thrown when an underlying error with the Apple Pay payment sheet occurs.UnsupportedVersionError
- This error is thrown when trying to access a method that is not available on the current version of iOS.ApplePayAuthorizationError
- This error is thrown when something goes wrong when authenticating with Apple Pay. The underlying error from Apple Pay is provided.InternalError
- This error is thrown when something goes wrong during the handling of the payment data. An underlying reason will be provided in this case.
Full example
A complete working example is included in the Evervault iOS package, located in the EvervaultIOSApp directory.
Running the Sample App
To run the sample app:
- Open the
EvervaultIOSApp.xcodeproj
file in Xcode. - Configure your Team ID and App ID in
EvervaultIOSAppApp.swift
or addEV_TEAM_UUID
andEV_APP_UUID
Environment Variables the Run Scheme. - Select a simulator or physical device as the build target.
- Build and run the app.
Reference
EvervaultCore
Evervault.shared.config(teamId: String, appId: String)
A shared instance of the Evervault class. This is the simplest way to get up and running if you only need to use a single Evervault team/app.
Parameters
Evervault(teamId: String, appId: String)
Initializes a single instance of the Evervault class. You'll need to use this initializer if you require more than one Evervault team/app.
Parameters
Evervault.encrypt(_ data: Any, role: String?) async throws -> Any
Encrypts the provided data using Evervault Encrypt and an optional data role.
The encrypt function supports: Boolean
, Numerics, String
, Array
, Dictionary
and Data
.
Note: Data Roles aren't yet supported when encrypting data of the Data
type
EvervaultInputs
PaymentCardInput(cardData: PaymentCardData)
Create a PaymentCardInput SwiftUI view
EvervaultEnclaves
Evervault.enclaveSession(enclaveAttestationData: AttestationData)
Create a URLSession which will attest connections to your Evervault Enclave.
Parameters
AttestationData
Config used to compare against the attestation doc served to the client from a Enclave.
AttestationData
PCRs
The attestation measurements measurement expected to be embedded in the attestation document returned from a Enclave.
PCRs
Using the Evervault API as a PCR Provider
The Evervault API exposes an endpoint to retrieve the PCRs for all active versions of your Enclave which you can use to keep your clients in sync with your Enclave across deployments.
EvervaultPay
The Evervault API exposes a SwiftUI component for accepting Apple Pay.
Transaction
An enum representing the different types of payment transactions supported by the system. Each transaction type encapsulates its own specific configuration and metadata needed to facilitate a payment via Apple Pay or a similar mechanism.
Transaction
Represents a single, immediate payment. Useful for purchases such as products or services.
Represents a payment made to a recipient, such as a payout or refund, potentially including fees.
Represents a simple one-time payment transaction.
OneOffPaymentTransaction
The three-letter ISO 4217 currency code that determines the currency the payment request uses.
Line items describing the transaction. The list must contain at least 1 item. The last item must represent the total.
Handling Payment Changes
You can react to shipping changes from the user by implementing the onShippingAddressChange
method on the EvervaultPaymentViewRepresentable
class in SwiftUI. This is called when the user updates their shipping address while checking out. This method should return the new list of SummaryItem
.
The callback is the opportunity to perform actions such as recalculating shipping, tax and a new total.
The last item in the list must be the total price, including shipping and taxes.
This is an optional method to implement.