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.
Your externalId tells Hyfin which invoice this is. 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.
{
"externalId": "INV-1001",
"invoiceNumber": "1001",
"description": "Lawn care, October",
"totals": {
"total": 4599
},
"customer": {
"externalId": "C-1001",
"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 same externalId with the fields you want to change. Hyfin finds the invoice by it and updates it.
{
"externalId": "INV-1001",
"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.