Quickstart

This guide walks you through the CheckYout Partner API integration in five minutes. By the end you receive checkout events and can trigger WhatsApp notifications.

1. Generate an API key

In the CheckYout dashboard, go to Settings → API keys and create a new key. Keys look like cyo_xxxxxxxxxxxx.

Important

The API key is shown in clear text only once. Store it in a secure environment variable right away.

2. Set your webhook URL

When you create the API key (or later via API), set the URL of your webhook endpoint. CheckYout sends a POST request to that URL on every guest check-out.

Optionally set a webhook secret. CheckYout then signs every event with HMAC-SHA256. See Authentication for details.

3. Build the webhook endpoint

Create an HTTP endpoint in your software that accepts POST requests from CheckYout:

// Express.js — receive a webhook
app.post('/webhooks/checkyout', (req, res) => {
  const event = req.body;

  console.log('Checkout event received:', event);
  // { event: "checkout", device_id: "...", property_name: "...", ... }

  // Your logic: create a cleaning task, etc.

  res.status(200).json({ received: true });
});

4. Call the Notify API

Once you have processed the check-out, use the Notify API to send a WhatsApp message to the assigned cleaner:

curl -X POST https://checkyout.app/api/v1/notify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cyo_YourApiKey" \
  -d '{
    "device_id": "your-device-uuid",
    "phone": "+41791234567",
    "name": "Alpenblick Vacation Rental"
  }'

const response = await fetch('https://checkyout.app/api/v1/notify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.CHECKYOUT_API_KEY,
  },
  body: JSON.stringify({
    device_id: 'your-device-uuid',
    phone: '+41791234567',
    name: 'Alpenblick Vacation Rental',
  }),
});

const data = await response.json();
console.log(data); // { success: true, message_sid: "SM..." }

import requests

response = requests.post(
    "https://checkyout.app/api/v1/notify",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": CHECKYOUT_API_KEY,
    },
    json={
        "device_id": "your-device-uuid",
        "phone": "+41791234567",
        "name": "Alpenblick Vacation Rental",
    },
)

print(response.json())  # {"success": True, "message_sid": "SM..."}

$ch = curl_init('https://checkyout.app/api/v1/notify');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: ' . getenv('CHECKYOUT_API_KEY'),
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'device_id' => 'your-device-uuid',
        'phone' => '+41791234567',
        'name' => 'Alpenblick Vacation Rental',
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);
echo $response; // {"success":true,"message_sid":"SM..."}

5. Test

Trigger a test check-out from the CheckYout dashboard. Your webhook endpoint should receive and process the event.

Tip

During development, expose your local endpoint to CheckYout via a tunnel service like ngrok.

Full example

A complete Node.js/Express example that receives webhooks, verifies the signature and calls the Notify API:

server.js

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.CHECKYOUT_WEBHOOK_SECRET;
const API_KEY = process.env.CHECKYOUT_API_KEY;

// Receive the webhook and verify the signature
app.post('/webhooks/checkyout', (req, res) => {
  const signature = req.headers['x-checkyout-signature'];

  if (WEBHOOK_SECRET && signature) {
    const expected = crypto
      .createHmac('sha256', WEBHOOK_SECRET)
      .update(JSON.stringify(req.body))
      .digest('hex');

    if (!crypto.timingSafeEqual(
      Buffer.from(expected, 'hex'),
      Buffer.from(signature, 'hex')
    )) {
      return res.status(401).json({ error: 'Invalid signature' });
    }
  }

  const { event, device_id, property_name } = req.body;
  console.log(`Event: ${event}, Property: ${property_name}`);

  // Example: notify the cleaner
  if (event === 'checkout') {
    notifyCleaner(device_id, property_name);
  }

  res.status(200).json({ received: true });
});

async function notifyCleaner(deviceId, propertyName) {
  const cleanerPhone = await getCleanerPhone(propertyName); // your logic

  await fetch('https://checkyout.app/api/v1/notify', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY,
    },
    body: JSON.stringify({
      device_id: deviceId,
      phone: cleanerPhone,
      name: propertyName,
    }),
  });
}

app.listen(3000, () => console.log('Listening on :3000'));

Next: Authentication in detail