Documentation API

API d'intégration réservée aux applications ILYGO : elles consomment ce service centralisé pour ouvrir des paiements, vérifier des licences et facturer leurs clients. ILYGO Pay n'est pas un service revendu à des tiers. API serveur-à-serveur (S2S) — spec machine : /api/openapi.

Authentification

Chaque app dispose d'un token ilypay_… (émis par un platform-admin, affiché une seule fois). Transmettez-le en Bearer :

Authorization: Bearer ilypay_xxxxxxxxxxxxxxxxxxxx

Le token porte l'identité de l'app (scoping azp) : une app ne peut agir que sur ses propres clients et licences.

Mode test

L'environnement UAT (https://api.pay.uat.ilygo.ch) est branché sur une clé Stripe de test. Utilisez un token d'app émis sur UAT et les cartes de test Stripe (ex. 4242 4242 4242 4242). Aucun débit réel. Passez en production en pointant la base sur l'environnement prod avec un token prod.

1 · Ouvrir un paiement

Crée une facture « à régler » rattachée à un payeur. Elle apparaît dans son portail ; il la règle lui-même (carte ou virement). Aucun débit immédiat.

curl -X POST https://api.pay.uat.ilygo.ch/v1/payments \
  -H "Authorization: Bearer $ILYPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_sub": "102f8bd8-…",
    "tenant": { "id": "<uuid>", "name": "Acme Sàrl" },
    "type": "oneshot",
    "amount": 4900,
    "currency": "chf",
    "title": "Plan Pro — licence annuelle",
    "locale": "fr",
    "collection_method": "card"
  }'
# → 201 { "license_id": "…", "status": "pending", "collection_method": "card" }

amount en centimes, TTC (la TVA suisse 8.1% est inclusive). collection_method: "bank_transfer" émet une facture payable par virement / QR-facture.

2 · Checkout immédiat (carte)

Ouvre + démarre une session Stripe Checkout et renvoie l'URL de redirection.

curl -X POST https://api.pay.uat.ilygo.ch/v1/checkout-sessions \
  -H "Authorization: Bearer $ILYPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant": { "id": "<uuid>", "name": "Acme Sàrl" },
    "license_id": "<uuid>",
    "type": "oneshot",
    "amount": 4900,
    "currency": "chf",
    "description": "Plan Pro",
    "return_url": "https://app.example.ch/retour"
  }'
# → 200 { "redirect_url": "https://checkout.stripe.com/…" }

3 · Vérifier une licence (gate-check)

À appeler au login pour autoriser une fonctionnalité (couplage minimal).

curl https://api.pay.uat.ilygo.ch/v1/licenses/<uuid> \
  -H "Authorization: Bearer $ILYPAY_TOKEN"
# → 200 { "id": "…", "status": "active", "type": "oneshot",
#         "current_period_end": null, "cancel_at_period_end": false }

403 si la licence n'appartient pas à l'app appelante.

4 · Vérification en lot & devis

Gate-check groupé (POST /v1/licenses/batch, jusqu'à 100 ids) et devis proforma B2B (POST /v1/quotes).

curl -X POST https://api.pay.uat.ilygo.ch/v1/licenses/batch \
  -H "Authorization: Bearer $ILYPAY_TOKEN" -H "Content-Type: application/json" \
  -d '{ "ids": ["<uuid>", "<uuid>"] }'
# → 200 { "licenses": [ { "id": "…", "status": "active", … } ] }

SDK

Clients officiels (dossier /sdk du dépôt) : TypeScript (@ilygo/pay), Python (ilygo_pay.py, stdlib) et Rust (ilygo-pay).

import { IlygoPay } from "@ilygo/pay";
const pay = new IlygoPay({ baseUrl: "https://api.pay.uat.ilygo.ch", token: process.env.ILYPAY_TOKEN! });
await pay.openPayment({ user_sub, tenant, type: "oneshot", amount: 4900, currency: "chf", title: "Plan Pro" });
const lic = await pay.getLicense(id);

Moyens de paiement

La Checkout utilise les moyens de paiement automatiques de Stripe : carte, et — lorsqu'ils sont activés sur le compte Stripe — TWINT et PostFinance en CHF. Le collection_method: "bank_transfer" émet une facture payable par virement. Le branding (logo, couleur) et les moyens locaux se configurent dans le Dashboard Stripe.

Codes d'erreur

Toutes les erreurs renvoient { "error": "…" } (et issues en cas de corps invalide). Statuts : 400 invalide, 401 auth,403 hors périmètre, 404 introuvable, 429 rate limit, 503 Stripe non configuré.