iOS

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.

1import EvervaultCore
2
3Evervault.shared.configure(teamId: "<TEAM_ID>", appId: "<APP_ID>")

If you need multiple instances of the Evervault SDK you can use the initializer as follows:

1import EvervaultCore
2
3let evervault = Evervault.init(teamId: "<TEAM_ID>", appId: "<APP_ID>")

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:

1let encryptedPassword = Evervault.shared.encrypt("Super Secret Password")

Or using a dedicated instance:

1let encryptedPassword = evervault.encrypt("Super Secret Password")

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.

1let encryptedPassword = Evervault.shared.encrypt("Super Secret Password")
2let decrypted: String = Evervault.shared.decrypt('<token generated by your backend application>', encryptedPassword)

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:

1import EvervaultInputs
2
3struct ContentView: View {
4
5    @State private var cardData = PaymentCardData()
6
7    var body: some View {
8        VStack {
9            PaymentCardInput(cardData: $cardData)
10
11            // Data captured:
12            Text("Encrypted credit card number: \(cardData.card.number)")
13        }
14    }
15}

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.

1import EvervaultInputs
2
3struct ContentView: View {
4
5    private var enabledFields = EnabledFields(isCardNumberEnabled: true, isExpiryEnabled: false, isCVCEnabled: false)
6
7    @State private var cardData = PaymentCardData()
8
9    var body: some View {
10        VStack {
11            PaymentCardInput(cardData: $cardData, fields: enabledFields)
12
13            // Data captured:
14            Text("Encrypted credit card number: \(cardData.card.number)")
15        }
16    }
17}

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 TextFields. These can be customized using SwiftUI modifiers like any other TextFields in your application:

1PaymentCardInput(cardData: $cardData)
2        .font(.footnote)
3        .foregroundColor(.blue)

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.

Screenshot of the iOS PaymentCardInput with Inline styling

To explicitly use this style:

1PaymentCardInput(cardData: $cardData)
2        .paymentCardInputStyle(.inline)

RowsPaymentCardInputStyle - puts the credit card number on a single row. Below it, places the expiry and cvc fields next to each other.

Screenshot of the iOS PaymentCardInput with Rows styling

To use this style:

1PaymentCardInput(cardData: $cardData)
2        .paymentCardInputStyle(.rows)

If these two styles do not match your use case, you can create your own style:

1struct CustomPaymentCardInputStyle: PaymentCardInputStyle {
2
3    func makeBody(configuration: Configuration) -> some View {
4        VStack(alignment: .center) {
5            configuration.cardImage
6
7            Text("CC Number").font(.title3)
8            configuration.cardNumberField
9
10            Divider()
11
12            Text("Expiry").font(.title3)
13            configuration.expiryField
14
15            Divider()
16
17            Text("CVC").font(.title3)
18            configuration.cvcField
19        }
20    }
21}

1PaymentCardInput(cardData: $cardData)
2        .paymentCardInputStyle(CustomPaymentCardInputStyle())

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 an Enclave session.

1import EvervaultCore
2import EvervaultEnclaves
3
4//Note: Make sure app uuid is hyphenated (eg: app-123456).
5let url = URL(string: "https://<ENCLAVE_NAME>.<APP_UUID>.enclave.evervault.com")
6let enclaveSession = Evervault.enclaveSession(
7  enclaveAttestationData: EnclaveAttestationData(
8    enclaveName: "<ENCLAVE_NAME>",
9    appUuid: "<APP_UUID>",
10    pcrs: PCRs(
11      pcr0: "<PCR0>",
12      pcr1: "<PCR1>",
13      pcr2: "<PCR2>",
14      pcr8: "<PCR8>",
15    )
16  )
17)
18
19do {
20  let response = try await enclaveSession.data(from: url)
21  // ...
22} catch {
23  // ...
24}

Apple Pay®

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.

In Sandbox apps, the encrypted network token maps to a brand-specific test card based on the card the customer selects in their Apple Wallet.

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 isn't constructed correctly — for example, the country or currency fields aren't valid, or the transaction has no summary items — Evervault throws EvervaultError.InvalidCountryError, EvervaultError.InvalidCurrencyError, or EvervaultError.EmptyTransactionError respectively.

Please refer to Apple's documentation on requirements for country and currency and amount fields.

1import EvervaultPayment
2
3let oneOff = try! OneOffPaymentTransaction(
4  country: "IE",
5  currency: "EUR",
6  paymentSummaryItems: [
7    SummaryItem(label: "Mens Shirt", amount: Amount("30.00")),
8    SummaryItem(label: "Socks", amount: Amount("5.00")),
9    SummaryItem(label: "Total", amount: Amount("35.00"))
10  ]
11)
12
13let transaction = EvervaultPayment.Transaction.oneOffPayment(oneOff)

OneOffPaymentTransaction and RecurringPaymentTransaction also accept a requestPayerDetails parameter to request billing contact fields — such as the payer's name, email, phone, or postal address — using PassKit's own PKContactField values:

1import EvervaultPayment
2
3let oneOff = try! OneOffPaymentTransaction(
4  country: "IE",
5  currency: "EUR",
6  paymentSummaryItems: [
7    SummaryItem(label: "Mens Shirt", amount: Amount("30.00")),
8    SummaryItem(label: "Socks", amount: Amount("5.00")),
9    SummaryItem(label: "Total", amount: Amount("35.00"))
10  ],
11  requestPayerDetails: [.name, .phoneticName, .phoneNumber, .emailAddress, .postalAddress]
12)
13
14let transaction = EvervaultPayment.Transaction.oneOffPayment(oneOff)

If you need to collect a shipping address, pass shippingType, shippingMethods, and requiredShippingContactFields to OneOffPaymentTransaction. shippingMethods are PKShippingMethod instances the customer can choose between on the payment sheet:

1import EvervaultPayment
2import PassKit
3
4let expressShipping = ShippingMethod(label: "Express Shipping", amount: NSDecimalNumber(string: "9.99"))
5expressShipping.identifier = "express_1day"
6expressShipping.detail = "Arrives in 1–2 business days."
7
8let standardShipping = ShippingMethod(label: "Standard Shipping", amount: NSDecimalNumber(string: "2.99"))
9standardShipping.identifier = "standard_3day"
10standardShipping.detail = "Arrives in 3-5 business days."
11
12let oneOff = try! OneOffPaymentTransaction(
13  country: "IE",
14  currency: "EUR",
15  paymentSummaryItems: [
16    SummaryItem(label: "Mens Shirt", amount: Amount("30.00")),
17    SummaryItem(label: "Socks", amount: Amount("5.00")),
18    SummaryItem(label: "Standard Shipping", amount: Amount("2.99")),
19    SummaryItem(label: "Total", amount: Amount("37.99"))
20  ],
21  shippingType: .shipping,
22  shippingMethods: [expressShipping, standardShipping],
23  requiredShippingContactFields: [.postalAddress, .name, .phoneNumber]
24)
25
26let transaction = EvervaultPayment.Transaction.oneOffPayment(oneOff)

Use the onShippingAddressChange modifier on EvervaultPaymentViewRepresentable (see Render the Apple Pay button) to update the summary items when the customer picks a different shipping address.

For subscriptions, use RecurringPaymentTransaction. You must provide a managementURL where customers can manage their subscription, and a regularBilling PKRecurringPaymentSummaryItem describing the billing interval. trialBilling and billingAgreement are optional and are set directly on the transaction after it's constructed:

1import EvervaultPayment
2import PassKit
3
4let regularBilling = PKRecurringPaymentSummaryItem(label: "Pro Subscription", amount: 5.00)
5regularBilling.intervalUnit = .month
6regularBilling.intervalCount = 1
7
8var recurring = try! RecurringPaymentTransaction(
9  country: "IE",
10  currency: "EUR",
11  paymentSummaryItems: [],
12  paymentDescription: "Monthly Pro subscription",
13  regularBilling: regularBilling,
14  managementURL: URL(string: "https://www.merchant.com/manage-subscriptions")!
15)
16
17recurring.trialBilling = PKRecurringPaymentSummaryItem(label: "Trial", amount: 0)
18recurring.billingAgreement = "https://www.merchant.com/billing-agreement"
19
20let transaction = EvervaultPayment.Transaction.recurringPayment(recurring)

For payouts to a customer's card, use DisbursementTransaction. Provide a disbursementItem describing the payout, an optional instantOutFee, the requiredRecipientDetails you need to collect from the recipient, and the merchantCapability your merchant account supports:

1import EvervaultPayment
2
3let disbursement = try! DisbursementTransaction(
4  country: "IE",
5  currency: "EUR",
6  paymentSummaryItems: [
7    SummaryItem(label: "Withdrawal Summary", amount: Amount("41.00")),
8    SummaryItem(label: "EUR Balance", amount: Amount("41.00"))
9  ],
10  disbursementItem: SummaryItem(label: "Disbursement", amount: Amount("41.00")),
11  instantOutFee: SummaryItem(label: "Instant funds out fee", amount: Amount("1.00")),
12  requiredRecipientDetails: [.emailAddress, .phoneNumber],
13  merchantCapability: .instantFundsOut
14)
15
16let transaction = EvervaultPayment.Transaction.disbursement(disbursement)

Check if Apple Pay is supported

Before displaying Apple Pay as a payment option, use the availability(supportedNetworks:) method to check whether the device supports Apple Pay, and whether the customer has a card in their wallet. It returns one of three states, matching the web SDK:

available: Apple Pay is supported and the customer has a usable card.
unavailable: Apple Pay is supported, but the customer hasn't added a card for the networks you accept.
unsupported: Apple Pay isn't supported on this device.

1let availability = EvervaultPaymentViewRepresentable.availability(supportedNetworks: [.visa, .masterCard, .amex])

Use unsupported to hide the Apple Pay button entirely. Use unavailable to show a Set Up Apple Pay button instead of a regular buy button (see Customise the Apple Pay button for more details).

If you support disbursement transactions, also check supportsDisbursements(). Disbursements require iOS 17+, so this returns false on earlier versions even if availability(supportedNetworks:) reports available:

1let canDisburse = EvervaultPaymentViewRepresentable.supportsDisbursements()

Deprecated

isAvailable() only reports whether the device is capable of Apple Pay. It doesn't tell you whether the customer has a card set up. Because of that, it can't distinguish between "no card added" and "card not supported." Use availability(supportedNetworks:) instead.

1let isAvailable = EvervaultPaymentViewRepresentable.isAvailable()

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, 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 your @State 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.
onResult: Use this callback to reset UI state or advance your checkout flow after the sheet closes with a definite outcome (either success or failure). Failures can happen when Apple Pay is unavailable, the transaction is invalid, presentation fails, or if Evervault can't decrypt the payment details. The callback returns a Result<Void, EvervaultError>. The EvervaultError includes a localizedDescription you can display in an alert, log for diagnostics, or present however appropriate. onResult doesn't fire if the customer cancels.
onCancel: Use this modifier to detect when the customer dismisses the sheet without authorizing a payment (e.g., taps Cancel). This is distinct from the success or failure provided by onResult.
shouldAuthorize: Use this modifier to inspect the authorized payment and approve or reject it before the sheet reports success. Return .success(()) to proceed, or .failure(reason) to reject the payment, where reason is any Error. Rejections are reported through onDecline, never onResult. This closure runs on the main actor, so it's safe to update UI state directly inside it.
onDecline: Use this modifier to handle a payment you rejected from shouldAuthorize. It fires only after the sheet closes, so it's safe to present your own UI in response. onDecline includes the reason passed in shouldAuthorize, and is distinct from onResult, which only reports SDK-level success or failure and doesn't fire for a decline.

1// Example decline reason — conforms to `Error`, so `onDecline` can switch over it exhaustively.
2enum DeclineReason: Error, LocalizedError {
3  case prepaidCardNotAccepted
4
5  var errorDescription: String? {
6    switch self {
7    case .prepaidCardNotAccepted:
8      return "Prepaid cards are not accepted"
9    }
10  }
11}
12
13struct ContentView: View {
14  @State private var applePayResponse: ApplePayResponse? = nil
15  let transaction = buildTransaction()
16
17  var body: some View {
18    VStack(spacing: 20) {
19      EvervaultPaymentViewRepresentable(
20        appId: "YOUR_EVERVAULT_APP_ID",
21        appleMerchantId: "YOUR_APPLE_MERCHANT_IDENTIFIER",
22        transaction: transaction,
23        supportedNetworks: [.visa, .masterCard, .amex],
24        authorizedResponse: $applePayResponse) { result in
25            switch result {
26            case .success(_):
27                print("Payment sheet dismissed with success")
28                if (applePayResponse != nil) {
29                    // Send to PSP via Relay on your backend
30                }
31                break
32            case let .failure(error):
33                print("Payment error: \(error.localizedDescription)")
34                break
35            }
36        }
37        .onCancel {
38            print("Payment sheet cancelled")
39        }
40        .onDecline { reason in
41            print("Payment declined: \(reason.localizedDescription)")
42        }
43        .shouldAuthorize { response in
44            // Example merchant rule: reject prepaid cards.
45            if response?.card.funding == "prepaid" {
46                return .failure(DeclineReason.prepaidCardNotAccepted)
47            }
48            return .success(())
49        }
50    }
51  }
52}

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:

1{
2  "networkToken": {
3    "number": "ev:Tk9D:hY5KJanIPOHBoI8S:AsnnjRl0FDe2zEddBAQG/eI2vN+b...:$",
4    "expiry": {
5      "month": "12",
6      "year": "31"
7    },
8    "rawExpiry": "12/31",
9    "tokenServiceProvider": "Apple"
10  },
11  "card": {
12    "brand": "visa",
13    "funding": "debit",
14    "segment": "consumer",
15    "country": "ie",
16    "currency": "eur",
17    "issuer": "Revolut Bank Uab"
18  },
19  "cryptogram": "ev:Tk9D:vUVeybXqrA9Ds4rZ...=:$",
20  // The ECI value is optional with Apple Pay.
21  // Learn more here: https://developer.apple.com/documentation/passkit/payment-token-format-reference#Detailed-payment-data-keys-3D-Secure
22  "eci": "5",
23  "paymentDataType": "3DSecure",
24  "deviceManufacturerIdentifier": "string",
25  "transactionType": "oneOff",
26  "transactionId": "5ee9e294a2e79032ca7529b2050c2a878187c54a54f07559cff8281fb9b4716c",
27
28  // Only present if you requested the corresponding contact fields on the transaction
29  "billingContact": {
30    "givenName": "John",
31    "familyName": "Doe",
32    "phoneticGivenName": null,
33    "phoneticFamilyName": null,
34    "emailAddress": "john.doe@example.com",
35    "phoneNumber": "1234567890",
36    "postalAddress": {
37      "street": "123 Main St",
38      "city": "City",
39      "state": "State",
40      "postalCode": "12345",
41      "country": "Country",
42      "isoCountryCode": "XX"
43    }
44  },
45  "shippingContact": {
46    "givenName": "John",
47    "familyName": "Doe",
48    "phoneticGivenName": null,
49    "phoneticFamilyName": null,
50    "emailAddress": "john.doe@example.com",
51    "phoneNumber": "1234567890"
52  }
53}

rawExpiry: the token's expiry in MM/YY format, as returned by Apple. Use expiry.month/expiry.year instead if you need the parsed values.
transactionType: indicates the transaction category (oneOff, recurring, or disbursement) based on how you created the transaction.
transactionId: Apple's identifier for the token, from the PKPaymentToken header. Some payment gateways require it to be passed through, though it isn't used to authorize the transaction itself.
billingContact / shippingContact: only populated when the transaction requested those contact fields.
phoneticFamilyName / phoneticGivenName: populated when the customer's Apple Wallet contact card includes a phonetic reading of their name (common in locales like Japan). null otherwise.

Complete example

Below is a complete example of Evervault Apple Pay in action:

1import SwiftUI
2import EvervaultPayment
3
4func buildTransaction() -> EvervaultPayment.Transaction {
5  let oneOff = try! OneOffPaymentTransaction(
6    country: "IE",
7    currency: "EUR",
8    paymentSummaryItems: [
9      SummaryItem(label: "Mens Shirt", amount: Amount("30.00")),
10      SummaryItem(label: "Socks", amount: Amount("5.00")),
11      SummaryItem(label: "Total", amount: Amount("35.00"))
12    ]
13  )
14  return Transaction.oneOffPayment(oneOff)
15}
16
17// Example decline reason — conforms to `Error`, so `onDecline` can switch over it exhaustively.
18enum DeclineReason: Error, LocalizedError {
19  case prepaidCardNotAccepted
20
21  var errorDescription: String? {
22    switch self {
23    case .prepaidCardNotAccepted:
24      return "Prepaid cards are not accepted"
25    }
26  }
27}
28
29struct ContentView: View {
30  @State private var applePayResponse: ApplePayResponse? = nil
31  let transaction = buildTransaction()
32  let supportedNetworks: [Network] = [.visa, .masterCard, .amex]
33
34  var body: some View {
35    let availability = EvervaultPaymentViewRepresentable.availability(supportedNetworks: supportedNetworks)
36
37    VStack(spacing: 20) {
38      if availability != .unsupported {
39        // Apple Pay is supported — show the setup button if there's no card yet
40        EvervaultPaymentViewRepresentable(
41          appId: "YOUR_EVERVAULT_APP_ID",
42          appleMerchantId: "YOUR_APPLE_MERCHANT_IDENTIFIER",
43          transaction: transaction,
44          supportedNetworks: supportedNetworks,
45          buttonStyle: .whiteOutline,
46          buttonType: availability == .unavailable ? .setUp : .checkout,
47          authorizedResponse: $applePayResponse) { result in
48              switch result {
49              case .success(_):
50                  print("Payment sheet dismissed with success")
51                  if (applePayResponse != nil) {
52                    // Send to PSP via Relay on your backend
53                  }
54                  break
55              case let .failure(error):
56                  print("Payment error: \(error.localizedDescription)")
57                  break
58              }
59          }
60          .onCancel {
61              print("Payment sheet cancelled")
62          }
63          .onDecline { reason in
64              print("Payment declined: \(reason.localizedDescription)")
65          }
66          .shouldAuthorize { response in
67              // Example merchant rule: reject prepaid cards.
68              if response?.card.funding == "prepaid" {
69                  return .failure(DeclineReason.prepaidCardNotAccepted)
70              }
71              return .success(())
72          }
73      } else {
74        Text("Not available")
75      }
76    }
77  }
78}
79
80#Preview {
81    ContentView()
82}

Using EvervaultPaymentView directly (UIKit)

If your app doesn't use SwiftUI, render Apple Pay with the raw EvervaultPaymentView — a UIView subclass — and its EvervaultPaymentViewDelegate protocol, instead of EvervaultPaymentViewRepresentable:

1import UIKit
2import EvervaultPayment
3
4class CheckoutViewController: UIViewController, EvervaultPaymentViewDelegate {
5  private var applePayResponse: ApplePayResponse?
6
7  override func viewDidLoad() {
8    super.viewDidLoad()
9
10    let paymentView = EvervaultPaymentView(
11      appId: "YOUR_EVERVAULT_APP_ID",
12      appleMerchantId: "YOUR_APPLE_MERCHANT_IDENTIFIER",
13      transaction: buildTransaction(),
14      supportedNetworks: [.visa, .masterCard, .amex],
15      buttonStyle: .whiteOutline,
16      buttonType: .checkout
17    )
18    paymentView.delegate = self
19    view.addSubview(paymentView)
20    // Position `paymentView` with Auto Layout or a frame, as you would any other UIView.
21  }
22
23  // Required. Fired when a payment is authorized, before the sheet dismisses.
24  func evervaultPaymentView(_ view: EvervaultPaymentView, didAuthorizePayment result: ApplePayResponse?) {
25    applePayResponse = result
26  }
27
28  // Optional — mirrors the SwiftUI wrapper's `onResult`.
29  func evervaultPaymentView(_ view: EvervaultPaymentView, didFinishWithResult result: Result<Void, EvervaultError>) {
30    switch result {
31    case .success:
32      if applePayResponse != nil {
33        // Send to PSP via Relay on your backend
34      }
35    case let .failure(error):
36      print("Payment error: \(error.localizedDescription)")
37    }
38  }
39
40  // Optional — mirrors the SwiftUI wrapper's `onCancel`.
41  func evervaultPaymentViewDidCancel(_ view: EvervaultPaymentView) {
42    print("Payment sheet cancelled")
43  }
44}

Delegate methods

EvervaultPaymentViewDelegate has eight methods. Only evervaultPaymentView(_:didAuthorizePayment:) is required. The rest have default no-op implementations, so implement only the ones you need. Each maps to a modifier on the SwiftUI wrapper:

didAuthorizePayment: the only required method. Writes the decrypted ApplePayResponse into your own state, in place of the SwiftUI wrapper's authorizedResponse binding.
didFinishWithResult: mirrors onResult.
evervaultPaymentViewDidCancel: mirrors onCancel.
didDeclinePayment: mirrors onDecline.
shouldAuthorize: mirrors shouldAuthorize.
didSelectShippingContact: mirrors onShippingAddressChange.
didUpdatePaymentMethod: mirrors onPaymentMethodChange.
prepareTransaction: mirrors prepareTransaction.

Static methods

availability(supportedNetworks:): works the same as on EvervaultPaymentViewRepresentable.
supportsDisbursements(): no equivalent on EvervaultPaymentView. Call PassKit's own PKPaymentAuthorizationViewController.supportsDisbursements() (iOS 17+) directly instead.

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.

1EvervaultPaymentViewRepresentable(
2  // other fields...
3  buttonStyle: .whiteOutline,
4  buttonType: .checkout,
5)

If availability(supportedNetworks:) returns unavailable, Apple recommends showing the Set Up Apple Pay button instead of the default buy button. This takes the customer through the flow for adding a card rather than opening a payment sheet, which would fail.

1EvervaultPaymentViewRepresentable(
2  // other fields...
3  buttonStyle: .whiteOutline,
4  buttonType: availability == .unavailable ? .setUp : .checkout,
5)

Error Handling

All errors from creating the Transaction object and the errors surfaced in the onResult callback on the EvervaultPaymentViewRepresentable can be cast to EvervaultError:

InvalidTransactionError: This error is thrown when there is an issue with the transaction. As a guideline to help prevent encountering this error:
- amount: The format of this value depends on the currency. 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 the amount as "50.0". As another example, JPY has no minor unit so the amount 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 doesn't match this spec.
InvalidCountryError: The country is the two-letter ISO 3166 country code. This error is thrown if the country doesn't match this spec.
EmptyTransactionError: This error is thrown when a transaction has no summary items. The transaction must have at least one summary item, and the final item is the total.
ApplePayUnavailableError: This error is thrown when Apple Pay isn't available on the device
ApplePayPaymentSheetError: 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's not available on the current version of iOS.
ApplePayAuthorizationError: This error is thrown when there's an issue 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 is provided in this case.

Full example

A complete working example is included in the evervault-pay repository, in the ios/Demo directory.

Running the Sample App

To run the sample app:

Open the Demo.xcodeproj file in Xcode.
Replace the "YOUR_EVERVAULT_APP_ID" and "YOUR_APPLE_MERCHANT_ID" placeholder strings in ContentView.swift with your own Evervault App ID and Apple Merchant Identifier.
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.

1import EvervaultCore
2
3Evervault.shared.configure(teamId: "<TEAM_ID>", appId: "<APP_ID>")

Parameters

teamIdRequiredString
The Uuid of your Evervault Team
appIdRequiredString
The Uuid of your Evervault App

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.

1import EvervaultCore
2
3let evervault = Evervault(teamId: "<TEAM_ID>", appId: "<APP_ID>")

Parameters

teamIdRequiredString
The Uuid of your Evervault Team
appIdRequiredString
The Uuid of your Evervault App

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

1let encryptedData = try await Evervault.shared.encrypt("Super Secret Password")
2// or
3let encryptedData = try await evervault.encrypt("Super Secret Password")
4// or
5let encryptedData = try await Evervault.shared.encrypt("Super Secret Password", "data-role")

Parameters

dataRequiredAny
The data you want to encrypt.

EvervaultInputs

PaymentCardInput(cardData: PaymentCardData)

Create a PaymentCardInput SwiftUI view

1import EvervaultInputs
2
3struct ContentView: View {
4
5    @State private var cardData = PaymentCardData()
6
7    var body: some View {
8        VStack {
9            PaymentCardInput(cardData: $cardData)
10
11            // Data captured:
12            Text("Encrypted credit card number: \(cardData.card.number)")
13        }
14    }
15}

Parameters

cardDataRequiredPaymentCardData
The card data state for the PaymentCardInput view

EvervaultEnclaves

Evervault.enclaveSession(enclaveAttestationData: AttestationData)

Create a URLSession which will attest connections to your Evervault Enclave.

1import EvervaultCore
2import EvervaultEnclaves
3
4let enclaveSession = Evervault.enclaveSession(
5  enclaveAttestationData: AttestationData(
6    enclaveName: "<ENCLAVE_NAME>",
7    pcrs: PCRs(
8      pcr0: "<PCR0>",
9      pcr1: "<PCR1>",
10      pcr2: "<PCR2>",
11      pcr8: "<PCR8>",
12    )
13  )
14)

Parameters

enclaveAttestationDataRequiredAttestationData
The values used during the attestation handshake with your Enclave

AttestationData

Config used to compare against the attestation doc served to the client from an Enclave.

AttestationData

enclaveNameRequiredString
The name of the Enclave to attest
pcrsRequiredPCRs
The platform configuration registers to compare against the attestation doc returned from the Enclave

PCRs

The attestation measurements measurement expected to be embedded in the attestation document returned from an Enclave.

PCRs

pcr0String
The value for PCR0 to attest
pcr1String
The value for PCR1 to attest
pcr2String
The value for PCR2 to attest
pcr8String
The value for PCR8 to attest

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.

1import EvervaultCore
2import EvervaultEnclaves
3
4struct AttestedEnclaveView: View {
5
6    private let enclaveName = "my-enclave"
7    private let appId = "app_123abc"
8    private let enclaveHostname = "my-enclave.app-123abc.enclave.evervault.com"
9
10    public struct EvervaultProviderResponse: Decodable {
11        public let data: [PCRs]
12
13        public init(data: [PCRs]) {
14            self.data = data
15        }
16    }
17
18    public var provider: (@escaping ([PCRs]?, Error?) -> Void) -> Void = { completion in
19        var request = URLRequest(url: URL(string: "https://api.evervault.com/enclaves/\(enclaveName)/attestation")!)
20        request.addValue(appId, forHTTPHeaderField: "x-evervault-app-id")
21
22        URLSession.shared.dataTask(with: request) { data, _, error in
23            guard let data = data, error == nil else {
24                completion(nil, error ?? NSError(domain: "Evervault Provider", code: -1, userInfo: [NSLocalizedDescriptionKey: "No data or error."]))
25                return
26            }
27            do {
28                // Decode the data into a PCRContainer
29                let container = try JSONDecoder().decode(EvervaultProviderResponse.self, from: data)
30                // Extract the PCRs array from the container and pass it to the completion handler
31                completion(container.data, nil)
32            } catch {
33                print("Error: ", error.localizedDescription)
34                completion(nil, error)
35            }
36        }.resume()
37    }
38
39    @State private var responseText: String? = nil
40
41    var body: some View {
42        Group {
43            if let responseText {
44                Text(responseText)
45            } else {
46                Text("Loading...")
47            }
48        }
49        .padding()
50        .task {
51            let url = URL(string: "https://\(enclaveHostname)/")!
52            let urlSession = Evervault.enclaveAttestationSession(
53                enclaveAttestationData: EnclaveAttestationData(
54                    enclaveName: enclaveName,
55                    appUuid: appId,
56                    provider: provider
57                )
58            )
59
60            do {
61                let response = try await urlSession.data(from: url)
62                print(response)
63            } catch {
64                responseText = error.localizedDescription
65                print("Error: \(error.localizedDescription)")
66            }
67        }
68    }
69}