Hosted checkout

Hoe het werkt

POST /api/v1/checkouts maakt een sessie en geeft een url terug naar een door Cijfr gehoste checkout. De betaler kiest daar een betaalmethode, vult zijn factuurgegevens in en betaalt via jouw gekoppelde PSP. Daarna maakt Cijfr de factuur, mailt hem naar de betaler en stuurt invoice.paid en checkout.completed naar je webhooks.

Sessie aanmaken

POST /api/v1/checkouts vraagt checkouts:write en accepteert Idempotency-Key.

curl https://api.cijfr.com/api/v1/checkouts \
  -H "Authorization: Bearer $CIJFR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{
    "title": "Bestelling #1042",
    "redirectUrl": "https://shop.example.nl/bedankt",
    "customer": {"email": "sanne@korenaar.nl", "companyName": "Bakkerij De Korenaar"},
    "lines": [
      {"description": "Workshop broodbakken", "quantity": 2, "unitPriceCents": 4500}
    ]
  }'

{
  "data": {
    "id": "cs_…",
    "status": "open",
    "url": "https://invoice.cijfr.com/checkout/cs_…",
    "amountIncl": 10890,
    "expiresAt": "2026-03-04T12:00:00.000Z"
  }
}

Abonnementen

kind: "subscription" is een keuzelijst. De betaler ziet de opties, niet een vast bedrag. Dezelfde id op twee intervallen is één product. amountIncl in het antwoord is de prijs van de eerste optie, inclusief btw. De betaler betaalt de optie die hij bevestigt.

curl https://api.cijfr.com/api/v1/checkouts \
  -H "Authorization: Bearer $CIJFR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Lidmaatschap",
    "kind": "subscription",
    "allowDowngrade": true,
    "currentOptionId": "plus",
    "currentInterval": "month",
    "options": [
      {"id": "basis", "label": "Basis", "rank": 1, "interval": "month", "unitPriceCents": 900, "fulfillment": "service"},
      {"id": "plus", "label": "Plus", "rank": 2, "interval": "month", "unitPriceCents": 1900}
    ]
  }'

De pagina grijst de huidige optie uit. Een optie met een lagere rank, of een goedkoper interval van dezelfde optie, is ook grijs, tenzij allowDowngrade aan staat. Een downgrade of een gratis optie schrijft niets af. Cijfr stuurt dan checkout.completed met action downgrade of subscribe en amount 0. Een betaalde keuze factureert alleen de gekozen optie en stuurt checkout.completed met action pay, plus optionId als die er is.

Bij scheduleRenewal komt na de periode een nieuwe factuur. Die betaalt de klant zelf. Er is geen automatische incasso en geen opgeslagen mandaat.

Cijfr gebruikt dezelfde regels voor de eigen pakketten Start, Plus, Pro en Max. Het pakket dat je al betaalt, op hetzelfde interval, kun je niet nog eens kopen. Van Max naar Pro, of naar Start, is een downgrade: die gaat in aan het einde van de betaalde periode, zonder nieuwe afschrijving. Maand naar jaar is een upgrade en wordt afgerekend. Jaar naar maand is een downgrade. Een proefperiode is geen gekocht pakket: Start, Plus, Pro en Max blijven kiesbaar.

Producten, digitaal en diensten

Elke regel en elke abonnementsoptie kan fulfillment hebben: goods (product), digital of service (dienst). Zonder fulfillment blijft een vaste checkout zich gedragen zoals voorheen: requiresShipping bepaalt of je een adres vraagt.

Staan alle regels of opties expliciet op digital of service, dan vraagt de checkout geen verzendadres, ook als requiresShipping aan staat. Een gekozen abonnementsoptie die geen goods is, zet verzending uit op het moment van betalen. Op de factuur wordt digital en service als dienst geboekt, goods als product.

Sessies ophalen

GET /api/v1/checkouts vraagt checkouts:read en pagineert met ?limit= en ?cursor=. Elke sessie heeft id, kind, status, title, amountIncl, url, redirectUrl, expiresAt en createdAt. kind is fixed of subscription. Status is onder andere open, paid of expired.