FAQ

Products questions

Frequently asked questions drawn from the halfin products pages. Each one links to a standalone answer.

Products questions

Every question below was authored on a products page and now has its own answer page. Pick the one that matches what you are working on.

explore

Every question, one page each.

Are conversions auditable?Yes. Every conversion is recorded against your balance history as an explicit event with provenance, and your held balances are readable through the same…
Are the balances I see in the dashboard final?Crediting is reorg-aware and respects per-chain confirmation thresholds, so a balance the dashboard shows as settled is one you can act on — it is not…
Can a customer reuse the same deposit address for multiple payments?Yes — that is the point. The address is issued once per customer and network and stays valid indefinitely. Each deposit is credited independently with its…
Can a finance or support team use the dashboard without engineering?Yes — that is the point of it. Once engineering wires the integration, finance and operations run invoicing, payout approval, reconciliation, and…
Can a payout be sent without operator approval?No. Every single payout is created in pending_approval and waits for an operator with payout permissions to authorize it. Funds are reserved at creation…
Can I auto-convert every payment to a stablecoin like USDT or USDC?Yes. Set your target settlement asset to a supported stablecoin and payments are converted toward it on credit, as long as a conversion route exists…
Can I bill in fiat but let the customer choose the crypto?Yes. You set the fiat amount and currency (for example 49.00 USD); the customer settles in any supported asset and network — USDT on Tron, USDC on Base…
Can I cancel a payout after creating it?Yes, while it is still pending_approval or approved but not yet executed. Once the transaction is signed and broadcast it is on-chain and final, so…
Can I convert only part of a held balance?Yes. A manual conversion is bounded to the source amount you name, so converting part of an asset now and the rest later is simply two recorded…
Can I fully restyle the page or use my own domain?Customization covers presentation and routing — branding, the offered networks, order context, and the return URL — not a full layout rebuild or a custom…
Can I issue a read-only API key for accounting?Yes. API keys carry scoped permissions, so you can mint a read-only key that lists invoices and reads balances but cannot create or approve payouts, and…
Can I limit what an automated caller is allowed to do?Yes. API keys carry scoped permissions. Give a billing service a create-invoice key, a disbursement worker a payouts key, and an accounting job a…
Can I limit which assets an invoice accepts?Yes — you can scope an invoice to a subset of the supported assets, for example stablecoins only, when that fits your business. Left open, the invoice…
Can I partially refund a crypto invoice?Yes. A refund is reasoned about relative to the amount paid on the original invoice, so you can return the full paid amount or part of it. That covers…
Can I put my own branding on the hosted checkout page?Yes. Your merchant name and brand are an account-level setting in the dashboard, and every hosted page you generate inherits them automatically. You don't…
Can I rebalance between any two assets or networks?Only where a supported conversion route exists between the source and target placements. Routes cover the assets and networks halfin supports for…
Can I show only some networks in my checkout?Yes. You decide which assets and networks appear in your picker and pass the chosen network when you create the invoice. Many self-hosted checkouts start…
Can I use this for recurring billing or auto-charging customers?No — this is for paying out, not charging. halfin has no saved-instrument auto-charge; recurring billing is handled by issuing an invoice per cycle…
Can one batch pay recipients on different chains and in different assets?Yes. Each line picks its own currency and network, so a single run can send USDT on Tron, USDC on Ethereum or Base, native SOL, and BTC at the same time…
Can one payroll run pay people on different chains and in different assets?Yes. Each line picks its own currency and network, so a single cycle can send USDT on Tron, USDC on Ethereum or Base, native SOL, and BTC at the same…
Do automated payouts skip the approval step?No. Automation only moves the trigger; it does not move funds. Each payout your job submits enters a pending-approval state and is released from the…
Do I have to run a blockchain node or hold private keys?No. That is the whole point of the split. You build the checkout UI and react to webhook events; halfin derives the deposit address, monitors the chain…
Do I have to use the SDK to integrate?No. The REST API is the product; @halfin/sdk-merchant is a convenience for TypeScript projects. Any language can call the endpoints directly with an…
Do I have to use the TypeScript SDK?No. The SDK is a convenience: @halfin/sdk-merchant is a thin, typed client generated from the same OpenAPI spec as the server, so the types match the…
Do I need a separate API call to customize the page?No. Branding is configured once on your account; the per-invoice presentation — the description and redirect_url — are just fields on the same…
Do I need the dashboard if my integration uses the API?Most teams use both. The API handles high-volume, event-driven work — an invoice per checkout, a payout per approved withdrawal, webhooks consumed in real…
Do I need to generate the QR code myself?No. The QR, the address rendering, the per-chain payment URI, and the live status are all part of the hosted page the invoice produces. You create the…
Do I need to write any wallet code to use hosted checkout?No. The wallet flows, QR code, address display, and per-chain confirmation watching all live on the hosted page. Your integration is creating the invoice…
Do payouts execute the moment I call the API?No. Each payout enters a pending-approval state and is released from the dashboard before funds move. That keeps a high-throughput programmatic path for…
Does a manual conversion let me cash out to a bank account?No. It moves value between the crypto assets you hold on the platform. halfin is digital-asset payment infrastructure, not a fiat off-ramp — converting…
Does auto-conversion settle me into fiat in a bank account?No. Automatic conversion moves value between the crypto assets you hold on the platform. halfin is digital-asset payment infrastructure, not a fiat…
Does balance conversion let me cash out to a bank account?No. Conversion moves value between the crypto assets you hold on the platform. halfin is digital-asset payment infrastructure, not a fiat on-ramp or…
Does createPayout send money immediately?No. createPayout queues a payout in a pending-approval state; it is released from the dashboard by an operator with the right permission. The SDK call and…
Does fiat anchoring convert crypto to fiat in my account?No. Anchoring fixes the amount in fiat for pricing and reconciliation — you state amount_fiat and fiat_currency, and halfin computes the payable token…
Does halfin reverse the original blockchain transaction?No — on-chain payments are final and cannot be reversed at the protocol level. A refund is a new outbound transfer that returns value to the payer, bound…
Does M2M settlement provide a fiat on-ramp or hold my ledger?No to both. halfin settles in supported crypto assets and chains between systems that already transact in them — it does not sell crypto or convert bank…
Does rebalancing let me move funds to a bank account?No. Rebalancing moves value between the crypto assets and networks you hold on the platform. halfin is digital-asset payment infrastructure, not a fiat…
Does staging a pay run move funds immediately?No. Every payout enters a pending-approval state and is released from the dashboard before funds move. Your integration assembles the cycle from HR or…
Does staging a settlement run move funds immediately?No. Every payout enters a pending-approval state and is released from the dashboard before funds move. Your integration assembles the run from approved…
Does the fiat amount change if the customer pays in a different asset?No. The fiat amount is fixed when you create the invoice. Each presented asset gets its own payable amount computed from the rate locked at activation…
Does the QR code include the amount, or just the address?It encodes the deposit address, and the amount too where the chain's payment URI scheme supports it, so the customer's wallet prefills a transaction…
How are payout approvals controlled?A payout is reviewed before it is released. The operator sees the destination, asset, network, and amount, and the approval is recorded against the…
How do API keys and permissions work in the dashboard?You create API keys and assign each one a narrow set of scoped permissions — for example, a read-only key for accounting that cannot move money, and a…
How do I auto-convert every payment to a stablecoin?Set your target settlement asset to a supported stablecoin such as USDC or USDT. From then on, incoming payments are converted toward that asset at the…
How do I avoid sending the same payout twice?Include an idempotency key on the create request. If the request is retried after a timeout or network error, halfin recognizes the key and returns the…
How do I control which networks the customer can pay with?The page offers only the rails you've enabled on your account. Enable the subset of Bitcoin, Ethereum and ERC-20, Base, Arbitrum, Polygon, BNB Smart…
How do I know when an invoice is actually paid?An invoice is marked paid only after on-chain confirmations reach the per-chain threshold, and crediting is reorg-aware. You track the transition through…
How do I know which asset and network a customer actually paid with?The invoice records the settling asset and network, and you can read them through the dashboard, the REST API, or the signed webhook event that fires when…
How do I make automated retries safe?Send an idempotency key with each value-moving request, derived from a stable identifier for the intent (order ID, billing period, batch run). The first…
How do I mark a supplier's invoice paid automatically?Use the invoice number as the payout's idempotency key when you submit the settlement. When the payment settles, halfin sends a `payout.completed`…
How do I pass an idempotency key through the SDK?Put idempotency_key in the body object you pass to createInvoice or createPayout — it is a snake_case body field, exactly as over raw HTTP, not an…
How do I rebalance before a payout run?Look ahead at what the next single or mass payout run pays out and on which network, read your current balances through the API to see where liquidity…
How do I schedule automated payouts with halfin?halfin does not run the schedule for you — you put your own cron job, queue consumer, or event handler in front of the ordinary single-payout endpoint…
How do I see the converted result after a payment settles?Read your balances through the REST API at api.thehalfin.com/api/v1 with an API key in the X-API-Key header — the same endpoint you use for invoices and…
How do I send idempotency on a create call?Pass idempotency_key as a field in the JSON request body — it is snake_case body data, not an Idempotency-Key header. A retried POST that carries the same…
How do I trigger a manual conversion?Two ways, with the same result. In the dashboard, an operator picks the source asset, the target asset, and the amount and confirms the move…
How do I verify a halfin webhook signature?Recompute an HMAC over the exact raw request body using the signing secret for your endpoint, then compare it to the signature header with a constant-time…
How do idempotency keys prevent double charges and double payouts?Send an idempotency_key field in the body of a state-changing request — usually derived from your own order or batch identifier. halfin records the result…
How does a customer pay by scanning the QR code?On the open invoice, the hosted page shows the amount due, a QR code, and the deposit address. The customer opens their mobile wallet's scanner, points it…
How does conversion help with payouts on different networks?The same logical asset lives on different networks — USDT as TRC-20, ERC-20, or Solana SPL; USDC as ERC-20, Solana SPL, or Base — and network fees differ…
How does halfin make sure a worker isn't paid twice in a cycle?Each payroll line carries a deterministic idempotency key — typically the worker's account id joined with the pay period. If halfin sees the same key…
How does halfin stop a recipient from being paid twice?Every payout carries a caller-supplied idempotency key. If halfin sees the same key again — from a timeout retry, a worker restart, or a re-run of the…
How does halfin stop an invoice from being paid twice?Each settlement carries a deterministic idempotency key, typically the supplier id joined with the invoice number. If halfin sees the same key again after…
How does my service learn that an asynchronous settlement actually completed?halfin pushes a signed webhook when the settlement reaches its terminal state. Recompute the HMAC over the raw request body, compare it to the…
How does my system learn that a refund was processed?Refund state is available through the spec-first REST API, and state changes arrive as HMAC-signed webhook events in the same envelope as your invoice and…
How does the customer know the payment went through?The page updates live. It starts in a waiting state with the QR and a countdown to expiry, moves to detected-and-confirming once a matching transaction is…
How does the SDK tell me an invoice was paid?It doesn't — settlement comes back over webhooks. halfin sends an HMAC-signed event such as invoice.paid to your endpoint when the state changes; you…
How is a refund different from a payout?A refund must point at a paid invoice and returns value against it, which keeps your revenue records honest. A single payout or mass payout has no…
How is a static deposit address different from an invoice?An invoice is a single, priced payment that locks a rate at activation and expires. A static deposit address is a persistent receive endpoint with no…
How is manual conversion different from automatic conversion?Automatic conversion fires on its own when a payment is credited, settling the incoming asset toward a target you chose in advance. Manual conversion is…
How is this different from hosted checkout?Hosted checkout is a payment page halfin renders and maintains at checkout.thehalfin.com — you redirect the customer to it. Self-hosted checkout exposes…
How will my system know when a payout completes?The same lifecycle is exposed in the dashboard, the API, and a signed webhook. Verify the webhook signature before acting on it, then mirror the final…
Is a manual conversion auditable?Yes. Every conversion is written to your balance history as a recorded event with provenance, and your held balances are readable through the same REST…
Is idempotency_key a header or a body field?A body field. Send idempotency_key as a snake_case property inside the JSON request body. The only request headers are Content-Type and X-API-Key — there…
Is machine-to-machine settlement a separate product from invoicing and payouts?No. It is a way of driving the existing primitives — invoicing, payouts, conversion, deposit addresses — entirely through the API, with idempotency keys…
Is the redirect or the webhook the source of truth?The webhook. The success redirect is for the customer's experience and can be missed if they close the tab. The HMAC-signed webhook arrives independently…
Is there a difference between creating an invoice in the dashboard and via the API?No functional difference — the dashboard and the API operate on the same invoice object with the same lifecycle. The API and the @halfin/sdk-merchant…
Is there a separate batch endpoint, or do I loop over single payouts?You fan out over the single-payout API, and idempotency keys make that loop safe to interrupt and re-run. There is no separate batch state to learn — the…
Is there an amount to set or a window to watch?No. Unlike an invoice, a deposit address has no pre-declared amount and no expiry, so there is no underpaid or overpaid state to reconcile and nothing…
Is this a card checkout?No. The customer pays on-chain from their own wallet — there is no card field and no card data passing through your systems, so this page does not bring a…
Is this a separate API from regular invoicing?No. You create the same invoice with a fiat amount and currency against POST /api/v1/invoices; the supported assets become the customer's payable options…
Is this saved-card style recurring billing?No. halfin doesn't store a payment instrument or auto-charge. Each pay cycle is a fresh batch you assemble, stage, and approve; the recurrence lives in…
Should I trust the webhook payload or re-read the resource from the API?Either works once the signature verifies. The data object on an event matches the corresponding REST resource, so you can act on the payload directly. If…
Should I use single payouts or a mass payout for supplier settlements?Both, depending on cadence. Settle invoices as single payouts when they arrive one at a time, and as a mass payout when you sweep everything approved at…
What does the customer see on the checkout page?The amount due in their chosen asset and network, a QR code and copyable address, the networks you accept, and the live payment status — waiting…
What happens if a customer underpays or overpays?The invoicing layer records what was actually received against what was quoted and lands the invoice in a defined underpaid or overpaid state rather than…
What happens if a customer underpays or pays after the invoice expires?Underpayments and overpayments are recorded with the exact amount received, not silently dropped, so you choose how to resolve them. The rate is locked at…
What happens if some recipients in a batch fail?Partial failure is reported per-line. A bad address, a dust-threshold amount, or an unsupported currency rejects only that line; the rest of the batch…
What happens if the customer underpays or overpays?Both are recorded against the invoice rather than discarded. An underpayment surfaces the shortfall so you can request a top-up or settle partially under…
What happens when a deposit arrives?halfin detects the deposit on-chain, applies reorg-aware crediting against the network's confirmation threshold, and credits your merchant balance. Your…
What happens when an incoming asset has no conversion route to my target?The asset is credited as-is and stays visible in your balance. Nothing is lost or hidden, and you can convert it later as a manual conversion. This…
What if my balance is not in the asset I need to pay out?Convert first, then pay out. A payout moves what your merchant balance holds, so if you collect in one asset and owe another, use balance conversion to…
What if my treasury holds a different asset than the invoice is in?Use balance conversion to rebalance asset-to-asset before you stage the run, so each line has the right asset on the right chain behind it. Balance…
What if the asset I hold isn't the asset I need to pay in?Use balance conversion to rebalance your treasury asset-to-asset before you stage the run, so each line has the right asset on the right chain behind it…
What if the customer picks an asset and then underpays on that network?It is handled on the rail they used. The invoice records the shortfall in the asset that arrived so you can request a top-up or settle partially under…
What if the wallet fails part-way or the customer reloads the page?The same QR and address stay on the page for the customer to re-scan, and the same address keeps accepting the deposit. A customer who closes the tab and…
What is the deferred flag for?deferred selects who picks the settlement asset. With deferred true you supply only the fiat amount and currency, and the payer chooses any supported…
What is the difference between automatic and manual conversion?Automatic conversion runs at the moment a payment is credited and settles the incoming asset toward a target you chose in advance, so revenue lands in…
What is treasury rebalancing on halfin?It is using balance conversion to move held value between assets and the networks they live on, so the liquidity an upcoming obligation needs is already…
What should my endpoint return, and how fast?Return a 2xx as soon as you have verified the signature and durably recorded the event, then do fulfilment, email, and ledger writes on a background…
What stops an overlapping cron run or a re-delivered event from paying someone twice?The idempotency_key on each payout. Derive it deterministically from your own ledger — account id plus payout period for a scheduled sweep, or the event's…
What stops someone from forging a 'paid' webhook?Every webhook is HMAC-signed. Verify the signature before you take any business action — releasing a product, crediting a balance, marking an order…
When does the conversion rate lock?At activation — when the invoice goes live and is presented for payment, not when you draft it. From that point the payable token amount is fixed for the…
When exactly does the exchange rate lock?At activation — the moment the invoice goes live and is presented for payment. From that point the payable token amount is fixed for the life of the…
When should I use manual conversion instead of automatic?Use automatic conversion for steady, high-volume revenue you want settling into one asset with no effort. Use manual conversion for deliberate, periodic…
Where does the customer go after paying?Wherever you point redirect_url on the invoice — the hosted page sends the customer back there once the payment resolves. It's for the customer's…
Where is the API and how do I authenticate?The merchant API is at api.thehalfin.com/api/v1 (the dashboard origin dashboard.thehalfin.com/api points at the same service). Authenticate every merchant…
Which assets and networks can I pay out in?USDT (Tron, Ethereum, Solana), USDC (Ethereum, Solana, Base), BTC, ETH and its L2s (Base, Arbitrum, Polygon), and the native assets of BNB Smart Chain…
Which events does halfin send?Invoice lifecycle events (activated, underpaid, paid, overpaid, expired), deposit events when an on-chain payment lands on a static address and as it…
Which networks and assets are supported for deposit addresses?Addresses are network-specific across Bitcoin, Ethereum and ERC-20 tokens, the EVM L2s Base, Arbitrum and Polygon, BNB Smart Chain, Tron and TRC-20, the…
Which networks appear on the page?Only the rails you enable, and only ones with a real on-chain gate behind them: Bitcoin, Ethereum and ERC-20, Base, Arbitrum, Polygon, BNB Smart Chain…
Who is allowed to issue a refund?Refunds run through operator approval and sit behind scoped permissions, the same model that governs payouts. You decide which operators and which API…
Why am I receiving the same event twice?Delivery is at least once, not exactly once. A timeout, a transient 5xx, or a slow acknowledgement causes halfin to redeliver, and the redelivered copy…
Why do amounts come back as strings instead of numbers?Monetary fields are decimal strings with per-currency precision. Parsing them into JavaScript's native floating-point number can lose a fraction of a unit…
Why does the network my stablecoin sits on matter if it is the same asset?Because a payout draws from a specific per-network balance, not a logical total. USDC on Base does not fund an Ethereum ERC-20 payout, and network fees…
Why is amount_fiat a string in the request?Monetary values are strings end to end across the halfin API so they never pick up a floating-point rounding error. Send "49.00", not 49.00 as a number…
Will an SDK upgrade break my code silently?No — a contract change shows up as a TypeScript error, not a runtime surprise. The SDK types are generated from the same OpenAPI spec as the server, so a…