Kiosk & self-service

Ridley is intentionally narrow: it accepts an amount, shows a checkout page, processes the card, and sends a webhook. It knows nothing about lockers, vending machines or hardware. Your kiosk software owns that.

Flow

Customer arrives
   → Kiosk identifies what they're paying for (scan, code, selection)
   → Kiosk backend calls POST /v1/sessions
   → Ridley returns checkout_url
   → Customer pays (QR to their phone, or on the kiosk screen)
   → Webhook POSTs to your backend
   → Kiosk triggers the action (unlock, dispense, print)

Create the session

curl https://api.ridleypay.com/v1/sessions \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: PKG-20260508-001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1500.00,
    "reference": "PKG-20260508-001",
    "currency": "JMD",
    "description": "Package pickup: Locker A-12",
    "success_url": "https://kiosk.example.com/success?ref=PKG-20260508-001",
    "cancel_url": "https://kiosk.example.com/?cancelled=1"
  }'

Then either show a QR code containing the checkout_url (customer pays on their phone) or navigate the kiosk browser to it (customer pays on screen).

Trigger the action from the webhook

Handle payment.completed, verify the X-Webhook-Signature, dedupe on the event ID, then act. See Webhooks.

A full reference implementation lives in the Kiosk Integration Guide in the repository.