Chorus Pay

Commandes

Créez et gérez des commandes pour générer des devis et permettre aux organismes publics de les accepter en ligne. Dans l'API, une commande est représentée par la ressource pay_link(endpoints /v1/pay-links, nom historique conservé pour la stabilité de l'API).

Créer une commande

POST/v1/pay-links

Créer une nouvelle commande avec son devis associé

✨ Client info optionnel : Si vous ne fournissez pas les informations client, le SIRET sera demandé au client lors du checkout. Si vous les fournissez, le checkout commencera directement à l'étape du devis.

🔍 Vérification Chorus Pro : Si un SIRET est fourni et que vous avez configuré l'intégration Chorus Pro, le SIRET sera automatiquement vérifié sur Chorus Pro. La structure doit être active, sinon la création sera bloquée avec un message d'erreur.

💡 En mode test, cette vérification est désactivée pour faciliter les tests.

Paramètres

descriptionrequis

Description du devis (string, 1-500 caractères)

client_infooptionnel

Informations du client (object). Si non fourni, le SIRET sera demandé au checkout.

  • • siret : Numéro SIRET (string 14 caractères, optionnel)
  • • name : Nom de l'organisme publique (string, requis si SIRET fourni, sinon optionnel)
  • • address : Adresse complète (string, requis si SIRET fourni, sinon optionnel)
  • • postal_code : Code postal (string, 5 chiffres, optionnel). Recommandé : utilisé tel quel par les connecteurs ERP pour la fiche client, sans parsing de l'adresse.
  • • city : Ville (string, optionnel). Recommandé, même usage que postal_code.
  • • email : Email de contact (string, optionnel). Sert de pré-remplissage au checkout, où le client peut le modifier et doit le confirmer.
  • • email_verified : (boolean, optionnel, défaut false). Passez true UNIQUEMENT si vous garantissez que le client contrôle cette adresse (votre propre flux d'authentification) : le champ email est alors verrouillé au checkout, sans étape de confirmation ni renvoi du devis.

⚠️ Si un SIRET est fourni, name et address deviennent obligatoires

Note : indépendamment de ce flag, les liens contenus dans les emails de devis envoyés par Chorus Pay portent un jeton de preuve - un client qui ouvre le lien depuis l'email reçu voit aussi son adresse confirmée automatiquement.

itemsrequis

Lignes du devis (array, min 1 item)

  • • description : Description de la ligne (string, requis)
  • • quantity : Quantité (number > 0, requis)
  • • unit_price : Prix unitaire HT (number > 0, requis, 4 décimales max)
  • • vat_rate : Taux de TVA en % (number 0-100, optionnel, défaut: 20)
discount_htoptionnel

Remise globale HT (number ≥ 0). Affichée comme ligne « Remise » sur le devis et ventilée au prorata des lignes lors du dépôt Chorus Pro.

metadataoptionnel

Données personnalisées (object, max 50 clés)

terms_template_idoptionnel

ID du modèle de conditions (number) à afficher lors de l'engagement. Si non fourni, le modèle par défaut pour les commandes est utilisé.

endpage_urloptionnel

URL de redirection après validation du devis par le client (string, URL valide, max 500 caractères). Le client est automatiquement redirigé vers cette URL quelques secondes après avoir accepté le devis. Si non fourni, la valeur configurée dans vos paramètres fournisseur est utilisée.

Request avec client_info
JSON
{
  "description": "Élection représentants parents 2025",
  "client_info": {
    "name": "Mairie de Saint-Cloud",
    "siret": "21092064000016",
    "email": "finances@saintcloud.fr",
    "address": "8 Place Charles de Gaulle, 92210 Saint-Cloud",
    "postal_code": "92210",
    "city": "Saint-Cloud"
  },
  "items": [
    {
      "description": "Licence plateforme",
      "quantity": 1,
      "unit_price": 16.67,
      "vat_rate": 20
    },
    {
      "description": "Classes (7x)",
      "quantity": 7,
      "unit_price": 5.00,
      "vat_rate": 20
    }
  ],
  "metadata": {
    "internal_ref": "REF-2025-001",
    "department": "Education"
  }
}
Request sans client_info (SIRET demandé au checkout)
JSON
{
  "description": "Élection représentants parents 2025",
  "items": [
    {
      "description": "Licence plateforme",
      "quantity": 1,
      "unit_price": 16.67,
      "vat_rate": 20
    },
    {
      "description": "Classes (7x)",
      "quantity": 7,
      "unit_price": 5.00,
      "vat_rate": 20
    }
  ],
  "metadata": {
    "internal_ref": "REF-2025-001",
    "department": "Education"
  }
}
Request en mode test
JSON
{
  "description": "Élection représentants parents 2025",
  "client_info": {
    "name": "Mairie de Saint-Cloud",
    "siret": "21092064000016",
    "email": "finances@saintcloud.fr",
    "address": "8 Place Charles de Gaulle, 92210 Saint-Cloud"
  },
  "items": [
    {
      "description": "Licence plateforme",
      "quantity": 1,
      "unit_price": 16.67,
      "vat_rate": 20
    }
  ]
}
Response (201 Created)
JSON
{
  "id": "pl_a1b2c3d4e5f6",
  "status": "draft",
  "amount": 62.01,
  "amount_ht": 51.67,
  "quote_number": "2025-001",
  "url": "https://choruspay.fr/link/pl_a1b2c3d4e5f6",
  "description": "Élection représentants parents 2025",
  "client": {
    "name": "Mairie de Saint-Cloud",
    "siret": "21092064000016",
    "email": "finances@saintcloud.fr",
    "address": "8 Place Charles de Gaulle, 92210 Saint-Cloud"
  },
  "items": [
    {
      "description": "Licence plateforme",
      "quantity": 1,
      "unit_price": 16.67,
      "vat_rate": 20,
      "total": 16.67
    },
    {
      "description": "Classes (7x)",
      "quantity": 7,
      "unit_price": 5.0,
      "vat_rate": 20,
      "total": 35.0
    }
  ],
  "metadata": {
    "internal_ref": "REF-2025-001",
    "department": "Education"
  },
  "endpage_url": null,
  "chorus_config": {
    "idStructureCPP": 26346724,
    "parametres": {
      "numeroEJDoitEtreRenseigne": false,
      "codeServiceDoitEtreRenseigne": false,
      "gestionNumeroEJOuCodeService": false
    },
    "informationGenerales": {
      "raisonSocialeStructure": "Mairie de Saint-Cloud",
      "identifiantStructure": "21092064000016"
    },
    "servicesActifs": [
      {
        "idService": 10693219,
        "codeService": "FACTURES_PUBLIQUES",
        "libelleService": "Service des factures publiques",
        "dateDbtService": "2025-11-04 16:37",
        "estActif": true
      },
      {
        "idService": 10693220,
        "codeService": "SERVICE_PUBLIQUE_1_97395107368257",
        "libelleService": "Label_SERVICE_PUBLIQUE_1_97395107368257",
        "dateDbtService": "2025-11-03 16:37",
        "estActif": true
      }
    ]
  },
  "created_at": "2025-10-25T10:30:00.000Z",
  "updated_at": "2025-10-25T10:30:00.000Z"
}
Erreur - Structure inactive sur Chorus Pro (400 Bad Request)
JSON
{
  "error": {
    "type": "invalid_request",
    "message": "Cette structure n'est pas active sur Chorus Pro"
  }
}

Lister

GET/v1/pay-links

Lister toutes les commandes avec pagination

Paramètres de query

statusFiltrer par statut (created, opened, accepted, invoiced, cancelled, action_required, paid)
limitNombre de résultats (défaut: 10, max: 100)
cursorCurseur pour la pagination
Request
Texte
GET /v1/pay-links?status=created&limit=10
Response (200 OK)
JSON
{
  "data": [
    {
      "id": "pl_a1b2c3d4e5f6",
      "status": "created",
      "amount": 62.01,
      "amount_ht": 51.67,
      "quote_number": "2025-001",
      "url": "https://choruspay.fr/link/pl_a1b2c3d4e5f6",
      "description": "Élection représentants parents 2025",
      "client": {
        "name": "Mairie de Saint-Cloud",
        "siret": "21092064000016",
        "email": "finances@saintcloud.fr"
      },
      "created_at": "2025-10-25T10:30:00.000Z",
      "sent_at": "2025-10-25T11:00:00.000Z",
      "accepted_at": null
    }
  ],
  "has_more": true,
  "next_cursor": "cursor_xyz123"
}

Récupérer

GET/v1/pay-links/:id

Récupérer une commande spécifique

Response (200 OK)
JSON
{
  "id": "pl_a1b2c3d4e5f6",
  "status": "accepted",
  "amount": 62.01,
  "amount_ht": 51.67,
  "quote_number": "2025-001",
  "url": "https://choruspay.fr/link/pl_a1b2c3d4e5f6",
  "description": "Élection représentants parents 2025",
  "client": {
    "name": "Mairie de Saint-Cloud",
    "siret": "21092064000016",
    "email": "finances@saintcloud.fr",
    "address": "8 Place Charles de Gaulle, 92210 Saint-Cloud"
  },
  "items": [
    {
      "description": "Licence plateforme",
      "quantity": 1,
      "unit_price": 16.67,
      "vat_rate": 20,
      "total": 16.67
    },
    {
      "description": "Classes (7x)",
      "quantity": 7,
      "unit_price": 5.0,
      "vat_rate": 20,
      "total": 35.0
    }
  ],
  "pdf_url": null,
  "purchase_order_url": null,
  "metadata": {
    "internal_ref": "REF-2025-001",
    "department": "Education"
  },
  "endpage_url": null,
  "created_at": "2025-10-25T10:30:00.000Z",
  "updated_at": "2025-10-25T10:30:00.000Z",
  "sent_at": "2025-10-25T11:00:00.000Z",
  "accepted_at": "2025-10-25T14:30:00.000Z",
  "rejected_at": null
}

Mettre à jour

PATCH/v1/pay-links/:id

Mettre à jour une commande (URL de redirection et/ou métadonnées)

Paramètres

Tous les paramètres sont optionnels, mais au moins un doit être fourni.

endpage_urloptionnel

URL de redirection après validation du devis par le client (string, URL valide, max 500 caractères). Passez null pour supprimer la redirection.

metadataoptionnel

Métadonnées à fusionner avec les métadonnées existantes de la commande (objet clé-valeur, valeurs string). Les clés fournies sont ajoutées ou écrasées, les clés existantes non fournies sont conservées.

Request - définir une URL de redirection
JSON
{
  "endpage_url": "https://monsite.fr/merci?ref=REF-2025-001"
}
Request - supprimer la redirection
JSON
{
  "endpage_url": null
}
Request - mettre à jour les métadonnées
JSON
{
  "metadata": {
    "order_id": "42",
    "order_reference": "ABCDEFGH"
  }
}
Request - les deux en même temps
JSON
{
  "endpage_url": "https://monsite.fr/merci?ref=REF-2025-001",
  "metadata": {
    "order_id": "42"
  }
}
Response (200 OK)
JSON
{
  "id": "pl_a1b2c3d4e5f6",
  "status": "created",
  "amount": 62.01,
  "amount_ht": 51.67,
  "quote_number": "2025-001",
  "url": "https://choruspay.fr/link/pl_a1b2c3d4e5f6",
  "description": "Élection représentants parents 2025",
  "client": {
    "name": "Mairie de Saint-Cloud",
    "siret": "21092064000016",
    "email": "finances@saintcloud.fr",
    "address": "8 Place Charles de Gaulle, 92210 Saint-Cloud"
  },
  "endpage_url": "https://monsite.fr/merci?ref=REF-2025-001",
  "metadata": {
    "order_id": "42",
    "order_reference": "ABCDEFGH"
  },
  "created_at": "2025-10-25T10:30:00.000Z",
  "updated_at": "2025-10-25T12:00:00.000Z"
}

Statuts des commandes

StatutDescription
draftCréé mais pas encore envoyé au client
sentEnvoyé au client, en attente d'acceptation
acceptedAccepté par le client, bon de commande généré
rejectedRefusé par le client
expiredExpiré ou annulé