Developer Docs

Build payments that just work

Clean REST API, signed webhooks with automatic retries, and a free sandbox that works exactly like production. Average integration time: under 30 minutes.

create-invoice.ts
// Works with any of 127 fiat currencies const ts = Date.now().toString(); const body = JSON.stringify({ amount: '4200.00', currency: 'UAH', // → auto-converted at live rate accepted_currencies: ['USDT_TRC20', 'BTC'], order_id: 'order_123', }); const res = await fetch('https://api.bekena.com/v1/invoices', { method: 'POST', headers: { Authorization: `Bearer ${PK}`, 'X-Bekena-Timestamp': ts, 'X-Bekena-Signature': sign(SK, ts, body), 'Content-Type': 'application/json', }, body, }); const { checkout_url } = await res.json(); // → https://pay.bekena.com/inv_...
API Features

Everything you need to ship fast

Built by developers, for developers. No gotchas, no surprise behaviors.

📄

OpenAPI Specification

Full OpenAPI 3.0 spec at api.bekena.com/docs. Generate client code in any language with a single command.

🔔

Signed Webhooks

Every webhook is HMAC-SHA256 signed with your endpoint secret. Delivery logs, auto-retries (5 attempts), manual replay.

🔑

Idempotency Keys

Pass X-Idempotency-Key on any POST to safely retry without creating duplicate invoices. Keys are stored 24 hours.

🧪

Sandbox Environment

Full sandbox at the same API base URL using sandbox API keys. Simulate deposits, trigger webhooks, test all edge cases.

🌍

Any Language

Plain HTTP — no proprietary SDK required. Works from cURL, Node.js, Python, PHP, Go, Ruby, or any HTTP client.

🔐

API Key Security

IP allowlists. Key rotation without downtime. Live and sandbox keys are fully isolated. Manage everything via dashboard.

Authentication

Signed requests

Every API call requires three headers — public key, timestamp, and HMAC signature.

Required headers
Authorization
Bearer pk_live_…

Your API public key from the dashboard

X-Bekena-Timestamp
1716900000

Unix timestamp in seconds or milliseconds — both accepted (±5 min window)

X-Bekena-Signature
sha256=abc123…

HMAC-SHA256 of timestamp + "." + raw request body, signed with your secret key

Content-Type
application/json

Required for POST/PATCH requests

Endpoints

Core API endpoints

Full reference with request/response examples at api.bekena.com/docs.

POST/v1/invoicesCreate invoice. Required: amount, accepted_currencies[]. Returns checkout_url + payment_addresses
GET/v1/invoices/:idGet invoice status, transactions, and payout details
GET/v1/invoicesList invoices with filters: status, order_id, date range
POST/v1/invoices/:id/cancelCancel a pending invoice (awaiting_payment only)
POST/v1/webhooksRegister a webhook endpoint (up to 5 per account)
GET/v1/webhooksList endpoints with delivery stats and health metrics
GET/v1/currencies/fiat127 supported fiat currencies with symbols and decimals (public)
GET/v1/exchange-ratesLive crypto + forex rates for all supported currencies (public)
GET/v1/analytics/summaryPayment volume, success rate, and revenue breakdown
View full API reference with request/response examples →
Webhooks

Real-time event delivery

Every event is HMAC-SHA256 signed, delivered with retries, and logged with full payloads. Wait for invoice.completed before fulfilling orders.

invoice.createdInvoice created — address generated, awaiting payment
invoice.detectedTransaction seen in mempool, not yet confirmed on-chain
invoice.confirmedOn-chain confirmed — funds forwarded to your payout address
invoice.completedSettlement complete — safe to fulfil the order
invoice.expiredInvoice expired without payment (default TTL: 30 minutes)
invoice.cancelledInvoice cancelled via API before payment was received
invoice.underpaidReceived less than the invoiced amount
invoice.overpaidReceived more than the invoiced amount
invoice.failedPayment failed or abandoned after expiry

Developer FAQ

What authentication headers are required?
Every API request needs three headers: Authorization: Bearer {public_key} (BEKENA_PUBLIC_KEY), X-Bekena-Timestamp (Unix seconds or milliseconds — both accepted), and X-Bekena-Signature (HMAC-SHA256 of timestamp + "." + raw request body, signed with BEKENA_SECRET_KEY). All values are available after creating an API key in the dashboard.
How do I test webhooks locally?
Use ngrok or a similar tunnelling tool to expose localhost to the internet, then register that URL as a webhook endpoint using your sandbox API keys. Use POST /v1/webhooks/:id/test to fire a test event immediately without creating a real invoice.
What is the webhook retry policy?
Failed webhooks are retried up to 5 times with exponential backoff: 1 min, 5 min, 15 min, 30 min, 60 min. After 5 failures the endpoint is auto-disabled. You can reactivate it and replay individual events from the dashboard or via POST /v1/webhooks/:id/reactivate.
Can I use the same API key for production and sandbox?
No. Create separate keys for each environment — sandbox keys only work against sandbox data and will never generate real transactions. This prevents accidental production calls during development.
Is there a rate limit?
Default is 500 requests/minute per API key. The rate limit window and current usage are returned in response headers on every request. If you need higher limits, contact support.
When is invoice.completed fired vs invoice.confirmed?
invoice.confirmed fires when the blockchain transaction is confirmed and funds start forwarding. invoice.completed fires once the payout to your address is complete. For Direct Wallet routing this is nearly instant; for Smart Conversion (THORChain swap) it takes a few minutes. Always wait for invoice.completed before fulfilling an order.
How do I create invoices in local currencies like UAH, JPY or EUR?
Pass currency=UAH (or any of the 127 supported fiat codes) in your POST /v1/invoices call. The response includes amount_usd and currency_rate so you always know the USD equivalent at time of creation. Use GET /v1/currencies/fiat to fetch the full list of supported codes, and GET /v1/exchange-rates to get live rates for your UI. You can also set a default currency per account (in dashboard Settings) or per brand — then you never need to pass currency at all.

Start building today

Free sandbox, full API access, no credit card required.

Get API Keys Free →Read the Docs