01
Find your topic
Every question has its own page, and the full list is linked below. The twelve topics here are a map, not folders: start with getting started if you are evaluating, jump to invoicing or payouts if you are mid-integration, and use the operational topics (deposit addresses, conversion, refunds) when you hit a specific question in production.
| Category | What it covers |
|---|---|
| Getting started | What halfin is, what you need before integrating, and the path from sandbox to live. |
| Invoicing | Fiat-anchored versus fixed-asset invoices, the rate lock at activation, expiry, underpaid and overpaid handling. |
| Payouts | Approving and sending a single payout, destinations, and per-payout idempotency. |
| Mass payouts | Paying many recipients as a fan-out over the single-payout API with a per-line idempotency key. |
| Deposit addresses | Persistent per-merchant receive addresses for flows that are not invoice-by-invoice. |
| Conversion | Automatic and manual balance conversion for holding settled funds in the asset you want. |
| Fees | How network fees behave per chain and what is and is not public about commercial pricing. |
| Security | API keys with scoped permissions, idempotency, and verifying the HMAC signature on webhooks. |
| Compliance | KYB onboarding and how AML and travel-rule obligations are treated as process. |
| API integration | Spec-first REST, idempotency keys, the TypeScript SDK, and where the full schema lives. |
| Refunds | Returning funds to a payer and how a refund relates to the original invoice. |
| Account setup | Onboarding, keys, permissions, and configuring your merchant account. |
02
The questions almost everyone asks first
The answers below are the cross-cutting ones — they come up regardless of which product you start with. Each links into a category if you want to go deeper.
faq6 questions
explore
Every question, one page each.
- Are API keys scoped?Yes. A halfin API key carries only the permissions you grant it, scoped to the operations it needs — a read or invoice key cannot release payouts.
- Are API requests rate limited?Yes. Public auth endpoints are rate limited per IP and authenticated API-key requests are limited too. Design clients to back off and retry idempotently.
- Are crypto payments final?Yes — a confirmed on-chain transfer is irreversible and there are no chargebacks. Finality is a property of the chain, which is what makes reconciliation clean.
- Are there chargebacks with crypto payments?No. A confirmed on-chain payment is final, so there are no card-style forced reversals. A refund is a deliberate action you choose to issue.
- Are there monthly or setup fees?halfin's commercial pricing is not published on this site yet, so there is no monthly or setup figure to quote here. Building in the sandbox is free.
- Assets and networks questionsFrequently asked questions drawn from the halfin assets and networks pages. Each one links to a standalone answer.
- Can a customer pay an invoice late?A deposit that lands after a halfin invoice expires fires invoice.late_deposit — the funds are credited and matched to the invoice, and you decide how to treat the order.
- Can a customer reuse the same deposit address?Yes. A halfin static deposit address is persistent, so repeat deposits to the same address credit the same customer — no new invoice or address per top-up.
- Can I auto-convert incoming payments to a stablecoin?Yes. halfin balance conversion can run automatically toward a target asset such as a stablecoin, so incoming payments settle in one currency on credit.
- Can I bill in fiat and get paid in crypto?Yes. Set amount_fiat and fiat_currency on a halfin invoice; the customer pays the equivalent in any supported asset at the locked rate you bill against.
- Can I build while onboarding is pending?Yes — build against a sandbox key first. The sandbox is the same API as production with test data, and your full integration is verified before going live.
- Can I cancel a payout?Yes — while a payout is still pending approval, before it is released. Once released and broadcast on-chain it is final, like any blockchain transaction.
- Can I create multiple API keys?Yes — and you should. Create one scoped key per integration so a leak is a one-key rotation, not an account-wide reset. Scopes are enforced server-side.
- Can I issue a partial refund?Yes. A halfin refund is reasoned about against the amount paid on the invoice, so you can return all of it or part — a partial credit or overpayment surplus.
- Can I pay out to any address?You can pay out to any valid address on the chain your currency code selects. halfin validates the destination at creation, so a malformed address is rejected before broadcast.
- Can I refund after a conversion?Yes. A refund is an on-chain send from the asset you hold. Conversion is asset-to-asset, so it changes the asset you refund in, not your ability to refund.
- Can I schedule recurring payouts?There is no built-in scheduler. Drive the timing from your own system and fan out POST /api/v1/payouts on your schedule, each call with its own idempotency key.
- Can I set a fixed crypto amount?Yes. A fixed-asset invoice takes amount plus currency (a crypto code) and an optional network — the payable quantity is exactly what you state, no rate conversion.
- Can I test before going live?Yes. Use a sandbox test API key from the halfin dashboard to run the full invoice, payout, and webhook lifecycle on test data, then swap to a live key.
- Can I use separate keys for sandbox and live?Yes — sandbox keys are sk_test_ prefixed and move only test data against the same API. Build and verify your whole key flow in sandbox before a live key touches real funds.
- Can lines in a run use different currencies?Yes. Each line is an independent payout with its own currency, destination, and idempotency_key, so one run can mix USDT on Tron, USDC on Base, ETH, and more.
- Can one address receive many deposits?Yes — a static deposit address is reusable and accumulates deposits over its lifetime. An invoice address is single-use for one payment. Pick by use case.
- Do I get a webhook when a deposit arrives?Yes. balance.credited fires when a deposit to a static address is credited after confirmations. The signed webhook is the source of truth — verify it, then act.
- Do I need my own crypto wallet to use halfin?No. halfin generates the deposit addresses, detects payments on-chain, and credits your balance. You convert or pay out — no wallet software to run yourself.
- Do I pay network fees on payouts?Yes. A payout is an on-chain send, so it carries the destination chain's network fee, paid from your side. The fee goes to the network, never to halfin.
- Do my customers need an account?No. Customers just pay an invoice or a deposit address from their own wallet. They create no halfin account, and halfin never holds a wallet on their behalf.
- Does a refund cost a fee?A refund is an on-chain send back to the customer, so it carries the blockchain's network fee like any transfer. That fee is the chain's, not a halfin charge.
- Does halfin cash out crypto to my bank account?No. halfin balance conversion moves value between crypto assets and stablecoins — it isn't a fiat off-ramp. Cashing out to a bank is handled elsewhere.
- Does halfin hold my funds?halfin describes its custody boundaries through signing, permissions, and audit, and makes no guarantee beyond that. It is not a regulated or licensed status.
- Does the dashboard support two-factor authentication?Yes. The halfin dashboard supports two-factor authentication for operator sign-in, so a stolen password alone is not enough to reach the surface that approves payouts.
- Does the rate lock add a cost?No. The rate lock is how a fiat-anchored invoice works — the quote is fixed at activation for exchange-rate certainty, not an add-on you are charged for.
- Countries questionsFrequently asked questions drawn from the halfin countries pages. Each one links to a standalone answer.
- Glossary terms questionsFrequently asked questions drawn from the halfin glossary terms pages. Each one links to a standalone answer.
- Guides questionsFrequently asked questions drawn from the halfin guides pages. Each one links to a standalone answer.
- How are my funds protected?halfin protects your balance with layered controls — funds reserved at payout creation, scoped API keys, an operator approval gate before broadcast, and an audit trail.
- How are payouts approved before money leaves my balance?Every halfin payout waits in pending approval. An operator releases it from the dashboard, and only then is it signed and broadcast on-chain.
- How are payouts protected from mistakes or abuse?Every halfin payout waits in pending approval and is released from the dashboard. Operator approval, address validation, and an audit trail guard payouts.
- How do fees work?Two separate things: the blockchain's network fee (set by the chain, varies by transaction) and halfin's commercial pricing, which is not published yet.
- How do I add a team member?Team access is operator-level: you invite each person from the dashboard, and every action they take is attributed to them in the audit log. No shared logins.
- How do I add halfin to my website?Two ways: redirect customers to halfin's hosted checkout, or call the API and render your own UI. Either way, the signed webhook is what confirms a payment.
- How do I authenticate API requests?Send your secret API key in the X-API-Key header on every request. Keys are scoped by permission, so a key that creates invoices cannot release payouts.
- How do I create a deposit address?Send a create-address request naming the asset and network. halfin returns a static deposit address you save to your user and receive on indefinitely.
- How do I create a payout?POST to /api/v1/payouts with currency, amount, destination, and an idempotency key. The payout enters pending-approval and is released from the dashboard.
- How do I fund my payout balance?Your payout balance is funded by the payments you receive — invoices and deposit addresses — and by asset-to-asset conversions. Payouts draw from spendable balance.
- How do I get sandbox access to test?Sandbox access and test API keys come once you start halfin onboarding. Simulate the full invoice, payout, and webhook lifecycle on test data, then swap to live keys.
- How do I issue a refund?You initiate a merchant-side refund against the paid invoice and an operator approves it; halfin then sends the value back to the customer on-chain.
- How do I keep my API key safe?Keep your halfin API key server-side, in a secret manager, never in a browser, mobile binary, or repository — and rotate it the moment you suspect exposure.
- How do I know when an invoice is paid?halfin sends invoice.confirming as a deposit gathers confirmations, then invoice.paid once it clears the threshold. The signed webhook is the source of truth.
- How do I move from sandbox to live?Finish KYB, create a live API key in the dashboard, and swap your sk_test_ key for it. The endpoints, base URL, payloads, and webhooks are identical.
- How do I reconcile a payout run?Reconcile off payout.completed and payout.failed webhooks (verify the HMAC first), then read each line's state from the API or dashboard in a recovery sweep.
- How do I retry failed lines?Re-POST each failed line to /api/v1/payouts with the SAME idempotency_key it carried. Succeeded lines return as no-ops, so re-running is safe.
- How do I rotate an API key?Create a new key with the same scope, deploy it, then revoke the old one — so there's no window where requests fail. Rotate on a schedule and on suspected exposure.
- How do I send many payouts at once?Fan out over POST /api/v1/payouts — one call per recipient, each with its own currency, amount, destination, and idempotency_key. There is no batch endpoint.
- How do I set my settlement currency?Configure it in the dashboard; the setting applies going forward. Settlement is asset-to-asset conversion of your crypto balance — halfin does not cash out to a bank.
- How do I start accepting crypto with halfin?Six concrete steps to accept crypto with halfin: sandbox access, KYB, a scoped API key, your first invoice, a verified webhook, then live keys.
- How do I track a payout run?There is no batch object to poll. Each line is its own payout with its own status and payout.completed / payout.failed webhooks — you aggregate run progress on your side.
- How do I verify a deposit is real?Trust a confirmed, signed halfin webhook — invoice.paid or balance.credited after confirmations — not a wallet screenshot or an unconfirmed mempool sighting.
- How do I verify a webhook signature?Recompute the HMAC over the raw webhook bytes with your signing secret, then constant-time compare it to the signature header before any business action.
- How do refunds work?A halfin refund attaches to the paid invoice and returns value toward the original payer — operator-approved, full or partial, and traceable back to the sale.
- How does halfin attribute operator actions?Each action a person takes in the dashboard is recorded against them, so after the fact you can answer who released a withdrawal or issued an API key.
- How does idempotency work for a mass payout run?Each payout line carries its own idempotency key derived from your ledger, so re-running the whole file returns existing payouts instead of paying twice.
- How does the rate lock work on an invoice?A halfin invoice locks the fiat-to-crypto rate at activation and pins the payable token amount for its life. After the expiry window it expires, not re-prices.
- How is a conversion fee applied?Balance conversion is asset-to-asset, and its cost is reflected in the route or quote you see before you convert — the rate already accounts for it.
- How is a crypto refund different from a card chargeback?A refund is a return you initiate; a chargeback is a card-network forced reversal. On-chain settlement has no chargebacks, so a refund is always your choice.
- How long does a conversion take?A balance conversion is asynchronous: it settles when the underlying route completes, and your balance updates on completion. Track it through the balance API.
- How long does a payout take to confirm?Confirmation depends on the destination chain. After an operator releases the payout, halfin signs and broadcasts it, then waits for the per-chain threshold.
- How long does a refund take?Once approved, a refund takes as long as the destination chain needs to confirm the send. The rail you send on, not halfin, sets the settlement time.
- How long is an invoice valid?Each halfin invoice has its own expiry window. While it is open the customer can pay; when the window passes, invoice.expired fires and the invoice closes.
- How much does it cost to start?Building against the halfin sandbox is free — no real money moves on test keys. For pricing on live transactions, the dashboard and sales are the source of truth.
- How should I handle webhook retries?Verify the signature, dedupe by event id so handling is idempotent, do the work, then return 2xx. Failed deliveries are retried, so duplicates are expected.
- When should I use an invoice vs a static deposit address?Use an invoice for a specific charge with a fixed amount, locked rate, and expiry. Use a static deposit address for open-ended account funding over time.
- Is conversion automatic or manual?Both. halfin can auto-convert an incoming invoice toward a target asset on credit, or you can convert held balance manually in the dashboard. Most teams use both.
- Is there a dedicated batch payout endpoint?No. A halfin mass payout is a fan-out over the single-payout API: call POST /api/v1/payouts once per recipient, each with its own idempotency key.
- Is there a limit on a mass payout run?There is no batch object to cap. A run is a fan-out you drive from your side, so its size is bounded by your own pacing — respect the API's rate limits with backoff.
- Is there a minimum payment amount?There is no fixed floor published here, but very small amounts are impractical: the chain's own network fee and dust limits make tiny payments uneconomic.
- Is there a TypeScript SDK?Yes — @halfin/sdk-merchant is the typed TypeScript client over halfin's spec-first REST API. What it covers, how it stays in sync, when to use REST.
- Is there an audit trail of operator actions?Yes — who did what is recorded against the operator who did it: approving a payout, creating a key, running a conversion. Machine activity is tied to the key that made the request.
- Legal and policy questionsFrequently asked questions drawn from the halfin legal and policy pages. Each one links to a standalone answer.
- Products questionsFrequently asked questions drawn from the halfin products pages. Each one links to a standalone answer.
- Platform questionsFrequently asked questions drawn from the halfin platform pages. Each one links to a standalone answer.
- Use cases questionsFrequently asked questions drawn from the halfin use cases pages. Each one links to a standalone answer.
- What can I accept with halfin?Accept BTC, ETH and ERC-20 tokens, USDT on Tron/Ethereum/Solana, USDC on Base/Ethereum/Solana, plus assets on Base, Arbitrum, Polygon, BSC, Tron, XRP, and Solana.
- What do I need for KYB onboarding?KYB verifies your business before real funds move on halfin. What it establishes, why it runs in parallel with your build, and where the specifics are settled.
- What happens during onboarding review?Onboarding review is the business-verification step before a live key moves real funds. What it establishes, why it scales to your business, and where it is settled.
- What happens if a payout fails?A payout.failed webhook fires and the reserved funds return to your spendable balance. To retry safely, send the same idempotency_key so you never double-send.
- What happens if an API key leaks?Revoke that one key. The blast radius is bounded by its scope, and your other integrations keep running. Keys are secrets kept server-side only.
- What happens if an invoice is overpaid?When a customer overpays a halfin invoice, the excess is recorded against the invoice and invoice.overpaid fires — the surplus stays visible and accountable.
- What happens if an invoice is underpaid?When a customer sends too little, halfin records the shortfall and fires an invoice.underpaid webhook. You decide: top-up, partial settle, or refund.
- What happens if some payouts in a run fail?A failing line in a halfin mass payout affects only that line. Retry the failed lines with the same idempotency key; reconcile per line via webhooks.
- What happens when an invoice expires?When a halfin invoice's window passes without enough settling on-chain, it closes and invoice.expired fires. A deposit that lands later surfaces as invoice.late_deposit — not lost.
- What is a static deposit address?A static deposit address is a persistent per-customer crypto address for account funding, reused for every top-up instead of a new invoice each time.
- What is an idempotency key and when do I use it?A client-supplied value that makes a create request safe to retry — resending the same key returns the original result instead of duplicating it.
- What is an XRP destination tag?A numeric destination tag routes an XRP payment to the right account behind a shared address. On the XRP rail it is required — a deposit without it cannot be attributed.
- What is balance conversion?Balance conversion moves value between the crypto assets you hold on halfin — automatically on credit or manually — so you settle and hold in one chosen asset.
- What is the API base URL?The canonical base is api.thehalfin.com/api/v1; dashboard.thehalfin.com/api resolves to the same API. Authenticate every request with the X-API-Key header.
- What is the payout approval gate?Every halfin payout waits in pending_approval until an operator releases it from the dashboard. The gate is the deliberate window to catch a wrong amount or destination.
- What is the redirect_url on an invoice?redirect_url is the hosted halfin payment page you send the customer to. It is a destination, not proof of payment — the invoice.paid webhook is the source of truth.
- What is treasury rebalancing?Treasury rebalancing moves held crypto balances between assets and networks so funds sit in the form you want to hold or pay out. How it works on halfin.
- What records does halfin keep for me?halfin keeps a durable record of invoices, payouts, conversions, refunds, and an operator audit trail — your source records for accounting and reconciliation.
- What SDKs are available?halfin ships one official TypeScript SDK, @halfin/sdk-merchant. For every other language the REST API is plain HTTP — no SDK required to integrate.
- What should I keep for accounting?Keep your invoice and payout records plus the webhook events as the authoritative log. The webhook is the source of truth — not the customer's redirect back.
- What webhook events does halfin send?halfin sends invoice, balance, and payout events such as invoice.paid and payout.completed. The webhook is the source of truth; the customer redirect is not.
- When do I get a webhook for a payout?halfin fires payout.completed when a payout settles on-chain and payout.failed if it does not. Both are terminal. Verify the HMAC signature before acting.
- When is a deposit credited to my balance?A deposit credits your halfin balance once it clears the network's confirmation threshold. Crediting is reorg-aware, with a signed webhook on credit.
- Where does a refund go?A halfin refund goes back toward the payer of the original invoice — a new outbound transfer under operator approval, recorded against that invoice.
- Which assets can I convert between?Conversion is asset-to-asset between the crypto assets halfin supports — BTC, ETH, SOL, XRP, and stablecoins across their networks. There is no fiat off-ramp.
- Which currencies can I invoice in?Anchor a halfin invoice in fiat (amount_fiat + fiat_currency) or fix it to a crypto amount (amount + currency). Supported rails span BTC, ETH, EVM L2s, BSC, Tron, XRP, and Solana.
- Which currencies can I pay out in?Pay out in any rail halfin supports — BTC, ETH and ERC-20, Base, Arbitrum, Polygon, BSC, Tron, XRP, Solana. The currency code names both the asset and the chain.
- Which networks support deposit addresses?Bitcoin, Ethereum and ERC-20, Base, Arbitrum, Polygon, BSC, Tron, XRP, and Solana with SPL. Each create-address request names one asset on one of these chains.
- Who absorbs an overpayment?You do — in your favor. An overpaid invoice credits the full amount received and fires invoice.overpaid; the surplus is yours to keep or refund.
- Who can approve a payout?An operator with payout permission releases a payout from the dashboard, and the action is attributed to that person. The approval gate sits before anything is signed or broadcast.
- Who is responsible for customer refunds?You are. The merchant decides whether and how much to refund; halfin executes the on-chain send. Crypto payments are final, so there is no chargeback mechanism.
- Who pays the fee on a refund?The network fee comes from your side. A refund is an on-chain send out of your balance, so you carry the chain's fee to move the funds back to the customer.
- Who pays the blockchain network fee?The sending wallet pays the network fee to the chain. On incoming payments the customer pays; on payouts it is part of moving the funds. Never a halfin charge.
- Why does halfin require KYB?KYB verifies your business before a live key can move real funds. Why it gates live mode, why the sandbox needs none, and how the two run in parallel.