Skip to content
revisit
Start today
Wallet and passesGift cards

Wallet and passes

Gift cards

Issue gift cards, top them up and spend them.

Pilotv1

A gift card is a pass from a Gift card design. It holds money in its own currency as whole minor units, and is not a Prepaid loyalty program: it has no member, rule or reward.

Reads never return a PIN, a full number or a pass link. Each issue and action carries your own sourceEventId, so it happens once.

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

Endpoints

List gift cards

GET/gift-cards

Scopepasses:read

Requires passes:read. Newest first. Never returns a PIN, a whole card number, issue values or a link. A key limited to programs or branches is 403.

Query

designIduuid
externalCustomerIdstring
serialstring
The whole card number (spaces and dashes ignored).
limitinteger
1 to 100. Default 25.
cursorstring
The nextCursor of the previous page.

Returns 200

itemsobject[]Required
items[].idstringRequired
items[].designIdstringRequired
items[].designNamestringRequired
items[].currencystringRequired
items[].minorUnitDigitsintegerRequired
items[].balanceintegerRequired
items[].reservedintegerRequired
Held by active checkout reservations now.
items[].availableintegerRequired
balance less reserved, never below zero.
items[].issuedAmountintegerRequired
items[].maskedSerialstringRequired
•••• 2345.
items[].pinRequiredbooleanRequired
items[].pinLockedUntilstring or nullRequired
items[].statusenumRequired
One of active, used.
items[].customerIdstring or nullRequired
items[].externalCustomerIdstring or nullRequired
items[].createdAtstringRequired
nextCursorstring or nullRequired
Request
curl "https://app.revisit.cards/v1/developer/gift-cards" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY"
Response
{
  "data": {
    "items": [
      {
        "available": 7,
        "balance": 7,
        "createdAt": "2026-11-03T08:41:12.000Z",
        "currency": "BDT",
        "customerId": "eb83b9c0-5619-432d-b857-cef7fcf84edb",
        "designId": "b05ff791-cd85-4fe1-923f-7e3f7e9fdd25",
        "designName": "Mishti Ghor",
        "externalCustomerId": "user-42",
        "id": "d12cc02b-02fe-4a1f-83b0-5414e70fd99c",
        "issuedAmount": 1250,
        "maskedSerial": "•••• 7310",
        "minorUnitDigits": 2,
        "pinLockedUntil": "2026-11-03T08:41:12.000Z",
        "pinRequired": false,
        "reserved": 0,
        "status": "active"
      }
    ],
    "nextCursor": "eyJvZmZzZXQiOjUwfQ"
  },
  "requestId": "9da4edb4-e757-4fd7-816e-8507acd647ac",
  "success": true
}

Issue a gift card

POST/gift-cards

Scopepasses:write

Requires passes:write. Issues one card from a Gift card design with an opening balance in the design's currency, in whole minor units. sourceEventId is your id for the sale: the card exists once however often the request arrives (replacement keys included); other content under the same id is 409 SOURCE_EVENT_CONFLICT. 422 CURRENCY_MISMATCH when currency differs from the design's, UNSUPPORTED_CURRENCY for a design currency outside the supported list. The PIN is never returned.

Send an Idempotency-Key header. Safe to retry.

Body

amountintegerRequired
Opening balance in the currency's minor unit.
currencystringRequired
The design's ISO 4217 currency; must match.
designIduuidRequired
eventNumberstring
externalCustomerIdstring
Link the card to a customer you added.
pinstring
Asked for at every spend. Never returned.
sourceEventIdstringRequired

Returns 201

idstringRequired
designIdstringRequired
designNamestringRequired
currencystringRequired
minorUnitDigitsintegerRequired
balanceintegerRequired
reservedintegerRequired
Held by active checkout reservations now.
availableintegerRequired
balance less reserved, never below zero.
issuedAmountintegerRequired
maskedSerialstringRequired
•••• 2345.
pinRequiredbooleanRequired
pinLockedUntilstring or nullRequired
statusenumRequired
One of active, used.
customerIdstring or nullRequired
externalCustomerIdstring or nullRequired
createdAtstringRequired
duplicatebooleanRequired
sourceEventIdstringRequired
warningsobject[]Required
warnings[].codestringRequired
WRONG_DAY or PAST_TIME. Never blocks.
warnings[].messagestringRequired

Errors

  • 409SOURCE_EVENT_CONFLICTthis source event id was already applied with different content (another customer, program, action or amount). Nothing changed.
  • 422CURRENCY_MISMATCHa money action named a currency other than the program's. Nothing changed.
Request
curl -X POST "https://app.revisit.cards/v1/developer/gift-cards" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY" \
  -H "Idempotency-Key: 5f0c2a8e-7b1d-4c3e-9a6f-0d4b8e285488" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1250,
    "currency": "BDT",
    "designId": "b05ff791-cd85-4fe1-923f-7e3f7e9fdd25",
    "sourceEventId": "order-1001"
  }'
Response
{
  "data": {
    "available": 7,
    "balance": 7,
    "createdAt": "2026-11-03T08:41:12.000Z",
    "currency": "BDT",
    "customerId": "eb83b9c0-5619-432d-b857-cef7fcf84edb",
    "designId": "b05ff791-cd85-4fe1-923f-7e3f7e9fdd25",
    "designName": "Mishti Ghor",
    "duplicate": false,
    "externalCustomerId": "user-42",
    "id": "d12cc02b-02fe-4a1f-83b0-5414e70fd99c",
    "issuedAmount": 1250,
    "maskedSerial": "•••• 7310",
    "minorUnitDigits": 2,
    "pinLockedUntil": "2026-11-03T08:41:12.000Z",
    "pinRequired": false,
    "reserved": 0,
    "sourceEventId": "order-1001",
    "status": "active",
    "warnings": [
      {
        "code": "WELCOME10",
        "message": "Your 10th chai is on us this week."
      }
    ]
  },
  "requestId": "e9e88ff1-befa-44e6-81f6-bcb3cf314a19",
  "success": true
}

Read one gift card with its recent history

GET/gift-cards/{id}

Scopepasses:read

Requires passes:read. Balance and amounts are in the card's currency minor unit.

Path

iduuidRequired

Returns 200

idstringRequired
designIdstringRequired
designNamestringRequired
currencystringRequired
minorUnitDigitsintegerRequired
balanceintegerRequired
reservedintegerRequired
Held by active checkout reservations now.
availableintegerRequired
balance less reserved, never below zero.
issuedAmountintegerRequired
maskedSerialstringRequired
•••• 2345.
pinRequiredbooleanRequired
pinLockedUntilstring or nullRequired
statusenumRequired
One of active, used.
customerIdstring or nullRequired
externalCustomerIdstring or nullRequired
createdAtstringRequired
warningsobject[]Required
Event tickets and boarding passes: what a check-in now would warn about.
warnings[].codestringRequired
WRONG_DAY or PAST_TIME. Never blocks.
warnings[].messagestringRequired
historyobject[]Required
history[].idstringRequired
history[].typeenumRequired
One of spend, topup, void.
history[].amountinteger or nullRequired
history[].balanceAfterinteger or nullRequired
history[].createdAtstringRequired
history[].reversedEventIdstring or nullRequired
history[].sourceenumRequired
One of api, counter.
history[].voidedbooleanRequired
Request
curl "https://app.revisit.cards/v1/developer/gift-cards/e01b010d-2c65-48e1-83a0-acad79f8d3b4" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY"
Response
{
  "data": {
    "available": 7,
    "balance": 7,
    "createdAt": "2026-11-03T08:41:12.000Z",
    "currency": "BDT",
    "customerId": "eb83b9c0-5619-432d-b857-cef7fcf84edb",
    "designId": "b05ff791-cd85-4fe1-923f-7e3f7e9fdd25",
    "designName": "Mishti Ghor",
    "externalCustomerId": "user-42",
    "history": [
      {
        "amount": 1250,
        "balanceAfter": 7,
        "createdAt": "2026-11-03T08:41:12.000Z",
        "id": "d12cc02b-02fe-4a1f-83b0-5414e70fd99c",
        "reversedEventId": "70d7b7ae-0017-44ae-a9b7-ef2a373b1b5f",
        "source": "api",
        "type": "spend",
        "voided": false
      }
    ],
    "id": "d12cc02b-02fe-4a1f-83b0-5414e70fd99c",
    "issuedAmount": 1250,
    "maskedSerial": "•••• 7310",
    "minorUnitDigits": 2,
    "pinLockedUntil": "2026-11-03T08:41:12.000Z",
    "pinRequired": false,
    "reserved": 0,
    "status": "active",
    "warnings": [
      {
        "code": "WELCOME10",
        "message": "Your 10th chai is on us this week."
      }
    ]
  },
  "requestId": "87b191c0-85ca-414c-9e5d-dd24871a31fa",
  "success": true
}

Top up or spend

POST/gift-cards/{id}/actions

Scopepasses:write

Requires passes:write. topup or spend in the card's own currency (required, never converted), once per sourceEventId. Same planner, PIN guard and ledger as the counter: 409 INSUFFICIENT_BALANCE, OVER_LIMIT; 403 PIN_REQUIRED, WRONG_PIN; 423 PIN_LOCKED; 422 CURRENCY_MISMATCH, UNSUPPORTED_ACTION (void, adjust, any balance field). 400 BRANCH_REQUIRED when several branches are open and branchId is missing.

Send an Idempotency-Key header. Safe to retry.

Path

iduuidRequired

Body

actionenumRequired
One of topup, spend.
amountintegerRequired
branchIduuid
currencystringRequired
pinstring
Spend only.
sourceEventIdstringRequired

Returns 200

actionenumRequired
One of topup, spend.
amountintegerRequired
balanceintegerRequired
currencystringRequired
duplicatebooleanRequired
eventIdstringRequired
giftCardIdstringRequired
sourceEventIdstringRequired

Errors

  • 409INSUFFICIENT_BALANCE
  • 403PIN_REQUIRED
  • 423PIN_LOCKED
  • 422CURRENCY_MISMATCHa money action named a currency other than the program's. Nothing changed.
  • 400BRANCH_REQUIRED
Request
curl -X POST "https://app.revisit.cards/v1/developer/gift-cards/e01b010d-2c65-48e1-83a0-acad79f8d3b4/actions" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY" \
  -H "Idempotency-Key: 5f0c2a8e-7b1d-4c3e-9a6f-0d4b8eb2dc41" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "topup",
    "amount": 1250,
    "currency": "BDT",
    "sourceEventId": "order-1001"
  }'
Response
{
  "data": {
    "action": "topup",
    "amount": 1250,
    "balance": 7,
    "currency": "BDT",
    "duplicate": false,
    "eventId": "4251c053-b8cd-48e3-885b-da303b8448cc",
    "giftCardId": "9c83a2c5-ee43-4698-bd57-cbed81fdc409",
    "sourceEventId": "order-1001"
  },
  "requestId": "95de33e1-3f00-40df-86d7-c899db77aff5",
  "success": true
}

Whether the card was handed to a wallet

GET/gift-cards/{id}/wallet-pass

Scopepasses:read

Requires passes:read. Flags and times only, never a link.

Path

iduuidRequired

Returns 200

appleobjectRequired
apple.addedAtstring or nullRequired
apple.availablebooleanRequired
googleobjectRequired
google.addedAtstring or nullRequired
google.availablebooleanRequired
environmentenumRequired
One of live, test.
giftCardIdstringRequired
simulatedbooleanRequired
Request
curl "https://app.revisit.cards/v1/developer/gift-cards/e01b010d-2c65-48e1-83a0-acad79f8d3b4/wallet-pass" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY"
Response
{
  "data": {
    "apple": {
      "addedAt": "2026-11-03T08:41:12.000Z",
      "available": false
    },
    "environment": "live",
    "giftCardId": "9c83a2c5-ee43-4698-bd57-cbed81fdc409",
    "google": {
      "addedAt": "2026-11-03T08:41:12.000Z",
      "available": false
    },
    "simulated": false
  },
  "requestId": "c098965b-2324-4786-979c-791509cf40a9",
  "success": true
}

The card's Apple Wallet file

GET/gift-cards/{id}/wallet-pass/apple

Scopepasses:write

Requires passes:write. The .pkpass raw, no-store, never recorded. Test keys: 403 TEST_MODE_BLOCKED. 409 WALLET_NOT_CONFIGURED.

Path

iduuidRequired

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

Errors

  • 403TEST_MODE_BLOCKEDtest mode asked for a real provider (SMS, push, wallet, payment); nothing real is ever sent from a test workspace.
  • 409WALLET_NOT_CONFIGUREDthe wallet asked for (Apple or Google) is not set up on this deployment. Nothing was created.
Request
curl "https://app.revisit.cards/v1/developer/gift-cards/e01b010d-2c65-48e1-83a0-acad79f8d3b4/wallet-pass/apple" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY" \
  -o download
Response
HTTP/1.1 200
Content-Type: application/vnd.apple.pkpass

(file)

The card's Google Wallet save link

GET/gift-cards/{id}/wallet-pass/google

Scopepasses:write

Requires passes:write. A bearer secret: give it to the customer, never log or store it. Not recorded anywhere.

Path

iduuidRequired

Returns 200

provider"google"Required
saveUrlstringRequired
A bearer secret.
Request
curl "https://app.revisit.cards/v1/developer/gift-cards/e01b010d-2c65-48e1-83a0-acad79f8d3b4/wallet-pass/google" \
  -H "Authorization: Bearer $DEVELOPER_API_KEY"
Response
{
  "data": {
    "provider": "google",
    "saveUrl": "https://pay.google.com/gp/v/save/eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJyZXZpc2l0In0"
  },
  "requestId": "02087b3f-1f8b-4c9d-9758-48960f65185b",
  "success": true
}