BitPay integration: where cryptocurrency acceptance breaks
Practice shows: cryptocurrency acceptance breaks not at the connection stage, but at the edges — where the happy path ends.
A payment goes to the network but hangs in an intermediate status: the address received funds, but the system does not consider the order an order because the payment notification did not arrive or arrived late.
The order hangs in "awaiting payment" for days, support manually searches for the transaction by hash, and the client has already written to chat.
A separate category is discrepancies in amount and confirmations. The network takes a fee, the fixation rate and the actual crediting rate diverge, and the account receives an amount several percent less or more than expected.
The confirmation threshold also cannot be taken "by eye": with a small number of blocks, a transaction may disappear after a chain reorganization and return to the mempool; with a large number, a legitimate payment does not move to paid status for hours, and the order is not shipped.
BitPay provides tools for both scenarios, but the choice of threshold and order closure logic remains on the integration side.
Payment reconciliation is the third point where everything falls apart.
If you store only the final order status, unidentified incoming payments accumulate in the blockchain without an owner: the address is unique for each invoice, but a transfer may be made to an outdated address or from an exchange where the sender is not identified.
Without an event log and matching by address, amount, and time window, such payments cannot be found, and repeated payment notifications lead to double crediting.
This also includes handling duplicates and network failures: a notification may arrive twice, get lost, or overtake the response to invoice creation.
We analyze how this is covered: idempotent processing, repeated status polling, manual review of unidentified incoming payments, and the rules by which an order is considered paid.
What BitPay integration delivers: effect in measurable numbers
Crediting speed stops depending on manual confirmation: the transaction goes into processing immediately after the network accepts it, and the confirmation threshold is set by a rule — lower for small amounts, higher for large ones.
Small operations close in minutes, large ones wait for the specified depth, and this window no longer stretches into hours waiting for an operator.
The share of stuck payments drops to single-digit percentages: underpayment, overpayment, and the wrong network no longer leave the operation in an undefined state — the incoming payment is matched with the order invoice automatically, and the status is assigned based on fact.
Everything that truly does not match goes into a separate queue with the reason indicated, rather than dissolving in the general list of operations.
Manual reconciliation leaves the monthly routine: the ledger is exported with a link to the order number, and discrepancies are visible line by line and immediately with the reason. Finance is left with selective exception checking instead of continuous recalculation.
Support load drops due to transparent states: the client sees at which step the payment is and how many confirmations remain, and notifications arrive at every transition.
Requests like "money sent, order not activated" stop reaching the first line because the answer lies in the status.
A separate class of failures is also covered, the most costly one — desynchronization between the payment service and internal order accounting.
Repeated notification delivery does not create duplicates, and each operation is idempotently tied to an invoice, so recovery after a failure does not require manually bringing statuses to completion.
Cryptocurrency acceptance connection schemes: page, API, invoice
The three modes differ not in the amount of work on the provider side, but in who owns the payment interface and how order accounting is structured.
BitPay supports all three, so the choice is determined by your model: a one-time purchase, payment inside a personal account, or a deal with deferred reconciliation.
| Option | When it fits | Limitations |
|---|---|---|
| Payment page | quick launch, one-time purchases, no own storefront | branding is limited, the client goes to an external domain and returns via a link |
| API connection | own account, unified order and status accounting, subscriptions | a notification handler is needed, your own control of errors and retries |
| Invoicing | B2B deals, payment under contract, large payments | status reconciliation as a separate task, confirmation is not instant |
Return to the site is configured separately: after confirmation, the page redirects the client back to the specified address; otherwise, they remain on a third-party domain and do not understand whether the payment went through.
Recurring charges are reproduced only in API connection mode: consent is stored on your side, and the next payment is initiated without the client's participation — on a ready-made page, such a scenario is unavailable.
A hybrid scheme also works: initial payment via the page, while recurring charges and history in the personal account go through the API with a shared transaction log.
Implementation stages: from scheme analysis to handover to support
The work order is the same for any cryptocurrency acceptance model: first we fix how money comes in and where it goes, then we configure, then we test on real operations.
Skipping the audit is expensive — an inconsistent confirmation scheme surfaces already at launch, when client payments hang between the network and the accounting system.
- Payment scheme audit. We analyze which currencies and networks are needed, where the payment initiator comes from, how the incoming payment enters accounting, and who is responsible for reconciliation. The output is a discrepancy map and a list of decisions that need to be made before the first line of code.
- Payment flow scheme. We determine addressing, conversion rules, limits, confirmation depth, and crediting order. Separately, we specify behavior for underpayment, overpayment, expired invoice, and refund.
- Setup and connection. We issue access in a secure perimeter, enable acceptance and withdrawal, configure notifications with retry delivery and protection against double crediting — a duplicate notification must not create a second operation.
- Test payments. We run through successful payment, underpayment, refund, and repeated notification with minimum amounts. We reconcile the result in the network, on the BitPay side, and in the accounting system — we look for discrepancies immediately, not on turnover.
- Reconciliation and review procedure. We reconcile the transaction log with provider statements, set up regular discrepancy control, and define the procedure for disputed transactions.
- Handover to support. We provide documentation, the flow scheme, the procedure for typical incidents, and the escalation procedure, and train the on-duty shift on analyzed cases.
- Enhanced monitoring. We keep the first turnovers under control: analyze anomalies, refine notification thresholds, and close remaining gaps.
By the end of the stages, the client's team has a working integration tested on real operations and a clear procedure if a payment behaves atypically.
What is included in the delivery: configurations, schemes, procedures
Delivery does not end with payment successfully passing in a test environment. You are left with a set of artifacts that allow payment acceptance to be reconfigured, expanded, and maintained by your own team — below we list exactly what is included.
- Payment acceptance configuration — configuration files for test and production environments: supported currencies and networks, invoice amount limits, its lifetime, rules for fixing the rate at the moment of confirmation.
- Integration scheme — a flow diagram from invoice creation to crediting in the accounting system, with failure points and described behavior when an external service is unavailable.
- Access policies — a permission matrix for creating payments, refunds, and viewing statements, key rotation procedure, and rules for storing secrets.
- Support instructions — a breakdown of each payment status: how to distinguish a stuck operation from an unpaid invoice and which part of the logs to look at first.
- Reconciliation procedure — daily matching of the provider statement with internal accounting, the allowable discrepancy window, and the escalation point if it is exceeded.
- Disputed payment review procedure — underpayment, overpayment, payment after invoice expiration, and refund: response times and the responsible person at each step.
Documentation is tied to the configuration version, so when adding a new network or changing terms, it is updated with the same change as the code. Describe the task — we will return with a delivery plan and a set of artifacts for your perimeter.
Case study: cryptocurrency acceptance without manual payment reconciliation
Starting point
The client — a subscription service — accepted cryptocurrency payments via BitPay, but reconciliation lived in a spreadsheet: an operator exported an invoice report once a day and manually matched incoming payments with orders.
Out of 5-6 thousand operations per month, up to 400 requests hung in the status "paid, but not found," reviewing each took 3-4 minutes, and some payments had to be manually confirmed before access was opened. Average crediting time exceeded two hours.
What was changed
We built an automatic reconciliation layer: for each issued invoice, an external callback arrives at our service, is placed in a queue with an idempotency key, and the signature and amount match with the rate fixed at invoice issuance are verified.
The order closes immediately after the required confirmations in the network are collected, and a separate background process rereads the event log every 15 minutes and picks up what was lost during non-delivery.
Metrics before and after
The share of unidentified incoming payments fell from 7% to 0.3% — now these are isolated anomalies for the on-duty operator, not a daily stream.
Crediting time was reduced from two hours to 1-3 minutes, manual operations decreased by 90%, and reconciliation closes at night without human involvement.
Payment resilience rests on retry delivery and the queue: restarting the service does not lose events, so complaints of "paid — no access" no longer arrive.
How gateway connection differs from direct work with the network
The difference is simple: a payment gateway signs transactions with its own keys and gives you a ready result, while with direct work with the blockchain, the keys and all signing logic remain with you.
A gateway is an intermediary: it takes on communication with the network but limits you to its own set of assets. Direct work means your own node, your own address indexing, and full responsibility for key security.
Key control is the main divide. When the provider stores the keys, you see the balance in the dashboard but cannot sign a withdrawal yourself: access to funds depends on a third-party service and its policies.
When keys are generated and remain in your perimeter, the gateway receives only an address for crediting, and outgoing transaction signing happens on your side.
Settlement speed and supported assets also diverge.
The gateway credits a payment after a specified number of network confirmations and takes on rollback processing — but the asset list is limited to what the provider has already enabled, and a new network will appear only after its decision.
With direct work, you add the asset yourself, but you also track confirmations, rollbacks, and balances yourself.
The amount of work on your side differs by an order of magnitude. With BitPay and analogues, it is enough to register a merchant, separate keys, receive payment notifications, and set up reconciliation.
Direct work requires nodes, address indexing, block height monitoring, hot and cold wallets, and a key rotation procedure. A hybrid is often chosen: acceptance through a gateway, storage and withdrawal on your own keys.
Limitations of cryptocurrency acceptance and common technical doubts
In card acquiring, the amount either matched or the payment did not go through.
In crypto acceptance, between these states lies a spectrum of transitional ones: the client sent less, sent more, paid after the quote window expired, sent from an address that does not accept a refund.
The provider returns each of them as a separate status, and whether we processed it or not determines whether the order is charged or hangs.
BitPay integration calculates by the payment invoice: it has a lifetime and a fixed rate, and incoming reconciliation is based on the confirmed amount in the network. Below are the doubts that most often surface at acceptance.
The client underpaid or overpaid — what happens?
Underpayment is marked with a separate status: the order either does not open or goes into partial payment with the remaining balance collected — we set the rule, not the provider.
We return overpayment with a separate transaction to the sender's address taken from the confirmed notification.
Which rate is fixed at the moment of payment?
The rate is tied to the invoice at the moment of its creation and lives until the end of the quote window. A payment after this period is marked by the provider as payment at a new rate — the amount to be credited changes, and this must enter accounting, not just the dashboard.
How are notifications protected and what enters accounting?
Each notification is verified by a signature with a secret, duplicates are filtered out by event ID, and the status before order start is reread from the provider — a forged request does not open access to what was paid for.
The credited amount, transaction rate, and transaction ID enter accounting: with them, refund and reconciliation are closed without correspondence with the client.
Let's discuss the task: what to prepare for the first conversation
We provide an estimate not based on general words, but on facts: to calculate the labor intensity of the integration and not over-scope, a short set of inputs is enough for the first conversation. Below is exactly what should be captured from the current process.
- Task statement. Which scenarios we cover: one-time payment, recurring charges, refunds and partial refunds, who initiates them — the client or support.
- Current acceptance scheme. What already works: checkout, acquiring, billing, CRM, where the fact of incoming payment is recorded, and who currently reconciles payments manually.
- Volume of operations. Payments per day and at peak, share of recurring ones, whether automatic conversion into the accounting currency is needed and at what frequency.
- Security requirements. Where access keys are stored, who has them, whether signature verification of incoming notifications is needed, address restrictions, and key rotation.
- Accounting requirements. Accounting currency, rate fixation moment, format of closing documents, reconciliation with the internal ledger, and allowable discrepancy.
- Assets and networks. List of cryptocurrencies we accept, whether to include stablecoins, whether separate addresses are needed for each client.
- Timelines and responsible persons. Desired launch date, who on your side approves the legal part and opens access to the test perimeter.
This is enough to return with an estimate, an implementation plan, and a list of what will be required from your team at the launch stage.