Liens de paiement

Lorsqu'un espace de travail atteint ses quotas ou demande une fonctionnalité réservée à un plan supérieur, vous pouvez générer par l'API un lien de paiement hébergé qui mène directement à l'écran de règlement. C'est le chemin de conversion standard : un espace en plan Free appelle POST /v1/billing/checkout-link, reçoit une URL Stripe Checkout prête à l'emploi, et l'ouvre dans son navigateur pour souscrire Pro ou Ultra. Cette page couvre la création du lien de paiement et la gestion de l'adresse de facturation (raison sociale, numéro de TVA, pays) associée à l'espace.

Générer un lien de paiement

L'endpoint crée une session Stripe Checkout en mode hébergé et renvoie une URL directement cliquable. Vous précisez le plan visé et, en option, la périodicité (monthly par défaut, ou annual pour la facturation annuelle). Le plan Pro ouvre automatiquement un essai de 14 jours ; Ultra est souscrit sans essai. La page de règlement est présentée en français et accepte les codes promotionnels.

Corps de la requête. Seul plan est obligatoire :

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const link = await coffrify.billing.createCheckoutLink({
  plan: 'pro',
  cycle: 'annual',
  return_url: 'https://app.exemple.fr/abonnement/retour',
});
 
console.log(link.url);        // URL Stripe Checkout à ouvrir
console.log(link.session_id); // identifiant de session
console.log(link.expires_at); // expiration de la session

Réponse. Ouvrez url dans le navigateur de l'utilisateur pour qu'il finalise son paiement :

{
  "url": "https://checkout.stripe.com/c/pay/cs_live_...",
  "session_id": "cs_live_a1b2c3...",
  "plan": "pro",
  "cycle": "annual",
  "customer_id": "cus_...",
  "expires_at": "2026-06-11T09:30:00.000Z"
}

Cas d'usage : faire payer un upgrade

Le scénario type consiste à proposer la montée en gamme quand l'espace approche d'une limite. Interrogez d'abord les quotas, puis, si la consommation est trop élevée, présentez le lien de paiement. Cet enchaînement transforme un blocage de quota en parcours d'abonnement fluide :

// 1. Vérifier l'état des quotas
const q = await coffrify.quotas.check();
 
if (q.over_quota.storage || q.consumption.storage_pct > 90) {
  // 2. Générer le lien de paiement vers Pro (annuel)
  const link = await coffrify.billing.createCheckoutLink({
    plan: 'pro',
    cycle: 'annual',
  });
 
  // 3. Rediriger l'utilisateur vers le règlement
  return Response.redirect(link.url, 303);
}

Adresse de facturation

Chaque espace de travail dispose d'une adresse de facturation qui alimente les factures et la TVA intracommunautaire. Vous la lisez avec GET /v1/billing/address et vous la mettez à jour avec PATCH /v1/billing/address. Renseigner ces informations avant de générer un lien de paiement garantit des factures correctes dès la première échéance.

Lecture puis mise à jour. La réponse encapsule l'adresse sous la clé address ; elle vaut null tant qu'aucune adresse n'a été enregistrée. Le premier PATCH la crée, les suivants la modifient. Pour vider un champ, passez une chaîne vide ou null :

// Lire l'adresse actuelle (null si non renseignée)
const { address } = await coffrify.billing.getAddress();
 
// Créer ou mettre à jour les champs souhaités
const updated = await coffrify.billing.updateAddress({
  company_name: 'Exemple SAS',
  vat_id: 'FR12345678901',
  tax_country: 'FR',
  address_line1: '10 rue de la Paix',
  city: 'Paris',
  postal_code: '75002',
  country: 'FR',
  billing_email: 'compta@exemple.fr',
});
 
console.log(updated.address);

Exemple de réponse après mise à jour :

{
  "address": {
    "company_name": "Exemple SAS",
    "vat_id": "FR12345678901",
    "tax_country": "FR",
    "address_line1": "10 rue de la Paix",
    "address_line2": null,
    "city": "Paris",
    "postal_code": "75002",
    "country": "FR",
    "billing_email": "compta@exemple.fr",
    "updated_at": "2026-06-10T09:30:00.000Z"
  }
}