Quick start: your first invoice

This takes one invoice from your software to paid on the stage environment, in four API calls and one webhook.


Before you start

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.

1. Create an invoice

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.

POST
{base_url}/api/v4/site/{site_id}/invoice/addUpdate
Request
			
{
  "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"
}


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


		

2. Update it

Send the _id back with the fields you want to change. Without it, Hyfin would create a second invoice.

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


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


		

3. Pay it

Open the link from step 1, or the email Hyfin sent you, and pay with a test card.

4. Get the payment webhook

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.

Webhook payload (trimmed)
			
{
  "action": "payment",
  "data": {
    "_id": "6537f2d4a90735097a811c9e",
    "status": "captured",
    "amount": 4599,
    "allocations": [
      {
        "ref_type": "Invoice",
        "ref": "6537f1c2a90735097a811c01",
        "amount": 4599
      }
    ]
  }
}


		

5. Read it back

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.

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