Concepts clés

Quelques règles s'appliquent à tous les points de terminaison. Lisez-les une fois et les tableaux de champs seront plus clairs.


_id et externalId

externalId est votre propre identifiant pour l'enregistrement, par exemple votre numéro de facture ou de client. Envoyez de nouveau le même externalId et Hyfin met à jour cet enregistrement au lieu d'en créer un nouveau.

_id est l'identifiant de Hyfin pour l'enregistrement, et chaque création le retourne. Enregistrez-le : les webhooks de paiement désignent les factures par _id, et les points de terminaison Get de la 4.0 recherchent les enregistrements avec celui-ci.

Les montants sont en cents

Chaque montant en 4.0 est un nombre entier de cents, dans les requêtes comme dans les réponses. Envoyez 4599 pour 45,99 $. Les webhooks de paiement utilisent aussi les cents pour les sites sur la version de webhook 4.0, la valeur par défaut des nouveaux sites.

Dates et horodatages

Un champ Date est un jour du calendrier sans heure, écrit YYYY-MM-DD, par exemple 2026-10-23. Une heure ou un fuseau horaire envoyé avec lui est ignoré, et non converti, de sorte que la date reste telle qu'écrite. Les réponses de Facture retournent invoiceDate et dueDate sous forme d'horodatage à minuit UTC à cette date, par exemple 2026-10-23T00:00:00.000Z.

Un champ Timestamp est un moment précis en format ISO 8601, avec millisecondes et fuseau horaire : YYYY-MM-DDTHH:mm:ss.SSSZ, par exemple 2026-10-23T15:04:05.123Z. Les réponses retournent les horodatages en UTC. Le paramètre de requête updated_after accepte uniquement ce format exact.

À qui appartient chaque enregistrement

Votre logiciel gère les clients, les articles, les factures et les abonnements. Envoyez-les à Hyfin lorsqu'ils sont créés ou modifiés. Hyfin gère les paiements : il les reçoit, puis vous en informe par le webhook de paiement.

Statuts de paiement

Le webhook de paiement envoie un appel chaque fois qu'un paiement atteint un nouveau status; un même paiement peut donc arriver plus d'une fois, par exemple comme captured, puis comme settled. Associez-le selon le _id du paiement et mettez à jour le paiement existant plutôt que d'en ajouter un nouveau.