FAQ
General
What is Coinsnap?
Coinsnap is a Bitcoin payment processor. It lets you accept Bitcoin and Lightning Network payments in your application without managing wallets, nodes, or blockchain infrastructure yourself.
Is Coinsnap custodial?
No. Coinsnap forwards payments directly to your configured Bitcoin wallet. Coinsnap does not hold your funds.
Which countries does Coinsnap support?
Coinsnap works globally. Bitcoin has no geographic restrictions — anyone with a Bitcoin wallet can pay an invoice regardless of their location.
What currencies can I invoice in?
You create invoices in any of the supported currencies: EUR, USD, GBP, CAD, CHF, CZK, PLN, JPY, RUB. Coinsnap converts the amount to Bitcoin at the current market rate and locks it for the invoice expiry window (typically 15 minutes).
You can also invoice directly in BTC or SATS if you prefer to denominate in Bitcoin rather than fiat.
Do I need to understand Bitcoin to integrate Coinsnap?
No. You work with familiar concepts: create an invoice for a fiat amount, redirect the customer, handle a webhook. Coinsnap handles all the Bitcoin and Lightning complexity.
How do I get started?
- Create an account at app.coinsnap.io
- Create a store and configure your receiving wallet
- Generate an API key
- Follow the Quickstart
Is there an SDK?
Not currently. The Coinsnap API is a standard REST API — a few fetch or curl calls is all you need. See the Node.js and PHP integration pages for ready-to-use client code.
Payments
What payment methods does Coinsnap support?
Every Coinsnap invoice supports two payment methods simultaneously:
- Lightning Network — instant, near-zero fees, recommended for most payments
- On-chain Bitcoin — confirmed after ~1 block (~10 minutes), better for larger amounts
The customer chooses which method to use. You receive the same Settled webhook either way.
How fast do payments confirm?
| Method | Confirmation time |
|---|---|
| Lightning | 1–3 seconds |
| On-chain | ~10 minutes (1 block) |
What happens if a customer underpays?
The invoice expires with additionalStatus: Underpaid and you receive an Expired webhook. Do not fulfill the order automatically — flag it for manual review.
What happens if a customer overpays?
Overpayments are accepted and the invoice settles normally. The full received amount is forwarded to your wallet. You can choose to refund the difference manually.
Can a customer pay after the invoice expires?
No. Expired invoices cannot be paid. If the customer returns after expiry, create a new invoice. See the Checkout Flow guide for how to handle this.
How long are invoices valid?
The default expiry is 15 minutes. This is the window during which the exchange rate is locked.
What is the minimum payment amount?
There is no hard minimum, but Lightning payments below 1 sat ($0.001) may fail depending on the customer's wallet. For practical purposes, keep invoices above €0.10.
Can I accept recurring payments?
Not with invoices directly — each invoice is single-use. For recurring billing, create a new invoice for each billing cycle. Pay Links can be reused multiple times but do not support scheduled billing.
Are payments reversible?
No. Bitcoin payments are irreversible by design. There are no chargebacks. This is one of the main advantages of accepting Bitcoin for digital goods and services.
What exchange rate does Coinsnap use?
Coinsnap fetches live rates from major exchanges at invoice creation time. The rate is locked for the invoice expiry window. You can retrieve the current rate via the Exchange Rate endpoint.
Integration
How do I confirm a payment server-side?
Always use webhooks. The redirect to your redirectUrl is a UX convenience — it can be bypassed. Register a webhook endpoint in the Coinsnap dashboard, verify the X-Coinsnap-Sig header, and handle the Settled event.
See Webhooks for full examples.
Why is my webhook signature verification failing?
The most common cause is parsing the request body before verifying. You must verify against the raw bytes of the body. In Express, use express.raw({ type: 'application/json' }) instead of express.json().
Other causes:
- Using the API key instead of the webhook secret (they are different)
- Trailing whitespace or encoding differences in the secret
- The body was modified by middleware before reaching your handler
Can I use Coinsnap on localhost?
Yes. Use ngrok or Cloudflare Tunnel to expose your local server for webhook delivery. See Webhooks → Local testing.
Do I need to poll for payment status?
No. Use webhooks. If you need to display live status in a browser (e.g. a waiting page), redirect the customer to the checkoutLink — Coinsnap's hosted page updates in real time. Polling the API is unnecessary and wastes rate limit.
Can I build a custom payment UI instead of using the hosted checkout?
Yes. Use lightningInvoice and onchainAddress from the invoice response to render your own QR codes. Poll GET /invoices/{invoiceId} for status, or use webhooks. See the API Reference for the full response schema.
What is the difference between an invoice and a pay link?
| Invoice | Pay Link | |
|---|---|---|
| Use | Single payment | Reusable link |
| Expires | Yes (15 min default) | No |
| Unique per customer | Yes | No — shared URL |
| Best for | Checkout flow | Donation pages, tip jars |
How do I handle failed or invalid payments?
Listen for Expired webhooks. Do not auto-fulfill. For expired invoices, offer the customer a button to generate a new invoice. For underpayments (additionalStatus: Underpaid), flag the order for manual review.
Can I issue refunds?
Bitcoin payments are irreversible. Refunds must be handled manually — send Bitcoin directly to the customer's wallet address. Coinsnap does not have a built-in refund mechanism.
Is the API rate limited?
Yes. Rate limit details are returned in the response headers (X-RateLimit-Limit, X-RateLimit-Remaining). For high-volume use cases, cache exchange rates and avoid polling invoice status — use webhooks instead.