Issue your first pass

In this tutorial you issue Harbour Coffee's stamp card to a customer, Maya Chen, from a terminal, then add stamps to it and see the card change on her phone. It takes about ten minutes and needs nothing but curl.

Before you start#

• A Walletap account on a plan with API access, signed in as the owner.
• A loyalty template with stamps. This tutorial uses Coffee Card, a ten-stamp card. If you do not have one, create a template first.
• An email address you can read on your phone. The pass is delivered there.
• A terminal with curl.

Issue the pass#

1. Create an API key

   In the dashboard, go to SettingsAPI keys and click Create. Leave Manage passes selected, label the key First pass, and click Create. Click Copy key — this is the only time the full key is shown.

   Save it in your terminal session so the commands below can use it:

   Shell

   export WALLETAP_API_KEY="wtap_sk_..."

2. Find the template's ID

   Ask the API for your templates:

   Shell

   curl https://api.walletap.com/templates \
     -H "X-API-Key: $WALLETAP_API_KEY"

   The response lists them under data. Find Coffee Card and note its id:

   JSON

   {
     "object": "list",
     "data": [
       {
         "object": "template",
         "id": "tmpl_123",
         "name": "Coffee Card",
         "type": "loyalty",
         "pass": "{\"useStampCollection\":true,\"stampCount\":10,…}",
         …
       },
       …
     ],
     "has_more": false,
     "next_cursor": null,
     "total_count": 6,
     "url": "/templates"
   }

   The same ID is in the dashboard's address bar when you open the template: app.walletap.com/template/tmpl_123/design.

3. Issue the pass

   Send one pass for the template. Replace tmpl_123 with your template's ID and the email address with your own:

   Shell

   curl -X POST https://api.walletap.com/pass \
     -H "X-API-Key: $WALLETAP_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "passes": [
         {
           "templateId": "tmpl_123",
           "externalId": "harbour-crm-1042",
           "templateFields": { "accountName": "Maya Chen" }
         }
       ],
       "email": "maya.chen@example.com",
       "locale": "en"
     }'

   • templateFields.accountName is the name on a loyalty card.
   • externalId is your own reference for this customer, such as their ID in your CRM. You can use it later to find the pass instead of Walletap's ID.
   • email is where the pass is sent.

Read the response#

The API answers with the new pass:

{
  "id": "pass_456",
  "externalId": "harbour-crm-1042",
  "link": "https://pass.walletap.com/pass_456",
  "pass": {
    "apple": "https://…/pass_456.pkpass?…",
    "google": "https://pay.google.com/gp/v/save/…"
  },
  "badge": {
    "apple": "https://…/badges/apple/en.png",
    "google": "https://…/badges/google/en.png"
  }
}

Add the pass to a wallet#

1. Open the email

   On your phone, open the email from Coffee Card via Walletap and tap the link. Or open the link from the response in your browser.

2. Add it

   On a phone, the page offers Add to Apple Wallet or Add to Google Wallet for that phone. On a computer it shows a QR code: scan it with your phone's camera to continue there.

   pass.walletap.com/…

   

The pass is now in the wallet, with Maya Chen's name and an empty stamp strip.

Update the pass#

Changes you make over the API reach the wallet on their own. Give Maya three stamps by stating her new count. Replace pass_456 with the id from the response:

curl -X PATCH https://api.walletap.com/pass \
  -H "X-API-Key: $WALLETAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "pass_456",
    "collectedStamps": 3
  }'

{
  "id": "pass_456",
  "externalId": "harbour-crm-1042",
  "stampCollection": {
    "totalCollected": 3,
    "collectedStamps": 3,
    "totalStamps": 10,
    "isComplete": false,
    "claimedTiers": [],
    "lastUpdated": 1760180400000
  }
}

Look at the card on your phone: within a few moments the strip shows three stamps. Nobody needed to reinstall anything — Walletap pushed the change to the wallet.

You can also see the pass in the dashboard, under TemplatesCoffee CardMembers.

What you built#

You issued a pass from your own code, delivered it, and changed it after it was already on a phone. A real integration does the same three things at the moment they happen in your business: issue when someone signs up, update when they buy a coffee.