Crypto payment gateway API: invoices, webhooks, payouts and white label

What does a crypto payment gateway API do?

The API hides the blockchain from your code. Instead of running nodes, deriving addresses and counting confirmations, you call an endpoint to create an invoice, store the gateway's identifier, and wait for notifications. The gateway quotes the exchange rate, watches the networks, applies AML screening and settles to your balance.

Most gateways expose the same building blocks under different names: invoices or orders for incoming payments, IPN or callbacks for notifications, conversion and balance endpoints, and payouts or withdrawals for outgoing transfers. Sandboxes exist at most providers, for example a separate sandbox host at CoinGate and a sandbox account at NOWPayments, and should be used before any mainnet test.

• Invoice API: create, read and cancel payment requests with fiat price, accepted coins, order reference and callback URL
• Notifications: webhooks or IPN on every status change, usually signed
• Payouts API: send crypto or fiat to customers, partners or your own wallet
• Rates and currencies: list supported coins, networks, minimum amounts and live quotes
• Plugins and SDKs: ready modules for e-commerce platforms on top of the same API

Crypto payment API or crypto payment gateway: is there a difference?

In practice the terms overlap. The gateway is the whole service: it watches the blockchain, converts or holds funds, settles to you and handles compliance checks. The crypto payment API is how your platform talks to that service. Some providers sell only the API and let you build the checkout, others add a hosted payment page, plugins and a dashboard on top.

The bigger difference is custody. With a custodial gateway the provider receives the coins and settles to you in crypto or fiat. With a non-custodial setup, payments go to wallets you control and the API mainly creates addresses and reports status. Custody decides who needs which licence and who carries the wallet security work.

Which endpoints does a crypto payments API usually expose?

Names differ between providers, but most APIs cover the same groups. Check each one against your use case before you sign.

How does the invoice lifecycle work?

Each gateway has its own status model, so map them to a small internal set before writing business logic. Only a final paid status should release goods; intermediate statuses exist because a transaction can be seen on-chain long before it is safe to accept.

The table maps two published status models to the states most platforms need. CoinGate, for example, expires an unpaid invoice after 20 minutes once the shopper has chosen a coin, and marks payments flagged by AML checks as invalid.

How should crypto webhooks and IPN be verified?

Treat every notification as untrusted until verified. Gateways use different schemes: NOWPayments signs the sorted JSON body with HMAC-SHA512 and sends it in the x-nowpayments-sig header, CoinGate sends a token you set on the order, and BitPay recommends fetching the invoice from the API after each notification instead of trusting its body.

The safest pattern combines both: verify the signature, then read the invoice from the API and act on that response. It costs one request per status change and protects you against forged or replayed callbacks.

• Verify signatures with a constant-time comparison and reject unsigned requests
• Re-fetch the invoice by its gateway ID before changing order state
• Return HTTP 200 quickly and process asynchronously; gateways retry on errors
• Store each notification with its event or status so duplicates are ignored
• Never trust amounts or currencies sent in the browser redirect

How to handle underpayments, overpayments and late payments?

Wallets and exchanges deduct withdrawal fees, and customers copy amounts imperfectly, so exact payment cannot be assumed. Define a tolerance and a rule for every case before launch, and expose the outcome to support staff.

How do idempotency and reconciliation work?

Create invoices with your own order reference and make the call safe to retry: if the request times out, look the invoice up by reference before creating another, or use an idempotency key where the gateway supports one. The same rule applies to payouts, where a duplicate request sends real money twice.

For reconciliation, store the gateway invoice ID, the transaction hash, the fiat amount, the crypto amount, the rate and the fee. Settlement reports list payouts as batches, so matching runs from order to invoice to payout rather than from order to bank line.

What does a payouts API need under the Travel Rule?

Payout endpoints send crypto from your gateway balance to an address, often in batches for affiliate commissions, marketplace sellers or customer withdrawals. Most require address whitelisting, two-factor approval or an API key with separate payout permissions.

In the EU, Regulation (EU) 2023/1113 requires the gateway to transmit originator and beneficiary information with each transfer and to verify ownership of self-hosted wallets above EUR 1,000. Expect payout requests to include beneficiary name and address type, and plan for transfers that wait for this data.

What are the white-label crypto payment gateway options?

Platforms that resell payments to their own merchants often want the payment page under their brand. There are three levels, and the price rises with control. Plisio, for example, lists 0.5% for its API and 1.5% for white label, and NOWPayments sells a separate white-label product.

Full white label shifts responsibility as well as branding. If you onboard merchants and hold their balances, you may need your own MiCA authorisation; using an authorised gateway's sub-merchant model keeps that obligation with the gateway.

How to connect crypto gateway APIs through OrsunPay

OrsunPay normalises crypto gateway statuses, webhooks and refunds into one API alongside your card and bank providers, using your own gateway accounts. It does not custody crypto or run payouts from its own balance; it routes requests to the gateway you choose and passes back signed, deduplicated events.

How to integrate a cryptocurrency payment gateway API

1. Open sandbox accounts Create sandbox and production accounts at the gateway, generate separate API keys for invoices and payouts, and set the IPN secret.
2. Map statuses Translate the gateway's statuses into your internal states and decide which one releases goods.
3. Create invoices idempotently Send fiat amount, currency, order reference and callback URL; look up by reference before retrying a timed-out call.
4. Verify notifications Check the signature, re-fetch the invoice from the API and process the event once.
5. Handle edge cases Implement tolerance, top-up, refund and expiry flows, and test each in the sandbox.
6. Reconcile settlements Store transaction hash, rate and fee per invoice and match payout batches to orders daily.