Démarrage rapide : votre première facture

Ceci fait passer une facture de votre logiciel à l'état payé dans l'environnement de test (stage), en quatre appels d'API et un webhook.


Avant de commencer

Vous avez besoin d'un jeton d'API et du site_id d'un site de test sur stage. Écrivez à api-support@hyfin.app pour obtenir les deux, et demandez d'activer l'accès à l'API pour ce site.

Envoyez chaque requête à https://stage-api.hyfin.app avec votre jeton dans l'en-tête x-access-token.

Vous avez aussi besoin d'une URL HTTPS publique qui affiche ce qui y est envoyé, pour recevoir le webhook. Un request bin convient pour les tests.

1. Créer une facture

Omettez _id et externalId : cela indique à Hyfin qu'il s'agit d'une nouvelle facture. Le client est créé avec celle-ci. Utilisez votre propre adresse courriel pour recevoir la facture, et définissez webhookUrl avec votre URL de test.

Enregistrez le _id de la réponse. link est la page où le client paie.

POST
{base_url}/api/v4/site/{site_id}/invoice/addUpdate
Demande
			
{
  "invoiceNumber": "1001",
  "description": "Lawn care, October",
  "totals": {
    "total": 4599
  },
  "customer": {
    "externalId": "C-1001",
    "primaryContact": {
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "you@yourcompany.com"
    }
  },
  "webhookUrl": "https://yourcompany.com/webhook"
}


		
Réponse
			
{
  "success": true,
  "action": "added",
  "_id": "6537f1c2a90735097a811c01",
  "updatedAt": "2026-10-22T15:04:05.123Z",
  "link": "https://site.url/L-KA39T1A45JL",
  "missingCustomer": false
}


		

2. La mettre à jour

Renvoyez le _id avec les champs que vous souhaitez modifier. Sans lui, Hyfin créerait une deuxième facture.

POST
{base_url}/api/v4/site/{site_id}/invoice/addUpdate
Demande
			
{
  "_id": "6537f1c2a90735097a811c01",
  "customerMemo": "Thank you for your business!"
}


		
Réponse
			
{
  "success": true,
  "action": "updated",
  "_id": "6537f1c2a90735097a811c01",
  "updatedAt": "2026-10-22T15:06:12.456Z",
  "link": "https://site.url/L-KA39T1A45JL",
  "missingCustomer": false
}


		

3. La payer

Ouvrez le link de l'étape 1, ou le courriel que Hyfin vous a envoyé, et payez avec une carte de test.

4. Recevoir le webhook de paiement

Hyfin envoie le paiement à votre webhookUrl. allocations[0].ref est le _id de la facture que vous avez enregistré à l'étape 1, ce qui permet à votre logiciel de savoir quelle facture a été payée. Les clés du webhook sont en snake_case.

Charge utile du webhook (abrégée)
			
{
  "action": "payment",
  "data": {
    "_id": "6537f2d4a90735097a811c9e",
    "status": "captured",
    "amount": 4599,
    "allocations": [
      {
        "ref_type": "Invoice",
        "ref": "6537f1c2a90735097a811c01",
        "amount": 4599
      }
    ]
  }
}


		

5. Relire les données

Get Facture liste les _id de paiement de la facture dans payments. Get Payment en retourne un en détail. C'est toute la boucle : la facture a été envoyée, le client a payé et votre logiciel est au courant.

GET
{base_url}/api/v4/site/{site_id}/invoice/{_id}