Walletpasses

Worked wallet-passes samples

The endpoint list below documents every operation’s parameters; this overlay walks a pass ledger the way a wallet integration actually uses it: issue a pass → re-check its platform payloads → update it → void it. Success envelopes are { data, meta }, error envelopes { error, meta } — the four shapes are documented in How to read a worked sample. Run samples with a sandbox (dv_test_sk_*) key; nothing below leans on a provider-side wallet until you call the install link, and the platform endpoints then return the payloads Apple or Google Wallet consumes. Every response carries meta.request_id. Quote the request id when you report a wobble — support can trace the pass end-to-end from the ledger.

1. Issue a pass

POST /api/v1/wallet-passes/issue mints a pass into the ledger. The body is a full issueBodySchema — required type and title, optional contact_id / external_id link, colors as #RRGGBB, and up to 20 fields ( tuples). The default barcode is QR_CODE.

curl -X POST "https://api.orbit.devotel.io/api/v1/wallet-passes/issue" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "LOYALTY_CARD",
  "title": "Northline Rewards",
  "subtitle": "Silver tier",
  "contact_id": "cnt_8fb2d1b7c00c",
  "external_id": "order-10042",
  "fields": [{ "key": "points", "label": "Points", "value": "1,240" }],
  "background_color": "#0B2545",
  "foreground_color": "#FFFFFF"
}'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/wallet-passes/issue",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "LOYALTY_CARD",
      title: "Northline Rewards",
      subtitle: "Silver tier",
      contact_id: "cnt_8fb2d1b7c00c",
      external_id: "order-10042",
      fields: [
        { key: "points", label: "Points", value: "1,240" },
      ],
      background_color: "#0B2545",
      foreground_color: "#FFFFFF",
    }),
  },
);
console.log(await res.json());

200

{
  "data": {
    "id": "wp_8fb2d1b7c00c4ec9",
    "type": "LOYALTY_CARD",
    "title": "Northline Rewards",
    "subtitle": "Silver tier",
    "status": "active",
    "contact_id": "cnt_8fb2d1b7c00c",
    "external_id": "order-10042",
    "platforms": {
      "apple": { "configured": true, "pass_json": {} },
      "google": { "configured": false, "object": {}, "save_url": "https://pay.google.com/gp/v/save/…" }
    },
    "expires_at": "2027-08-01T00:00:00.000Z"
  },
  "meta": {
    "request_id": "req_wp_issue",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

platforms.apple.configured / platforms.google.configured tell you whether your tenant’s wallet credentials are in place; the payload keys (pass_json / object / save_url) are what a mobile client.download wraps into the wallet install link.

2. Re-read the pass

GET /api/v1/wallet-passes/{id} re-issues the pass record with the platform payloads rebuilt on every read (the response below is a live payloads snapshot, not a cached one). Prefer a re-read over an issue echo when you need the current barcode or the latest status.

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/wallet-passes/wp_8fb2d1b7c00c4ec9" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/wallet-passes/wp_8fb2d1b7c00c4ec9",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

3. Update a pass

POST /api/v1/wallet-passes/{id}/update is the in-place rewrite the ledger exposes — send only the fields you are changing. The update echoes the fresh state including fields and colors, and it is complete (the guard at least one field must be provided rejects an empty body at 422).

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/wallet-passes/wp_8fb2d1b7c00c4ec9/update" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "subtitle": "Silver tier — 1,250 points",
  "fields": [{ "key": "points", "label": "Points", "value": "1,250" }]
}'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/wallet-passes/wp_8fb2d1b7c00c4ec9/update",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      subtitle: "Silver tier — 1,250 points",
      fields: [{ key: "points", label: "Points", value: "1,250" }],
    }),
  },
);
console.log(await res.json());

200

{
  "data": {
    "id": "wp_8fb2d1b7c00c4ec9",
    "type": "LOYALTY_CARD",
    "title": "Northline Rewards",
    "subtitle": "Silver tier — 1,250 points",
    "status": "active",
    "fields": [{ "key": "points", "label": "Points", "value": "1,250" }],
    "platforms": {
      "apple": { "configured": true, "pass_json": {} },
      "google": { "configured": false, "object": {}, "save_url": "https://pay.google.com/gp/v/save/…" }
    }
  },
  "meta": {
    "request_id": "req_wp_update",
    "timestamp": "2026-08-26T12:01:00.000Z"
  }
}

4. Void a pass

POST /api/v1/wallet-passes/{id}/void flips the ledger to voided — the pass stops validating at a scan, the reason travels with the ledger row, and the void is idempotent-safe because the ledger keeps the original issue rows attached.

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/wallet-passes/wp_8fb2d1b7c00c4ec9/void" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "customer requested cancellation" }'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/wallet-passes/wp_8fb2d1b7c00c4ec9/void",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      reason: "customer requested cancellation",
    }),
  },
);
console.log(await res.json());

200

{
  "data": {
    "id": "wp_8fb2d1b7c00c4ec9",
    "status": "voided",
    "voided_reason": "customer requested cancellation"
  },
  "meta": {
    "request_id": "req_wp_void",
    "timestamp": "2026-08-26T12:02:00.000Z"
  }
}

5. Errors

Errors follow the { error, meta } envelope. The failure every issuer hits: 422 — field validation. Colors not in #RRGGBB, more than 20 fields, or an empty update body:

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "background_color must be a #RRGGBB hex color.",
    "status": 422
  },
  "meta": {
    "request_id": "req_wp_err",
    "timestamp": "2026-08-26T12:03:00.000Z"
  }
}

API Reference

All Endpoints

Worked wallet-passes samples

1. Issue a pass

2. Re-read the pass

3. Update a pass

4. Void a pass

5. Errors

​Worked wallet-passes samples

​1. Issue a pass

​2. Re-read the pass

​3. Update a pass

​4. Void a pass

​5. Errors

Worked wallet-passes samples

1. Issue a pass

2. Re-read the pass

3. Update a pass

4. Void a pass

5. Errors