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.