Question 1

How do I add halfin to my website?

Accepted Answer

Two ways. The fast path is hosted checkout: your server creates an invoice with a POST to /api/v1/invoices (X-API-Key header, idempotency_key in the body) and redirects the customer to the response's redirect_url, where halfin renders the payment page. The custom path is to call the same API and render the deposit address and amount in your own UI. In both cases the signed webhook — not the customer's return to your site — is what tells your backend the payment actually arrived. Build it against the sandbox first, then swap to a live key.

Question 2

Should I use hosted checkout or build my own payment page?

Accepted Answer

Use hosted checkout when you want the least code and do not want to render crypto payment UI yourself — you redirect to the page from the invoice's redirect_url and halfin owns the address, network, and confirmation display. Build your own UI when the payment must live inside your design; you call the same API and render the address and amount yourself. Either way, keep the API key server-side and confirm payments from the webhook, not the browser.

Question 3

How does my site know a customer actually paid?

Accepted Answer

From the webhook, which is the source of truth — not from the customer returning to your site. Register an HTTPS endpoint to receive HMAC-signed events such as invoice.paid, verify the signature over the raw request bytes before acting, and fulfill the order on that verified event. The redirect back to your pages is just a navigation and can be opened, replayed, or skipped, so it is never treated as proof of payment.

How do I add halfin to my website?

Keep reading across the cluster.