Digital wallets allow users to store and use their cards without carrying a physical card with them. This guide describes how to provision cards using Apple Pay.

At a high level, this is what provisioning a card to Apple Wallet entails:

  1. The user taps the Add to Apple Wallet button.
  2. Apple Wallet prepares and returns the public certificates, nonce, and nonce signature to your app.
  3. Your app passes the public certificates, nonce, and nonce signature to Treasury Prime, which implements the issuer host responsibilities for you.
  4. A payment data payload is prepared and encrypted then returned to your app along with the ephemeral public key and activation data.
  5. Your app passes the encrypted payment data payload, ephemeral public key, and activation data to Apple Wallet.
  6. Apple Wallet processes the request.

This guide uses the following endpoints

To provision a card, you must do these things

  1. Look up cards a user owns
  2. Provision digital wallet token

1. Look up cards

The first step in provisioning a card for a digital wallet is looking up which cards a user has. Filter available cards by the person whose device the card is being provisioned for.

curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/card?person_id="psn_qda4pJZfpzn4f"
{
  "data": [
    {
      "cvv": null,
      "account_id": "acct_11ggtz5y2wsj",
      "pan": null,
      "expiration": "0925",
      "person_id": "psn_qda4pJZfpzn4f",
      "last4": "3496",
      "card_product_id": "cdpt_11ggtwth2wshde",
      "updated_at": "2021-09-27T21:12:07Z",
      "card_controls": null,
      "status": "active",
      "fulfillment": {
        "status": "issued"
      },
      "id": "card_11gn4cvm4c7t6p",
      "pin_is_set": false,
      "created_at": "2021-09-27T21:11:16Z",
      "userdata": null
    },
    {
      "cvv": null,
      "account_id": "acct_11ggtz5y2wsj",
      "pan": null,
      "expiration": "0925",
      "person_id": "psn_qda4pJZfpzn4f",
      "last4": "5732",
      "card_product_id": "cdpt_11ggtwth2wshde",
      "updated_at": "2021-09-27T21:12:09Z",
      "card_controls": null,
      "status": "terminated",
      "fulfillment": {
        "status": "issued"
      },
      "id": "card_11gmwjx63qty7h",
      "pin_is_set": true,
      "created_at": "2021-09-24T22:05:26Z",
      "userdata": null
    }
  ],
  "total_estimated": 10
}

You application will display eligible cards to the user, and the user can initiate card tokenization by choosing to add it to their wallet.

2. Add card to wallet

After the user has clicked the Add to Wallet button, your application will receive a payload you must pass to Treasury Prime, at the card/:card_id/digital_wallet_token/apple_pay endpoint. For this example, we will tokenize card_11gn4cvm4c7t6p.

curl https://api.treasuryprime.com/card/card_11gn4cvm4c7t6p/digital_wallet_token/apple_pay \
  -u $API_KEY_ID:$API_SECRET_KEY
{
  "card_id": "card_11gn4cvm4c7t6p",
  "encrypted_pass_data": "w9NGKYa3OkPGeQ+FmAKGga",
  "activation_data": "TUJQQUMtMS1GSy03NDgwNTIuMS0tVERF",
  "ephemeral_public_key": "BMop3NufgKwy/r0GX1muvomvw"
}

Your application must pass this data to the PKAddPaymentPassViewController to complete adding the card to the user's wallet.