> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/transit-digitization/implement-apple-transit/card-based-ticketing-cbt/in-app-provisioning.md).

# 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 <a href="#workflow" id="workflow"></a>

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 <a href="#sequence-diagram" id="sequence-diagram"></a>

#### Associating existing transit cards in Apple Wallet <a href="#associating-existing-transit-cards-in-apple-wallet" id="associating-existing-transit-cards-in-apple-wallet"></a>

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.

<figure><img src="/spaces/SokLBgfEhZisVFcUdPiW/files/AIz9GcAYdNDiA61CQ10e" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
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
{% endhint %}

#### Provisioning <a href="#provisioning" id="provisioning"></a>

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.

<figure><img src="/spaces/SokLBgfEhZisVFcUdPiW/files/yQQfbIYgzJwbrukWLvZy" alt=""><figcaption></figcaption></figure>

#### Provisioning Outcome <a href="#provisioning-outcome" id="provisioning-outcome"></a>

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.

<figure><img src="/spaces/SokLBgfEhZisVFcUdPiW/files/l1wg9zl6U1GFj60vT2CL" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.payments.thalescloud.io/transit-digitization/implement-apple-transit/card-based-ticketing-cbt/in-app-provisioning.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.