Reseller Orders

These endpoints allow resellers to generate promotion codes that require payment (bijbetaling), check code status, and retrieve all codes associated with a customer email address or customer identifier.

POST/promotion/generate-payment-code

Generate payment code

Creates a promotion code that requires payment before activation. The payment amount is calculated based on the product price minus any scanner discount configured on the device.

Required headers

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

  • Name
    Authorization
    Type
    string
    Description

    Bearer token of the authenticated device.

Request body

  • Name
    organization_identifier
    Type
    string
    Description

    Identifier of the organization.

  • Name
    promotion_identifier
    Type
    string
    Description

    UUID of the promotion.

  • Name
    product_id
    Type
    integer
    Description

    ID of the product to be purchased.

  • Name
    location_id
    Type
    integer
    Description

    ID of the location where the code will be activated.

  • Name
    email
    Type
    email
    Description

    Customer email address. If provided, a user account will be created or linked. Either email or customer_identifier must be provided.

  • Name
    customer_identifier
    Type
    string
    Description

    Unique external identifier for the customer (e.g., loyalty ID, customer number). Used to track customers across channels without requiring an email address. Either email or customer_identifier must be provided.

Behavior

  • Validates the device, organization, and promotion
  • Calculates payment amount: price - (price * scanner_discount / 100)
  • Creates or links user account if email is provided
  • If customer_identifier is provided, creates or links external_user record for cross-channel tracking
  • Generates a unique promotion code with payment requirement
  • Creates Mollie payment directly and returns checkout URL for immediate payment
  • Stores external_user_id in promotion_codes table for customer_identifier lookups
  • Code expires in 91 days from creation

Request

POST
/promotion/generate-payment-code
curl -X POST "https://api.walletapp.co/promotion/generate-payment-code" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_identifier": "9jYwYpYhu1vWrWsSRlshURzf0a",
    "promotion_identifier": "1cfd74ec-d085-4d05-9b8f-e436c68132ef",
    "product_id": 5377,
    "location_id": 1,
    "email": "customer@example.com",
    "customer_identifier": "1444"
  }'

Response

{
  "success": true,
  "message": "Bijbetaling payment created successfully",
  "data": {
    "code": "WLNT-ABC-DEF-GHI2",
    "checkout_url": "https://www.mollie.com/payscreen/select-method/7UhSN1zuXS",
    "order_id": "BIJ-XKPNQW9T7L",
    "email": "customer@example.com",
    "customer_identifier": "1444",
    "user_id": 12345,
    "external_user_id": 789,
    "product": {
      "id": 5377,
      "title": "Premium Car Wash",
      "original_price": "25.00"
    },
    "location": {
      "id": 1,
      "title": "Main Street Location"
    },
    "bijbetaling": {
      "amount": "20.00",
      "discount_percentage": 20,
      "currency": "EUR"
    },
    "expiration_date": "2025-04-15 14:30:00"
  }
}
POST/promotion/check-code-status

Check code status

Retrieves the current status of a promotion code, including activation status, redemption status, payment status, and location information.

QR Code / Barcode Availability

The qr_image_url field is only included in the response when all of the following conditions are met:

  • Code is activated (status.activated = true)
  • Code is paid (status.paid = true OR no payment required)
  • Code is not redeemed (status.redeemed = false)

This ensures the code image is only shown when the code is ready to be scanned at a location.

QR vs Barcode

The URL returned can be either a QR code or a barcode, determined by the requesting device's configuration:

  • QR Code (default): For standard scanning devices, returns /qrcode/{code} route with the WLNT code
  • Barcode: For manual entry devices (response_type = 'manual'), returns /barcode/{value} where value is:
    • Product's cash_register_column if available
    • Device-promotion reference if configured
    • Falls back to the WLNT code if neither is set

Required headers

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

  • Name
    Authorization
    Type
    string
    Description

    Bearer token of the authenticated device.

Request body

  • Name
    organization_identifier
    Type
    string
    Description

    Identifier of the organization.

  • Name
    promotion_identifier
    Type
    string
    Description

    UUID of the promotion.

  • Name
    code
    Type
    string
    Description

    The promotion code to check (e.g., "WLNT-ABC-DEF-GHI2").

Response fields

  • status: Boolean flags for activated, redeemed, and paid
  • dates: Timestamps for creation, activation, redemption, and expiration
  • user: Email (if provided when creating code) and external_identifier (customer_identifier if provided when creating code)
  • redemption_location: Where the code was redeemed (if redeemed)
  • bijbetaling: Payment requirement details including amount and payment status
  • qr_image_url: QR code or barcode image URL (only included when code is activated, paid, and not redeemed). Returns QR or barcode based on device type.

Request

POST
/promotion/check-code-status
curl -X POST "https://api.walletapp.co/promotion/check-code-status" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_identifier": "9jYwYpYhu1vWrWsSRlshURzf0a",
    "promotion_identifier": "1cfd74ec-d085-4d05-9b8f-e436c68132ef",
    "code": "WLNT-ABC-DEF-GHI2"
  }'

Response - Code Ready for Redemption

{
  "success": true,
  "data": {
    "code": "WLNT-ABC-DEF-GHI2",
    "status": {
      "activated": true,
      "redeemed": false,
      "paid": true
    },
    "dates": {
      "created_at": "2025-01-15 10:30:00",
      "activation_date": "2025-01-15 11:00:00",
      "redeemed_at": null,
      "expiration_date": "2025-04-15 10:30:00"
    },
    "user": {
      "email": "customer@example.com",
      "external_identifier": null
    },
    "redemption_location": null,
    "qr_image_url": "https://api.walletapp.co/qrcode/WLNT-ABC-DEF-GHI2",
    "bijbetaling": {
      "required": true,
      "amount": "20.00",
      "paid": true,
      "paid_at": "2025-01-15 10:45:00"
    }
  }
}

Response - Code with Customer Identifier

{
  "success": true,
  "data": {
    "code": "WLNT-ABC-DEF-GHI2",
    "status": {
      "activated": true,
      "redeemed": false,
      "paid": true
    },
    "dates": {
      "created_at": "2025-01-15 10:30:00",
      "activation_date": "2025-01-15 11:00:00",
      "redeemed_at": null,
      "expiration_date": "2025-04-15 10:30:00"
    },
    "user": {
      "email": null,
      "external_identifier": "1444"
    },
    "redemption_location": null,
    "qr_image_url": "https://api.walletapp.co/qrcode/WLNT-ABC-DEF-GHI2",
    "bijbetaling": {
      "required": true,
      "amount": "20.00",
      "paid": true,
      "paid_at": "2025-01-15 10:45:00"
    }
  }
}

Response - Code Not Ready (Not Paid)

{
  "success": true,
  "data": {
    "code": "WLNT-XYZ-789-DEF3",
    "status": {
      "activated": true,
      "redeemed": false,
      "paid": false
    },
    "dates": {
      "created_at": "2025-01-15 10:30:00",
      "activation_date": "2025-01-15 11:00:00",
      "redeemed_at": null,
      "expiration_date": "2025-04-15 10:30:00"
    },
    "user": {
      "email": "customer@example.com",
      "external_identifier": null
    },
    "redemption_location": null,
    "bijbetaling": {
      "required": true,
      "amount": "20.00",
      "paid": false,
      "paid_at": null
    }
  }
}

Response - Barcode for Manual Device

{
  "success": true,
  "data": {
    "code": "WLNT-ABC-DEF-GHI2",
    "status": {
      "activated": true,
      "redeemed": false,
      "paid": true
    },
    "dates": {
      "created_at": "2025-01-15 10:30:00",
      "activation_date": "2025-01-15 11:00:00",
      "redeemed_at": null,
      "expiration_date": "2025-04-15 10:30:00"
    },
    "user": {
      "email": "customer@example.com",
      "external_identifier": null
    },
    "redemption_location": null,
    "qr_image_url": "https://api.walletapp.co/barcode/12345",
    "bijbetaling": {
      "required": true,
      "amount": "20.00",
      "paid": true,
      "paid_at": "2025-01-15 10:45:00"
    }
  }
}

Response - Code Already Redeemed

{
  "success": true,
  "data": {
    "code": "WLNT-ABC-123-XYZ9",
    "status": {
      "activated": true,
      "redeemed": true,
      "paid": true
    },
    "dates": {
      "created_at": "2025-01-10 09:00:00",
      "activation_date": "2025-01-10 09:30:00",
      "redeemed_at": "2025-01-12 14:20:00",
      "expiration_date": "2025-04-10 09:00:00"
    },
    "user": {
      "email": "customer@example.com",
      "external_identifier": null
    },
    "redemption_location": {
      "id": 5,
      "title": "Downtown Location",
      "address": "456 Main St, City"
    },
    "bijbetaling": {
      "required": true,
      "amount": "20.00",
      "paid": true,
      "paid_at": "2025-01-10 09:15:00"
    }
  }
}
POST/promotion/codes-by-email

Get user codes by email

Retrieves all promotion codes associated with an email address for a specific promotion, including their status, dates, locations, and payment information.

Required headers

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

  • Name
    Authorization
    Type
    string
    Description

    Bearer token of the authenticated device.

Request body

  • Name
    organization_identifier
    Type
    string
    Description

    Identifier of the organization.

  • Name
    promotion_identifier
    Type
    string
    Description

    UUID of the promotion.

  • Name
    email
    Type
    email
    Description

    Customer email address to search for.

Response fields

For each code found:

  • code: The promotion code string
  • status: Activation, redemption, and payment status
  • dates: All relevant timestamps
  • locations: Both activation and redemption locations (with address)
  • product: Product details if linked
  • bijbetaling: Payment requirement and status

Request

POST
/promotion/codes-by-email
curl -X POST "https://api.walletapp.co/promotion/codes-by-email" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_identifier": "9jYwYpYhu1vWrWsSRlshURzf0a",
    "promotion_identifier": "1cfd74ec-d085-4d05-9b8f-e436c68132ef",
    "email": "customer@example.com"
  }'

Response

{
  "success": true,
  "message": "Codes retrieved successfully",
  "data": {
    "email": "customer@example.com",
    "total_codes": 3,
    "codes": [
      {
        "code": "WLNT-ABC-DEF-GHI2",
        "status": {
          "activated": true,
          "redeemed": true,
          "paid": true
        },
        "dates": {
          "created_at": "2025-01-15 10:30:00",
          "activation_date": "2025-01-15 11:00:00",
          "redeemed_at": "2025-01-16 14:20:00",
          "expiration_date": "2025-04-15 10:30:00"
        },
        "locations": {
          "activation_location": {
            "id": 1,
            "title": "Main Street Location",
            "address": "123 Main St, City"
          },
          "redemption_location": {
            "id": 2,
            "title": "Downtown Location",
            "address": "456 Downtown Ave, City"
          }
        },
        "product": {
          "id": 5377,
          "title": "Premium Car Wash",
          "price": "25.00"
        },
        "bijbetaling": {
          "required": true,
          "amount": "20.00",
          "paid": true,
          "paid_at": "2025-01-15 10:45:00"
        }
      },
      {
        "code": "WLNT-XYZ-123-ABC7",
        "status": {
          "activated": false,
          "redeemed": false,
          "paid": false
        },
        "dates": {
          "created_at": "2025-01-20 09:15:00",
          "activation_date": null,
          "redeemed_at": null,
          "expiration_date": "2025-04-20 09:15:00"
        },
        "locations": {
          "activation_location": null,
          "redemption_location": null
        },
        "product": {
          "id": 5378,
          "title": "Basic Wash",
          "price": "15.00"
        },
        "bijbetaling": {
          "required": true,
          "amount": "12.00",
          "paid": false,
          "paid_at": null
        }
      }
    ]
  }
}
POST/promotion/codes-by-customer-identifier

Get user codes by customer identifier

Retrieves all promotion codes associated with a customer identifier for a specific promotion. This endpoint is useful for looking up codes for customers who don't have email addresses but are tracked via external identifiers (e.g., loyalty IDs, customer numbers).

Required headers

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

  • Name
    Authorization
    Type
    string
    Description

    Bearer token of the authenticated device.

Request body

  • Name
    organization_identifier
    Type
    string
    Description

    Identifier of the organization.

  • Name
    promotion_identifier
    Type
    string
    Description

    UUID of the promotion.

  • Name
    customer_identifier
    Type
    string
    Description

    Customer identifier to search for (e.g., loyalty ID, customer number).

Response fields

For each code found:

  • code: The promotion code string
  • status: Activation, redemption, and payment status
  • dates: All relevant timestamps
  • locations: Both activation and redemption locations (with address)
  • product: Product details if linked
  • bijbetaling: Payment requirement and status

Behavior

  • Searches for external_user by customer_identifier and device channel
  • Returns all codes associated with that external user for the specified promotion
  • Returns empty array if no external user or codes are found

Request

POST
/promotion/codes-by-customer-identifier
curl -X POST "https://api.walletapp.co/promotion/codes-by-customer-identifier" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_identifier": "9jYwYpYhu1vWrWsSRlshURzf0a",
    "promotion_identifier": "1cfd74ec-d085-4d05-9b8f-e436c68132ef",
    "customer_identifier": "1444"
  }'

Response

{
  "success": true,
  "message": "Codes retrieved successfully",
  "data": {
    "customer_identifier": "1444",
    "total_codes": 2,
    "codes": [
      {
        "code": "WLNT-ABC-DEF-GHI2",
        "status": {
          "activated": true,
          "redeemed": true,
          "paid": true
        },
        "dates": {
          "created_at": "2025-01-15 10:30:00",
          "activation_date": "2025-01-15 11:00:00",
          "redeemed_at": "2025-01-16 14:20:00",
          "expiration_date": "2025-04-15 10:30:00"
        },
        "locations": {
          "activation_location": {
            "id": 1,
            "title": "Main Street Location",
            "address": "123 Main St, City"
          },
          "redemption_location": {
            "id": 2,
            "title": "Downtown Location",
            "address": "456 Downtown Ave, City"
          }
        },
        "product": {
          "id": 5377,
          "title": "Premium Car Wash",
          "price": "25.00"
        },
        "bijbetaling": {
          "required": true,
          "amount": "20.00",
          "paid": true,
          "paid_at": "2025-01-15 10:45:00"
        }
      },
      {
        "code": "WLNT-XYZ-123-ABC7",
        "status": {
          "activated": false,
          "redeemed": false,
          "paid": false
        },
        "dates": {
          "created_at": "2025-01-20 09:15:00",
          "activation_date": null,
          "redeemed_at": null,
          "expiration_date": "2025-04-20 09:15:00"
        },
        "locations": {
          "activation_location": null,
          "redemption_location": null
        },
        "product": {
          "id": 5378,
          "title": "Basic Wash",
          "price": "15.00"
        },
        "bijbetaling": {
          "required": true,
          "amount": "12.00",
          "paid": false,
          "paid_at": null
        }
      }
    ]
  }
}

Response - No Codes Found

{
  "success": true,
  "message": "No codes found for this customer identifier",
  "data": {
    "customer_identifier": "1444",
    "total_codes": 0,
    "codes": []
  }
}