Quick Start Guide

Get up and running with Payylo in a few minutes. This guide walks you through creating your first group payment split across multiple slots — using the REST API directly, so you can integrate from any language or stack.

Prerequisites

• A Payylo merchant account
• A secret API key (from your dashboard)
• curl or any HTTP client

Every endpoint, parameter and response is documented in the interactive API Reference  — you can fire real requests from the browser there.

Test vs live mode

There’s a single base URL — https://api.payylo.com — for everything. Whether a request runs in test or live mode is decided by your API key, not by a different URL:

Start with a sk_test_… key (created on a sandbox account in your dashboard). When you’re ready to go live, switch to a sk_live_… key — nothing else in your integration changes.

Get your API key

1. Log in to your Payylo Dashboard 
2. Go to Integration → API Keys
3. Copy your Secret Key (sk_test_… for sandbox, sk_live_… for live)

PAYYLO_SECRET_KEY=sk_test_your_secret_key

Keep your secret key server-side. Never expose it in client-side code.

Create a group payment

Amounts are in currency units (e.g. 150.00), not cents. Slots are created automatically from the distribution — either split equally across N slots, or custom amounts per slot. expires_at must be in the future (≤ 7 days out).

curl https://api.payylo.com/v1/group-payments \
  -H "Authorization: Bearer $PAYYLO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "group_name": "Team Dinner",
    "total_amount": 150.00,
    "currency": "EUR",
    "expires_at": "2026-06-21T18:00:00Z",
    "distribution": { "type": "equally", "number_of_slots": 3 }
  }'

Add an Idempotency-Key header to make POSTs safe to retry — replays return the stored response instead of creating a second group payment.

For explicit amounts use a custom distribution (slot amounts must sum to the total):

{
  "distribution": {
    "type": "custom",
    "slots": [
      { "amount": 100.0, "metadata": { "participant": "Alice" } },
      { "amount": 50.0, "metadata": { "participant": "Bob" } }
    ]
  }
}

Understand the response

{
  "group_payment": {
    "id": "eda0165c-7c2f-4b1e-9a3d-1f2e3d4c5b6a",
    "group_name": "Team Dinner",
    "merchant_order_id": "…",
    "total_amount": 150.0,
    "currency": "EUR",
    "state": "open",
    "expires_at": "2026-06-21T18:00:00Z",
    "metadata": {},
    "created_at": "2026-06-20T18:00:00Z",
    "updated_at": "2026-06-20T18:00:00Z"
  },
  "payment_slots": [
    {
      "id": "…",
      "sequence_no": 1,
      "amount": 50.0,
      "currency": "EUR",
      "state": "unassigned"
    },
    {
      "id": "…",
      "sequence_no": 2,
      "amount": 50.0,
      "currency": "EUR",
      "state": "unassigned"
    },
    {
      "id": "…",
      "sequence_no": 3,
      "amount": 50.0,
      "currency": "EUR",
      "state": "unassigned"
    }
  ],
  "checkout_url": "https://checkout.payylo.com/g/eda0165c-…"
}

Share the checkout URL

Send checkout_url to participants. Each can open it to pick and pay their slot(s). To read or reconcile later:

# Retrieve one group payment
curl https://api.payylo.com/v1/group-payments/eda0165c-… \
  -H "Authorization: Bearer $PAYYLO_SECRET_KEY"
 
# List, with filters + pagination
curl "https://api.payylo.com/v1/group-payments?state=paid&limit=20" \
  -H "Authorization: Bearer $PAYYLO_SECRET_KEY"
# → { "group_payments": [...], "pagination": { "limit", "offset", "total", "has_more" } }

Test with sandbox cards

In sandbox, use the test card for your connected provider:

Receive webhooks

Register an endpoint to be notified when payments complete or are refunded — no polling required:

curl https://api.payylo.com/v1/webhooks \
  -H "Authorization: Bearer $PAYYLO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/payylo-webhook",
    "event_types": ["group_payment.paid", "group_payment.refunded"]
  }'
# Response includes "secret": "whsec_…" — store it now, shown only once.

See the Webhooks guide for event types and signature verification.

Next Steps

🎉 You’ve created your first group payment.

• API Reference  — interactive Swagger UI: every endpoint, try it live
• Embedded Checkout — drop the white-label widget into your site
• Payment Flow — the end-to-end process
• Authentication — API keys and security
• Webhooks — real-time events and signature verification

Need help? Contact support .

Common Issues

Invalid API key

Use the right key for your environment (sk_test_… sandbox vs sk_live_… live).

Slot amounts don’t sum to the total

For a custom distribution the slot amounts must equal total_amount:

• ✅ total_amount: 150.00, slots sum to 150.00
• ❌ total_amount: 150.00, slots sum to 120.00

Expiry rejected

expires_at must be in the future and at most 7 days out.