REST API Reference & SDKs

Passinstance Developer Documentation

Build high-volume Apple Wallet (.pkpass) and Google Wallet integrations. Issue, update, scan, and broadcast real-time lockscreen notifications via production-grade REST APIs.

Get API Keys

Developer Docs/Scanner & Devices

REST API v1

All API Reference Passes Templates Scanner & Devices Push & Delivery Webhooks Batch Operations

POSThttps://api.passinstance.com/api/v1/passes/{id}/use

Bearer

Apply mechanic action

Execute an atomic pass mechanic operation: INCREMENT (stamp card), DECREMENT, DEBIT (prepaid balance), CREDIT, or VALIDATE (single-use coupon).

Path Parameters1 required

idstring (UUID)

Required

The unique UUID of the pass to operate upon.

example: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

UsePassDto containing the mechanic action, optional decimal amount, operator ID, and location.

Request Body1 required • 4 optional

actionstring (enum)

Required

INCREMENT, DECREMENT, DEBIT, CREDIT, VALIDATE, or NOOP.

example: INCREMENT

Response Status Codes

200OK

ApiResponseDto with execution details and new balance/stamp count.

400Bad Request

Insufficient balance or invalid action.

Related:Adjust pass stored value

POSThttps://api.passinstance.com/api/v1/scans

Scanner Key

Process barcode / NFC scan

Validate an optical barcode, QR code, or Apple VAS / Google Smart Tap NFC scan payload from a terminal or mobile scanner.

Headers2 required

x-scanner-keystring

Required

Dedicated hardware/software scanner credential.

example: scan_key_77a8b9c0d1e2f3a4b5c6d7e8

Content-Typestring

Required

Must be application/json.

example: application/json

ScanRequestDto payload containing scanned barcode string and optional terminal metadata.

Request Body1 required • 2 optional

scannedBarcodeValuestring

Required

The raw payload string read from the QR code, PDF417, or NFC tap.

example: PI-8891-JD-VIP

Response Status Codes

200OK

ScanResponseDto containing decision, snapshot, effects, and display instructions.

401Unauthorized

Invalid or inactive scanner key.

POSThttps://api.passinstance.com/api/v1/passes/{id}/adjust-value

Bearer

Adjust pass stored value

Manually credit (add) or debit (deduct) stored value or reward points on a pass with transaction audit logging.

Path Parameters1 required

idUUID

Required

Target pass instance ID.

example: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Adjustment payload specifying CREDIT or DEBIT operation, amount, and reason.

Request Body2 required • 2 optional

actionstring

Required

Transaction action: 'CREDIT' to add value, or 'DEBIT' to deduct value.

example: CREDIT

amountstring

Required

Numeric amount to credit or debit as a string.

example: 25.00

Response Status Codes

200OK

ApiResponseDto returning scan/transaction record with previous and resulting value.

Related:Apply mechanic action

POST/passes/{id}/use

Pass Mechanics

Request

curl -X POST https://api.passinstance.com/api/v1/passes/pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/use \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "INCREMENT",
    "deviceId": "terminal_front_pos_01",
    "operatorId": "staff_usr_442",
    "location": "Store #104 - Downtown"
  }'

Response

OKApiResponseDto with execution details and new balance/stamp count.

{
  "success": true,
  "data": {
    "scanId": "scan_4c8b2a1e-7f6d-4a3b-8c9e-0f1a2b3c4d5e",
    "passId": "pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
    "action": "INCREMENT",
    "success": true,
    "resultingValue": "6",
    "errorCode": null,
    "errorMessage": null
  },
  "description": "Pass INCREMENT successfully",
  "errors": [],
  "statusCode": 200
}

Envelope: ApiResponseDto<T>HTTPS (TLS 1.3)