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.
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.
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.
{
"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"
}
{
"success": true,
"action": "added",
"_id": "6537f1c2a90735097a811c01",
"updatedAt": "2026-10-22T15:04:05.123Z",
"link": "https://site.url/L-KA39T1A45JL",
"missingCustomer": false
}
Renvoyez le _id avec les champs que vous souhaitez modifier. Sans lui, Hyfin créerait une deuxième facture.
{
"_id": "6537f1c2a90735097a811c01",
"customerMemo": "Thank you for your business!"
}
{
"success": true,
"action": "updated",
"_id": "6537f1c2a90735097a811c01",
"updatedAt": "2026-10-22T15:06:12.456Z",
"link": "https://site.url/L-KA39T1A45JL",
"missingCustomer": false
}
Ouvrez le link de l'étape 1, ou le courriel que Hyfin vous a envoyé, et payez avec une carte de test.
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.
{
"action": "payment",
"data": {
"_id": "6537f2d4a90735097a811c9e",
"status": "captured",
"amount": 4599,
"allocations": [
{
"ref_type": "Invoice",
"ref": "6537f1c2a90735097a811c01",
"amount": 4599
}
]
}
}
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.