Blockchain Payment Integration for Developers: Start Here

Your path through the portal

Key points

Encode payment requests with a standard URI (BIP-21 or EIP-681) instead of asking people to type addresses.
Seen in the mempool is not paid; decide a confirmation or finality threshold per network and amount.
Treat every webhook as possibly duplicated, delayed or forged: verify the signature and process idempotently.
Keep private keys out of application servers and never ask users for a seed phrase.
Design for exceptions from the start: underpayment, overpayment, expiry and the wrong network.

The questions to answer before you write code

How is the payment request encoded? Address, amount, asset, network and an order reference.
When is a payment final enough to ship? A rule per network and per amount band.
How do events reach your system? Your own node or indexer, or webhooks from a provider.
What happens to edge cases? Partial payments, late payments, overpayments, refunds.
Where do keys live and who can move funds? The answer shapes your whole architecture.

Payment requests: BIP-21 and EIP-681

BIP-21 defines a bitcoin: URI that carries an address and optional parameters such as amount, label and message. EIP-681 defines an ethereum: URI that can describe a plain transfer or a token transfer call, including the chain and the amount. Either can be rendered as a QR code.

Two practical points. First, include enough information for a wallet to pre-fill the payment, so nobody types an address. Second, keep your own order reference server-side and map it to the receiving address or request, because the chain will not carry your invoice number for you. Try both formats in the payment request QR sandbox, and read payment request standards for the details.

Confirmations and finality

A transaction in the mempool is a broadcast intention, not a payment. It becomes part of the chain when included in a block, and grows more settled with each further block or, on proof-of-stake networks, once it is finalized.

As rough illustrative defaults: Bitcoin targets an average block interval of about 10 minutes and many recipients wait for several confirmations. Ethereum's proof-of-stake uses 12-second slots and 32-slot epochs, and finality typically takes about two epochs, roughly 12.8 minutes. Real timing varies by network and congestion, so make thresholds configurable.

A simple order state model
State	Trigger	What your system does
awaiting_payment	Request created	Show amount, address and expiry
detected	Transaction seen, unconfirmed	Tell the customer it is pending; do not ship
confirming	Included in a block	Count confirmations or wait for finality
paid	Threshold reached, amount correct	Fulfil the order once, record hash and CAD value
exception	Underpaid, overpaid, late or wrong asset	Route to a person with a clear playbook

Watch it happen

The transaction lifecycle sandbox steps a simulated payment through these states with adjustable block times. It uses simulated data only.

Webhooks, signatures and idempotency

If you rely on a provider's webhooks, assume they can arrive twice, out of order, late or not at all, and that someone may send you fake ones.

Verify each payload's signature, typically an HMAC over the raw body with a shared secret, before parsing it. Store an event ID or idempotency key and ignore repeats. Reconcile periodically against the chain or the provider's API, so a missed event does not leave an order stuck. The webhook explorer lets you replay and tamper with sample events to see how your handler should respond, and webhooks and payment events covers the patterns.

Keys, security and what the sandbox will never ask

Keep signing keys off web and application servers; receiving payments does not require a private key on the server.
Generate receiving addresses from an extended public key or a provider's API, not by storing private keys.
Use testnets for development, and label any test environment clearly.
Never request, log or store a user's seed phrase or private key. The site's sandbox never asks for either, and nothing legitimate should.
Log the transaction hash, amount, asset, network, CAD value and rate source for every payment; finance will need them.

Card checkout still has PCI DSS duties

If your checkout also takes cards, PCI DSS still applies to anyone who stores, processes or transmits cardholder data. PCI DSS v4.0.1 (June 2024) kept March 31, 2025 as the effective date for the future-dated requirements introduced in v4.0, including 6.4.3 and 11.6.1, which cover scripts on payment pages. There is no direct PCI equivalent for accepting crypto-assets; key management, wallet security and, depending on the model, FINTRAC or RPAA obligations take its place. See PCI DSS vs crypto.

Suggested order through the sandbox

Build and scan a request in the payment request QR sandbox.
Step a payment through the transaction lifecycle sandbox and note where your state machine would act.
Replay duplicate, delayed and badly signed events in the webhook explorer.
Create an invoice in the invoice builder sandbox and map its reference to a receiving address.
Hand the record format to your accountant before going near real funds.

Questions people ask

How many confirmations should I wait for?

There is no single answer. Set a threshold per network and amount, make it configurable, and use the illustrative block and finality times as a starting point, not a guarantee.

Does the sandbox use real funds or real wallets?

No. The sandbox is simulation-only, uses simulated or testnet-style data, and never asks for a private key or seed phrase.

Do I need a private key on my server to receive payments?

No. Receiving only needs an address; derive addresses from public key material or a provider's API and keep signing keys elsewhere.

Why verify webhook signatures if the endpoint is secret?

Endpoint URLs leak. A signature check, such as an HMAC over the raw body, is what proves the event came from the sender you expect.

Sources

Reviewed October 30, 2026. Educational information only; not financial, legal, tax or investment advice. This site does not process payments or hold funds.