FAQ

Guides questions

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

Guides questions

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

explore

Every question, one page each.

Can a customer charge back a crypto payment?No — not in the card sense. A card chargeback is a forced reversal initiated by the issuing bank, who can pull settled funds back out of your account…
Can a leaked API key drain my balance the way a stolen hot-wallet key would?Only if it is the wrong key and your process allows it. A read-only or invoicing-scoped key cannot initiate a payout at all. A leaked payouts-scoped key…
Can halfin cash my USDC out to a bank account?No. halfin is digital-asset payment infrastructure, not a fiat off-ramp — it does not sell USDC to a bank account. The USDC you collect sits in a balance…
Can halfin convert my crypto balance to dollars in a bank account?No. Every conversion is asset-to-asset and stays on-chain — for example native SOL into USDC, or ETH into USDT. halfin is not a fiat off-ramp and does not…
Can halfin convert my crypto to fiat and send it to my bank?No — halfin does not cash out to a bank. It converts between the crypto assets you hold on the platform, including settling volatile assets into a…
Can halfin pay affiliates out to a bank account?No. A payout sends a crypto asset to a crypto address; halfin has no fiat off-ramp and does not move money to a bank. Balance conversion can rebalance…
Can I accept both native ETH and ERC-20 tokens like USDC or USDT?Yes. 'Ethereum' covers native ETH and ERC-20 tokens on the same network, and halfin treats each asset as its own settlement rail. You choose which to…
Can I auto-charge a customer's wallet every month like a saved card?No, and no crypto payment system can for a self-custody wallet — a wallet does not delegate standing authority to pull funds the way a card network lets a…
Can I avoid network fees entirely?No — any transaction on a public blockchain pays the network for block space; that is how the chain is secured. What you can do is choose the rail…
Can I build my integration before KYB is complete?Yes — and you should. Verification gates live transacting, not development. Use the sandbox to create invoices, simulate payments, and exercise your…
Can I do this without building a backend service?Yes, for low volume. Create an invoice in the halfin dashboard for the cart total, send the buyer the checkout link, and mark the matching Shopify order…
Can I keep some revenue in a volatile asset like BTC on purpose?Yes. Leave automatic conversion off for that asset and convert it manually only when your own policy says to. Separating automatic from manual conversion…
Can I make one reusable link that many people pay?No — each invoice is one amount for one payment with one expiry, so each link is a specific request, not a standing 'pay me anything' page. That is what…
Can I price directly in a stablecoin instead of in fiat?Yes. halfin supports fixed-asset invoices where you state an amount and a crypto currency directly — for example a specific USDT quantity — with no fiat…
Can I refund only part of a crypto payment?Yes. A halfin refund is reasoned about relative to the amount actually paid on the original invoice, so you can return the full paid amount, a portion of…
Can I save on fees by batching payouts into one call?There is no /payouts/batches endpoint — a mass payout is a fan-out where you loop POST /api/v1/payouts once per recipient, and every line that executes is…
Can I send USDT to any of my addresses?No — a deposit address is bound to one chain. A Tron address receives TRC-20 USDT on Tron; an Ethereum address receives ERC-20 USDT on Ethereum; they are…
Can the button bill in fiat but let the customer choose the crypto?Yes, and it is the cleanest setup. Create a deferred, fiat-anchored invoice with amount_fiat and fiat_currency; the customer settles in any supported…
Do I have to build a separate integration for each blockchain?No. Multi-chain acceptance is a property of your account's enabled gates, not of separate code paths. You create one fiat-anchored invoice and the…
Do I have to choose between stablecoins and Bitcoin?No. A single fiat-anchored invoice can present multiple supported assets, and the customer settles in whichever one they hold — USDT on Tron, USDC on…
Do I have to choose one network for my whole store?No. A halfin invoice carries one fiat-anchored amount and can present more than one supported rail; the customer settles in whichever USDC network they…
Do I have to know which crypto the customer will use before I send the link?Not if you bill in fiat. Create the invoice with amount_fiat, fiat_currency, and deferred: true; the rate locks when the invoice activates and the…
Do I mark the order paid when the customer returns to my page?No. The redirect to your redirect_url is for the customer's experience and can be missed if they close the tab after paying. Mark the order paid from the…
Do I need separate code to handle TRC-20 versus ERC-20 payments?No. Your fulfilment logic waits for the same invoice.paid webhook, verifies the HMAC signature over the raw bytes, and credits to one balance regardless…
Do I need to hold Bitcoin or run a node to accept it?No. halfin provides the Bitcoin deposit address, watches the chain, and credits the invoice once it confirms — you never run a node or manage keys for the…
Do I need to run a blockchain node or hold private keys to set up the gateway?No. The gateway watches the supported chains for you — Bitcoin, Ethereum and ERC-20, Base, Arbitrum, Polygon, BNB Smart Chain, Tron, the XRP Ledger, and…
Do I need to run a Solana node or manage SPL token accounts to accept payments?No. halfin provides the Solana deposit address, watches the chain, and credits the invoice once it confirms — you never run a node, and the SPL…
Do I still need idempotency if I verify the signature?Yes — they solve different problems. Verification proves an event is real; idempotency makes acting on a real event safe to repeat. Delivery is at least…
Do payouts move funds the moment my loop submits them?No. Each payout enters a pending-approval state and is released from the dashboard before funds move. That keeps the programmatic path that stages the run…
Does a failed payout mean the money left my balance?No. payout.failed is a terminal outcome that means the line reached a dead end and no funds were disbursed for it. There is nothing to claw back or…
Does halfin charge the network fee?No. The network fee — gas on EVM chains, the byte-priced fee on Bitcoin — is paid to the chain's validators or miners as the incentive to include your…
Does halfin charge the network fee, or is that separate?The on-chain network fee — gas, a Bitcoin transaction fee, a Solana lamport charge — is set by the blockchain itself and paid to its validators or miners…
Does halfin guarantee custody of my funds?halfin's custody story is signing, scoped permissions, and an audit trail — not a custody guarantee beyond those controls, and nothing here is legal, tax…
Does passing KYB make my business regulated or compliant?No. KYB clears your account to operate with the processor; it does not confer a license or a regulated status on your business, and it is not a…
Does settlement work differently on each chain?The mechanics differ — each chain has its own confirmation threshold and crediting is reorg-aware — but your integration does not. You act on the same…
Does testing in the sandbox require real on-chain transfers?No. The sandbox lets you create invoices, drive them through their full lifecycle, exercise your webhook handler, and rehearse payouts without a single…
Does the confirmation wait change the amount the customer pays?No. The payable asset amount is locked when the invoice activates, and the invoice carries an expiry window. A customer who pays inside the window settles…
Does the rail change how I reconcile a payment?No. The fiat anchor on the invoice is the source of truth regardless of which network the payment arrived on, so a confirmed payment maps back to the…
Does the travel rule apply to me?The travel rule is the obligation, in many jurisdictions, to pass certain originator and beneficiary information alongside transfers of value above a…
Does USDT on Ethereum cost me more to accept than on Tron?No. Network (gas) fees are paid by the sender to the chain, not to halfin or to you, so an Ethereum gas spike does not raise your cost of accepting the…
Does using halfin make my business compliant?No — compliance is a process, not a status a payment platform confers on you. halfin operates the controls inside the product: KYB verification at…
Ethereum gas fees are high — can my customers pay somewhere cheaper?Yes. The fee is a property of the network, not the asset. halfin runs gates on EVM L2s — Base, Arbitrum, and Polygon — where fees are a fraction of…
How do I add crypto payments to my existing website?Three steps. Create an invoice server-side with your fiat price (the API key stays on your server), then either redirect the customer to the hosted…
How do I avoid double-counting a payment during reconciliation?halfin delivers webhooks at least once, so the same event can arrive more than once carrying the same stable event id. Record processed event ids and make…
How do I force a single network when a wallet can only receive on one?Create a fixed-asset invoice and set the currency to USDT_TRC20 or USDT_ERC20 directly instead of using a fiat anchor. That pins both the asset and the…
How do I get a sandbox and test API keys for halfin?Both come from the merchant dashboard. Switch into the sandbox environment and create a test API key there, scoped to what your integration does…
How do I handle a customer who underpays or lets the invoice expire?Both arrive as their own signed webhook. An invoice.underpaid records the shortfall against the quote — do not extend; ask for the remainder or void the…
How do I keep a retried payout from paying twice?Carry a stable idempotency_key on each payout line. A mass payout fans out lines over a single POST /api/v1/payouts request, and re-submitting the same…
How do I keep accounting sane across many chains?Anchor every invoice to a fiat amount. You state the amount in USD or EUR with deferred pricing; the customer settles the equivalent in any supported…
How do I keep an auditable record of every balance movement?Drive your records from signed webhook events rather than polling or optimistic updates. Events such as invoice.paid and payout.completed report movements…
How do I keep my store priced in USD or EUR if crypto prices move?Create each invoice anchored to fiat — send the Magento order grand total as amount_fiat with the store's fiat_currency. halfin computes the payable…
How do I keep the amount correct when USDT lives on three networks?Create a fiat-anchored invoice with amount_fiat and fiat_currency (for example "49.00" USD) rather than hardcoding a USDT figure. halfin computes the…
How do I keep the amount stable when I bill in dollars?Create the invoice with a fiat amount and currency (amount_fiat and fiat_currency, both strings). halfin quotes the USDC equivalent and locks that quote…
How do I keep the dollar amount stable while BTC's price moves?Create a fiat-anchored invoice: send amount_fiat and fiat_currency (for example 49.00 USD). halfin computes the payable BTC amount and locks that rate…
How do I keep the dollar amount stable while ETH's price moves?Create a fiat-anchored invoice: send amount_fiat and fiat_currency (for example 49.00 USD). halfin computes the payable crypto amount and locks that rate…
How do I keep the subscription price stable when crypto prices move?Price the plan in fiat and create each cycle's invoice with amount_fiat and fiat_currency. halfin computes the payable asset amount and locks that rate…
How do I know a payout actually went through?Reconcile from signed webhook events, not from the POST response. halfin sends an HMAC-signed payout.completed when a payout settles and payout.failed…
How do I know each payout actually settled?Reconcile from signed webhooks, not by polling. payout.completed fires when a payout settles under the chain's confirmation threshold with reorg-aware…
How do I know the customer actually paid?Confirm on the webhook, not on the redirect. invoice.paid fires when the invoice settles under the chain's confirmation threshold with reorg-aware…
How do I know the exact shortfall or excess?Read it off the invoice object on the event. halfin tracks the amount expected against the amount actually received on-chain and records the difference…
How do I make sure a 'paid' webhook is genuine and not forged?Verify the HMAC signature before you act. Recompute the HMAC over the exact raw request bytes with your endpoint's signing secret, compare it to the…
How do I reconcile an underpaid, overpaid, or reversed invoice?Each is a first-class reconciliation event, not a failure. invoice.underpaid records a real but insufficient payment — hold the order and request a…
How do I retry a failed payout without paying the recipient twice?Resubmit the line with the same idempotency_key it carried originally. Because the failed line never settled, halfin creates the payout on the retry; and…
How do I stop a double-click from creating two invoices?Attach an idempotency_key in the request body derived from your own order id — for example order-10472. If halfin sees that key again from a retried…
How do I stop a double-submitted checkout from creating two invoices?Pass an idempotency_key in the invoice request body — it is a snake_case body field, not an HTTP header — derived from a stable identifier like the…
How do I stop a recipient from being paid twice?Give every payout a deterministic idempotency_key derived from your own records — for example account id joined with the payout period, like…
How do I stop a refund from being sent twice?Give every refund a deterministic idempotency_key derived from your own records — for example order_8841:refund. If halfin sees that key again, from a…
How do I test that my webhook handler is correct?Register a webhook endpoint and signing secret in the dashboard, point it at your test build, and prove three things. First, verify the HMAC over the raw…
How do I verify the webhook is really from halfin?Recompute an HMAC over the exact raw request body (read php://input before PrestaShop reparses it) using your endpoint's signing secret, then compare it…
How do idempotency keys stop me from paying an affiliate twice?Each payout line carries an idempotency_key you derive from the payee id and the cycle — deterministic, never random. If your job crashes or an operator…
How do the platform's controls help with a compliance review?They produce an attributable record. Payouts are drafted and then separately approved by an operator before anything is signed, with that authorization…
How does my backend find out a payment arrived?Through an HMAC-signed webhook. An invoice payment raises invoice.paid (or invoice.underpaid / invoice.overpaid), and a confirmed deposit to a static…
How does my backend know the invoice was paid?Through a signed webhook, not polling. halfin POSTs an HMAC-signed invoice.paid event to your endpoint once on-chain confirmations reach the chain's…
How does my system find out a refund went through?A refund is bound to the invoice it was issued against, so you reconcile it by re-reading that invoice and reading the operation log, which records the…
How does the crypto payment connect back to the Shopify order?Carry the Shopify order id on the invoice you create (for example in a field you control), then reconcile from the webhook. When halfin POSTs the signed…
How does the Magento order get marked paid?From a signed webhook, not from the browser redirect. halfin POSTs an HMAC-signed invoice.paid event to a controller on your store; you verify the…
How does the WooCommerce order get marked paid?From a signed webhook, not from the browser redirect. halfin POSTs an HMAC-signed invoice.paid event to an endpoint on your store; you verify the…
How long does a customer have to pay an invoice?Until the expiry stamped at activation. The expiry bounds the window during which the locked quote is valid. Pay inside it and the asset amount shown…
How many confirmations does halfin wait for before marking an invoice paid?It depends on the chain — there is no single number. halfin sets a confirmation threshold per chain to match how that network settles, because block…
If I don't hold the keys, what is the custody boundary exactly?It is signing, permissions, and audit — nothing beyond that is promised. Permissions mean keys are scoped so a leaked credential can only do its one job…
If there are no chargebacks, how do I handle a legitimate refund?You send the money back deliberately, as a payout. Issue a refund to an address the customer controls with currency, amount as a string, destination, and…
If webhooks are signed and reliable, why also reconcile via the API?Because delivery is at least once, not exactly once, and the webhook is a trigger rather than the ledger. Dedupe on the stable event id so a redelivered…
Is a crypto refund the same as a chargeback?No. A chargeback is a card-network reversal that an acquirer can force after a sale; crypto has no equivalent, because a confirmed on-chain payment is…
Is a payment link a separate halfin product?No. A payment link is just an invoice's hosted checkout URL on checkout.thehalfin.com. You create an invoice with POST /api/v1/invoices, read the hosted…
Is Bitcoin too volatile to accept as a payment?Not when you anchor the invoice to fiat. The volatility risk people warn about only bites if you quote a fixed BTC quantity and let the dollar value drift…
Is halfin licensed or regulated?halfin does not present itself as licensed or regulated as a status, and you should not infer one. It provides crypto payment infrastructure and operates…
Is there a batch endpoint for mass payouts?No. halfin does not expose a /payouts/batches endpoint. A mass payout is a fan-out over the single-payout API: you loop POST /api/v1/payouts once per…
Is there a bulk endpoint for paying many affiliates at once?No — there is no /payouts/batches endpoint. A payout run is a fan-out: you loop over your payees and submit one POST /api/v1/payouts per payee, each line…
Is there a halfin button widget or script I embed?No. A pay button is your own button plus a small backend route. The button calls your route, your route creates an invoice through the REST API with your…
Is there an invoice.activated webhook event?No. The real invoice events are invoice.confirming, invoice.paid, invoice.overpaid, invoice.underpaid, invoice.expired, invoice.late_deposit, and…
Is there an official halfin Magento extension?No. halfin does not publish a packaged Magento (Adobe Commerce) extension on the Marketplace. You accept crypto on Magento by building a small custom…
Is there an official halfin PrestaShop module to install?No. halfin does not ship a packaged PrestaShop plugin. You build a small custom payment module against the public REST API: it registers the…
Is there an official halfin Shopify app or plugin?No. halfin does not publish a Shopify app, and Shopify reserves its native checkout payment step for Shopify Payments and approved gateways, so there is…
Is there an official halfin WooCommerce plugin?No. halfin does not publish a packaged WooCommerce extension. You accept crypto on WooCommerce by building a small custom payment gateway against the…
Is TRC-20 USDT different from ERC-20 USDT?It is the same stablecoin — one dollar of USDT either way — issued on two different networks. TRC-20 is the token standard on Tron; ERC-20 is the standard…
Is USDC on Solana the same as USDC on Ethereum or Base?It is the same dollar-denominated stablecoin brand, but a different on-chain mint. USDC on Solana is an SPL token; USDC on Ethereum and Base are ERC-20…
Should I act on invoice.confirming or wait for invoice.paid?Use invoice.confirming only to drive a UI waiting state — it means a real payment is climbing toward the threshold, not that it is final. Fulfil the order…
Should I compute the crypto amount myself, or let the invoice do it?Let the invoice do it. halfin locks the conversion rate when the invoice activates and pins the payable asset amount for the life of that invoice. If you…
Should I convert automatically or manually?Use both. Turn on automatic conversion for the steady stream of invoice and checkout revenue, so each payment settles into your reference stablecoin on…
Should I grant access from the success redirect or the webhook?The webhook, always. The success redirect can be missed if the customer's browser tab closes after they pay on a phone. halfin POSTs an HMAC-signed…
Should I grant access on the redirect or the webhook?The webhook, always. The success redirect can be missed if the customer's browser tab closes after they pay on a phone, so treating it as your paid signal…
Should I poll the API to find failed payouts?No — reconcile from the payout.failed webhook. Subscribe to it alongside payout.completed, verify the HMAC over the raw bytes with a constant-time compare…
Should I reconcile by polling the API or by webhooks?Drive reconciliation off signed webhooks as your real-time source of truth, and use the REST API only for recovery — backfilling a window your endpoint…
Should I refund an overpayment or credit it?Either, as long as you decide once and state it in your terms. Refunds are a first-class halfin primitive, so you can fulfil the order and refund the…
Should I rely on the redirect or the webhook to confirm payment?The webhook, always. The success redirect can be missed — a customer who pays on a phone may never return to your success page. halfin POSTs an…
Should I rely on the success redirect or the webhook to mark an order paid?The webhook, always. The success redirect can be missed when a customer pays from a phone wallet and the browser tab is gone. halfin sends an HMAC-signed…
Should I use an invoice or a static deposit address?Use an invoice when you are billing a specific amount tied to an order, a subscription cycle, or a single bill — it locks the rate at activation, sets an…
Should I use hosted checkout or build my own?Use hosted checkout unless a redirect genuinely breaks your product. Hosted checkout is a finished page at checkout.thehalfin.com — you create the…
Should I use hosted checkout or build my own payment page?Hosted checkout is the smallest integration: the create-invoice response includes a URL on checkout.thehalfin.com, and halfin owns the asset picker, QR…
Solana is fast — can I fulfil the order the moment the transaction appears?No. Solana confirms quickly, but a payment is final only when the invoice reaches paid — not when the transaction is first seen on the network. halfin…
Then what does 'convert crypto to fiat' actually mean on halfin?It means settling into a USD-stable asset. Balance conversion takes the mix of assets your customers paid with and converts them toward a stablecoin you…
What actually changes when I move from sandbox to live?Only the API key your code loads. The sandbox and production contracts are identical, so the same handler that passed every sandbox test runs in…
What address does a refund go to, and what if I send it to the wrong one?Send the refund on the network the original payment arrived on, to a destination you have validated — the paid invoice already carries the asset and…
What do I do when a customer underpays or overpays?Treat both as real states, not failures. invoice.underpaid means a genuine payment arrived below the amount due — hold the order and request a top-up…
What documents do I need for KYB?The exact requirements depend on your jurisdiction and the processor's compliance program, and you will see the specific list in the onboarding flow…
What fields do I send to create a crypto invoice?For the common case, send a fiat anchor: amount_fiat as a string, fiat_currency as a fiat code (for example…
What goes in a single payout line?Four fields: currency (a crypto asset code such as USDT or USDC), amount as a string, destination (the payee's wallet address), and idempotency_key. The…
What happens if a customer pays too little or too late?An underpaid invoice records the shortfall against the locked quote, so you can request the remainder or settle partially under your own policy instead of…
What happens if a customer pays USDT on the wrong network?Sending USDT on one network to an address for a different network loses the funds, which is why the checkout must show the address that belongs to the…
What happens if a customer sends slightly too little USDC?The invoice is marked underpaid and the shortfall is recorded against it rather than discarded — commonly the customer's wallet quoted the amount before a…
What happens if a customer underpays or overpays the order?halfin records both against the invoice and sends invoice.underpaid or invoice.overpaid webhooks. Map underpaid to holding the order with an order note…
What happens if some lines in the run fail?Partial failure is reported per line and is the normal case, not a reason to abort. A bad address, a dust-threshold amount, or an unreceivable currency…
What happens if the link expires before the customer pays?The invoice emits invoice.expired and stops being payable, because the rate lock only holds for a bounded window. Generate the link close to when you send…
What happens to a payment in an asset that can't be converted?The original asset is credited as-is and stays fully visible in your balance — nothing is lost, hidden, or stranded. Automatic conversion is fail-open…
What happens to an asset that can't be auto-converted to my settlement target?It is credited as-is and stays visible in your balance — nothing is lost or hidden. Automatic conversion is fail-open: it only fires when a supported…
What if a customer sends USDC on the wrong network?Because the two rails are separate, USDC sent on a network your invoice was not watching lands on a rail you are not tracking against that invoice. The…
What if my webhook endpoint was down and I missed events?Use the REST API as the recovery layer. For any invoice or payout your ledger still shows as non-terminal past the window it should have settled, read it…
What if the customer sends too little or too much?Both are recorded against the invoice rather than discarded. An underpaid invoice surfaces the shortfall — often a stale quote or an exchange withdrawal…
What if the customer sends too little or too much BTC?Both are recorded against the invoice rather than discarded. An underpaid invoice surfaces the shortfall — often the customer paid the network fee out of…
What if the webhook never arrives?Reconcile against the API. Run a scheduled sweep over orders still awaiting payment and read each invoice back by its id — if the API says paid but your…
What is a reorg, and can it reverse a payment I already saw?A chain reorganization happens when the network briefly disagrees on the latest blocks and then discards one; a transaction that lived only in the…
What is KYB and when does it happen?KYB — know your business — is the verification of your company before it can transact, the business-side counterpart to the KYC checks consumers go…
What is KYB in the context of crypto payments?KYB — Know Your Business — is the business-level verification a crypto payment processor runs at onboarding before your account can transact. It is the…
What is the actual verification I have to perform?Recompute an HMAC over the exact raw request bytes using your endpoint's signing secret, then compare that digest to the signature header with a…
What is the cheapest network to send USDT or USDC on?It depends on the asset and what the recipient can receive, not on a fixed ranking. For USDT, Tron (TRC-20) and Solana carry the same dollars at a far…
What is the difference between the sandbox and going live?The sandbox mirrors production — same invoice lifecycle, same webhook envelope, same signature scheme, same per-chain confirmation behavior — but you pay…
What is the first webhook event I'll see for a live invoice?invoice.confirming — fired when a matching deposit is on-chain and confirmations are accumulating toward the per-chain threshold. There is no…
What is the single most important security step in a halfin integration?Verify the HMAC signature on every webhook before you act on it. The endpoint URL is public, so anyone can POST a body claiming "invoice.paid". Recompute…
What's the difference between a fiat-anchored and a fixed-asset invoice?A fiat-anchored invoice names a fiat amount (for example 49.00 USD) and the customer pays the crypto-equivalent at the rate halfin locks when the invoice…
What's the equivalent of 'keeping a small float hot' on halfin?Two things. First, scope your API keys so the credential any given service holds can do as little as possible — an invoicing key cannot initiate a payout…
What should I do when a customer underpays?Pick a policy and apply it from the invoice.underpaid event: request a top-up of the recorded shortfall and hold the order until it is covered; settle…
What stops a forged 'paid' webhook from granting free access?Signature verification. Your webhook endpoint URL is public the moment you register it, so anyone can POST arbitrary JSON to it. Before acting on any…
What stops disputes if there's no issuer to mediate?Operational hygiene, mostly. Fiat-anchored invoices map every confirmed payment to the exact amount billed and the order it belongs to, so 'I paid but you…
When does the exchange rate lock?At activation — the moment the invoice goes live and is presented for payment. Creating with deferred:true defers the lock to that point so the payment…
When is a Bitcoin payment safe to fulfil?When the invoice reaches paid — not when the transaction is first seen in the mempool. halfin applies Bitcoin's per-chain confirmation threshold and…
When is a crypto payment actually final?When the invoice reaches its paid state, not when a deposit is first seen. halfin waits for the per-chain number of confirmations before marking an…
When is a crypto payment final enough to act on?Once it has met the chain's confirmation threshold. A transaction is first seen in the mempool, then included in a block, then confirmed as more blocks…
When is a crypto payment safe to act on?On the invoice.paid event, not on first sight of a transaction. invoice.paid means the payment confirmed past the chain's per-chain threshold under…
When is a USDT payment actually final?When the invoice reaches paid. A transfer must land in a block and accumulate enough confirmations that a reorg is no longer a realistic risk, and that…
When is an Ethereum payment safe to fulfil?When the invoice reaches paid — not when the transaction is first seen in the mempool. halfin applies the chain's per-chain confirmation threshold and…
When is it safe to ship the order or grant access?When the invoice reaches paid, not when a transaction first appears on-chain. halfin applies a per-chain confirmation threshold with reorg-aware…
When should I mark the PrestaShop order as Payment accepted?Only when a verified invoice.paid (or invoice.overpaid) webhook arrives — never on the redirect back from checkout. The redirect means the customer…
When should I mark the Shopify order paid — on the redirect or the webhook?The webhook, always. The success redirect can be missed if the buyer's tab closes after paying on a phone, and a payment is not final until it clears the…
When should I use a new idempotency_key instead of the original?Reuse the original key whenever it is the same logical payment — for example after correcting a typo'd address or topping up a short balance. Mint a new…
Where do I put the idempotency key — a header or the body?The body. halfin's create-invoice request takes only X-API-Key and Content-Type as headers; the idempotency_key is a snake_case field in the JSON body…
Where do I set the idempotency key on the create call?As an idempotency_key field in the JSON request body — it is a snake_case body field, not an Idempotency-Key header. The only request headers you set are…
Where does the idempotency key go — a header or the body?The body. halfin's only request headers are X-API-Key and Content-Type; the idempotency key is a snake_case field, idempotency_key, inside the JSON body…
Which asset should I hold my treasury in?For most merchants, a stablecoin — USDT or USDC — on the network your payouts already use. A stablecoin balance is the closest on-chain analogue to…
Which chain should I default the customer to?Match the default to the payment's shape and your payers' habits. Lead with a low-fee stablecoin rail for small recurring payments so the network fee is…
Which chains and assets can I actually accept?The real supported surface: BTC on Bitcoin; ETH and ERC-20 on Ethereum; native assets on Base, Arbitrum, Polygon, and BNB Smart Chain; USDT on Tron…
Which crypto can my PrestaShop customers pay with?Whatever halfin's hosted checkout supports: stablecoins like USDT (Tron, Ethereum, Solana) and USDC (Ethereum, Base, Solana), plus native assets including…
Which cryptocurrencies can a Shopify store accept this way?The assets halfin actually settles: BTC; ETH and ERC-20 tokens; USDT on Tron, Ethereum, and Solana; USDC on Ethereum, Base, and Solana; SOL and SPL…
Which cryptocurrencies can customers pay with at checkout?The customer chooses on the hosted checkout page from the assets halfin supports: USDT on Tron, Ethereum, or Solana; USDC on Ethereum, Base, or Solana…
Which do customers actually prefer?It depends on the audience. Dollar-movers — contractors, traders, marketplaces, SaaS, affiliate payees — default to stablecoins like USDT and USDC because…
Which event names should my switch statement handle?The canonical set: invoice.confirming, invoice.paid, invoice.underpaid, invoice.overpaid, invoice.expired, invoice.late_deposit, invoice.deposit_reversed…
Which events do I reconcile against?For invoices: invoice.paid for settlement, invoice.underpaid and invoice.overpaid for amount mismatches, invoice.expired for an unpaid lapse…
Which has lower fees, stablecoins or Bitcoin?Network fees are a property of the chain, not a halfin charge, and they shift with congestion — so there is no fixed answer. Stablecoins on Tron, Solana…
Which invoice and payout events should I rehearse before going live?For invoices: invoice.confirming, invoice.paid, invoice.underpaid, invoice.overpaid, and invoice.expired — there is no 'activated' event, so wire against…
Which rail is cheaper for my customer to pay on?Base. It is built as a low-cost Ethereum L2, so the gas a customer pays to send USDC is a minor characteristic rather than a deterrent — which matters…
Which scope should my first API key have?Give each key only the permissions its service needs. A storefront that creates invoices gets an invoicing-scoped key; a reporting job gets read-only; a…
Which USDT network should I accept as a merchant?Accept both and let the payer choose. A fiat-anchored invoice presents the supported networks and the customer settles on whichever they hold, so you do…
Which USDT network should I accept first?TRC-20 on Tron, if you only enable one. Its transfer fee is small and predictable, and it is what a large share of USDT holders default to, so it covers…
Which webhook events fire for an underpayment or an overpayment?invoice.underpaid fires when a real, confirmed on-chain payment arrives below the amount due, and invoice.overpaid fires when the invoice settles with a…
Who is allowed to issue a refund in halfin?Refunds run through operator approval and sit behind scoped permissions, the same model that governs payouts. You decide which operators and which API…
Why can't the button call the halfin API directly?Because the invoice create call carries your API key in the X-API-Key header, and any key shipped to the browser can be lifted from the network tab and…
Why did my customer's deposit arrive slightly short of the invoice amount?Almost always because the customer's wallet or exchange deducted the network fee to broadcast the payment, so a little less reached the chain's view of…
Why did my payout fail in the first place?Common causes are an invalid or unreceivable destination (a malformed address, or an asset sent on a network that address cannot receive), an insufficient…
Why do Ethereum and Bitcoin fees jump around so much?Both have a competitive fee market: when the network is congested, transactions bid up the price to be included in a block, and the fee falls again when…
Why does a crypto payment processor need to verify my business?A processor sits in the flow of funds, and that position carries an obligation to know who is using its rails and for what. KYB is how that obligation is…
Why does my signature fail even though the secret is correct?Almost always because you hashed a re-serialized body instead of the raw bytes. A framework that parses JSON and then re-encodes it changes whitespace and…
Why does the create-invoice request use amount_fiat and not currency: USD?A fiat-anchored invoice puts the fiat amount in amount_fiat and its code in fiat_currency, and halfin computes and locks the payable crypto amount at…
Why does the network my stablecoin sits on matter?The same dollar lives in different places — USDT as TRC-20, ERC-20, or Solana SPL; USDC as ERC-20, Solana SPL, or on Base — and network fees differ…
Why does the same payout cost a different fee at different times?Network fees track congestion in real time. When many transactions are bidding for the same limited block space — a busy trading day or a network-wide…
Why fulfil off the webhook instead of the success redirect?The redirect back to your site can be missed — a customer who pays on a phone may never see the success page if the wallet app foregrounds and the browser…
Why is my customer's payment still pending after their wallet says it was sent?A broadcast transaction is unconfirmed until it is written into a block and enough further blocks build on top of it. Until the payment reaches the…
Why is the network fee different on different chains?Each blockchain has its own throughput, block size, and fee mechanics, so the baseline cost to move value is simply not the same across them. Some chains…
Why might the same underpaid or overpaid event arrive 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 must I verify the webhook signature before doing anything?Because the endpoint URL is public the moment you register it, so anyone can POST arbitrary JSON to it. The HMAC signature is the only thing that…
Why must the comparison be constant-time?A normal string comparison short-circuits at the first differing byte, and the time it takes leaks how many leading bytes matched — enough for an attacker…
Why should I use separate API keys instead of one?To limit blast radius. halfin issues keys with scoped permissions, so the storefront holds an invoicing-only key, reporting holds a read-only key, and the…
Why would I rebalance across networks if I already hold one stablecoin?Because the same stablecoin lives on several networks and a payout draws from the balance on the network it is sent over. You can hold USDT on Tron…
Will a lower-fee chain make my payments less safe?No. halfin credits every chain reorg-aware and waits for that chain's confirmation threshold before marking a payment settled, so Tron, Solana, and Base…
With halfin, do I run my own hot or cold wallet?In day-to-day use you operate against a halfin balance rather than holding raw private keys and deciding which is hot. Confirmed invoices accrue to it…