Skip to main content
The Caratuva API is a single REST surface served from api.caratuva.com/v1. It is designed for ERPs, marketplaces, and trade-finance platforms that want to add cross-border collection without building their own treasury, FX, or compliance stack.
  • Base URL — https://api.caratuva.com/v1
  • Format — JSON. Request bodies and responses are UTF-8 JSON.
  • Spec — OpenAPI 3.x, served by the API host at /docs-json, with a browsable Swagger UI at /docs. These are reachable once the API host (api.caratuva.com) is publicly available. In the meantime, pnpm dev in the docs repo generates a local spec snapshot from a running API.

​
Versioning

The current major version is v1, baked into the URL path. Breaking changes will land on v2 rather than mutating v1. Non-breaking additions land on v1 continuously.

​
Capabilities

SurfaceWhat it does
API keysIssue, list, and revoke server-to-server credentials per organization.
Payment intentsCreate payment requests with hosted payment links. The integrator-facing primary surface.
InvoicesRead invoice state for both API-created and dashboard-created invoices.
PaymentsRead the canonical payment view (collection, FX, settlement).
Webhook subscriptionsRegister and inspect outbound webhook endpoints; rotate signing secrets.
Connected accountsOnboard your own end clients (sellers/buyers) to KYB/KYC server-to-server and register a seller end client’s PIX payout destination.
Health/healthz and /readyz probes (no auth).
The flows that do not have a public API surface — your own organization’s KYB submission and PIX destination, buyer KYC on the hosted payment page, and team management — live in the dashboard. They are too document-heavy and too security-sensitive to be useful through programmatic access.

​
What’s NOT in the API

We’ve deliberately kept some things out of the v1 API:
  • No buyer KYC on the hosted payment page via API. Buyer KYC happens on the hosted payment page, where document capture, the verification selfie, and consent flows are first-class. You cannot upload a buyer’s passport for the hosted flow via the API. (Onboarding your own end clients to KYB/KYC is available via Connected accounts.)
  • No configuration of your own organization’s PIX destination. Your org’s PIX payout key is dashboard-only and gated by ownership. (A seller end client’s PIX destination is set via connected-accounts payout-config.)
  • No buyer authentication. Buyer sign-in lives on the hosted payment page.
  • No “skip KYC” flag. Every buyer goes through identity verification on first payment, regardless of how the invoice was created.

​
Auth schemes

SchemeHeaderUsed by
API keyX-API-Key: pk_<mode>_<id>.<secret>Server-to-server clients on the seller side.
Bearer JWTAuthorization: Bearer <jwt>Dashboard sessions.
See Authentication for details, including idempotency and tenancy.

​
Rate limits

Per-API-key rate limits apply on specific high-cost routes (e.g. payment-intent and invoice creation), not on every endpoint. There are no X-RateLimit-* response headers. When you exceed a limit, the API returns 429 RateLimitExceeded with a retryAfter field (seconds) in the JSON body: 
{
  "statusCode": 429,
  "error": "RateLimitExceeded",
  "message": "Rate limit exceeded. Retry after 30s.",
  "retryAfter": 30
}
Wait retryAfter seconds, then retry. Don’t hammer.

​
Idempotency

Resource-creating endpoints (POST /v1/invoices, POST /v1/payment-intents) accept an Idempotency-Key header (any UUID-like string). A replay with the same key returns the existing resource (re-serialized from storage, reflecting its current state) without re-executing side effects — there is no expiry. Always set one on retries. See Authentication → Idempotency.

​
Where to next