Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.clear-box.io/llms.txt

Use this file to discover all available pages before exploring further.

To let a user tap their iPhone to pay, the ClearBox card must be added to Apple Wallet. This is done with Apple’s In-App Provisioning protocol, which pushes an encrypted card payload directly into the device’s Secure Element — the user never types a 16-digit card number. It corresponds to the tap-to-pay provisioning sequence your team works from.
Apple entitlement required. To use the native Apple Wallet “Add to Wallet” flow, your iOS app’s business entity (ClearBox) must hold Apple’s In-App Provisioning Entitlement. Crossmint provides the encrypted payloads, but your app must have Apple’s clearance to pass those payloads into iOS’s local Secure Element. Apply for this entitlement before building the flow.

​
Flow at a glance

1

User taps Issue Tap-to-Pay Card

Inside the iOS app, the user requests a tap-to-pay card. ClearBox issues the virtual card (see Issue a virtual card).
2

Request the encrypted PassKit payload

The ClearBox backend requests the encrypted Apple PassKit data for the card from Crossmint.
3

Send the payload to the device

The backend sends the encrypted payload to the iOS app.
4

Trigger the native Add to Wallet prompt

The app triggers the native iOS prompt and the user authenticates with Face ID / Touch ID.
5

Pass the payload to the Secure Element

The encrypted payload is passed into Apple’s Secure Element, and the card is added to Apple Wallet.

​
1. Request the encrypted PassKit payload

When provisioning begins, Apple’s PassKit framework provides device-specific data (a certificate, a nonce, and a nonce signature). Your app passes these to the ClearBox backend, which requests the encrypted payload from Crossmint for the issued card. 
GET https://www.crossmint.com/api/v1/cards/{cardId}/apple-pay-payload
X-API-KEY: <CROSSMINT_SERVER_API_KEY>
Crossmint returns the encrypted payload needed by PKAddPaymentPassRequest. 
{
  "encryptedPassData": "<base64>",
  "activationData": "<base64>",
  "ephemeralPublicKey": "<base64>"
}
The full card credentials are never exposed to your app or backend in plaintext. The payload is encrypted end-to-end for Apple’s Secure Element.

​
2. Send the payload to the device

Return the encrypted payload to the iOS app over your authenticated channel. The app holds it only long enough to complete provisioning.

​
3. Trigger the native Add to Wallet prompt

In the iOS app, use Apple’s In-App Provisioning APIs to present the native “Add to Wallet” prompt. The user authenticates with Face ID or Touch ID, and your PKAddPaymentPassViewController delegate supplies the encrypted payload to PassKit. 
func addPaymentPassViewController(
  _ controller: PKAddPaymentPassViewController,
  generateRequestWithCertificateChain certificates: [Data],
  nonce: Data,
  nonceSignature: Data,
  completionHandler handler: @escaping (PKAddPaymentPassRequest) -> Void
) {
  // Send certificates, nonce, nonceSignature to ClearBox backend,
  // receive the encrypted payload from Crossmint, then:
  let request = PKAddPaymentPassRequest()
  request.encryptedPassData = encryptedPassData
  request.activationData = activationData
  request.ephemeralPublicKey = ephemeralPublicKey
  handler(request)
}

​
4. Card added to Apple Wallet

On success, the card is provisioned into Apple Wallet and is ready for tap-to-pay. The user can now tap their phone at any contactless terminal.

Next: Authorization & settlement

See what happens when the user taps to pay.

​
Reference

The apple-pay-payload path follows Crossmint’s public card API. Confirm the current shape against Crossmint’s docs. The Apple entitlement application is handled by your team directly with Apple.