Devices

Devices are refered to as scanners in the dashboard. They are used to scan QR codes. They are also used to scan the members card.

Latest Update (March 30, 2026): The scanner API now supports storecards! Scan endpoints (/devices/scan/info and /devices/scan) now return pass_type: "payment" for storecards and payment instruments, while coupons and promotions continue to return pass_type: "discount". See Understanding Pass Types for integration details.

The device model

The device model contains info about its current configuration.

Properties

Name
name
Type
string
Description
The name of the device.
Name
identifier
Type
string
Description
Unique identifier for the brand.
Name
external_device_id
Type
string
Description
Your identifier or unique reference to the device.
Name
add_multiplier
Type
integer
Description
The multiplier for adding points to a storecard. Defaults to 1.
Name
subtract_multiplier
Type
integer
Description
The multiplier for subtracting points from a storecard. Defaults to 1.
Name
pin
Type
string
Description
The authentication token used to login to the device.
Name
location
Type
object
Description
The location that is attached to the location, contains: ["identifier", "address"]

GET/devices

Get a list of devices

This endpoint returns a list of devices.

Required headers

Name
Authorization
Type
string
Description
The token itself as a bearer token.

Abilities

Name
devices.get
Type
string
Description
The scope required to access this endpoint.

Request

GET

/devices

curl -X GET https://api.walletapp.co/devices
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"

Response

{
    "message": "Request successful",
    "data": [
        {
            "name": "<device_name>",
            "identifier": "<uuid>",
            "external_device_id": "<external_device_id>",
            "add_multiplier": 1,
            "subtract_multiplier": 1,
            "pin": "1234",
            "location": {
                "identifier": "<uuid>",
                "address": "<address>"
            }
        },
        ...
    ]
}

POST/devices

Store a device

This endpoint is used to create a new device.

Required headers

Name
Authorization
Type
string
Description
The token itself as a bearer token.

Abilities

Name
devices.store
Type
string
Description
The scope required to access this endpoint.

Request body

Name
name
Type
string|Required
Description
The name of the device.
Name
location_id
Type
string|Required
Description
The location identifier.
Name
external_device_id
Type
string|Required
Description
A unique identifier for the device.
Name
pin
Type
string|Required
Description
An authentication token used to sign in to the device.
Name
add_multiplier
Type
integer
Description
If a storecard is scanned what the amount of points scanned should be multiplied by.
Name
subtract_multiplier
Type
integer
Description
If a storecard is scanned what the amount of points scanned should be multiplied by.

Request

POST

/devices

curl -X POST https://api.walletapp.co/devices
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"
-d '{
    "name": "<device_name>",
    "location_id": "<location_id>",
    "pin": "1234",
    "external_device_id": "<external_device_id>",
    "add_multiplier": 1,
    "subtract_multiplier": 1
}'

Response

    {
        "message": "Request successful",
        "data": {
            "name": "<device_name>",
            "identifier": "<uuid>",
            "external_device_id": "<external_device_id>",
            "add_multiplier": 1,
            "subtract_multiplier": 1,
            "pin": "1234",
            "location": {
                "identifier": "<uuid>",
                "address": "<address>"
            }
        }
    }

GET/devices/:identifier

Fetch a device

Fetch a specific device.

Required headers

Name
Authorization
Type
string
Description
The token itself as a bearer token.

Abilities

Name
devices.get
Type
string
Description
The scope required to access this endpoint.

Route parameters

Name
identifier
Type
string
Description
The identifier of the device.

Request

GET

/devices/:identifier

curl -X GET https://api.walletapp.co/devices/:identifier
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"

Response

    {
        "message": "Request successful",
        "data": {
            "name": "<device_name>",
            "identifier": "<uuid>",
            "external_device_id": "<external_device_id>",
            "add_multiplier": 1,
            "subtract_multiplier": 1,
            "pin": "1234",
            "location": {
                "identifier": "<uuid>",
                "address": "<address>"
            }
        }
    }

PUT/devices/:identifier

Update a device

This endpoint is used to update a device.

Required headers

Name
Authorization
Type
string
Description
The token itself as a bearer token.

Abilities

Name
devices.put
Type
string
Description
The scope required to access this endpoint.

Route parameters

Name
identifier
Type
string
Description
The identifier of the device.

Request body

Name
name
Type
string
Description
The name of the device.
Name
location_id
Type
string
Description
The location identifier.
Name
external_device_id
Type
string
Description
A unique identifier for the device.
Name
pin
Type
string|Required
Description
An authentication token used to sign in to the device.
Name
add_multiplier
Type
integer
Description
If a storecard is scanned what the amount of points scanned should be multiplied by.
Name
subtract_multiplier
Type
integer
Description
If a storecard is scanned what the amount of points scanned should be multiplied by.

Request

PUT

/devices/:identifier

curl -X PUT https://api.walletapp.co/devices/:identifier
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"
-d '{
    "name": "<device_name>",
    "location_id": "<location_id>",
    "pin": "1234",
    "external_device_id": "<external_device_id>",
    "add_multiplier": 1,
    "subtract_multiplier": 1
}'

Response

    {
        "message": "Request successful",
        "data": {
            "name": "<device_name>",
            "identifier": "<uuid>",
            "external_device_id": "<external_device_id>",
            "add_multiplier": 1,
            "subtract_multiplier": 1,
            "pin": "1234",
            "location": {
                "identifier": "<uuid>",
                "address": "<address>"
            }
        }
    }

DELETE/device/:identifier

Archive a device

Archive a specific device.

Required headers

Name
Authorization
Type
string
Description
The token itself as a bearer token.

Abilities

Name
devices.get
Type
string
Description
The scope required to access this endpoint.

Route parameters

Name
identifier
Type
string
Description
The identifier of the device.

Request

DELETE

/devices/:identifier

curl -X DELETE https://api.walletapp.co/devices/:identifier
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"

Response

{
    "message": "Request successful",
    "message": "Device deleted"
}

PATCH/devices/:identifier

Restore a device

Restore a specific device.

Required headers

Name
Authorization
Type
string
Description
The token itself as a bearer token.

Abilities

Name
devices.get
Type
string
Description
The scope required to access this endpoint.

Route parameters

Name
identifier
Type
string
Description
The identifier of the device.

Request

PATCH

/devices/:identifier

curl -X PATCH https://api.walletapp.co/devices/:identifier
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"

Response

{
    "message": "Request successful",
    "message": "Device restore"
}

GET/devices/scan/info

Pass info

Get the info of a barcode.

This API requires a Device Token. These tokens are generated in the dashboard by navigating to "Scanners" and clicking the key icon.

Required headers

Name
Authorization
Type
string
Description
The token itself as a bearer token.

Abilities

Name
scanners.get
Type
string
Description
The scope required to access this endpoint.

Query parameters

Name
code
Type
string
Description
The qr code on the pass

Response

Name
pass_identifier
Type
string
Description
The QR code of the pass.
Name
pass_type
Type
string
Description
The type of the pass: discount for coupons and promotions, payment for storecards and payment instruments.
Name
user_identifier
Type
string
Description
The identifier of the user that owns the pass.
Name
user_first_name
Type
string
Description
The first name of the user that owns the pass.
Name
pass_title
Type
string
Description
The title of the pass.
Name
pass_subtitle
Type
string
Description
The subtitle of the pass.
Name
reference
Type
string
Description
The reference provided by the third party vendor or integrator.

Request

GET

/devices/scan/info

curl -X GET https://api.walletapp.co/devices/scan/info?code=<code>
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"

Response - Coupon

    {
        "pass_identifier": "ABC123XYZ",
        "pass_type": "discount",
        "pass_installed": false,
        "user_identifier": "USR789",
        "user_first_name": "John Doe",
        "pass_title": "Free Coffee Coupon",
        "pass_subtitle": "Valid at all locations",
        "reference": "COUPON456"
    }

Response - Storecard

    {
        "pass_identifier": "DEF456UVW",
        "pass_type": "payment",
        "pass_installed": false,
        "user_identifier": "USR123",
        "user_first_name": "Jane Smith",
        "pass_title": "Store Credit Card",
        "pass_subtitle": "€25.00 balance",
        "reference": "CARD789"
    }

Response - Promotion Code

    {
        "pass_identifier": "WLNT-1234-5678-9012",
        "pass_type": "discount",
        "pass_installed": false,
        "user_identifier": "",
        "user_first_name": "",
        "pass_title": "20% Discount Promotion",
        "pass_subtitle": "Valid until end of month",
        "reference": "PROMO123-PERCENTAGE-100"
    }

Understanding Pass Types

The pass_type field in the response indicates how the scanned code should be processed by your system:

Discount Type (`discount`)

Used for promotional offers and coupons that reduce the transaction total.

Use Cases:

Coupons (e.g., "Free item", "20% off")
Promotion codes (format: WLNT-XXXX-XXXX-XXXX)
Discounts and offers

Implementation: Apply the scanned code as a discount/reduction on the current transaction. Use the reference field to map to your POS system's discount codes.

Payment Type (`payment`)

Used for payment instruments that have stored value, balance, or points.

Use Cases:

Storecards with balance
Loyalty cards with points
Gift cards
Prepaid cards

Implementation: Process the scanned code as a payment method. Deduct the transaction amount from the customer's balance or points. Use the reference field to identify the payment account.

Integration Tip: Always check the pass_type field and handle both types appropriately in your POS integration:

if (response.pass_type === 'discount') {
  applyDiscount(response.reference);
}
else if (response.pass_type === 'payment') {
  processPayment(response.reference);
}

POST/devices/scan

Redeem a pass

Redeem the pass for a location

This API requires a Device Token. These tokens are generated in the dashboard by navigating to "Scanners" and clicking the key icon.

Required headers

Name
Authorization
Type
string
Description
The token itself as a bearer token.

Abilities

Name
scanners.post
Type
string
Description
The scope required to access this endpoint.

Query parameters

Name
code
Type
string
Description
The qr code on the pass

Response

Name
pass_identifier
Type
string
Description
The QR code of the pass.
Name
pass_type
Type
string
Description
The type of the pass: discount for coupons and promotions, payment for storecards and payment instruments.
Name
user_identifier
Type
string
Description
The identifier of the user that owns the pass.
Name
user_first_name
Type
string
Description
The first name of the user that owns the pass.
Name
pass_title
Type
string
Description
The title of the pass.
Name
pass_subtitle
Type
string
Description
The subtitle of the pass.
Name
reference
Type
string
Description
The reference provided by the third party vendor or integrator.

Request

POST

/devices/scan

curl -X POST https://api.walletapp.co/devices/scan
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"
-d '{"code": "<code>"}'

Response - Coupon

    {
        "pass_identifier": "ABC123XYZ",
        "pass_type": "discount",
        "pass_installed": false,
        "user_identifier": "USR789",
        "user_first_name": "John Doe",
        "pass_title": "Free Coffee Coupon",
        "pass_subtitle": "Valid at all locations",
        "reference": "COUPON456"
    }

Response - Storecard

    {
        "pass_identifier": "DEF456UVW",
        "pass_type": "payment",
        "pass_installed": false,
        "user_identifier": "USR123",
        "user_first_name": "Jane Smith",
        "pass_title": "Store Credit Card",
        "pass_subtitle": "€25.00 balance",
        "reference": "CARD789"
    }

The pass is marked as redeemed after this endpoint is called. The response format is identical to /devices/scan/info, but the code can only be redeemed once.

Devices

Properties

Required headers

Abilities

Request

Response

Required headers

Abilities

Request body

Request

Response

Required headers

Abilities

Route parameters

Request

Response

Required headers

Abilities

Route parameters

Request body

Request

Response

Required headers

Abilities

Route parameters

Request

Response

Required headers

Abilities

Route parameters

Request

Response

Required headers

Abilities

Query parameters

Response

Request

Response - Coupon

Response - Storecard

Response - Promotion Code

Discount Type (discount)

Payment Type (payment)

Required headers

Abilities

Query parameters

Response

Request

Response - Coupon

Response - Storecard

Discount Type (`discount`)

Payment Type (`payment`)