Crypto payment gateway integration into a website: from selection to implementation

Crypto Payment Gateway Integration: Where Payments Get Lost

Crypto payment gateway integration rarely breaks at the API level — it breaks at the junctions between payment steps.

The client selects an asset and network, sees an address, goes to the wallet, and does not return: the form does not track that the invoice was left, does not remind, and does not allow returning to the same address.

In analytics, such a drop-off appears as an abandonment at the checkout stage, so accepting crypto payments on a website looks operational right up to the point when conversion is calculated by funds actually received.

The second point is the exchange rate in the window between invoice creation and confirmation.

While the transaction is in the mempool, the fiat amount changes, and without an explicit rate-lock rule for a short window, the order receives either an underpayment or a refund of the difference.

Here the network fee also comes up: if it is deducted from the transfer amount, less than expected reaches the merchant — and the order is marked as an unsuccessful payment, even though the money has already been sent.

The third is confirmation of receipt. Until the required number of network confirmations is reached, the payment sits in an intermediate status, and during a chain reorganization it may roll back.

A gateway that closes an order on the first incoming event releases goods for which the money has not arrived. The reverse mistake is keeping the order open too long: the client does not understand whether it is paid or not.

Then payment reconciliation begins. While it is done manually, discrepancies accumulate where the payment reference lacks an order number or it does not match the database: the same address, similar amounts, close dates.

Plus double crediting, when a gateway notification is duplicated and the order is extended twice. We break down how this is closed at each step.

What Changes After Integration: Effect by Payment Step

Integrating a gateway changes not the very ability to pay in crypto, but the distribution of payments by status. Previously, some payments were lost between sending funds and order confirmation; now it is visible which failure reasons remain and what their share is. Below are metrics taken from gateway logs and the accounting system, not from impressions.

Share of Successful Payments and Failure Reasons

The main class of failures is not "the client changed their mind," but incomplete transactions: funds were sent to the address, the required number of confirmations was not awaited, and the tab was closed.

An invoice with a fixed amount and an address that lives for a set time brings such a client back to pay for the same cart.

The second source is a network mismatch: the payment goes to a parallel network and is not linked to the order.

Explicitly specifying the network in the invoice and checking the sender's address on the provider side turns this case into a clear message to the client instead of a stalled operation.

Gateways such as Coinbase Commerce return status for each invoice as a separate event, so the share of successful payments is calculated by fact, not by the number of support requests.

Crediting Time and Volume of Manual Reconciliations

While incoming payments are parsed manually from a statement, an order sits in "pending" status until the next business day.

A confirmation event closes this gap: the system records payment at the moment funds arrive, and crediting no longer depends on when an employee opens the register.

Accounting automation is built on linking the invoice identifier to the order: amount, network, fee, and transaction hash enter the database as a single record.

This eliminates double entry, and period reconciliation is done using a generated report, not a set of screenshots and messages.

Methods of Accepting Crypto Payments: Hosted Checkout, Link, Direct Interface

There are three methods of acceptance, and they differ not in the appearance of the "Pay" button, but in who holds the private keys and who is responsible for a stuck transaction.

Hosted checkout, a payment link, and direct integration provide different levels of control at different entry costs — the choice is determined by payment volume and readiness to maintain one's own infrastructure.

Hosted Checkout and Payment Link

Here the provider renders the payment page: it also locks the rate, accepts network confirmations, and sends us a status notification.

We add a call and handler to the website — usually several days of work, including amount reconciliation and protection against repeated notifications.

The limitations are honest: part of the revenue goes to the provider, the payment flow is hardcoded into its interface, and account limits and rules change without our involvement.

A payment link is good for invoices and one-off sales: the client receives an address, pays, and returns to an agreed page. It cannot handle mass flow — statuses have to be matched manually or reconciliation has to be modified separately.

Direct Integration and Your Own Wallet

Direct integration removes the intermediary: the website itself generates an address for each order, monitors incoming funds, and credits payment after the required number of confirmations.

Key storage moves to us — we keep them in a separate environment, not on the same server as the website, with limited access and an operations log. Such an environment is convenient to build on BTCPay Server or your own combination of a wallet and a network node.

Responsibility also moves to us: node monitoring, handling rate discrepancies, stuck transactions, and refunds.

This pays off at volume when the provider fee is already noticeable, but it requires engineering support — we analyze which option to choose in a specific case during the assessment stage.

Implementation Procedure: From Audit of Current Payments to Handover

Implementation proceeds in waves: first we understand how payment is structured now, then we build a fund flow scheme, configure the gateway, and run scenarios on a test environment.

The order is not accidental — if the audit is skipped, discrepancies will surface at the very first reconciliation, when some orders remain without status while the money has already arrived.

Audit of Current Payment Acceptance

1. Audit of payment acceptance. We collect a map: which payment methods are enabled, who initiates refunds, where order identifiers are stored, how incoming payments are matched to orders. The output is a list of discrepancies and points that must not be broken during migration.
2. Fund flow scheme. We fix the route from the client to the settlement account, who holds the keys, how limits are configured, and where fees go. We separately mark manual transfers so they do not remain outside accounting.
3. Gateway configuration. Connection on a test environment, access keys, return addresses, confirmation policy — how long we wait before shipment or crediting. We process gateway notifications with protection against reapplying the same event.
4. Payment scenario testing. We run successful payment, underpayment, overpayment, cancellation, timeout, refund, and repeated notification. After the test environment — several real payments of the minimum class and reconciliation of the result with the accounting system.
5. Training. Support operators and the finance team receive a procedure: how to read the operation status, what to do with a stuck transaction, whom to escalate to, and within what window.
6. Handover to support. We provide access, the operations log, the flow scheme, and an escalation channel to our engineers, so incident analysis does not begin with searching for contacts.

What Remains with You: Configurations, Schemes, Procedures

Project handover is not a final call, but a set of artifacts your team can use to continue working without us. Below is what exactly remains with the merchant: it is enough to change limits, add currencies, handle stuck operations, and pass an external audit.

Configurations and Access Matrix

• Gateway configuration with a comment for each parameter: list of networks and currencies, confirmation thresholds, limits per operation and per address, behavior for underpayment or overpayment.
• Access matrix: which roles can do what — view, initiate payment, sign, withdraw, rotate keys; the initiator and approver are separated so one account cannot withdraw funds.
• Fund flow scheme: the path from the client's wallet through hot and cold environments to crediting, including network fees, consolidation, and handling of "stuck" transactions.
• Gateway documentation: API methods, callbacks and their idempotency, error codes, operation statuses, requirements for request signing, and behavior for state discrepancies.

Procedures and Instructions

• Refund procedure: grounds, who approves, timelines, verification of the recipient address before sending, what to do when refunding to a non-working address.
• On-call shift instructions: checklist for a balance discrepancy, escalation order, actions when the node is unavailable or confirmations are delayed.
• Incident log template and alert list: which event wakes the on-call person, and which simply goes into the report.
• Key and wallet address rotation plan — with frequency and responsible person, so access does not live with one person for years.

Case: Share of Unsuccessful Payments Dropped Several Times

What It Was Like Before Implementation

The store accepted cryptocurrency manually: the client transferred funds to a shared wallet, and a manager reconciled incoming payments with requests in a spreadsheet.

Crediting delay reached several hours; on peak days, some transfers hung until the next business day — the buyer saw an eternal "awaiting confirmation" and left.

Accounting once a week matched network transfers with orders using the statement. One payment could be credited twice or lost, discrepancies were found after shipment, and the investigation took the team a whole day.

What Changed After

We integrated a gateway with automatic confirmation of transfers on the Ethereum network and a handler for incoming events.

Crediting now takes less than a minute after the required number of confirmations: the share of unsuccessful payments dropped several times, and waiting no longer depends on whether a manager is watching the screen.

Reconciliation is continuous, not once a week.

Each transfer is linked to an order number, duplicates are filtered by a unique operation attribute, so manual reconciliations have shrunk to selective checks of disputed cases — instead of hundreds of rows in a spreadsheet, a few records per day remain.

The case stopped being a story about "it became more convenient": crediting time, failure share, and volume of manual operations are visible in the gateway report and confirmed by reconciliation with accounting.

What to Do If a Crypto Payment Gateway Is Already Installed?

When a crypto payment gateway is already installed, the question is not choosing a provider, but the boundaries of responsibility between the existing payment module and the new channel.

Usually the module handles order checkout and some statuses, so it is not thrown away entirely — it is broken down by layers, and a decision is made as to which layer remains the source of truth for the payment.

Double accounting occurs where both channels write the order status simultaneously.

This is treated with idempotency: each transaction confirmation notification carries an identifier, repeated processing does not create a second entry, and discrepancies are caught by daily reconciliation of the two sources.

Migration without downtime is built in parallel mode: the new crypto payment gateway accepts part of the orders, the previous one continues to work, and both write to one accounting system through a common status layer.

Switching is done by traffic share, and rollback is returning the share to the previous channel without editing already-posted data.

The practical order is this: first reconciliation of reference data and test refunds, then transfer of part of the traffic, and only after totals match is the old module removed from processing.

Technical Doubts: Keys, Rate, Refunds, Reconciliation

Access keys are the first thing asked about before implementation. There is no private key on the web server: the application forms a payment and sends it for signing to a separate node with its own list of allowed addresses and a limit on the amount of one transaction. Every signature enters the log.

Rate discrepancies, underpayments, refunds, and coexistence with current acquiring are solved by rules and statuses, not by "we'll figure it out situationally." Below are four questions engineers most often ask during the assessment stage.

How is the exchange rate difference between invoice and confirmation calculated?

The rate is locked at the moment the invoice is created and stored together with its validity period and the exact amount in cryptocurrency. A transfer outside the window closes the invoice and goes to investigation.

We calculate the discrepancy between the expected and actual amount at the confirmation rate and put it as a separate line in the reconciliation register.

What happens with underpayment, overpayment, and refund?

Underpayment moves the invoice to partial payment: the remainder can be paid within the window, otherwise the amount goes to refund. Overpayment is credited by fact, and the surplus remains on the client's balance.

A refund goes to the sender's address minus the network fee and is marked with the identifier of the original operation — a repeated request does not create a second transaction.

Can crypto payments be accepted in parallel with current acquiring?

Yes. The crypto channel sits alongside: an invoice is created under the same order number, and statuses from both systems are consolidated into one table by identifier. Disabling one channel does not affect the other.

Let's Discuss Your Task: Where We Start

For the implementation estimate to be substantive rather than "based on impressions," we need to understand your scenario as a whole — from the moment the client clicks "pay" to crediting funds to your account.

Describe the task in free form, and attach input data for the estimate according to the points below: this is enough to calculate the scope of work and avoid redoing the integration halfway.

• Payment scenario: one-off payment on the website, subscription, withdrawal, or exchange — what exactly should work and in what mode.
• Assets and networks: which coins you plan to work with, whether wallets or a custodial provider already exist.
• How order accounting is structured now: CMS, database, payment module, availability of notification handlers from payment systems.
• Compliance requirements: what your lawyer or partner bank dictates regarding customer verification and transaction reporting.
• Expected load: how many payments per day occur at peak and how quickly the order status must be confirmed for the client.
• Access and restrictions: where the website is hosted, whether there is access to the repository and server, who approves changes in production.

After reviewing the input data, we will return with a work plan, a phased implementation estimate, and a fund flow scheme: where money enters, where it is converted, where it settles, and at which step the order status is fixed.

We will discuss the task — and propose an option that will not have to be rewritten when adding new assets.