In-App Provisioning

The In-App Provisioning workflow allows users to provision cards from the issuer app to Apple Wallet. Additionally, if the issuer app supports reading content from a plastic transit card, users can perform this action before provisioning it to Apple Wallet.

Workflow

Below are the high level steps of the in-app provisioning workflow:

1. Provisioning

   1. Initiation: Use PassKit APIs to initiate the In-App provisioning process.
   2. Bundle delivery: Apple fetches the provisioning bundle containing the card details.
2. Provisioning Outcome: Apple sends a notification indicating the provisioning result.

This workflow assumes that the user already has a valid transit card linked to his card account. If the user does not have a transit card, he can either purchase one through the transit operator app or, if supported, use the app to read the content of his plastic card before provisioning it to the Apple Wallet.

Sequence diagram

Associating existing transit cards in Apple Wallet

Users may have digital cards that were provisioned directly through Apple Wallet (DCI) without requiring access to the transit operator's app. When the user opens the transit operator's app, Apple PassKit API, passes, enables the app to read existing transit cards from Apple Wallet that are linked to the app's entitlement. The app can display the user's existing transit cards and offer an option to add these cards to the app for future use. However, the user doesn't have to associate these cards with the app and can continue using the app without making this association.

Note that this process is not part of the In-App Provisioning flow; it is a way to associate existing transit cards in the Apple Wallet with the user's card account.

It is important to note that the Transit Issuer shall start preparing the data required to issue the digital card as soon as the payment request is validated with the PSP

Provisioning

When the user presses the "Add to Apple Wallet" button, the transit operator's mobile app must provide the card details to its backend to begin the preparation of the provisioning bundle. D1 Transit generates an encryptedData payload containing the necessary details to initiate the provisioning workflow. This encryptedData payload is then sent back to the transit operator's mobile app, which subsequently calls Apple PassKit API PKAddPaymentPassRequest to initiate the provisioning workflow with Apple.

Upon receiving the encryptedData, Apple sends a request to D1 Transit to obtain the encrypted provisioning bundle.

Error Scenarios

No request from Apple to get the provisioning bundle

A timeout period between prepare push provisioning bundle response and provisioning bundle request from Apple is set on D1 Transit side.

If the provisioning bundle request is not received by D1 Transit within this timeout period, card account and digital card references are completely discarded. Transit issuer shall refund the customer.

If Apple requests the provisioning bundle after the timeout, D1 Transit will notify Apple that the provisioning bundle is no longer available, prompting Apple to halt the provisioning workflow.

Provisioning Outcome

Once Apple receives the provisioning bundle, the keys and data are securely extracted and stored on the applet. After completing personalization, a notification is sent to D1 Transit to report the outcome of the provisioning workflow.

Error Scenarios

Card fails to provision onto device

If provisioning fails, Apple sends a notification to D1 Transit with eventType as provisioningFailure. D1 Transit notifies Transit issuer about the failure. Transit Issuer can either:

• refund the customer and notify D1 Transit that the card account is deleted.
• Allow the customer to reinitiate in-app provisioning

No notification from Apple

D1 Transit has a timeout period after sending the provisioning bundle to Apple. If no notification is received within the specified timeframe, D1 Transit sends a getStatus(provisioningBundleIdentifier) request to Apple to check the current state of the card.

If the card's state is active, meaning the card successfully provisioned onto the device and is available for use, D1 Transit completes the workflow considering the provisioning as successful

If the card's state is not active, D1 Transit completes the worklow considering the provisioning as failed, i.e. Transit issuer is notified so it can refund the customer.