CoinPayments

What you need

This driver uses CoinPayments' new platform (docs.coinpayments.net, API v2), not the legacy api.php / IPN integration. The old "Merchant ID + IPN Secret" pair does not work here.

CoinPayments Dashboard → Integrations → Add Integration → API Integrations. Enter the two values shown when the integration is created:

• client_id: the integration's clientId
• secret_key: the integration's clientSecret (shown once; regenerate it from the dashboard if lost)

In your panel choose Settings → Payments → Add method → CoinPayments.

Instance: a CoinPayments account lives on one of three production instances (A: a-api.coinpayments.net, B: b-api…, C: c-api…) and credentials are not interchangeable between them. The driver defaults to instance A; if your account is on B or C, tell the panel team (the method's instance setting).

Sandbox: with sandbox (test) mode ticked, requests go to the api.coinpayments.net sandbox instance. CoinPayments also offers the free LTCT test coin (Dashboard → Balances → Get Free LTCT); disable LTCT in Payment Settings before going live.

Callback (webhook)

The callback is a server webhook: CoinPayments' servers call it, not the customer's browser. It is attached to every invoice automatically (a per-invoice webhook), so nothing has to be configured in the CoinPayments dashboard. Its shape:

https://<your-panel-domain>/payments/coinpayments/callback

If you also add a webhook to the integration in the dashboard, enter exactly this address (no trailing /, https not http): the signature is computed over this URL and a differently spelled one fails verification.

Your domain needs a valid TLS certificate; CoinPayments only delivers to https endpoints.

Flow

1. The customer enters an amount and picks CoinPayments. An invoice is created in your panel's currency (e.g. 250 TRY); its invoice number is our payment reference.
2. The customer is sent to CoinPayments' checkout, picks a coin there (BTC, ETH, USDT, …) and pays. The rate is locked for 60 minutes.
3. CoinPayments posts a webhook on every on-chain confirmation; the payment shows as pending with the confirmation count in its memo.
4. When the invoice becomes completed (funds landed in your CoinPayments balance) the balance is credited. Every webhook's signature is verified with secret_key; unsigned deliveries or ones from another integration are ignored.
5. The customer's browser may return to the panel through successUrl; that return never credits, it only shows the page.

A repeated completed webhook for the same invoice is ignored; balance is never credited twice.

Statuses

CoinPayments event / invoice state	In the panel
InvoiceCreated, InvoicePending (each confirmation), InvoicePaymentCreated	pending
InvoicePaid (chain-confirmed, not yet in your balance)	pending, memo: "being credited"
InvoiceCompleted / state completed	completed, balance credited
InvoiceCancelled	failed
InvoiceTimedOut (not confirmed within 60 min)	expired

An underpayment is not a separate terminal state at CoinPayments: the invoice never completes, turns timedOut when the window closes, and CoinPayments puts the sent funds into its refund flow for the buyer (a claim link by e-mail). An overpayment completes the invoice and the excess is refunded to the buyer.

Currencies

The invoice is opened in your panel's currency; CoinPayments knows 49 fiat currencies (TRY, USD, EUR, GBP, RUB, …). The driver translates the code into CoinPayments' numeric currency id itself (USD → 5057, TRY → 5166). The coin the customer pays with is not fixed on the invoice; the customer chooses it on CoinPayments' checkout from the coins you left enabled under Payment Settings in the dashboard. A crypto code as panel currency (e.g. USDT) does not work: CoinPayments names tokens with a chain suffix (USDT.TRC20).

Common problems

• "CoinPayments credentials missing": client_id or secret_key is empty. Both come from the integration screen; they are not your account password or a legacy API key.
• 401 / signature error when creating the invoice: the sandbox tick and the environment the credentials came from disagree (sandbox credentials in live mode, or the account is on instance B/C). Credentials do not cross instances.
• Paid but no balance: check the payment's memo under Admin → Payments. If InvoicePaid arrived but completed did not, the funds are not yet in your CoinPayments balance; depending on the payout setting in the dashboard this takes a few minutes. If no webhook arrived at all, check the domain's TLS certificate and that the callback starts with https://.
• Webhook fails verification: a webhook added by hand in the dashboard is spelled differently from the panel's (trailing /, www.); match the address exactly.
• An unconfirmed payment stays pending: chain confirmations are still being collected; CoinPayments posts a webhook per confirmation and the memo shows x/y.