Kobaru implements multiple layers of security to protect your payments and prevent abuse. This page explains the security mechanisms and best practices.
API key security#
API keys authenticate your requests to Kobaru's gateway endpoints.| Component | Description |
|---|
kbr | Kobaru prefix |
env | Environment (live or test) |
random | 40 character base62 string (256 bits of entropy) |
Example: kbr_live_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW3xY5zAStorage and validation#
Keys are never stored in plaintext - only SHA-256 hashes
Validation uses constant-time comparison to prevent timing attacks
Keys are generated with cryptographically secure randomness
Best practices#
1.
Never commit keys to source control - Use environment variables
2.
Rotate keys periodically - Create new keys and revoke old ones
3.
Use separate keys for test and production - kbr_test_* vs kbr_live_*
4.
Limit key scope - Create service-specific keys when possible
5.
Monitor key usage - Check last-used timestamps in the console
Transaction verification#
Kobaru validates every payment transaction before settlement.Solana validation checks#
| Check | What it prevents |
|---|
| Fee payer validation | Spoofed fee payer addresses |
| Amount validation | Underpayment attacks |
| Recipient validation | Payment to wrong address |
| Instruction topology | Malformed transactions |
| Priority fee limits | Gas exhaustion attacks |
| Transaction simulation | Failed transactions |
Simulation before settlement#
Every transaction is simulated on-chain before signing. This ensures:Payer has sufficient balance
If simulation fails, the transaction is rejected without consuming gas.
Idempotency and replay protection#
Kobaru processes each payment at most once, no matter how many times you send it. For how this works end to end, what to do with each response and how it compares to key-based idempotency, see Idempotency.The problem#
In distributed systems, the same payment request might arrive multiple times due to:Intentional replay attacks
A payment's identity is its on-chain authorization#
Kobaru identifies a payment by what the chain itself accepts only once, not by the exact bytes you send:| Network | Payment identity |
|---|
| EVM (EIP-3009) | Token, authorization.from and authorization.nonce |
| Solana | The transaction message (signatures excluded) |
Re-encoding or altering a signature doesn't create a new payment. Other payload shapes fall back to the exact payload together with the payment requirements.Safe retries#
You can resend the same /verify or /settle request after a timeout or network error:| Situation | What you get |
|---|
| The first request finished | The stored result (same signature only), with "replayed": true and the header Idempotent-Replayed: true |
| The first request is still running | duplicate_request (409) with Retry-After: 5 |
| A settle's outcome isn't known yet (a retry checks the chain first; Kobaru also resolves it in the background) | settlement_pending (409) with Retry-After: 30 |
/verify of a payment that was already settled | payment_already_settled (400) |
| The payment couldn't be claimed (temporary database problem) | claim_unavailable (503) with Retry-After: 5 |
| A retry with a different signature than the one the payment was settled or first broadcast with | payment_proof_mismatch (400), nothing recorded |
A settle retry can't pay twice. An EIP-3009 authorization is single-use on-chain, and Solana rejects a signed transaction it has already processed.Replays are marked#
A replayed /settle success carries the same transaction as the original and no new on-chain transfer happened. Treat it as a payment you already delivered for, not as a new payment. Fresh results never carry replayed.Don't grant access on replayed: true alone. Once a payment is broadcast, its proof works like a bearer token: anyone who saw it (in a request header, a log, or the transaction on chain) can send it again and get the same stored success. A replay proves that the payment happened, not that the caller in front of you made it or hasn't been served. Grant access only through your own record of the payment: the order, session or account it was first settled for. A replay for a payment you have already delivered gets nothing new.Conflicts#
The same payment is bound to the requirements it was first presented with (network, scheme, asset, payTo and amount). Presenting it again with different requirements returns idempotency_conflict (409) without touching the chain. Retrying can't succeed: send the original requirements, or have the payer sign a new authorization.See Errors for the full list of reasons and how to handle them.
TOCTOU prevention#
Time-of-check to time-of-use (TOCTOU) attacks occur when state changes between validation and action.1.
Attacker submits payment A
2.
System checks: no duplicate found
3.
Attacker submits payment A again (concurrent)
4.
System checks: no duplicate found
5.
Both payments succeed (double charge!)
Kobaru records the claim on a payment and checks for earlier attempts in one database transaction that locks the payment's record. A concurrent request for the same payment waits for that lock, then sees the first claim and gets duplicate_request. Only one request ever reaches the chain, and it does so only after the claim is committed.
Server-side payment requirements#
When using the proxy, payment requirements (amount, asset, recipient wallet) are always determined server-side from your route configuration in the database. The proxy never trusts client-provided values.Clients cannot manipulate the payment amount
Clients cannot redirect payments to a different wallet
The facilitator verifies client payments against your configured requirements, not what the client claims
This is enforced automatically — no action needed from merchants.
Rate limiting#
Abuse protection runs at the network layer, in Kobaru's firewall, before requests reach the gateway. /verify and /settle also require valid on-chain cryptographic proofs, which make spam expensive.If you receive a 429 Too Many Requests response, it comes from the firewall. Wait for the Retry-After interval before you retry.
Network security#
Edge deployment#
Kobaru runs on a global edge network, providing:TLS encryption everywhere
No single point of failure
Request validation#
All requests are validated:Body size limit: 64KB max
Content-Type validation: JSON only
Schema validation: every input is checked against a strict schema
Proxy mode protections#
The transparent proxy only forwards requests to destinations that pass its validation:HTTPS only. Every other protocol is blocked.
Hostname and domain validation. Private, internal and restricted destinations are rejected, including Kobaru's own domains.
A request to a destination that fails validation is blocked before any network activity, and the client gets a generic error.
Best practices for merchants#
1. Validate payment responses#
Always check the response from /verify or /settle:2. Use HTTPS everywhere#
All communication must use HTTPS - this is enforced at multiple levels:For API requests#
Never transmit API keys or payment data over unencrypted HTTP connections. Always use:https://gateway.kobaru.io/verify
https://gateway.kobaru.io/settle
For backend APIs (Proxy mode)#
If you're using Kobaru's transparent proxy, your backend API must be accessible via HTTPS. HTTP endpoints are blocked for security reasons.✅ HTTP URLs are rejected when you save them
✅ HTTP requests are blocked at runtime
❌ http://api.example.com - Rejected
✅ https://api.example.com - Allowed
For local development:
Use an HTTPS tunnel, such as ngrok:This provides a public HTTPS endpoint that proxies to your local server.3. Implement webhook signature verification#
When we add webhooks, always verify signatures before processing.4. Monitor for anomalies#
Requests from unexpected locations
5. Keep dependencies updated#
Update your SDK and dependencies regularly to receive security patches.
Reporting security issues#
If you discover a security vulnerability, please report it responsibly:Do not disclose publicly until we've addressed the issue
We appreciate responsible disclosure and will acknowledge your contribution
Idempotency - Safe retries, payment identity and guarantees Modified at 2026-11-12 03:41:54