Wallet and passesWallet

Wallet and passes

Wallet

Designs, images, previews and loyalty pass delivery.

Pilotv1

Wallet designs are the looks of the shop's passes. Read whether Apple and Google Wallet are set up, change designs, upload images and preview a card, then hand a member's loyalty pass to Apple Wallet (a .pkpass file) or Google Wallet (a save link).

A save link is a short-lived credential: it is never stored or logged. A test key never reaches a wallet provider.

Paths are relative to https://app.revisit.cards/v1/developer.

Endpoints

GET/wallet/status
What Apple and Google Wallet can do for this key
GET/wallet/designs
List saved wallet designs
POST/wallet/designs
Save a wallet design
GET/wallet/designs/{id}
Read a wallet design
PUT/wallet/designs/{id}
Replace a wallet design
DELETE/wallet/designs/{id}
Delete a wallet design
POST/wallet/media
Upload a design image
GET/wallet/designs/{id}/preview/apple
Sample Apple pass of a design
GET/wallet/designs/{id}/preview/google
Sample Google save link of a design
GET/programs/{programId}/wallet-preview/apple
Sample Apple pass of a program's loyalty card
GET/programs/{programId}/wallet-preview/google
Sample Google save link of a program's loyalty card
GET/memberships/{membershipId}/wallet-pass
Read a member's wallet pass state
POST/memberships/{membershipId}/wallet-pass
Get a member's card ready for the wallets
GET/memberships/{membershipId}/wallet-pass/apple
The member's Apple Wallet file
GET/memberships/{membershipId}/wallet-pass/google
The member's Google Wallet save link

What Apple and Google Wallet can do for this key

GET/wallet/status

Scopewallet:read

Requires wallet:read. configured is whether this deployment has the wallet's credentials; deliverable is whether a pass can be built for this key right now. A test key is simulated: true and never deliverable: nothing is created at Apple or Google from a test workspace.

Returns 200

appleobjectRequired
apple.configuredbooleanRequired
apple.deliverablebooleanRequired
googleobjectRequired
google.configuredbooleanRequired
google.deliverablebooleanRequired
environmentenumRequired: One of live, test.
simulatedbooleanRequired

Request

curl "https://app.revisit.cards/v1/developer/wallet/status" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY"

Response

{
  "data": {
    "apple": {
      "configured": false,
      "deliverable": false
    },
    "environment": "live",
    "google": {
      "configured": false,
      "deliverable": false
    },
    "simulated": false
  },
  "requestId": "99413630-e5e7-4f99-99c5-414c1d34658e",
  "success": true
}

List saved wallet designs

GET/wallet/designs

Scopewallet:read

Requires wallet:read. Saved designs are the non-loyalty wallet cards (gift card, offer, event ticket, boarding pass, transit, generic); a loyalty card is its program (PATCH /programs/{id}). A key limited to some programs or branches is 403: designs are business-wide.

Returns 200

itemsobject[]Required
items[].idstringRequired
items[].namestringRequired
items[].typestringRequired
items[].draftobjectRequired
items[].suspendedbooleanRequired: A plan downgrade left the design read-only.
items[].updatedAtstringRequired

Request

curl "https://app.revisit.cards/v1/developer/wallet/designs" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY"

Response

{
  "data": {
    "items": [
      {
        "draft": {},
        "id": "d12cc02b-02fe-4a1f-83b0-5414e70fd99c",
        "name": "Chai card",
        "suspended": false,
        "type": "Café",
        "updatedAt": "2026-11-03T08:41:12.000Z"
      }
    ]
  },
  "requestId": "924453f7-8239-4e0f-b416-9be26dc260bf",
  "success": true
}

Save a wallet design

POST/wallet/designs

Scopewallet:write

Requires wallet:write. The body is the card editor's own: name and a draft (the draft's type picks the card type; its fields and limits are the editor's, images are /api/media/<id> paths from POST /wallet/media or public https links). Same plan rules as the app (the designs limit, a paid plan). 422 LOYALTY_SAVED_ELSEWHERE for a loyalty draft. Unknown fields are 422.

Send an Idempotency-Key header. Safe to retry.

Body

namestringRequired: 1 to 60 characters.
draftobjectRequired: The card editor's draft; type is giftCard, offer, eventTicket, boardingPass, transit or generic.

Returns 201

idstringRequired
namestringRequired
typestringRequired
draftobjectRequired
suspendedbooleanRequired: A plan downgrade left the design read-only.
updatedAtstringRequired

Errors

422LOYALTY_SAVED_ELSEWHERE

Request

curl -X POST "https://app.revisit.cards/v1/developer/wallet/designs" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY" \
  -H "Idempotency-Key: 5f0c2a8e-7b1d-4c3e-9a6f-0d4b8ea595e4" \
  -H "Content-Type: application/json" \
  -d '{
    "draft": {},
    "name": "Chai card"
  }'

Response

{
  "data": {
    "draft": {},
    "id": "d12cc02b-02fe-4a1f-83b0-5414e70fd99c",
    "name": "Chai card",
    "suspended": false,
    "type": "Café",
    "updatedAt": "2026-11-03T08:41:12.000Z"
  },
  "requestId": "bd9d1da3-20af-44fe-897c-83cf471439c3",
  "success": true
}

Read a wallet design

GET/wallet/designs/{id}

Scopewallet:read

Requires wallet:read. A design of another business is 404.

Path

iduuidRequired

Returns 200

idstringRequired
namestringRequired
typestringRequired
draftobjectRequired
suspendedbooleanRequired: A plan downgrade left the design read-only.
updatedAtstringRequired

Request

curl "https://app.revisit.cards/v1/developer/wallet/designs/e01b010d-2c65-48e1-83a0-acad79f8d3b4" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY"

Response

{
  "data": {
    "draft": {},
    "id": "d12cc02b-02fe-4a1f-83b0-5414e70fd99c",
    "name": "Chai card",
    "suspended": false,
    "type": "Café",
    "updatedAt": "2026-11-03T08:41:12.000Z"
  },
  "requestId": "bc342a11-336d-4b7f-8367-59353beb215f",
  "success": true
}

Replace a wallet design

PUT/wallet/designs/{id}

Scopewallet:write

Requires wallet:write. The type is fixed at creation (409 TYPE_FIXED). Saved Google passes of the design are brought up to date.

Send an Idempotency-Key header. Safe to retry.

Path

iduuidRequired

Body

namestringRequired: 1 to 60 characters.
draftobjectRequired: The card editor's draft; type is giftCard, offer, eventTicket, boardingPass, transit or generic.

Returns 200

idstringRequired
namestringRequired
typestringRequired
draftobjectRequired
suspendedbooleanRequired: A plan downgrade left the design read-only.
updatedAtstringRequired

Errors

409TYPE_FIXED

Request

curl -X PUT "https://app.revisit.cards/v1/developer/wallet/designs/e01b010d-2c65-48e1-83a0-acad79f8d3b4" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY" \
  -H "Idempotency-Key: 5f0c2a8e-7b1d-4c3e-9a6f-0d4b8e1c700c" \
  -H "Content-Type: application/json" \
  -d '{
    "draft": {},
    "name": "Chai card"
  }'

Response

{
  "data": {
    "draft": {},
    "id": "d12cc02b-02fe-4a1f-83b0-5414e70fd99c",
    "name": "Chai card",
    "suspended": false,
    "type": "Café",
    "updatedAt": "2026-11-03T08:41:12.000Z"
  },
  "requestId": "3e56b66c-09ed-4908-9b3d-f276154c84dd",
  "success": true
}

Delete a wallet design

DELETE/wallet/designs/{id}

Scopewallet:write

Requires wallet:write. A design with issued passes stays (409 DESIGN_HAS_PASSES).

Send an Idempotency-Key header. Safe to retry.

Path

iduuidRequired

Returns 200

deletedtrueRequired
idstringRequired

Errors

409DESIGN_HAS_PASSES

Request

curl -X DELETE "https://app.revisit.cards/v1/developer/wallet/designs/e01b010d-2c65-48e1-83a0-acad79f8d3b4" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY" \
  -H "Idempotency-Key: 5f0c2a8e-7b1d-4c3e-9a6f-0d4b8e83ccbf"

Response

{
  "data": {
    "deleted": true,
    "id": "d12cc02b-02fe-4a1f-83b0-5414e70fd99c"
  },
  "requestId": "1d6b4766-96c7-49db-b3c8-c5f8218889fb",
  "success": true
}

Upload a design image

POST/wallet/media

Scopewallet:write

Requires wallet:write. Multipart with one file part: PNG, JPEG or WebP, at most 2 MB (422 IMAGE_TYPE, 413 IMAGE_TOO_LARGE), 10 a minute per business. Returns the url to put in a design's image fields. The same key and file answers the first upload.

Send an Idempotency-Key header. Safe to retry.

Body (multipart)

filefileRequired

Returns 200

urlstringRequired: /api/media/<id>; use it in a design's image fields.
contentTypestringRequired
sizeintegerRequired

Errors

422IMAGE_TYPE
413IMAGE_TOO_LARGE

Request

curl -X POST "https://app.revisit.cards/v1/developer/wallet/media" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY" \
  -H "Idempotency-Key: 5f0c2a8e-7b1d-4c3e-9a6f-0d4b8e11ff1e" \
  -F "file=@photo.png"

Response

{
  "data": {
    "contentType": "image/png",
    "size": 48213,
    "url": "https://app.revisit.cards/api/media/logo.png"
  },
  "requestId": "f885b8ab-9eb4-479e-a533-5911a91b4de4",
  "success": true
}

Sample Apple pass of a design

GET/wallet/designs/{id}/preview/apple

Scopewallet:read

Requires wallet:read. A signed .pkpass with sample data. 409 WALLET_NOT_CONFIGURED; a test key is 403 TEST_MODE_BLOCKED.

Path

iduuidRequired

Answers with a file: application/vnd.apple.pkpass.

Errors

409WALLET_NOT_CONFIGUREDthe wallet asked for (Apple or Google) is not set up on this deployment. Nothing was created.
403TEST_MODE_BLOCKEDtest mode asked for a real provider (SMS, push, wallet, payment); nothing real is ever sent from a test workspace.

Request

curl "https://app.revisit.cards/v1/developer/wallet/designs/e01b010d-2c65-48e1-83a0-acad79f8d3b4/preview/apple" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY" \
  -o download

Response

HTTP/1.1 200
Content-Type: application/vnd.apple.pkpass

(file)

Sample Google save link of a design

GET/wallet/designs/{id}/preview/google

Scopewallet:read

Requires wallet:read. A signed link; nothing is written at Google. Same refusals as the Apple preview.

Path

iduuidRequired

Returns 200

provider"google"Required
saveUrlstringRequired: A bearer secret.

Request

curl "https://app.revisit.cards/v1/developer/wallet/designs/e01b010d-2c65-48e1-83a0-acad79f8d3b4/preview/google" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY"

Response

{
  "data": {
    "provider": "google",
    "saveUrl": "https://pay.google.com/gp/v/save/eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJyZXZpc2l0In0"
  },
  "requestId": "fa1abcba-a1dd-4ff9-bbc9-603d061124e9",
  "success": true
}

Sample Apple pass of a program's loyalty card

GET/programs/{programId}/wallet-preview/apple

Scopewallet:read

Requires wallet:read. No customer in it. A program outside the key's limits is 404.

Path

programIduuidRequired

Answers with a file: application/vnd.apple.pkpass.

Request

curl "https://app.revisit.cards/v1/developer/programs/d7595bbd-4342-41b4-9037-2e61a9f8403f/wallet-preview/apple" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY" \
  -o download

Response

HTTP/1.1 200
Content-Type: application/vnd.apple.pkpass

(file)

Sample Google save link of a program's loyalty card

GET/programs/{programId}/wallet-preview/google

Scopewallet:read

Requires wallet:read. Nothing is written at Google.

Path

programIduuidRequired

Returns 200

provider"google"Required
saveUrlstringRequired: A bearer secret.

Request

curl "https://app.revisit.cards/v1/developer/programs/d7595bbd-4342-41b4-9037-2e61a9f8403f/wallet-preview/google" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY"

Response

{
  "data": {
    "provider": "google",
    "saveUrl": "https://pay.google.com/gp/v/save/eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJyZXZpc2l0In0"
  },
  "requestId": "8028c0a1-fac0-4528-9dd2-c940b765edef",
  "success": true
}

Read a member's wallet pass state

GET/memberships/{membershipId}/wallet-pass

Scopewallet:read

Requires wallet:read. Flags and first-hand-over times only (a hand-over is a tap, not a confirmed install). Never a link, card token or secret. A membership outside the key's business, environment or limits, or of an erased customer, is 404.

Path

membershipIduuidRequired

Returns 200

membershipIdstringRequired
programIdstringRequired
customerIdstringRequired
externalCustomerIdstring or nullRequired
environmentenumRequired: One of live, test.
simulatedbooleanRequired
appleobjectRequired
apple.availablebooleanRequired
apple.addedAtstring or nullRequired
googleobjectRequired
google.availablebooleanRequired
google.addedAtstring or nullRequired

Request

curl "https://app.revisit.cards/v1/developer/memberships/b53ca741-1e76-4ddb-b6a5-998b65c4aff3/wallet-pass" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY"

Response

{
  "data": {
    "apple": {
      "addedAt": "2026-11-03T08:41:12.000Z",
      "available": false
    },
    "customerId": "eb83b9c0-5619-432d-b857-cef7fcf84edb",
    "environment": "live",
    "externalCustomerId": "user-42",
    "google": {
      "addedAt": "2026-11-03T08:41:12.000Z",
      "available": false
    },
    "membershipId": "b53ca741-1e76-4ddb-b6a5-998b65c4aff3",
    "programId": "d7595bbd-4342-41b4-9037-2e61a9f8403f",
    "simulated": false
  },
  "requestId": "86dea209-994a-4056-8a72-d53c98da04ae",
  "success": true
}

Get a member's card ready for the wallets

POST/memberships/{membershipId}/wallet-pass

Scopewallet:write

Requires wallet:write. Creates or refreshes the program's Google class; safe to repeat. A test key only gets simulated: true: nothing is created anywhere. Wallet use is optional: enrolling, earning and redeeming never need it, and it never changes marketing consent.

Send an Idempotency-Key header. Safe to retry.

Path

membershipIduuidRequired

Returns 200

membershipIdstringRequired
programIdstringRequired
customerIdstringRequired
externalCustomerIdstring or nullRequired
environmentenumRequired: One of live, test.
simulatedbooleanRequired
appleobjectRequired
apple.availablebooleanRequired
apple.addedAtstring or nullRequired
googleobjectRequired
google.availablebooleanRequired
google.addedAtstring or nullRequired

Request

curl -X POST "https://app.revisit.cards/v1/developer/memberships/b53ca741-1e76-4ddb-b6a5-998b65c4aff3/wallet-pass" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY" \
  -H "Idempotency-Key: 5f0c2a8e-7b1d-4c3e-9a6f-0d4b8eb4c141"

Response

{
  "data": {
    "apple": {
      "addedAt": "2026-11-03T08:41:12.000Z",
      "available": false
    },
    "customerId": "eb83b9c0-5619-432d-b857-cef7fcf84edb",
    "environment": "live",
    "externalCustomerId": "user-42",
    "google": {
      "addedAt": "2026-11-03T08:41:12.000Z",
      "available": false
    },
    "membershipId": "b53ca741-1e76-4ddb-b6a5-998b65c4aff3",
    "programId": "d7595bbd-4342-41b4-9037-2e61a9f8403f",
    "simulated": false
  },
  "requestId": "78496a59-f10c-4692-980d-11a2afda5902",
  "success": true
}

The member's Apple Wallet file

GET/memberships/{membershipId}/wallet-pass/apple

Scopewallet:write

Requires wallet:write. Sends the .pkpass raw (Cache-Control: no-store); hand it to the customer. Not recorded anywhere. 409 WALLET_NOT_CONFIGURED; a test key is 403 TEST_MODE_BLOCKED.

Path

membershipIduuidRequired

Answers with a file: application/vnd.apple.pkpass.

Errors

409WALLET_NOT_CONFIGUREDthe wallet asked for (Apple or Google) is not set up on this deployment. Nothing was created.
403TEST_MODE_BLOCKEDtest mode asked for a real provider (SMS, push, wallet, payment); nothing real is ever sent from a test workspace.

Request

curl "https://app.revisit.cards/v1/developer/memberships/b53ca741-1e76-4ddb-b6a5-998b65c4aff3/wallet-pass/apple" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY" \
  -o download

Response

HTTP/1.1 200
Content-Type: application/vnd.apple.pkpass

(file)

The member's Google Wallet save link

GET/memberships/{membershipId}/wallet-pass/google

Scopewallet:write

Requires wallet:write. A signed link that adds only this pass. It is a bearer secret: give it to the customer, never log or store it. Not recorded anywhere.

Path

membershipIduuidRequired

Returns 200

provider"google"Required
saveUrlstringRequired: A bearer secret.

Request

curl "https://app.revisit.cards/v1/developer/memberships/b53ca741-1e76-4ddb-b6a5-998b65c4aff3/wallet-pass/google" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY"

Response

{
  "data": {
    "provider": "google",
    "saveUrl": "https://pay.google.com/gp/v/save/eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJyZXZpc2l0In0"
  },
  "requestId": "9408328b-4a26-49ef-b3b5-dd279f596324",
  "success": true
}