Web Push Provisioning

🚧

This feature is only supported for Apple Pay at this time.

Web Push Provisioning allows you to show an "Add to Apple Wallet" button on your website that will allow users to add their card directly to Apple Pay on selected devices.

Implementation Steps

1. Your BIN must be enabled for Digital Wallet Provisioning in order to use Web Push Provisioning. See the standard Digital Wallet Implementation guide for additional details. Web Push Provisioning can be completed during the initial digital wallet implementation or added later.
2. In order to show the card artwork to the user, Lithic's team will add the same artwork and Terms and Conditions that's uploaded to Visa/Mastercard to the Apple Business Register Application.
3. Integrate to Lithic's Web Push Provisioning endpoints following the development steps below.
4. You'll be required to follow network and digital wallet guidelines for user authentication, displaying the card, etc. Your Implementations Manager or Customer Success Manager will provide documentation on Apple's requirements.
5. After integration is finished Lithic will work with you to complete the Apple test cases.
6. Lithic will work with Apple to review the testing and schedule a Go-Live date.

Provisioning Flow

Step 1: After the user has gone through proper authentication to login, they can click "Add to Apple Wallet" to start the provisioning flow.

Step 2: You will then call the cards/{cards_token}/web_provision endpoint to initiate the request.

Steps 3-7: The user will see a pop-up window from Apple and will need to follow the prompts to login to their Apple ID, select the device(s) they want to provision their card to, and agree to the Terms and Conditions.

Steps 8-9: The request for tokenization will be completed between Lithic, Apple Pay, and the Network.

Steps 10-13: The response will be shown to the user.

Development Integration

💬

To complete your integration you'll need additional documentation from your Implementation Manager or Customer Success Manager.

Add to Apple Wallet Button

The Add to Apple Wallet button you place on your front-end site must follow Apple’s guidelines here. You can also download the Add to Wallet badge files from their site.

Web Provision API Request and Response

# Request
curl --request POST \
     --url https://api.lithic.com/v1/cards/{card_token}/web_provision \
     --header 'Authorization: {API_KEY}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "digital_wallet": "APPLE_PAY"
}
'

# Response
{
  'jws': {
    'protected': 'ey...',
    'payload': 'ey...',
    'signature': '...',
    'header': {
      'kid': '...'
    }
  },
  'state': '...'
}

Code Snippet to Invoke Add to Apple Wallet Button Script

Below is a code snippet for how to invoke Apple’s popup script via the Add to Apple Wallet button. In this example, the HTML ID of the button is expected to be add-to-apple-wallet.

<script src="https://smp-device-content.apple.com/navweb/asset/initAddToAppleWallet.js"></script>
<script>
  initAddToAppleWallet({
    partnerId: 'ORG-97a7c2b2-11ec-4d6d-a3f7-c3d06f4b2703',
    domain: 'https://apple-pay.apple.com',
    buttonId: 'add-to-apple-wallet',
    jwsResolver: jwsResolverCallback,
    resultResolver: resultResolverCallback
  });
</script>

Here, the jwsResolverCallback should be a function that invokes Lithic’s /cards/{card_token}/web_provision endpoint.

Code Snippet for resultResolverCallback

Below is an example for a resultResolverCallback function:

function resultResolverCallback(result) {
  if (result.status === "500") {
      // Action for error
  } else if (result.status === "408") {
      // Action for timeout
  } else if (["200", "202", "206"].includes(result.status) && addToAppleWalletButton) {
    // In the case of success, hide the Add to Apple Wallet button
    addToAppleWalletButton.style.display = "none";
  }
}

Note that upon successful provisioning, the Add to Apple Wallet button must be hidden per Apple's requirements

Callouts

• If users have pop-ups disabled on their web browser, the Apple script may fail to load.
• To avoid exposing API keys, we suggest having your front-end site call a backend proxy. The backend proxy should be responsible for actually executing a call to Lithic’s web provisioning API endpoint (this is invoked by the jwsResolver)