This guide walks you through creating your first tip via the Aplauso API using the sandbox environment - no real money involved.

Prerequisites

  • An Aplauso account (sign up at auth.aplauso.io)
  • A property and at least one employee set up (see the Setup Checklist)
  • A REST client (curl, Postman, Insomnia, or fetch in Node.js)
  • Firebase project access (or an existing ID token)

Step 1 - Get a Firebase ID Token

Sign in to the Firebase project and get your ID token. The easiest way during development is to use the Firebase client SDK in a short script:

import { initializeApp } from "firebase/app";
import { getAuth, signInWithEmailAndPassword } from "firebase/auth";

const app = initializeApp({ /* your firebaseConfig */ });
const auth = getAuth(app);

const { user } = await signInWithEmailAndPassword(auth, "you@example.com", "yourpassword");
const token = await user.getIdToken();
console.log(token);  // Copy this for the next steps

Or retrieve your token from my.aplauso.io by opening browser DevTools > Application > IndexedDB > firebaseLocalStorage and finding the idToken value in the stored auth data.

Step 2 - Look Up Your Employee ID

curl "https://us-central1-aplauso-f0501.cloudfunctions.net/api/v2/employees?me=true&environment=sandbox" \
  -H "Authorization: Bearer YOUR_ID_TOKEN"

Response:

{
  "employee": {
    "employeeId": "emp_xxxxxxxxxxx",
    "firstName": "Your",
    "lastName": "Name",
    "shortCode": "YOU123",
    "propertyId": "prop_yyy",
    "status": 10
  }
}

Copy the employeeId - you will need it in the next step.

Step 3 - Create a Tip in Sandbox

curl -X POST "https://us-central1-aplauso-f0501.cloudfunctions.net/api/v2/tips" \
  -H "Content-Type: application/json" \
  -d '{
    "employeeId": "emp_xxxxxxxxxxx",
    "amount": 10.00,
    "paymentMethod": "card",
    "source": "api",
    "environment": "sandbox"
  }'

Response:

{
  "success": true,
  "tipId": "tip_zzzzzzzzzzz",
  "disbursement": {
    "primaryEmployee": {
      "employeeId": "emp_xxxxxxxxxxx",
      "amount": 8.20,
      "currency": "USD"
    },
    "total": 8.20
  },
  "fees": {
    "paymentProcessing": 1.50,
    "fixedFee": 0.30,
    "total": 1.80
  }
}

The tip is created in status 5 (Pending). To simulate payment completion:

Step 4 - Mark the Tip as Paid

curl -X PATCH "https://us-central1-aplauso-f0501.cloudfunctions.net/api/v2/tips" \
  -H "Content-Type: application/json" \
  -d '{
    "tipId": "tip_zzzzzzzzzzz",
    "status": 20,
    "paymentTransaction": {
      "transactionId": "pi_test_fake_id",
      "amount": 10.00,
      "currency": "USD",
      "status": "succeeded",
      "processor": "stripe",
      "method": "card"
    },
    "createDividends": true,
    "environment": "sandbox"
  }'

This transitions the tip to status 20 (Paid) and creates dividend records. In a real kiosk integration, Stripe's webhook does this step automatically.

Step 5 - Verify the Result

Check the tip status:

curl "https://us-central1-aplauso-f0501.cloudfunctions.net/api/v2/tips?employeeId=emp_xxxxxxxxxxx&environment=sandbox" \
  -H "Authorization: Bearer YOUR_ID_TOKEN"

Check the employee's sandbox wallet:

curl "https://us-central1-aplauso-f0501.cloudfunctions.net/api/v2/wallet?environment=sandbox" \
  -H "Authorization: Bearer YOUR_ID_TOKEN"

Check the dividends:

curl "https://us-central1-aplauso-f0501.cloudfunctions.net/api/v2/dividends?tipId=tip_zzzzzzzzzzz&environment=sandbox" \
  -H "Authorization: Bearer YOUR_ID_TOKEN"

You should see:

  • Tip with status: 20
  • Wallet pendingBalance increased by the tip disbursement amount
  • One dividend record with status: 10 (pending payout)

Combining Tips with Ratings

To create a rating at the same time as a tip (mimicking the full kiosk flow):

curl -X POST "https://us-central1-aplauso-f0501.cloudfunctions.net/api/v2/ratings" \
  -H "Content-Type: application/json" \
  -d '{
    "employeeId": "emp_xxxxxxxxxxx",
    "value": 5,
    "tipId": "tip_zzzzzzzzzzz",
    "source": "api",
    "environment": "sandbox"
  }'

Next Steps