Quickstart

Enroll a customer and award their first stamp - five minutes, three requests.

This walkthrough wires the smallest real integration: create a customer on your stamp card, award a stamp when they buy, and watch the event arrive. Use your API key from Settings → Developer → API keys, or a sandbox key (vxn_test_sk_...) if you would rather run it away from real customers first (see Testing and environments).

​

Anatomy of your first call

Every step below is the same four-beat pattern: grab your key once, put it on every request, call an endpoint, read what comes back. Once this loop feels automatic, the rest of the API is just new endpoints inside it.

Set VXN_API_KEY once as an environment variable and every curl below just works: export VXN_API_KEY=vxn_test_sk_...

1. Find your card id

   curl https://api.vexioncards.one/v1/cards \
     -H "Authorization: Bearer $VXN_API_KEY"
   

   Grab the id of your stamp card (crd_...) from the response.

2. Enroll a customer

   POST /v1/customers is an upsert - the same call from your checkout can run on every order, and the dedupe key (external_id → email → phone, scoped to the card) makes it idempotent:

   curl -X POST https://api.vexioncards.one/v1/customers \
     -H "Authorization: Bearer $VXN_API_KEY" \
     -H "Idempotency-Key: order-1001-enroll" \
     -H "Content-Type: application/json" \
     -d '{
       "card_id": "crd_YOUR_STAMP_CARD",
       "email": "[e-mail]",
       "first_name": "Jana"
     }'
   

   The response includes claim_url. Send it to the customer yourself, or add "deliver": { "channel": "email" } to the request and we email it. When the customer opens the link, the pass lands in their Apple or Google Wallet.

3. Award a stamp

   curl -X POST https://api.vexioncards.one/v1/transactions \
     -H "Authorization: Bearer $VXN_API_KEY" \
     -H "Idempotency-Key: order-1001-stamp" \
     -H "Content-Type: application/json" \
     -d '{
       "customer_id": "cus_FROM_STEP_2",
       "action": "award",
       "value": 1
     }'
   

   The server computes everything else - the response carries type: "stamp.add" and balance_after.stamps_collected. Once the customer has added the pass, it updates and their lock screen shows the banner.

4. Hear about it (optional)

   Register a webhook receiver and prove it in one call:

   curl -X POST https://api.vexioncards.one/v1/webhook_endpoints \
     -H "Authorization: Bearer $VXN_API_KEY" \
     -H "Idempotency-Key: wh-setup-1" \
     -H "Content-Type: application/json" \
     -d '{ "url": "https://yourapp.example/webhooks", "enabled_events": ["transaction.created"] }'
   # → store the whsec_ secret from the response, then:
   curl -X POST https://api.vexioncards.one/v1/webhook_endpoints/{id}/test \
     -H "Authorization: Bearer $VXN_API_KEY" -H "Idempotency-Key: wh-test-1"
   

​

Where next

Transactions

Every loyalty event, one endpoint.

Webhooks

Signatures, retries, the 22-event catalog.

Testing and environments

The sandbox, and how to go live.

Idempotency

Why every POST carries the key.