> 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/account-based-ticketing-abt/wallet-post-provisioning-fare-product-purchase.md). # Wallet Post Provisioning Fare Product Purchase The Wallet Post-Provisioning Fare Product Purchase workflow is initiated by the user through the Wallet app. The primary goal is for the user to purchase or renew a fare product and have it seamlessly applied to his transit card in Apple Wallet for immediate use. ### Workflow The following high level steps outline the Wallet Post-Provisioning Fare Product Purchase workflow: **Fare Product Selection**: The user selects the fare product they wish to purchase. Options may include adding stored value to an existing balance or purchasing/renewing a commute plan. **Payment**: Once the user authorizes the purchase of the selected fare product, the Payment Manager processes the payment. **Updated Bundle Retrieval and Wallet Display Update**: Upon receiving the updateBundle request, Apple requests the provisioning bundle containing the card details from D1 Transit. This step is only required if a fare product is being purchased or renewed.\ D1 Transit uses the Apple Push Notification service (APNS) to update Apple Wallet with the new fare product details. For balance update, Transit issuer sends handleEvent to D1 Transit to trigger notification through APNS in order to update Apple Wallet with the new balance value. #### Fare Product Selection **Error Scenarios** **Renewal not permitted** Apple Wallet includes a "renew" button for fare products, which becomes available based on the Transit Issuer's business rules. For instance, a monthly pass might be eligible for renewal only within a window that starts 3 days before its expiration and ends 3 days after expiration. When the user selects the "renew" button, if the cohabitation rule engine determines that renewal options are not allowed due to business rules, D1 Transit must notify Apple by returning a response with an empty cardActions array. This indicates that no renewal actions are available for the selected card. **Purchase not permitted** If the cohabitation rule engine determines that no products are available to purchase due to business rules, D1 Transit must notify Apple by returning a response with an empty cardActions array. This indicates that no purchase actions are available for the selected card.
#### Payment Upon the user authorizing the payment, a performPayment API call is triggered and sent to D1 Transit platform, which sends a purchaseProducts request to Transit Issuer. Transit Issuer is responsible for ensuring the payment request is processed by the PSP. After processing, the outcome of the transaction is communicated back to the Apple. If the payment is successfully processed, D1 Transit returns a Purchase object with its state set to complete. **Error scenarios** When a payment failure or timeout occurs, Apple Wallet displays a red exclamation mark to the user. The user can retry the payment using the same or a different payment sheet, with either the same or a different payment credential. **retry with same payment sheet** In this case, the same orderId will be used. Transit issuer needs to check the status of the payment linked to that orderId. It's possible that the existing payment was successfully processed by the PSP, but due to a delay, the previous attempt timed out. **retry with a different payment sheet** Here, a new orderId is generated for this new payment request.
#### Bundle Retrieval and Wallet Display Update After successfully purchasing or renewing a fare product, Transit Issuer sends handleEvent to D1 Transit which then notifies Apple by making an updateBundle API request, with the intentionType parameter set to updatePass. However, if the user has topped up his stored value balance, there is no need to provide an updated bundle. Upon receiving the updateBundle request, Apple retrieves the provisioning bundle by making a getProvisioningBundle request to D1 Transit. Once the bundle is returned to Apple, D1 Transit notifies Transit Issuer that the bundle was successfully updated. For balance updates, Transit Issuer notifies D1 Transit using handleEvent. The Apple Push Notification service (APNs) is used to ensure Apple Wallet reflects the latest information. **Error Scenarios** **No request from Apple to get the provisioning bundle** D1 Transit defines a timeout period between receiving the updateBundle response and the getProvisioningBundle request from Apple. If the getProvisioningBundle request is not received by D1 Transit within this timeout period, D1 Transit will apply a configured retry policy. If all retry attempts are exhausted and the getProvisioningBundle request is still not received, Thales escalates the issue by contacting Apple for further investigation and resolution. Since this integration uses ABT, the fare products bound to the card are stored on the server, which means there shouldn't be a need to refund the customer if the bundle update fails. **Provisioning bundle request received after timeout** In cases where the getProvisioningBundle request is received after the timeout, D1 Transit first verifies if the triggeringRequestIdentifier is linked to a previously timed out updateBundle requestIdentifier. If the request is associated with a timed-out updateBundle, D1 Transit returns an HTTP 200 status to Apple, setting the statusCode to HTTP 500. This response informs Apple that no further updates are necessary for the card. **Unauthorized authentication token** When the card is provisioned, Apple registers the device for transactions with D1 Transit by calling D1 Transit transactionNotifications/register endpoint. In response, D1 Transit returns an authenticationToken, which is stored on the device. If the device makes a request with an expired authenticationToken, D1 Transit returns an HTTP 401 status, prompting the device to re-register for transactions.
--- # 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/account-based-ticketing-abt/wallet-post-provisioning-fare-product-purchase.md?ask=&goal= ``` `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.