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 devin the docs repo generates a local spec snapshot from a running API.
Versioning
The current major version isv1, baked into the URL path. Breaking changes will land on v2 rather than mutating v1. Non-breaking additions land on v1 continuously.
Capabilities
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
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 noX-RateLimit-* response headers. When you exceed a limit, the API returns 429 RateLimitExceeded with a retryAfter field (seconds) in the JSON body:
retryAfter seconds, then retry. Don’t hammer.
Idempotency
Resource-creating endpoints (POST /v1/invoices, POST /v1/payments) 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
- Authentication — credentials and tenancy.
- B2B integration quickstart — your first paid intent in five steps.
- Errors — error envelope and the codes you’ll actually see.