This takes one invoice from your software to paid on the stage environment, in four API calls and one webhook.
You need an API token and the site_id of a test site on stage. Email api-support@hyfin.app for both, and ask them to turn on API access for that site.
Send every request to https://stage-api.hyfin.app with your token in the x-access-token header.
You also need a public HTTPS URL that shows you what is posted to it, to receive the webhook. A request bin works for testing.
Leave out _id and externalId: that tells Hyfin this is a new invoice. The customer is created with it. Use your own email address so the invoice comes to you, and set webhookUrl to your test URL.
Save the _id from the response. link is the page where the customer pays.
{
"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
}
Send the _id back with the fields you want to change. Without it, Hyfin would create a second invoice.
{
"_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
}
Open the link from step 1, or the email Hyfin sent you, and pay with a test card.
Hyfin posts the payment to your webhookUrl. allocations[0].ref is the invoice _id you saved in step 1, which is how your software knows which invoice was paid. Webhook keys are snake_case.
{
"action": "payment",
"data": {
"_id": "6537f2d4a90735097a811c9e",
"status": "captured",
"amount": 4599,
"allocations": [
{
"ref_type": "Invoice",
"ref": "6537f1c2a90735097a811c01",
"amount": 4599
}
]
}
}
Get Invoice lists the invoice's payment _ids in payments. Get Payment returns one of them in full. That is the whole loop: the invoice went out, the customer paid, and your software knows.