GriffNode API Reference (v1.0.1)
Accept Bitcoin, Litecoin, Dogecoin, Dash, Ethereum and ERC-20 tokens. Server-to-server, authenticated with a secret API key (Authorization: Bearer sk_live_… for live, or sk_test_… for test mode — same base URL). All monetary amounts in API responses are JSON numbers; webhook amounts are strings to preserve decimal precision (see the webhooks section).
Rate limits. Every request is rate-limited per API key in two windows — per minute and per hour — by plan tier (min/hour): starter 30/500, business 100/2000, professional 300/5000, enterprise 1000/20000. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds) for the per-minute window. On 429 the body is error: "RATE_LIMIT_EXCEEDED" (either window) with a Retry-After header (seconds) — clients should retry after it. A separate 429 with error: "MONTHLY_LIMIT_REACHED" means the plan's monthly transaction quota (not the request rate).
Base URL: https://api.griffnode.com/v1. Single base URL for both live and test traffic. A live secret key (sk_live_) settles real funds on mainnet; a test secret key (sk_test_) runs in test mode with no real funds. There is no separate sandbox host.
Authentication: Secret API key: Authorization: Bearer sk_live_… (or sk_test_…).
Transactions
Create and read merchant payment transactions.
POST /transactions/create
Create a payment transaction
Endpoint: POST https://api.griffnode.com/v1/transactions/create · Operation ID createTransaction · Requires a secret API key.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-Idempotency-Key | header | string | optional | Optional unique key for a create request (e.g. a UUID). A retried create with the same key returns the original transaction instead of creating a duplicate — send it on every create so a network retry can't double-charge the customer. |
Request body: application/json, a CreateTransactionRequest object (required).
| Field | Type | Required | Description |
|---|---|---|---|
crypto | CryptoSymbol | required | Supported coin/token symbol. /cryptos/list is authoritative at runtime. One of: BTC, LTC, DOGE, DASH, ETH, USDT, USDC, DAI, WBTC, SHIB, PEPE, LINK, UNI, AAVE, MKR. |
amount | number | required | Fiat amount (≥ 1.00 USD equivalent). |
currency_fiat | FiatCurrency | optional | One of: USD, PLN, EUR, GBP. Default USD. |
metadata | Metadata | optional | Free-form key/value (≤20 keys, string values ≤500 chars, ≤4 KB total). |
customer_email | string or null | optional | Format email. |
success_url | string or null | optional | Format uri. |
cancel_url | string or null | optional | Format uri. |
| Status | Body | Description |
|---|---|---|
201 | TransactionEnvelope | Transaction created. |
400 | Error | Validation error (INVALID_REQUEST, INVALID_CRYPTO, INVALID_AMOUNT, AMOUNT_TOO_LOW, INVALID_CURRENCY, INVALID_METADATA, WALLET_NOT_CONFIGURED, MISSING_ITEMS, MISSING_ORDER_ID, …). |
401 | Error | Missing or invalid API key (UNAUTHORIZED). |
402 | Error | Merchant platform balance too low for overage fees (INSUFFICIENT_BALANCE). |
403 | Error | Key lacks permission — e.g. a publishable key on a secret-only endpoint, or plan too low (FORBIDDEN, USE_PAY_ENDPOINT, PLAN_UPGRADE_REQUIRED, NO_ACTIVE_PLAN). |
409 | object | This client IP already has an active transaction (ACTIVE_TRANSACTION_EXISTS). Body includes an existing_transaction object. |
429 | Error | Rate limit or quota exceeded. error is RATE_LIMIT_EXCEEDED (per-minute request rate — honour Retry-After) or MONTHLY_LIMIT_REACHED (the plan's monthly transaction quota). Rate-limit headers accompany the RATE_LIMIT_EXCEEDED case. |
POST /transactions/create-detailed
Create an itemized transaction (Professional/Enterprise plans)
Endpoint: POST https://api.griffnode.com/v1/transactions/create-detailed · Operation ID createDetailedTransaction · Requires a secret API key.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-Idempotency-Key | header | string | optional | Optional unique key for a create request (e.g. a UUID). A retried create with the same key returns the original transaction instead of creating a duplicate — send it on every create so a network retry can't double-charge the customer. |
Request body: application/json, a CreateDetailedTransactionRequest object (required).
| Field | Type | Required | Description |
|---|---|---|---|
crypto | CryptoSymbol | required | Supported coin/token symbol. /cryptos/list is authoritative at runtime. One of: BTC, LTC, DOGE, DASH, ETH, USDT, USDC, DAI, WBTC, SHIB, PEPE, LINK, UNI, AAVE, MKR. |
currency_fiat | FiatCurrency | optional | One of: USD, PLN, EUR, GBP. Default USD. |
items | array of LineItem | required | |
order_id | string | required | |
metadata | Metadata | optional | Free-form key/value (≤20 keys, string values ≤500 chars, ≤4 KB total). |
customer_email | string or null | optional | Format email. |
success_url | string or null | optional | Format uri. |
cancel_url | string or null | optional | Format uri. |
| Status | Body | Description |
|---|---|---|
201 | TransactionEnvelope | Transaction created. |
400 | Error | Validation error (INVALID_REQUEST, INVALID_CRYPTO, INVALID_AMOUNT, AMOUNT_TOO_LOW, INVALID_CURRENCY, INVALID_METADATA, WALLET_NOT_CONFIGURED, MISSING_ITEMS, MISSING_ORDER_ID, …). |
401 | Error | Missing or invalid API key (UNAUTHORIZED). |
402 | Error | Merchant platform balance too low for overage fees (INSUFFICIENT_BALANCE). |
403 | Error | Key lacks permission — e.g. a publishable key on a secret-only endpoint, or plan too low (FORBIDDEN, USE_PAY_ENDPOINT, PLAN_UPGRADE_REQUIRED, NO_ACTIVE_PLAN). |
429 | Error | Rate limit or quota exceeded. error is RATE_LIMIT_EXCEEDED (per-minute request rate — honour Retry-After) or MONTHLY_LIMIT_REACHED (the plan's monthly transaction quota). Rate-limit headers accompany the RATE_LIMIT_EXCEEDED case. |
GET /transactions/list
List the merchant's transactions (newest first)
Endpoint: GET https://api.griffnode.com/v1/transactions/list · Operation ID listTransactions · Requires a secret API key.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer | optional | Default 20. Minimum 1. Maximum 100. |
offset | query | integer | optional | Default 0. Minimum 0. |
status | query | TransactionStatus | optional | Public transaction status (internal sub-states are mapped to these). One of: pending, awaiting_confirmation, completed, partial, expired, failed. |
crypto | query | CryptoSymbol | optional | Supported coin/token symbol. /cryptos/list is authoritative at runtime. One of: BTC, LTC, DOGE, DASH, ETH, USDT, USDC, DAI, WBTC, SHIB, PEPE, LINK, UNI, AAVE, MKR. |
| Status | Body | Description |
|---|---|---|
200 | object | A page of transactions. Fields: success, data. |
401 | Error | Missing or invalid API key (UNAUTHORIZED). |
403 | Error | Key lacks permission — e.g. a publishable key on a secret-only endpoint, or plan too low (FORBIDDEN, USE_PAY_ENDPOINT, PLAN_UPGRADE_REQUIRED, NO_ACTIVE_PLAN). |
GET /transactions/{transaction_id}
Retrieve a single transaction
Endpoint: GET https://api.griffnode.com/v1/transactions/{transaction_id} · Operation ID getTransaction · Requires a secret API key.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
transaction_id | path | string | required |
| Status | Body | Description |
|---|---|---|
200 | TransactionEnvelope | The transaction. |
401 | Error | Missing or invalid API key (UNAUTHORIZED). |
403 | Error | Key lacks permission — e.g. a publishable key on a secret-only endpoint, or plan too low (FORBIDDEN, USE_PAY_ENDPOINT, PLAN_UPGRADE_REQUIRED, NO_ACTIVE_PLAN). |
404 | Error | Resource not found (TRANSACTION_NOT_FOUND). |
Market Data
Live prices and the supported-currency catalogue.
GET /prices
Current crypto and fiat exchange rates (USD-denominated)
Endpoint: GET https://api.griffnode.com/v1/prices · Operation ID getPrices · Requires a secret API key.
| Status | Body | Description |
|---|---|---|
200 | object | Live rates. Fields: success, data. |
401 | Error | Missing or invalid API key (UNAUTHORIZED). |
500 | Error | Internal error (RATE_FETCH_FAILED, ADDRESS_GENERATION_FAILED, UPSTREAM_ERROR, …). |
GET /cryptos/list
All supported cryptocurrencies and tokens
Endpoint: GET https://api.griffnode.com/v1/cryptos/list · Operation ID listCryptocurrencies · Requires a secret API key.
| Status | Body | Description |
|---|---|---|
200 | object | Supported-currency catalogue. Fields: success, data. |
401 | Error | Missing or invalid API key (UNAUTHORIZED). |
GET /merchant/cryptos
Cryptocurrencies this merchant has wallets configured for
Endpoint: GET https://api.griffnode.com/v1/merchant/cryptos · Operation ID listMerchantCryptocurrencies · Requires a secret API key.
| Status | Body | Description |
|---|---|---|
200 | object | The merchant's configured currencies. Fields: success, data. |
401 | Error | Missing or invalid API key (UNAUTHORIZED). |
Account
Merchant plan, usage, balances, stats and invoices.
GET /account
Merchant plan, usage and limits
Endpoint: GET https://api.griffnode.com/v1/account · Operation ID getAccount · Requires a secret API key.
| Status | Body | Description |
|---|---|---|
200 | object | Account details. Fields: success, data. |
401 | Error | Missing or invalid API key (UNAUTHORIZED). |
403 | Error | Key lacks permission — e.g. a publishable key on a secret-only endpoint, or plan too low (FORBIDDEN, USE_PAY_ENDPOINT, PLAN_UPGRADE_REQUIRED, NO_ACTIVE_PLAN). |
GET /plans
Plan catalogue and pricing
Endpoint: GET https://api.griffnode.com/v1/plans · Operation ID listPlans · Requires a secret API key.
| Status | Body | Description |
|---|---|---|
200 | object | Plans. Fields: success, data. |
401 | Error | Missing or invalid API key (UNAUTHORIZED). |
403 | Error | Key lacks permission — e.g. a publishable key on a secret-only endpoint, or plan too low (FORBIDDEN, USE_PAY_ENDPOINT, PLAN_UPGRADE_REQUIRED, NO_ACTIVE_PLAN). |
GET /balances
On-platform balances (for overage/top-up; NOT crypto settlement)
Endpoint: GET https://api.griffnode.com/v1/balances · Operation ID listBalances · Requires a secret API key.
| Status | Body | Description |
|---|---|---|
200 | object | Balances. Fields: success, data. |
401 | Error | Missing or invalid API key (UNAUTHORIZED). |
403 | Error | Key lacks permission — e.g. a publishable key on a secret-only endpoint, or plan too low (FORBIDDEN, USE_PAY_ENDPOINT, PLAN_UPGRADE_REQUIRED, NO_ACTIVE_PLAN). |
GET /stats
Merchant transaction analytics
Endpoint: GET https://api.griffnode.com/v1/stats · Operation ID getStats · Requires a secret API key.
| Status | Body | Description |
|---|---|---|
200 | object | Stats. Fields: success, data. |
401 | Error | Missing or invalid API key (UNAUTHORIZED). |
403 | Error | Key lacks permission — e.g. a publishable key on a secret-only endpoint, or plan too low (FORBIDDEN, USE_PAY_ENDPOINT, PLAN_UPGRADE_REQUIRED, NO_ACTIVE_PLAN). |
GET /invoices
GriffNode billing invoices (platform ↔ merchant)
Endpoint: GET https://api.griffnode.com/v1/invoices · Operation ID listInvoices · Requires a secret API key.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer | optional | Default 20. Minimum 1. Maximum 100. |
offset | query | integer | optional | Default 0. Minimum 0. |
| Status | Body | Description |
|---|---|---|
200 | object | Invoices. Fields: success, data. |
401 | Error | Missing or invalid API key (UNAUTHORIZED). |
403 | Error | Key lacks permission — e.g. a publishable key on a secret-only endpoint, or plan too low (FORBIDDEN, USE_PAY_ENDPOINT, PLAN_UPGRADE_REQUIRED, NO_ACTIVE_PLAN). |
Billing
Plan upgrades and account top-ups.
POST /billing/checkout
Start a plan upgrade or account top-up
Endpoint: POST https://api.griffnode.com/v1/billing/checkout · Operation ID createBillingCheckout · Requires a secret API key.
Request body: application/json (required).
| Field | Type | Required | Description |
|---|---|---|---|
tier | PlanTier | required | One of: starter, business, professional, enterprise. |
billing_months | integer | optional | Default 1. Minimum 1. |
payment_method | string | optional | Default crypto. |
| Status | Body | Description |
|---|---|---|
201 | TransactionEnvelope | Billing transaction created. |
401 | Error | Missing or invalid API key (UNAUTHORIZED). |
402 | Error | Merchant platform balance too low for overage fees (INSUFFICIENT_BALANCE). |
403 | Error | Key lacks permission — e.g. a publishable key on a secret-only endpoint, or plan too low (FORBIDDEN, USE_PAY_ENDPOINT, PLAN_UPGRADE_REQUIRED, NO_ACTIVE_PLAN). |
System
Health and hosted-checkout redirect.
GET /health
API health check
Endpoint: GET https://api.griffnode.com/v1/health · Operation ID getHealth · No API key required.
| Status | Body | Description |
|---|---|---|
200 | object | Service status (intentionally NOT wrapped in the success envelope). Fields: status, service, version. |
GET /pay
Hosted-checkout redirect (browser flow, publishable key)
Browser-facing redirect to the hosted payment page, authenticated by a publishable key in the query string (safe to expose client-side). Not used by the server-side SDKs — included for completeness.
Endpoint: GET https://api.griffnode.com/v1/pay · Operation ID hostedCheckoutRedirect · No API key required.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
pk | query | string | required | Publishable key, pk_live_… / pk_test_… |
amount | query | string | required | Fiat amount (≥ 1.00 USD equivalent). |
crypto | query | CryptoSymbol | required | Supported coin/token symbol. /cryptos/list is authoritative at runtime. One of: BTC, LTC, DOGE, DASH, ETH, USDT, USDC, DAI, WBTC, SHIB, PEPE, LINK, UNI, AAVE, MKR. |
link | query | string | optional | Payment-link slug for attribution. |
| Status | Body | Description |
|---|---|---|
302 | — | Redirect to https://griffnode.com/transaction/{transaction_id} |
400 | Error | Validation error (INVALID_REQUEST, INVALID_CRYPTO, INVALID_AMOUNT, AMOUNT_TOO_LOW, INVALID_CURRENCY, INVALID_METADATA, WALLET_NOT_CONFIGURED, MISSING_ITEMS, MISSING_ORDER_ID, …). |
Webhooks
GriffNode delivers payment lifecycle events to the webhook URL configured in your dashboard. Amounts in webhook payloads are decimal strings, not JSON numbers, so precision is preserved.
POST webhook: paymentEvent
Payment lifecycle event delivered to the merchant's webhook URL
Signed with HMAC-SHA256 over the RAW request body. Verify by comparing X-GriffNode-Signature: sha256=<hex> to hex(hmac_sha256(webhook_secret, raw_body)) using a constant-time compare. Also sent: X-GriffNode-Event (the event type) and X-Webhook-ID (unique delivery id — use for idempotency).
Endpoint: POST webhook: paymentEvent · Operation ID paymentWebhook · Requires a secret API key.
Request body: application/json, a WebhookPayload object.
| Field | Type | Required | Description |
|---|---|---|---|
event | string | required | One of: payment.created, payment.pending, payment.completed, payment.overpaid, payment.partial, payment.expired, payment.failed. |
timestamp | string | required | Format date-time. |
transaction_id | string | required | |
status | TransactionStatus | required | Public transaction status (internal sub-states are mapped to these). One of: pending, awaiting_confirmation, completed, partial, expired, failed. |
currency_crypto | CryptoSymbol | optional | Supported coin/token symbol. /cryptos/list is authoritative at runtime. One of: BTC, LTC, DOGE, DASH, ETH, USDT, USDC, DAI, WBTC, SHIB, PEPE, LINK, UNI, AAVE, MKR. |
currency_fiat | FiatCurrency | optional | One of: USD, PLN, EUR, GBP. Default USD. |
amount_fiat | string | optional | Decimal string. |
amount_usd | string | optional | Decimal string. |
amount_crypto | string | optional | Decimal string. |
order_id | string or null | optional | |
receipt_url | string or null | optional | Present on completed/overpaid. Format uri. |
metadata | Metadata | optional | Free-form key/value (≤20 keys, string values ≤500 chars, ≤4 KB total). |
| Status | Body | Description |
|---|---|---|
200 | — | Acknowledge within 15s. Non-2xx is retried with backoff. |
Data objects
Every request body and response payload above is composed from these objects.
CryptoSymbol
Supported coin/token symbol. /cryptos/list is authoritative at runtime.
Type: string. Supported coin/token symbol. /cryptos/list is authoritative at runtime. One of: BTC, LTC, DOGE, DASH, ETH, USDT, USDC, DAI, WBTC, SHIB, PEPE, LINK, UNI, AAVE, MKR.
FiatCurrency
Type: string. One of: USD, PLN, EUR, GBP. Default USD.
TransactionStatus
Public transaction status (internal sub-states are mapped to these).
Type: string. Public transaction status (internal sub-states are mapped to these). One of: pending, awaiting_confirmation, completed, partial, expired, failed.
PlanTier
Type: string. One of: starter, business, professional, enterprise.
Metadata
Free-form key/value (≤20 keys, string values ≤500 chars, ≤4 KB total).
Type: object or null. Free-form key/value (≤20 keys, string values ≤500 chars, ≤4 KB total).
LineItem
| Field | Type | Required | Description |
|---|---|---|---|
name | string | required | |
quantity | integer | optional | Default 1. Minimum 1. |
price | number | required |
CreateTransactionRequest
| Field | Type | Required | Description |
|---|---|---|---|
crypto | CryptoSymbol | required | Supported coin/token symbol. /cryptos/list is authoritative at runtime. One of: BTC, LTC, DOGE, DASH, ETH, USDT, USDC, DAI, WBTC, SHIB, PEPE, LINK, UNI, AAVE, MKR. |
amount | number | required | Fiat amount (≥ 1.00 USD equivalent). |
currency_fiat | FiatCurrency | optional | One of: USD, PLN, EUR, GBP. Default USD. |
metadata | Metadata | optional | Free-form key/value (≤20 keys, string values ≤500 chars, ≤4 KB total). |
customer_email | string or null | optional | Format email. |
success_url | string or null | optional | Format uri. |
cancel_url | string or null | optional | Format uri. |
CreateDetailedTransactionRequest
| Field | Type | Required | Description |
|---|---|---|---|
crypto | CryptoSymbol | required | Supported coin/token symbol. /cryptos/list is authoritative at runtime. One of: BTC, LTC, DOGE, DASH, ETH, USDT, USDC, DAI, WBTC, SHIB, PEPE, LINK, UNI, AAVE, MKR. |
currency_fiat | FiatCurrency | optional | One of: USD, PLN, EUR, GBP. Default USD. |
items | array of LineItem | required | |
order_id | string | required | |
metadata | Metadata | optional | Free-form key/value (≤20 keys, string values ≤500 chars, ≤4 KB total). |
customer_email | string or null | optional | Format email. |
success_url | string or null | optional | Format uri. |
cancel_url | string or null | optional | Format uri. |
PaymentSplit
One on-chain payment toward the transaction.
| Field | Type | Required | Description |
|---|---|---|---|
txid | string | optional | On-chain transaction hash (blockchain id, NOT the GriffNode transaction_id). |
amount_crypto | number | optional | |
confirmations | integer | optional | |
status | string | optional | |
detected_at | string | optional | Format date-time. |
confirmed_at | string or null | optional | Format date-time. |
Transaction
The canonical, curated public view of a transaction (same shape from create, get and list). Internal fields (capability tokens, client_ip, address_index, derivation/db internals) are deliberately NOT exposed.
| Field | Type | Required | Description |
|---|---|---|---|
transaction_id | string | required | |
status | TransactionStatus | required | Public transaction status (internal sub-states are mapped to these). One of: pending, awaiting_confirmation, completed, partial, expired, failed. |
type | string | optional | One of: basic, detailed. |
crypto | CryptoSymbol | required | Supported coin/token symbol. /cryptos/list is authoritative at runtime. One of: BTC, LTC, DOGE, DASH, ETH, USDT, USDC, DAI, WBTC, SHIB, PEPE, LINK, UNI, AAVE, MKR. |
deposit_address | string | optional | |
amount_crypto | number | optional | |
amount_fiat | number | required | |
amount_usd | number | required | |
amount_paid | number | optional | |
amount_remaining | number | optional | |
currency_fiat | FiatCurrency | required | One of: USD, PLN, EUR, GBP. Default USD. |
fiat_to_usd_rate | number | optional | |
exchange_rate | number | optional | USD per unit of crypto, locked at creation. |
confirmations_required | integer | optional | |
payment_url | string | optional | Format uri. |
order_id | string or null | optional | |
customer_email | string or null | optional | |
items | array or null | optional | |
payments | array of PaymentSplit | optional | On-chain payments detected toward this transaction. |
metadata | Metadata | optional | Free-form key/value (≤20 keys, string values ≤500 chars, ≤4 KB total). |
success_url | string or null | optional | |
cancel_url | string or null | optional | |
created_at | string | required | Format date-time. |
updated_at | string | optional | Format date-time. |
expires_at | string | required | Format date-time. |
TransactionEnvelope
| Field | Type | Required | Description |
|---|---|---|---|
success | true | required | |
data | Transaction | required | The canonical, curated public view of a transaction (same shape from create, get and list). Internal fields (capability tokens, client_ip, address_index, derivation/db internals) are deliberately NOT exposed. Fields: transaction_id, status, type, crypto, deposit_address, amount_crypto, amount_fiat, amount_usd, amount_paid, amount_remaining, currency_fiat, fiat_to_usd_rate, exchange_rate, confirmations_required, payment_url, order_id, customer_email, items, payments, metadata, success_url, cancel_url, created_at, updated_at, expires_at. |
Cryptocurrency
| Field | Type | Required | Description |
|---|---|---|---|
symbol | CryptoSymbol | optional | Supported coin/token symbol. /cryptos/list is authoritative at runtime. One of: BTC, LTC, DOGE, DASH, ETH, USDT, USDC, DAI, WBTC, SHIB, PEPE, LINK, UNI, AAVE, MKR. |
name | string | optional | |
blockchain | string | optional | |
network | string | optional | |
type | string | optional | One of: coin, token. |
Account
| Field | Type | Required | Description |
|---|---|---|---|
plan | object | optional | Fields: tier, billing_cycle, auto_renewal, expires_at. |
usage | object | optional | Fields: monthly_transactions_used, monthly_transaction_limit, overage_cost_per_tx. |
limits | object | optional | Fields: api_rate_limit_per_minute, api_rate_limit_per_hour, webhook_support. |
Plan
| Field | Type | Required | Description |
|---|---|---|---|
tier | PlanTier | optional | One of: starter, business, professional, enterprise. |
monthly_price_usd | number or null | optional | |
yearly_price_usd | number or null | optional | |
monthly_transaction_limit | integer or null | optional | |
overage_cost_per_tx | number | optional | |
webhook_support | boolean | optional | |
webhook_limit | integer or null | optional | |
ip_whitelist | boolean | optional | |
api_rate_limit_per_minute | integer | optional | |
api_rate_limit_per_hour | integer | optional | |
custom_pricing | boolean | optional |
Balance
| Field | Type | Required | Description |
|---|---|---|---|
currency | string | optional | |
available_balance | number | optional | |
pending_balance | number | optional | |
updated_at | string | optional | Format date-time. |
Invoice
| Field | Type | Required | Description |
|---|---|---|---|
transaction_id | string | optional | |
purchase_type | string | optional | |
amount_fiat | number | optional | |
currency_fiat | FiatCurrency | optional | One of: USD, PLN, EUR, GBP. Default USD. |
status | string | optional | |
crypto_symbol | CryptoSymbol | optional | Supported coin/token symbol. /cryptos/list is authoritative at runtime. One of: BTC, LTC, DOGE, DASH, ETH, USDT, USDC, DAI, WBTC, SHIB, PEPE, LINK, UNI, AAVE, MKR. |
created_at | string | optional | Format date-time. |
confirmed_at | string or null | optional | Format date-time. |
expires_at | string | optional | Format date-time. |
Pagination
| Field | Type | Required | Description |
|---|---|---|---|
limit | integer | required | |
offset | integer | required | |
total | integer | required |
WebhookPayload
Payment-event payload. AMOUNTS ARE STRINGS (e.g. "100.00", "0.00109462") to preserve decimal precision — parse before arithmetic.
| Field | Type | Required | Description |
|---|---|---|---|
event | string | required | One of: payment.created, payment.pending, payment.completed, payment.overpaid, payment.partial, payment.expired, payment.failed. |
timestamp | string | required | Format date-time. |
transaction_id | string | required | |
status | TransactionStatus | required | Public transaction status (internal sub-states are mapped to these). One of: pending, awaiting_confirmation, completed, partial, expired, failed. |
currency_crypto | CryptoSymbol | optional | Supported coin/token symbol. /cryptos/list is authoritative at runtime. One of: BTC, LTC, DOGE, DASH, ETH, USDT, USDC, DAI, WBTC, SHIB, PEPE, LINK, UNI, AAVE, MKR. |
currency_fiat | FiatCurrency | optional | One of: USD, PLN, EUR, GBP. Default USD. |
amount_fiat | string | optional | Decimal string. |
amount_usd | string | optional | Decimal string. |
amount_crypto | string | optional | Decimal string. |
order_id | string or null | optional | |
receipt_url | string or null | optional | Present on completed/overpaid. Format uri. |
metadata | Metadata | optional | Free-form key/value (≤20 keys, string values ≤500 chars, ≤4 KB total). |
Error
| Field | Type | Required | Description |
|---|---|---|---|
success | false | required | |
error | string | required | Machine-readable code. |
message | string | required | Human-readable description. |
Error responses
Errors return the standard error envelope — success: false, a machine-readable error code and a human-readable message.
| Response | When it is returned |
|---|---|
BadRequest | Validation error (INVALID_REQUEST, INVALID_CRYPTO, INVALID_AMOUNT, AMOUNT_TOO_LOW, INVALID_CURRENCY, INVALID_METADATA, WALLET_NOT_CONFIGURED, MISSING_ITEMS, MISSING_ORDER_ID, …). |
Unauthorized | Missing or invalid API key (UNAUTHORIZED). |
Forbidden | Key lacks permission — e.g. a publishable key on a secret-only endpoint, or plan too low (FORBIDDEN, USE_PAY_ENDPOINT, PLAN_UPGRADE_REQUIRED, NO_ACTIVE_PLAN). |
NotFound | Resource not found (TRANSACTION_NOT_FOUND). |
InsufficientBalance | Merchant platform balance too low for overage fees (INSUFFICIENT_BALANCE). |
ActiveTransactionExists | This client IP already has an active transaction (ACTIVE_TRANSACTION_EXISTS). Body includes an existing_transaction object. |
TooManyRequests | Rate limit or quota exceeded. error is RATE_LIMIT_EXCEEDED (per-minute request rate — honour Retry-After) or MONTHLY_LIMIT_REACHED (the plan's monthly transaction quota). Rate-limit headers accompany the RATE_LIMIT_EXCEEDED case. |
ServerError | Internal error (RATE_FETCH_FAILED, ADDRESS_GENERATION_FAILED, UPSTREAM_ERROR, …). |