Sellers & buyers

Connected accounts are your own end clients — onboarded via /v1/accounts, KYB (businesses) or KYC (individuals), server-to-server, without redirecting anyone to a hosted flow. Each is a receiver at our settlement partner, private to your organization and bound to one mode (test or live). Two roles:

seller — a business or individual that receives payments and settles to its own PIX. This is who an invoice collects for. On approval Caratuva provisions settlement rails (verified receiver + off-ramp wallet); once you register its PIX it becomes readyToCollect and can be named on invoices.
buyer — an optional pre-KYB of a known business payer. Not required for normal flows: the payer in a hosted payment is KYC’d automatically at pay-time (Buyer KYC) and needs no connected account.

A seller here is the settlement target of your invoices. Once it reports readyToCollect: true, reference it by externalId when you create an invoice or payment intent (sellerExternalId) — funds settle to that seller’s PIX. See the Sellers quickstart.

Authentication & scopes

All routes use your API key (X-API-Key: pk_<test|live>_...). The key’s prefix fixes the mode — a connected account created with a pk_test_ key is invisible to live and routes to the settlement partner sandbox. Routes require the relevant scope (keys with no scopes set are unrestricted, for backward compatibility):

Scope	Grants
`connected_accounts:write`	create, ToS, upload-url, submit, payout-config
`connected_accounts:read`	get, list

The lifecycle

create ──▶ (tos-session ▶ tos-accepted) ──▶ [upload-url …] ──▶ submit ──▶ verifying ──▶ approved | rejected
                                                                                    │
                                                                 seller approved ───▶ settlement provisioned
                                                                                    └▶ payout-config (PIX)

status values: created (local shell, no receiver yet) · verifying (submitted to the settlement partner) · approved · rejected.

1. Create

curl -X POST https://api.caratuva.com/v1/accounts \
  -H "X-API-Key: $CARATUVA_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "role": "seller",
    "entityType": "business",
    "externalId": "merchant-42",
    "legalName": "Acme Comércio LTDA",
    "country": "BR"
  }'

Field	Type	Required	Notes
`role`	`seller` \| `buyer`	yes	What the end client will do once verified.
`entityType`	`business` \| `individual`	yes	Selects the verification path on `submit`.
`externalId`	string (1–200)	no	Your primary key for this end client. Unique per `(org, mode)`. Re-creating with the same value returns the existing account — safe under retry.
`email`, `legalName`, `displayName`, `country`, `taxId`	string	no	Identity hints; finalised on `submit`.

Returns a ConnectedAccount with status: "created".

2. Terms of Service (per end client)

Our settlement partner requires ToS acceptance before a receiver can be created. Mint a session, direct your end client to the URL, and record the tos_id from the redirect.

# Mint a session
curl -X POST https://api.caratuva.com/v1/accounts/{id}/tos-session \
  -H "X-API-Key: $CARATUVA_API_KEY" -H "content-type: application/json" \
  -d '{ "redirectUrl": "https://app.example.com/onboarding/{id}/tos-done" }'
# -> { "url": "https://...", "idempotencyKey": "..." }

# After the redirect carries ?tos_id=...
curl -X POST https://api.caratuva.com/v1/accounts/{id}/tos-accepted \
  -H "X-API-Key: $CARATUVA_API_KEY" -H "content-type: application/json" \
  -d '{ "tosId": "tos_..." }'

tos-accepted requires a session minted first (it binds the redirect to this account, closing the cross-account tos_id replay window). You may also pass tosId directly on submit; it must match the recorded value.

3. Documents (optional)

Provide your own pre-hosted HTTPS URLs in the submit body, or mint short-lived signed upload URLs:

curl -X POST https://api.caratuva.com/v1/accounts/{id}/upload-url \
  -H "X-API-Key: $CARATUVA_API_KEY" -H "content-type: application/json" \
  -d '{ "kind": "id_doc_front", "contentType": "image/jpeg" }'
# -> { uploadUrl, publicUrl, uploadHeaders, uploadMethod, expiresAt }

kind: selfie · id_doc_front · id_doc_back · proof_of_address · incorporation_doc · proof_of_ownership_doc. For business beneficial owners, pass ownerIndex (a zero-based integer, 0–20). PUT the bytes to uploadUrl with the returned headers, then pass publicUrl in submit. Returns 503 KycStorageDisabled if document storage isn’t configured — use pre-hosted URLs instead.

4. Submit to the settlement partner

One endpoint; the fields required depend on (role, entityType). Missing fields return 400 ConnectedAccountMissingFields with the offending paths. Seller business (createKyb, Brazilian CNPJ):

curl -X POST https://api.caratuva.com/v1/accounts/{id}/submit \
  -H "X-API-Key: $CARATUVA_API_KEY" -H "content-type: application/json" \
  -d '{ "email": "ops@acme.com.br", "legalName": "Acme Comércio LTDA", "cnpj": "12345678000199" }'

Individual (createKyc):

curl -X POST https://api.caratuva.com/v1/accounts/{id}/submit \
  -H "X-API-Key: $CARATUVA_API_KEY" -H "content-type: application/json" \
  -d '{
    "email": "jane@example.com",
    "firstName": "Jane", "lastName": "Doe",
    "dateOfBirth": "1990-04-12",
    "idDocCountry": "US", "idDocType": "PASSPORT",
    "selfieFile": "https://...", "idDocFrontFile": "https://..."
  }'

Buyer business (createBuyerKyb) requires legalName, formationDate, taxId, website, country, address fields, incorporationDocFile, proofOfOwnershipDocFile, and at least one owners[] beneficial owner (role, name, dateOfBirth, taxId, address, idDocType, selfieFile, idDocFrontFile, proofOfAddressDocType, proofOfAddressDocFile). submit is idempotent while the account is verifying/approved — it returns the current submission rather than creating a second receiver. In the sandbox, KYB auto-approves; KYC resolves to verifying and completes via webhook.

5. Seller payout destination (PIX)

After a seller is approved, register where it gets paid. The raw PIX key is sent to our settlement partner and never stored by Caratuva.

curl -X POST https://api.caratuva.com/v1/accounts/{id}/payout-config \
  -H "X-API-Key: $CARATUVA_API_KEY" -H "content-type: application/json" \
  -d '{ "pixKey": "acme@pix.example.com", "accountHolderName": "Acme Comércio LTDA" }'

Sellers only, and the account must be approved first (400 ConnectedAccountNotApproved otherwise). After this the account reports payoutConfigured: true and — with KYB approved + an off-ramp wallet + PIX — readyToCollect: true. That boolean is your single gate: only a readyToCollect seller can be named on an invoice.

6. Collect for this seller

Once a seller is readyToCollect, create an invoice (or payment intent) naming it by externalId — funds settle to that seller’s PIX:

curl -X POST https://api.caratuva.com/v1/invoices \
  -H "X-API-Key: $CARATUVA_API_KEY" -H "content-type: application/json" \
  -d '{
    "sellerExternalId": "merchant-42",
    "buyerEmail": "buyer@example.com", "buyerName": "Foreign Buyer Inc",
    "amount": "1000.00",
    "lineItems": [{ "description": "Order #42", "quantity": "1", "unitPrice": "1000.00", "subtotal": "1000.00" }]
  }'

The buyer pays via the returned hosted link; on settlement the seller receives BRL on its registered PIX. sellerExternalId is required on every invoice and payment intent.

Read

curl https://api.caratuva.com/v1/accounts/{id} -H "X-API-Key: $CARATUVA_API_KEY"
curl "https://api.caratuva.com/v1/accounts?role=seller&status=approved&limit=50" \
  -H "X-API-Key: $CARATUVA_API_KEY"

The ConnectedAccount object includes status, receiverId, tosAccepted, payoutConfigured, readyToCollect, and approvedAt / rejectedAt. List is cursor-paginated (nextCursor), filterable by role and status.

How status updates land

The settlement partner’s verification decision arrives at Caratuva’s signed inbound webhook; Caratuva resolves the receiver to your connected account and updates its status (idempotently). A terminal decision (approved/rejected) also purges any documents Caratuva stored for the account. To observe the result today, poll GET /v1/accounts/:id (or GET /v1/accounts?status=verifying) until status is terminal. In the sandbox, seller-business KYB auto-approves synchronously on submit, so the submit response already carries approved.

Subscribe to connected_account.* outbound webhooks to learn when a seller becomes collectible without polling: connected_account.created, connected_account.kyb_approved, connected_account.kyb_rejected, and connected_account.ready_to_collect. See Webhooks.

Overview

Integration

Endpoints

Authentication & scopes

The lifecycle

1. Create

2. Terms of Service (per end client)

3. Documents (optional)

4. Submit to the settlement partner

5. Seller payout destination (PIX)

6. Collect for this seller

Read

How status updates land

​Authentication & scopes

​The lifecycle

​1. Create

​2. Terms of Service (per end client)

​3. Documents (optional)

​4. Submit to the settlement partner

​5. Seller payout destination (PIX)

​6. Collect for this seller

​Read

​How status updates land

Authentication & scopes

The lifecycle

1. Create

2. Terms of Service (per end client)

3. Documents (optional)

4. Submit to the settlement partner

5. Seller payout destination (PIX)

6. Collect for this seller

Read

How status updates land