CoinPayments Integration: API, IPN, Accepting Crypto Payments

CoinPayments integration: where crypto payments get lost

Accepting cryptocurrency breaks not at the moment funds are debited, but at the junction of two systems. The client sends a payment, the transaction goes out to the network, and confirmation takes anywhere from a few minutes to an hour — depending on network load and the fee set.

All this time the order in the accounting system sits in an intermediate status, and neither the operator nor the warehouse has a clear answer as to whether it is paid or not.

Usually it is not the payment itself that breaks, but the notification about it.

CoinPayments sends a callback notification (IPN) to your handler, and that handler may be unavailable, fail on a timeout, or receive a repeat delivery — without idempotent processing, a repeat creates a duplicate payment.

If the handler does not respond with a correct code, the gateway considers the delivery unsuccessful, but the transaction in the network has already gone through: the funds are at the address, the order status is unchanged.

So the order hangs between confirmation in the network and the accounting system, and then manual payment reconciliation begins. An engineer or accountant reconciles transaction hashes against the statement and moves the order status by hand.

At a flow of hundreds of payments per day, that means hours of work and inevitable lost orders: the client paid, the goods were not shipped, a support ticket.

We break down how this gets closed: scheduled reconciliation instead of betting on a single callback, idempotent handlers, and a discrepancy log that highlights a mismatch before the client finds it.

Implementation effect: payment confirmations, reconciliations, disputed transactions

Previously, a payment entered accounting as a line in a report, and from there a human drove the order: check the amount, change the status, grant access.

After integration, the order closes on an event — the payment is confirmed, the status changes, access and shipping receive a command. Order confirmation time drops from hours to minutes, and payments at night and on weekends no longer wait for an operator.

The key part of the effect is reconciliation. Notifications from CoinPayments land in the same log as order statuses, amounts are matched automatically, and discrepancies surface in a separate queue for review.

The share of manual operations drops to isolated cases: only partial payments and refunds, where a human makes the decision, remain manual.

A separate class of disputed payments gets closed as well. A repeat-delivered notification does not create a second order — the payment is bound to an identifier and reprocessing duplicates nothing.

Underpayment and overpayment, an expired invoice, a cancelled operation are handled by rules: the order either stays pending or closes with an explicit mark. Previously such cases were found during statement reconciliation — already after shipment.

Support is offloaded by exactly the volume of identical "I paid, where is my order" requests. The status is visible in the system rather than being clarified in correspondence, so the share of such questions drops severalfold — the freed-up time goes to complex cases.

CoinPayments integration schemes: full automation and semi-manual acceptance

Acceptance is built on a payment link: the buyer goes to the payment page, selects a coin and network, sends the transfer, and the platform waits for the required number of block confirmations.

How the order learns about the payment and how status reconciliation is performed determines the delay in delivering the goods and the system's behavior on a late confirmation.

The scheme is chosen for the order flow, operator involvement and acceptable delay. Any option is trialed in a test environment on test coins — switching to production does not require rewriting the buyer's account area.

Working schemes and their limitations

Notifications give speed but not a guarantee: repeat deliveries and lost calls are a routine situation. That is why in the production scheme we always keep background status reconciliation via the software interface and an operations log.

The buyer sees the current status in the account area, the operator sees discrepancies, accounting sees an export of operations. If payments went through another path, we migrate the history and set up reconciliation with existing orders.

Order of work: from analyzing the payment scenario to handover of regulations

The payment loop breaks not on an API call, but on state desynchronization: the client paid, the order in the accounting system stayed pending, and support handles each case manually.

That is why we run the CoinPayments integration from an audit of the payment scenario to a test environment and only then into production — with verification of every status transition and clear behavior on failures.

1. Audit of the payment scenario. We break down the current customer path: where the invoice is created, what counts as the moment of payment, how partial payment and exchange rate changes during the wait are accounted for, which statuses are already used in the accounting system and warehouses.
2. Scheme design and test environment. We agree on a status map — pending, network confirmation, underpayment, overpayment, cancellation, refund — and spin up a separate environment with test keys; production data never gets in there.
3. Setting up acceptance and status processing. We connect invoice creation, set the waiting window and the rules for moving the order to the target state, writing every change to the log with the operation identifier for later reconciliation.
4. Verification of notifications. We separately exercise IPN notifications: signature verification, idempotency, repeat deliveries of the same event, behavior when our service is unavailable — we accumulate them in a queue and process them later, without double crediting.
5. Failure handling and reconciliation. We run through underpayment, overpayment, cancellation and refund, then reconcile statuses against the operations history — no discrepancies should remain.
6. Handover to operation. We hand over regulations, access, alerts and a memo for support: the team itself distinguishes a stuck payment from an erroneous one.

What stays with you: configuration, schemes and regulations

What exactly stays with you after launch is not access to someone else's panel, but working artifacts your team can act on without us.

All keys, settings and documentation live in your environment: we configure the merchant in CoinPayments, describe the system's behavior and hand over regulations, not "magic that only the contractor understands."

• Configuration description. A full list of merchant parameters: which coins are enabled, default values, allowed ranges, network confirmation requirements and the lifetime of the payment invoice.
• Key access policies. Separation of the public and secret key, where the secret is stored, the rotation procedure and the procedure for a suspected compromise.
• Payment flow diagram. From invoice creation to crediting: the points where a failure is possible, and how that failure looks in the logs — so diagnostics take minutes rather than hours of correspondence.
• Notification handling. How the signature is verified, what we do with repeat deliveries, how the system reacts to a mismatch in the amount or the recipient address.
• Support instructions. Typical requests — "the payment is hanging," "the wrong amount went through," "the client lost access" — with ready-made verification steps and the boundary beyond which development gets involved.
• Refund regulations. Grounds for a refund, who makes the decision, how we calculate the refund amount, how we reflect the operation in accounting and what we tell the client.
• Reconciliation scheme. Daily matching of statuses in the merchant and in your database — discrepancies surface the next day, not at the end of the reporting period.
• Acceptance checklist. A set of test scenarios you run yourself: successful payment, underpayment, cancellation, duplicate notification.

Implementation breakdown: confirmed payments and reconciliations before and after

The client is a digital subscription service accepting crypto payments via CoinPayments.

Before implementation, 68% of payments were confirmed: some transfer notifications arrived repeatedly or with a delay, and orders for them were issued manually — an operator once a day reconciled the statement against the order history.

Support response time to "I paid but did not receive it" reached 4-6 hours, and such requests took up to a third of the first line.

What we changed

We built an idempotent IPN notification handler: every event lands in the log with a unique key, repeats are discarded, the order is created once even if the request is duplicated.

Crediting moves to "confirmed" status only after the required number of network confirmations — until then the order is visible as pending, not paid.

Reconciliation was moved out of manual mode: once a day the payment export is matched against orders, discrepancies go into a report with a reason — lost notification, extra confirmation, operator edit.

Metrics before and after

• Share of confirmed payments: 68% → 97%; the failure class "payment went through, order not issued" is gone.
• Support response time: 4-6 hours → 15 minutes thanks to automatic payment lookup in the event log.
• Manual reconciliation: about 3 hours a day → 20 minutes to review the discrepancy report.

Customer feedback: "The longest thing we discussed was repeat notifications — that is exactly what predictability rests on. After launch, 'paid but did not receive it' requests almost disappeared from the first line."

What to do if a crypto payment arrives but the order is not closed?

A payment via CoinPayments went through, but the order is hanging in "pending" — the mismatch almost always occurs at one of three points: the notification did not arrive, the notification was processed twice, or the payment status was not reconciled with the network.

Below are the characteristic symptoms and the procedure, which does not require reworking the entire acceptance loop.

The breakdown always starts with the operations log: it shows whether the request arrived at all, with what body, and what response we returned. No entry — the problem is in delivery; there is an entry — we look at what happened to the payment status after processing.

Reprocessing must be safe: the handler is idempotent by transaction identifier and on a repeat does not create a second order, only updates the status.

Manual order closing is a working tool for the on-duty engineer, but every such action is recorded in the log: who, when and based on which network confirmation.

So that the failure does not recur, we set up monitoring of undelivered notifications, periodic reconciliation of open invoices with the API and retries with increasing delay.

A separate signal is for "payment confirmed, order not closed for longer than N minutes": it catches the problem before the client contacts us.

Acceptance limitations, refunds and key security

When integrating CoinPayments, accepting crypto payments runs up not against the payment itself, but against what surrounds it: access to keys, refunds, disputed transactions and limits on the provider's side. These questions surface during operation, so we break them down before the start.

How do we return funds if a payment went to the wrong place?

A blockchain refund is a separate transaction and requires the recipient's consent. We return to a mistaken address only through the wallet owner, so the acceptance scenario includes address and memo verification before confirmation.

What to do with a disputed transaction?

We store the transaction hash, the number of network confirmations and all events on the invoice — we reconstruct the picture in minutes and show it to both parties. We fix the handling regulations in advance.

What acceptance limits exist and how do we change the provider?

The daily volume of operations and the confirmation threshold are configured for your profile and raised as history accumulates.

We do not "sew" the provider into the code: acceptance is moved into a separate layer, so changing the gateway is a module replacement, not a rewrite of orders and the personal account area.

Let's discuss your payment scheme and come back with a work plan

To come back with an estimate of the task rather than generalities, we need a minimum of input on your payment scheme. Below is what we request from your side; usually this is enough to assemble a work plan with stages and acceptance points.

• Payment scenarios — which money movements must work: one-time payment, repeat charge, partial refund, cancellation of a confirmed operation. For each scenario we fix the expected order status and behavior on underpayment or overdue.
• Access and test environment — merchant keys for the sandbox, a separate environment and domain for checks, the IPN notification handler address. Without an isolated environment we cannot reproduce rare statuses and test repeat delivery of notifications.
• Project owner on your side: who makes decisions on disputed scenarios and signs off on stage acceptance. A single channel of approvals saves weeks of correspondence.
• Current accounting scheme — where orders and billing live, how payment statuses are set now, which system is the source of truth on a mismatch.
• Reconciliation and reporting requirements — which statuses are needed for exports, how often we reconcile the provider's data with your database and what to do with "stuck" operations.
• Constraints — supported assets, payer jurisdictions, refund rules, amount limits, compliance requirements.
• Priorities — what is critical for launch and what can be moved to a second iteration without losing operability.

Once we receive this, we come back with a work plan: the scope of the integration, the sequence of stages, dependencies, risks and the points where your review is needed. Describe the task — we will put together an estimate for your volume of operations.