Authentication and API Key Architecture
Crypto payment APIs authenticate requests using API keys — unique credentials issued to each merchant account that identify the caller and scope their permissions. Most gateways issue at least two key types: a publishable (or public) key that can be embedded in client-side code and used for low-risk read operations, and a secret key that must be kept server-side and is required for sensitive actions like creating invoices, initiating refunds, or updating settlement settings.
Many enterprise gateways support fine-grained key scoping: a developer can create a key with read-only access to transaction reports, another key with permission to create invoices, and a separate key authorised for payout initiation — following the principle of least privilege so that a compromised key limits potential damage to its permitted scope.
Core API Endpoints in a Crypto Payment Gateway
● POST /invoices — creates a new payment invoice, specifying the amount, currency, accepted cryptocurrencies, order reference, callback URL, and expiry. Returns the payment address, crypto amount, and invoice ID.
● GET /invoices/{id} — retrieves the current status and details of a specific invoice. Used for status polling as an alternative to webhooks.
● GET /invoices — lists invoices with filtering options (date range, status, currency). Used for reconciliation and reporting exports.
● POST /invoices/{id}/refund — initiates a refund transaction for a completed invoice, specifying the amount and destination address.
● GET /transactions — retrieves on-chain transaction records associated with the merchant's account, with filtering by status, network, and date.
● GET /rates — returns current exchange rates for supported currency pairs, used for displaying pre-checkout rate estimates.
● GET /balances — returns current settlement balance by currency.
● POST /payouts — initiates an outgoing payment (for mass payout or refund use cases), specifying recipient address and amount.
Idempotency Keys — Preventing Duplicate Invoices
Network failures create a specific risk in payment API integrations: a request to create an invoice may time out before the merchant's server receives the response, leaving the merchant's system uncertain whether the invoice was created. If the merchant retries the request, they may create a duplicate invoice — two payment pages for the same order, either of which the customer could pay.
Idempotency keys solve this. A merchant generates a unique key (typically a UUID) per invoice creation attempt and includes it in a request header (e.g., Idempotency-Key: uuid). If the gateway receives a second request with the same idempotency key, it returns the result of the first request rather than creating a new invoice, regardless of whether the second request's body is identical. This makes invoice creation safely retryable without risk of duplication. Merchants should generate idempotency keys from stable order identifiers, not random values, so that retries after server restarts use the same key.
API Versioning and Backwards Compatibility
Payment APIs evolve over time, and gateways must manage breaking changes carefully. A breaking change in the invoice creation endpoint — for example, renaming a field or changing the response structure — would silently break merchant integrations if not versioned. Professional gateways use explicit API version numbers in the URL path (e.g., /v1/invoices, /v2/invoices) and maintain deprecated versions for a defined sunset period, typically 12–24 months, with advance notice to merchants.
Merchants should pin their integration to a specific API version and subscribe to the gateway's developer changelog to receive advance notice of deprecations. Integrations that rely on undocumented response fields or make assumptions about field ordering in JSON responses are particularly vulnerable to unexpected breakage when gateways update their internal systems.
Sandbox vs. Production Environments
All production-grade crypto payment APIs provide a sandbox environment — a testing instance that mimics the production API but uses test networks (Bitcoin testnet, Ethereum Goerli, etc.) or simulated blockchain events rather than real transactions. Sandbox environments issue separate API keys and may have relaxed rate limits and additional testing utilities, such as endpoints that simulate payment confirmation or expiry events on demand without waiting for actual blockchain activity.
Merchants should complete full end-to-end testing in the sandbox before going live, including webhook delivery, error handling, and edge cases (underpayment, overpayment, expiry). A common mistake is testing only the happy path — confirmed payment — and discovering edge case handling issues only after going live with real customer transactions.
Compliance Note: This glossary entry is provided for general educational purposes only and does not constitute financial, investment, legal, or tax advice. Industry terminology may vary across jurisdictions and providers; definitions herein may not directly reflect the specific features, terms, or specifications of Finassets' services. For details on Finassets' offerings, please refer to official product documentation or contact our team directly.