# Caratuva

> Cross-border B2B payments for Brazilian commodity exporters. Collect from foreign buyers, settle in BRL.

## Docs

- [API keys](https://docs.caratuva.com/api-reference/api-keys.md): Issue, list, and revoke server-to-server credentials.
- [Create a new API key (full secret returned once)](https://docs.caratuva.com/api-reference/api-keys/create-a-new-api-key-full-secret-returned-once.md)
- [List API keys for the caller organization](https://docs.caratuva.com/api-reference/api-keys/list-api-keys-for-the-caller-organization.md)
- [Revoke an API key (irreversible)](https://docs.caratuva.com/api-reference/api-keys/revoke-an-api-key-irreversible.md)
- [Email a magic-link sign-in to the seller user](https://docs.caratuva.com/api-reference/auth/email-a-magic-link-sign-in-to-the-seller-user.md): Always returns {status:"sent"} so callers cannot enumerate registered emails. Rate-limited per email + per IP at the edge.
- [Exchange a magic-link token for a 12h Bearer JWT](https://docs.caratuva.com/api-reference/auth/exchange-a-magic-link-token-for-a-12h-bearer-jwt.md): Single-use: consuming a token marks it consumedAt and invalidates further uses.
- [Switch the dashboard session between test and live mode](https://docs.caratuva.com/api-reference/auth/switch-the-dashboard-session-between-test-and-live-mode.md): Re-mints the Bearer JWT bound to the chosen mode. B2B API-key callers carry mode in their pk_test_/pk_live_ prefix and cannot use this endpoint.
- [Authentication](https://docs.caratuva.com/api-reference/authentication.md): API keys, bearer tokens, idempotency, and per-organization tenancy.
- [B2B quickstart](https://docs.caratuva.com/api-reference/b2b-quickstart.md): From zero to first settled payment in five steps.
- [Clear the buyer session cookie](https://docs.caratuva.com/api-reference/buyer-auth/clear-the-buyer-session-cookie.md)
- [Email a magic-link sign-in to the buyer](https://docs.caratuva.com/api-reference/buyer-auth/email-a-magic-link-sign-in-to-the-buyer.md): Idempotent contract — multiple requests are rate-limited per email + per IP at the edge (Cloud Armor + in-process counter).
- [Exchange a magic-link token for a session cookie](https://docs.caratuva.com/api-reference/buyer-auth/exchange-a-magic-link-token-for-a-session-cookie.md): Sets an httpOnly + Secure session cookie on success.
- [Buyer-session: get latest buyer KYC submission](https://docs.caratuva.com/api-reference/buyer-kyc/buyer-session:-get-latest-buyer-kyc-submission.md)
- [Buyer-session: mint a settlement-partner ToS-acceptance URL. Buyer-portal directs the buyer to the returned URL; on acceptance the settlement partner redirects to ?tos_id=... which the buyer-portal forwards via /tos-accepted below.](https://docs.caratuva.com/api-reference/buyer-kyc/buyer-session:-mint-a-settlement-partner-tos-acceptance-url-buyer-portal-directs-the-buyer-to-the-returned-url;-on-acceptance-the-settlement-partner-redirects-to-?tos_id=-which-the-buyer-portal-forwards-via-tos-accepted-below.md)
- [Buyer-session: mint a signed PUT URL for a KYC file (selfie or ID document). The buyer-portal PUTs the file to uploadUrl with uploadHeaders, then sends publicUrl in the /buyer-kyc submit.](https://docs.caratuva.com/api-reference/buyer-kyc/buyer-session:-mint-a-signed-put-url-for-a-kyc-file-selfie-or-id-document-the-buyer-portal-puts-the-file-to-uploadurl-with-uploadheaders-then-sends-publicurl-in-the-buyer-kyc-submit.md)
- [Buyer-session: record the tos_id from the ToS-acceptance redirect.](https://docs.caratuva.com/api-reference/buyer-kyc/buyer-session:-record-the-tos_id-from-the-tos-acceptance-redirect.md)
- [Buyer-session: start buyer KYC via the settlement partner](https://docs.caratuva.com/api-reference/buyer-kyc/buyer-session:-start-buyer-kyc-via-the-settlement-partner.md)
- [Get latest buyer KYC submission](https://docs.caratuva.com/api-reference/buyer-kyc/get-latest-buyer-kyc-submission.md)
- [Mint a one-shot signed PUT URL for uploading a KYC file (selfie or ID document). Browsers PUT directly to GCS using the returned URL + headers; the publicUrl flows through to the settlement partner in the /buyer-kyc submit.](https://docs.caratuva.com/api-reference/buyer-kyc/mint-a-one-shot-signed-put-url-for-uploading-a-kyc-file-selfie-or-id-document-browsers-put-directly-to-gcs-using-the-returned-url-+-headers;-the-publicurl-flows-through-to-the-settlement-partner-in-the-buyer-kyc-submit.md)
- [Mint a settlement-partner ToS-acceptance session URL. Direct your buyer to the returned URL; on acceptance the settlement partner redirects to your redirectUrl with ?tos_id=...&idempotency_key=... query params. Then call /tos-accepted (or pass tosId in the next /buyer-kyc submit).](https://docs.caratuva.com/api-reference/buyer-kyc/mint-a-settlement-partner-tos-acceptance-session-url-direct-your-buyer-to-the-returned-url;-on-acceptance-the-settlement-partner-redirects-to-your-redirecturl-with-?tos_id=&idempotency_key=-query-params-then-call-tos-accepted-or-pass-tosid-in-the-next-buyer-kyc-submit.md)
- [Persist the tos_id the settlement partner returned in the redirect querystring. Call this once per acceptance; subsequent /buyer-kyc submits will use the stored value automatically.](https://docs.caratuva.com/api-reference/buyer-kyc/persist-the-tos_id-the-settlement-partner-returned-in-the-redirect-querystring-call-this-once-per-acceptance;-subsequent-buyer-kyc-submits-will-use-the-stored-value-automatically.md)
- [Settlement-partner KYC webhook (stub; signature check Phase 2)](https://docs.caratuva.com/api-reference/buyer-kyc/settlement-partner-kyc-webhook-stub;-signature-check-phase-2.md)
- [Start buyer KYC via the settlement partner](https://docs.caratuva.com/api-reference/buyer-kyc/start-buyer-kyc-via-the-settlement-partner.md)
- [Connected accounts](https://docs.caratuva.com/api-reference/connected-accounts.md): Onboard your own end clients (sellers and buyers) to KYB/KYC through the API, server-to-server.
- [Create a connected account (an end client you onboard to the settlement partner). Supply externalId for idempotent creates.](https://docs.caratuva.com/api-reference/connected-accounts/create-a-connected-account-an-end-client-you-onboard-to-the-settlement-partner-supply-externalid-for-idempotent-creates.md)
- [Get a connected account](https://docs.caratuva.com/api-reference/connected-accounts/get-a-connected-account.md)
- [List connected accounts (filter by role/status; cursor-paginated)](https://docs.caratuva.com/api-reference/connected-accounts/list-connected-accounts-filter-by-rolestatus;-cursor-paginated.md)
- [Mint a one-shot signed PUT URL for a KYC/KYB document. Optional — you may instead pass pre-hosted HTTPS URLs in the /submit body.](https://docs.caratuva.com/api-reference/connected-accounts/mint-a-one-shot-signed-put-url-for-a-kyckyb-document-optional-—-you-may-instead-pass-pre-hosted-https-urls-in-the-submit-body.md)
- [Mint a settlement-partner ToS-acceptance session URL for this end client. Direct them to the returned URL; the settlement partner redirects back with ?tos_id=... — then call /tos-accepted (or pass tosId on /submit).](https://docs.caratuva.com/api-reference/connected-accounts/mint-a-settlement-partner-tos-acceptance-session-url-for-this-end-client-direct-them-to-the-returned-url;-the-settlement-partner-redirects-back-with-?tos_id=-—-then-call-tos-accepted-or-pass-tosid-on-submit.md)
- [Record the tos_id the settlement partner returned in the acceptance redirect](https://docs.caratuva.com/api-reference/connected-accounts/record-the-tos_id-the-settlement-partner-returned-in-the-acceptance-redirect.md)
- [Register a seller end client’s PIX payout destination at the settlement partner (sellers only; requires approval). The raw PIX key is never stored by Caratuva.](https://docs.caratuva.com/api-reference/connected-accounts/register-a-seller-end-client’s-pix-payout-destination-at-the-settlement-partner-sellers-only;-requires-approval-the-raw-pix-key-is-never-stored-by-caratuva.md)
- [Settlement-partner connected-account webhook (stub; signed ingress is canonical)](https://docs.caratuva.com/api-reference/connected-accounts/settlement-partner-connected-account-webhook-stub;-signed-ingress-is-canonical.md)
- [Submit the end client to the settlement partner for KYB (business) or KYC (individual). Idempotent while verifying/approved.](https://docs.caratuva.com/api-reference/connected-accounts/submit-the-end-client-to-the-settlement-partner-for-kyb-business-or-kyc-individual-idempotent-while-verifyingapproved.md)
- [Submit a sales-contact lead from the marketing site](https://docs.caratuva.com/api-reference/contact/submit-a-sales-contact-lead-from-the-marketing-site.md)
- [Get current payout configuration (presence only, no secrets)](https://docs.caratuva.com/api-reference/developers/get-current-payout-configuration-presence-only-no-secrets.md)
- [Upsert PIX key payout config](https://docs.caratuva.com/api-reference/developers/upsert-pix-key-payout-config.md)
- [Environments](https://docs.caratuva.com/api-reference/environments.md): How test and live mode are carried on the API.
- [Errors](https://docs.caratuva.com/api-reference/errors.md): Error envelope, HTTP status codes, and the error codes you'll actually encounter.
- [Lock an FX quote for the buyer to confirm on-ramp against (10-min TTL).](https://docs.caratuva.com/api-reference/fx-quotes/lock-an-fx-quote-for-the-buyer-to-confirm-on-ramp-against-10-min-ttl.md)
- [Get healthz](https://docs.caratuva.com/api-reference/health/get-healthz.md)
- [Get readyz](https://docs.caratuva.com/api-reference/health/get-readyz.md)
- [API overview](https://docs.caratuva.com/api-reference/introduction.md): REST + OpenAPI. One surface for everything an integrator needs.
- [Approve an invoice awaiting four-eyes review](https://docs.caratuva.com/api-reference/invoices/approve-an-invoice-awaiting-four-eyes-review.md)
- [Cancel an invoice (15-min undo window — see ADR 0007)](https://docs.caratuva.com/api-reference/invoices/cancel-an-invoice-15-min-undo-window-—-see-adr-0007.md)
- [Create a new invoice (requires Idempotency-Key)](https://docs.caratuva.com/api-reference/invoices/create-a-new-invoice-requires-idempotency-key.md)
- [Get invoice with full event timeline](https://docs.caratuva.com/api-reference/invoices/get-invoice-with-full-event-timeline.md)
- [Invite the buyer (transitions approved -> awaiting_buyer and sends a magic-link)](https://docs.caratuva.com/api-reference/invoices/invite-the-buyer-transitions-approved->-awaiting_buyer-and-sends-a-magic-link.md)
- [List invoices for the caller organization (cursor-paginated)](https://docs.caratuva.com/api-reference/invoices/list-invoices-for-the-caller-organization-cursor-paginated.md): Returns the most recently created invoices first. Pass `cursor` (the previous response's `nextCursor`) to fetch the next page. `nextCursor` is null when there are no more results.
- [Public buyer-facing invoice view (no auth; identified by publicId).](https://docs.caratuva.com/api-reference/invoices/public-buyer-facing-invoice-view-no-auth;-identified-by-publicid.md)
- [Reassign the buyer on an invoice (useful when KYC is stuck on a consumed TOS token)](https://docs.caratuva.com/api-reference/invoices/reassign-the-buyer-on-an-invoice-useful-when-kyc-is-stuck-on-a-consumed-tos-token.md)
- [Reject an invoice awaiting four-eyes review (cancels it)](https://docs.caratuva.com/api-reference/invoices/reject-an-invoice-awaiting-four-eyes-review-cancels-it.md)
- [Update an invoice (draft or awaiting_approval only)](https://docs.caratuva.com/api-reference/invoices/update-an-invoice-draft-or-awaiting_approval-only.md)
- [Get the current organization KYB submission](https://docs.caratuva.com/api-reference/kyb/get-the-current-organization-kyb-submission.md)
- [Get the live settlement-partner receiver detail (compliance data, owners, limits, kyc/fraud warnings) for the current organization](https://docs.caratuva.com/api-reference/kyb/get-the-live-settlement-partner-receiver-detail-compliance-data-owners-limits-kycfraud-warnings-for-the-current-organization.md)
- [Initiate seller business KYB via the settlement partner](https://docs.caratuva.com/api-reference/kyb/initiate-seller-business-kyb-via-the-settlement-partner.md)
- [Mint a settlement-partner ToS-acceptance session URL for the seller organization](https://docs.caratuva.com/api-reference/kyb/mint-a-settlement-partner-tos-acceptance-session-url-for-the-seller-organization.md)
- [Mint a signed PUT URL for a seller KYB document (incorporation, proof-of-ownership, proof-of-address, or an owner-scoped file). The dashboard PUTs the file, then sends publicUrl in the /kyb submit.](https://docs.caratuva.com/api-reference/kyb/mint-a-signed-put-url-for-a-seller-kyb-document-incorporation-proof-of-ownership-proof-of-address-or-an-owner-scoped-file-the-dashboard-puts-the-file-then-sends-publicurl-in-the-kyb-submit.md)
- [Record the tos_id the settlement partner returned in the ToS-acceptance redirect](https://docs.caratuva.com/api-reference/kyb/record-the-tos_id-the-settlement-partner-returned-in-the-tos-acceptance-redirect.md)
- [Resubmit corrected KYB to the settlement partner after a rejection (updates the existing receiver)](https://docs.caratuva.com/api-reference/kyb/resubmit-corrected-kyb-to-the-settlement-partner-after-a-rejection-updates-the-existing-receiver.md)
- [Settlement-partner KYB webhook (stub; signature check Phase 2)](https://docs.caratuva.com/api-reference/kyb/settlement-partner-kyb-webhook-stub;-signature-check-phase-2.md)
- [Whether the organization has accepted the settlement partner ToS](https://docs.caratuva.com/api-reference/kyb/whether-the-organization-has-accepted-the-settlement-partner-tos.md)
- [Issue a Courier Inbox JWT scoped to the caller](https://docs.caratuva.com/api-reference/notifications/issue-a-courier-inbox-jwt-scoped-to-the-caller.md)
- [List notifications dispatched on behalf of the calling org](https://docs.caratuva.com/api-reference/notifications/list-notifications-dispatched-on-behalf-of-the-calling-org.md)
- [Initiate settlement-partner on-ramp for this invoice using an active FX quote.](https://docs.caratuva.com/api-reference/on-ramp/initiate-settlement-partner-on-ramp-for-this-invoice-using-an-active-fx-quote.md)
- [Latest on-ramp attempt + banking instructions for this invoice (buyer's own).](https://docs.caratuva.com/api-reference/on-ramp/latest-on-ramp-attempt-+-banking-instructions-for-this-invoice-buyers-own.md)
- [Settlement-partner on-ramp completion webhook (idempotent replay-safe).](https://docs.caratuva.com/api-reference/on-ramp/settlement-partner-on-ramp-completion-webhook-idempotent-replay-safe.md)
- [Test-mode: simulate the buyer deposit by creating a settlement-partner payin.](https://docs.caratuva.com/api-reference/on-ramp/test-mode:-simulate-the-buyer-deposit-by-creating-a-settlement-partner-payin.md)
- [Onboarding status for the caller's active mode](https://docs.caratuva.com/api-reference/onboarding/onboarding-status-for-the-callers-active-mode.md)
- [Reset onboarding for the caller's active mode (test mode only)](https://docs.caratuva.com/api-reference/onboarding/reset-onboarding-for-the-callers-active-mode-test-mode-only.md)
- [Approve (enabled=true) or reject/revoke (enabled=false) an org’s production access](https://docs.caratuva.com/api-reference/ops/approve-enabled=true-or-rejectrevoke-enabled=false-an-org’s-production-access.md)
- [Issue a short-lived impersonation token (requires ops role + reason)](https://docs.caratuva.com/api-reference/ops/issue-a-short-lived-impersonation-token-requires-ops-role-+-reason.md)
- [List pending production-access requests (admin queue)](https://docs.caratuva.com/api-reference/ops/list-pending-production-access-requests-admin-queue.md)
- [Reassign the buyer on an invoice (requires ops role + email + reason)](https://docs.caratuva.com/api-reference/ops/reassign-the-buyer-on-an-invoice-requires-ops-role-+-email-+-reason.md)
- [Report a chargeback/clawback from the settlement partner; debits reserve first](https://docs.caratuva.com/api-reference/ops/report-a-chargebackclawback-from-the-settlement-partner;-debits-reserve-first.md)
- [Reset buyer KYC to not_started (requires ops role + reason)](https://docs.caratuva.com/api-reference/ops/reset-buyer-kyc-to-not_started-requires-ops-role-+-reason.md)
- [Retry a failed off-ramp (requires ops role + reason)](https://docs.caratuva.com/api-reference/ops/retry-a-failed-off-ramp-requires-ops-role-+-reason.md)
- [Set an org’s negotiated per-deal fee rate and/or monthly minimum](https://docs.caratuva.com/api-reference/ops/set-an-org’s-negotiated-per-deal-fee-rate-andor-monthly-minimum.md)
- [Payment intents](https://docs.caratuva.com/api-reference/payment-intents.md): Create payment requests with hosted payment links from your own ERP or CMS.
- [Cancel a payment intent (only valid before off-ramp settles)](https://docs.caratuva.com/api-reference/payment-intents/cancel-a-payment-intent-only-valid-before-off-ramp-settles.md)
- [Create a payment intent (integrator-facing — keeps your CMS, lets Caratuva run the payment + KYC + off-ramp).](https://docs.caratuva.com/api-reference/payment-intents/create-a-payment-intent-integrator-facing-—-keeps-your-cms-lets-caratuva-run-the-payment-+-kyc-+-off-ramp.md)
- [Get a payment intent by Caratuva id or `ext_<externalId>`](https://docs.caratuva.com/api-reference/payment-intents/get-a-payment-intent-by-caratuva-id-or-`ext_<externalid>`.md)
- [Canonical payment projection (invoice + on-ramp + events + FX).](https://docs.caratuva.com/api-reference/payments/canonical-payment-projection-invoice-+-on-ramp-+-events-+-fx.md)
- [Production-access status for the organization](https://docs.caratuva.com/api-reference/production-access/production-access-status-for-the-organization.md)
- [Request production (live mode) access for the organization](https://docs.caratuva.com/api-reference/production-access/request-production-live-mode-access-for-the-organization.md): Submits the org’s first company details + expected volume. Idempotent — an open or approved request is returned as-is. The Caratuva team is notified and approves out-of-band.
- [E2E: create an OnRampAttempt for an existing invoice so the reconciler can find it](https://docs.caratuva.com/api-reference/reconciler/e2e:-create-an-onrampattempt-for-an-existing-invoice-so-the-reconciler-can-find-it.md)
- [E2E: stage settlement-partner on-ramp truth-state without firing a webhook](https://docs.caratuva.com/api-reference/reconciler/e2e:-stage-settlement-partner-on-ramp-truth-state-without-firing-a-webhook.md)
- [Internal: run a reconciliation pass](https://docs.caratuva.com/api-reference/reconciler/internal:-run-a-reconciliation-pass.md): Called by Cloud Scheduler every 120s with the reconciler bearer token. Pulls settlement-partner + Request Network truth, synthesizes missing PaymentEvent rows via source=reconciler.
- [Transfer-pricing report (CSV) for the given quarter](https://docs.caratuva.com/api-reference/reports/transfer-pricing-report-csv-for-the-given-quarter.md)
- [Transfer-pricing report (JSON) for the given quarter](https://docs.caratuva.com/api-reference/reports/transfer-pricing-report-json-for-the-given-quarter.md): Returns one row per settled invoice in the period plus an HMAC-SHA256 manifest signature.
- [Transfer-pricing report (PDF) for the given quarter](https://docs.caratuva.com/api-reference/reports/transfer-pricing-report-pdf-for-the-given-quarter.md)
- [Request LGPD Art. 18 erasure of this buyer’s PII](https://docs.caratuva.com/api-reference/retention/request-lgpd-art-18-erasure-of-this-buyer’s-pii.md): Sets Buyer.erasureRequestedAt; the daily retention cron tombstones PII while preserving financial-record references.
- [Download a monthly statement PDF (stub until reports module lands)](https://docs.caratuva.com/api-reference/statements/download-a-monthly-statement-pdf-stub-until-reports-module-lands.md)
- [Create an outbound webhook subscription](https://docs.caratuva.com/api-reference/webhook-subscriptions/create-an-outbound-webhook-subscription.md)
- [List recent delivery attempts for a subscription](https://docs.caratuva.com/api-reference/webhook-subscriptions/list-recent-delivery-attempts-for-a-subscription.md)
- [List webhook subscriptions for this org](https://docs.caratuva.com/api-reference/webhook-subscriptions/list-webhook-subscriptions-for-this-org.md)
- [Rotate the signing secret (old secret invalid immediately)](https://docs.caratuva.com/api-reference/webhook-subscriptions/rotate-the-signing-secret-old-secret-invalid-immediately.md)
- [Soft-delete a webhook subscription](https://docs.caratuva.com/api-reference/webhook-subscriptions/soft-delete-a-webhook-subscription.md)
- [Webhooks](https://docs.caratuva.com/api-reference/webhooks.md): Subscribe to payment-intent lifecycle events. HMAC-signed, retried with exponential backoff.
- [Courier delivery-event webhook ingress](https://docs.caratuva.com/api-reference/webhooks-inbound/courier-delivery-event-webhook-ingress.md)
- [Settlement-partner webhook ingress (KYC, on-ramp, off-ramp)](https://docs.caratuva.com/api-reference/webhooks-inbound/settlement-partner-webhook-ingress-kyc-on-ramp-off-ramp.md)
- [Internal: drain outbound-webhook retry queue](https://docs.caratuva.com/api-reference/webhooks-outbound/internal:-drain-outbound-webhook-retry-queue.md): Called by Cloud Scheduler every 60s with the webhook-retry bearer token. Picks up pending WebhookDelivery rows whose nextAttemptAt has elapsed.
- [Buyer KYC](https://docs.caratuva.com/buyer-kyc.md): What we ask buyers, why, and how it shapes the payment experience.
- [Dashboard tour](https://docs.caratuva.com/dashboard.md): Every screen in the seller dashboard, what it's for, and who uses it.
- [Test & live modes](https://docs.caratuva.com/environments.md): One account, two isolated environments — a working sandbox and production.
- [Introduction](https://docs.caratuva.com/introduction.md): Cross-border B2B payments for Brazilian commodity exporters.
- [Invoicing](https://docs.caratuva.com/invoicing.md): Create, approve, share, and reconcile invoices from the dashboard.
- [Notifications](https://docs.caratuva.com/notifications.md): How Caratuva tells you what happened — in-product, by email and WhatsApp, and via webhooks.
- [Onboarding (KYB)](https://docs.caratuva.com/onboarding.md): Verify your organization before you collect live payments.
- [Payment links](https://docs.caratuva.com/payment-links.md): What your buyer sees on pay.caratuva.com, and how it gets them from invoice to paid.
- [Payouts](https://docs.caratuva.com/payouts.md): Where settled BRL lands, and how to register the destination.
- [Platform overview](https://docs.caratuva.com/platform.md): How the three Caratuva surfaces fit together.
- [Quickstart](https://docs.caratuva.com/quickstart.md): From signup to your first paid invoice in ten minutes.
- [Sign up](https://docs.caratuva.com/signup.md): Create a Caratuva account with your email — no invite, no waitlist.

## OpenAPI Specs

- [docs-json](https://api.caratuva.com/docs-json)
- [openapi](https://docs.caratuva.com/api-reference/openapi.json)