Tap to Share on iPhone

Add the Tap to Share capability

Tap to Share builds on your existing Tap to Pay on iPhone entitlement. In Xcode, select your app target, then in Signing & Capabilities, add the Tap to Share capability.

Adding the capability to your entitlements file isn't enough on its own. Xcode also needs a provisioning profile that grants the capability to your app's bundle ID.

If you plan to accept Apple Pay on the customer's device, also add the Apple Pay capability, with a merchant identifier.

Before you submit your app, review Apple's Adding support for Tap to Share documentation and human interface guidelines.

Check device support

Before you show a Tap to Share option to the merchant, check whether their device can support it:

guard moov.isCustomerSessionSupported() else {
  // Hide Tap to Share and use a Tap to Pay card tap instead.
  return
}

isCustomerSessionSupported() only checks the OS and reader. There's no API to detect the iPhone model, and the simulator always returns true. That means createCustomerSession(configuration:) can still throw CustomerSessionError.notSupported, so always handle that error and keep a fallback payment path.

Open a session

First, initialize the reader with initReader(), as you do for Tap to Pay. Then, register a customer event handler before opening the session. That way, you'll catch the connected and ready events from the start.

await moov.setCustomerEventHandler { event in
  switch event {
  case .connected:    // The customer's iPhone connected.
  case .ready:        // Safe to share a cart or request information.
  case .disconnected: // The customer's iPhone went out of range.
  case .closed:       // The session ended.
  case .unsupported:  // An event added after this SDK release.
  }
}

let configuration = CustomerSessionConfiguration(
  currency: .USD,
  region: .unitedStates,
  privacyPolicyURL: URL(string: "https://example.com/privacy")!,
  storeName: "Oakbrook Mall",
  deviceName: "Emily"
)

try await moov.createCustomerSession(configuration: configuration)

The customer sees the store name, device name, and privacy policy link when they connect. Prompt the merchant to bring the tops of the two iPhones together. createCustomerSession(configuration:) returns once the devices connect. Wait for the .ready event before you send any requests. Any requests you send before that will throw CustomerSessionError.notReady.

MoovKit handles authentication for you. If you've already called createSession(invalidateTerminalConfiguration:) for Tap to Pay, MoovKit reuses that session. Otherwise, it fetches a card reader token from your TerminalConfigurationProvider.

Share the cart

Send the cart to the customer's iPhone with updateShoppingCart(_:). The customer's iPhone doesn't remember previous carts, so every call replaces the whole cart. Always send the complete cart, not just what changed.

• Enter amounts in whole currency units, like 15.00 for $15.00. They're formatted using the currency and region from your CustomerSessionConfiguration and the customer's locale.
• Give every item a unique id, and reuse it for the same product in later updates so the customer's screen can animate changes to quantity and price.
• To show a placeholder on the customer's screen, share an empty cart.

let cart = ShoppingCart(
  items: [
    ShoppingCart.Item(
      id: "HRSP-M-UN-11-001",
      name: "Hair Spray",
      quantity: 4,
      totalPrice: Decimal(string: "20.00")!,
      totalAdjustedPrice: Decimal(string: "15.00")!,
      descriptions: ["Unscented, 11 oz", "Buy 3 Get 1 Free Offer"],
      details: ["This item cannot be shipped."]
    ),
  ],
  summary: ShoppingCart.Summary(
    summaryLines: [
      ShoppingCart.Summary.LineItem(label: "Subtotal", value: Decimal(string: "15.00")!),
      ShoppingCart.Summary.LineItem(label: "Coupon Code: NY2OFF", value: Decimal(string: "-2.00")!),
      // Values that aren't amounts are displayed verbatim.
      ShoppingCart.Summary.LineItem(label: "Shipping", value: "Free"),
      ShoppingCart.Summary.LineItem(label: "Tax", value: "10%"),
    ],
    footer: "Thank you for shopping with us.",
    total: Decimal(string: "14.30")!
  )
)

let cartToken = try await moov.updateShoppingCart(cart)

Save the ShoppingCartToken from your most recent update. You'll need it to request Apple Pay.

Request customer information

Each request opens a form on the customer's iPhone. The customer chooses what to share, so any field you ask for can come back as nil. If the customer declines the whole request, it throws CustomerSessionError.userDeclined. You can only show one form at a time. If you send a second request while a form is open, it throws CustomerSessionError.sessionBusy.

let info = try await moov.requestCustomerInfo(
  purpose: .checkIn,
  fields: [.emailAddress],
  message: "Look up your account"
)
// info.emailAddress, info.phoneNumber

let address = try await moov.requestAddress(
  purpose: .shipping,
  fields: [.emailAddress, .phoneNumber]
)
// address.name, address.street, address.city, address.state, address.postalCode, ...

let signUp = try await moov.requestSignup(
  fields: [.emailAddress, .phoneNumber],
  emailConsent: .visible,
  smsConsent: .visible,
  termsAndConditions: "**Terms and Conditions**\n\nYour terms, in Markdown."
)
// signUp.emailOptInSelection, signUp.smsOptInSelection

The purpose explains to the customer why you're asking. Available purposes are accountCreation, accountUpdate, billing, checkIn, membership, receipt, and shipping. Consent options can be hidden, visible, or preSelected.

Accept Apple Pay on the customer's device

Apple only shows the Apple Pay option for a cart you've already shared, so pass the ShoppingCartToken from your latest updateShoppingCart(_:) call. First, check customerClientType:

• .localWireless – The customer is on an iPhone with iOS 27 or newer, and you can offer Apple Pay.
• .web – The customer connected through Apple's web app fallback. Apple Pay isn't available, so take payment with a Tap to Pay card tap.

guard await moov.customerClientType == .localWireless else {
  // Fall back to a Tap to Pay card tap on the merchant's iPhone.
  return
}

let paymentRequest = PKPaymentRequest()
paymentRequest.merchantIdentifier = "merchant.com.example.posapp"
paymentRequest.currencyCode = "USD"
paymentRequest.countryCode = "US"
paymentRequest.supportedNetworks = [.amex, .discover, .masterCard, .visa]
paymentRequest.merchantCapabilities = .threeDSecure
paymentRequest.paymentSummaryItems = paymentSummaryItems

let presented = try await moov.requestApplePayPayment(
  for: cartToken,
  using: paymentRequest,
  delegate: paymentAuthorizationControllerDelegate
)

if !presented {
  // The customer chose another option or hasn't set up Apple Pay.
  // Fall back to another payment method.
}

MoovKit shows the payment sheet and passes the authorization to your PKPaymentAuthorizationControllerDelegate. It doesn't process the resulting PKPayment. Your delegate sends the payment to your backend, and your backend completes it the same way as Apple Pay on the web:

1. Link the token to the payer's account. Call the link Apple Pay token endpoint with the accountID of the customer paying, and pass in the token from the PKPayment. Your access token needs the /accounts/{accountID}/cards.write scope for that account.

   curl -X POST "https://api.moov.io/accounts/{payerAccountID}/apple-pay/tokens" \
     -H "Authorization: Bearer {token}" \
     -H "x-moov-version: v2026.07.00" \
     --data '{
       "token": {
         "paymentData": { ... },
         "paymentMethod": { ... },
         "transactionIdentifier": "string"
       }
     }'
   

   On API v2026.04.00 and newer, the response is an array of payment methods. Use the paymentMethodID with a paymentMethodType of apple-pay.

2. Create a transfer. Call the create transfer endpoint with the apple-pay payment method as the source and the merchant's Moov wallet as the destination. Add the X-Wait-For header to get a synchronous response.

3. Finish the payment sheet. Call the delegate's completion handler with .success or .failure, based on the transfer result.

func paymentAuthorizationController(
  _ controller: PKPaymentAuthorizationController,
  didAuthorizePayment payment: PKPayment,
  handler completion: @escaping (PKPaymentAuthorizationResult) -> Void
) {
  Task {
    do {
      // Your backend links payment.token and creates the transfer.
      try await partnerClient.payWithApplePay(token: payment.token, amount: total)
      completion(PKPaymentAuthorizationResult(status: .success, errors: nil))
      try await moov.updateCustomerStatus(.paymentCompleted)
    } catch {
      completion(PKPaymentAuthorizationResult(status: .failure, errors: [error]))
    }
  }
}

If Apple Pay isn't available, the merchant can still take payment with a regular Tap to Pay card tap on their own iPhone. Customer details collected through Tap to Share still work with that flow.

Update status & close the session

After the payment goes through, show a status screen on the customer's iPhone. You can do this anytime a request form isn't open.

try await moov.updateCustomerStatus(.paymentCompleted)

Available statuses are ready, paymentCompleted, paymentFailed, and checkoutCompleted.

Close the session as soon as the checkout is done, so the customer's iPhone doesn't stay connected:

await moov.closeCustomerSession()

MoovKit returns customer details directly to your app. Your app is responsible for storing, using, and deleting that data in line with the privacy policy you linked in CustomerSessionConfiguration.