Vendedores e compradores

As contas conectadas são os seus próprios clientes finais — onboarding via /v1/accounts, KYB (empresas) ou KYC (pessoas físicas), servidor a servidor, sem redirecionar ninguém para um fluxo hospedado. Cada uma é um recebedor no nosso parceiro de liquidação, privado da sua organização e vinculado a um modo (teste ou produção). Dois papéis:

seller — uma empresa ou pessoa física que recebe pagamentos e liquida no próprio PIX. É para ele que uma fatura cobra. Na aprovação, a Caratuva provisiona os trilhos de liquidação (recebedor verificado + carteira de off-ramp); ao registrar o PIX dele, ele fica readyToCollect e pode ser indicado em faturas.
buyer — um pré-KYB opcional de um pagador empresa já conhecido. Não é necessário no fluxo normal: o pagador de um pagamento hospedado passa por KYC automaticamente no momento do pagamento (Buyer KYC) e não precisa de conta conectada.

Um vendedor aqui é o destino de liquidação das suas faturas. Assim que ele reportar readyToCollect: true, indique-o pelo externalId ao criar uma fatura ou um pedido de pagamento (sellerExternalId) — os fundos liquidam no PIX desse vendedor. Veja o Guia rápido de vendedores.

Autenticação e escopos

Todas as rotas usam sua chave de API (X-API-Key: pk_<test|live>_...). O prefixo da chave fixa o modo — uma conta conectada criada com uma chave pk_test_ é invisível em produção e roteia para o sandbox do parceiro de liquidação. As rotas exigem o escopo correspondente (chaves sem escopos definidos não têm restrição, por compatibilidade retroativa):

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

O ciclo de vida

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

Valores de status: created (casca local, ainda sem recebedor) · verifying (enviado ao parceiro de liquidação) · approved · rejected.

1. Criar

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"
  }'

Campo	Tipo	Obrigatório	Observações
`role`	`seller` \| `buyer`	sim	O que o cliente final fará depois de verificado.
`entityType`	`business` \| `individual`	sim	Seleciona o caminho de verificação no `submit`.
`externalId`	string (1–200)	não	Sua chave primária para este cliente final. Único por `(org, mode)`. Recriar com o mesmo valor retorna a conta existente — seguro sob retentativa.
`email`, `legalName`, `displayName`, `country`, `taxId`	string	não	Dicas de identidade; finalizadas no `submit`.

Retorna um ConnectedAccount com status: "created".

2. Termos de Serviço (por cliente final)

Nosso parceiro de liquidação exige a aceitação dos Termos de Serviço antes que um recebedor possa ser criado. Crie uma sessão, direcione seu cliente final para a URL e registre o tos_id vindo do redirecionamento.

# 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_..." }'

O tos-accepted exige que uma sessão tenha sido criada primeiro (ela vincula o redirecionamento a esta conta, fechando a janela de replay do tos_id entre contas). Você também pode passar o tosId diretamente no submit; ele deve corresponder ao valor registrado.

3. Documentos (opcional)

Forneça suas próprias URLs HTTPS pré-hospedadas no corpo do submit, ou crie URLs de upload assinadas e de curta duração:

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. Para beneficiários finais de empresas, passe ownerIndex (um inteiro baseado em zero, 0–20). Faça o PUT dos bytes para uploadUrl com os headers retornados e, em seguida, passe publicUrl no submit. Retorna 503 KycStorageDisabled se o armazenamento de documentos não estiver configurado — use URLs pré-hospedadas nesse caso.

4. Enviar ao parceiro de liquidação

Um único endpoint; os campos exigidos dependem de (role, entityType). Campos ausentes retornam 400 ConnectedAccountMissingFields com os caminhos problemáticos. Vendedor empresa (createKyb, CNPJ brasileiro):

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" }'

Pessoa física (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://..."
  }'

Comprador empresa (createBuyerKyb) exige legalName, formationDate, taxId, website, country, campos de endereço, incorporationDocFile, proofOfOwnershipDocFile e ao menos um beneficiário final em owners[] (role, nome, dateOfBirth, taxId, endereço, idDocType, selfieFile, idDocFrontFile, proofOfAddressDocType, proofOfAddressDocFile). O submit é idempotente enquanto a conta está verifying/approved — ele retorna o envio atual em vez de criar um segundo recebedor. No sandbox, o KYB é aprovado automaticamente; o KYC fica em verifying e é concluído via webhook.

5. Destino de repasse do vendedor (PIX)

Depois que um vendedor é aprovado, registre onde ele recebe os pagamentos. A chave PIX bruta é enviada ao nosso parceiro de liquidação e nunca é armazenada pela 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" }'

Apenas para vendedores, e a conta precisa estar approved primeiro (caso contrário, 400 ConnectedAccountNotApproved). Depois disso, a conta reporta payoutConfigured: true e — com KYB aprovado + carteira de off-ramp + PIX — readyToCollect: true. Esse booleano é o seu único gate: só um vendedor readyToCollect pode ser indicado em uma fatura.

6. Cobrar para este vendedor

Assim que um vendedor está readyToCollect, crie uma fatura (ou pedido de pagamento) indicando-o pelo externalId — os fundos liquidam no PIX desse vendedor:

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": "Pedido #42", "quantity": "1", "unitPrice": "1000.00", "subtotal": "1000.00" }]
  }'

O comprador paga pelo link hospedado retornado; na liquidação, o vendedor recebe em BRL no PIX registrado. sellerExternalId é obrigatório em toda fatura e pedido de pagamento.

Consultar

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"

O objeto ConnectedAccount inclui status, receiverId, tosAccepted, payoutConfigured, readyToCollect e approvedAt / rejectedAt. A listagem é paginada por cursor (nextCursor), filtrável por role e status.

Como as atualizações de status chegam

A decisão de verificação do parceiro de liquidação chega ao webhook de entrada assinado da Caratuva; a Caratuva resolve o recebedor para a sua conta conectada e atualiza o status dela (de forma idempotente). Uma decisão terminal (approved/rejected) também expurga quaisquer documentos que a Caratuva tenha armazenado para a conta. Para observar o resultado hoje, faça polling em GET /v1/accounts/:id (ou GET /v1/accounts?status=verifying) até que status seja terminal. No sandbox, o KYB de vendedor empresa é aprovado automaticamente e de forma síncrona no submit, então a resposta do submit já carrega approved.

Assine os webhooks de saída connected_account.* para saber quando um vendedor fica apto a cobrar, sem precisar de polling: connected_account.created, connected_account.kyb_approved, connected_account.kyb_rejected e connected_account.ready_to_collect. Veja Webhooks.

Visão geral

Integração

Endpoints

Vendedores e compradores

Autenticação e escopos

O ciclo de vida

1. Criar

2. Termos de Serviço (por cliente final)

3. Documentos (opcional)

4. Enviar ao parceiro de liquidação

5. Destino de repasse do vendedor (PIX)

6. Cobrar para este vendedor

Consultar

Como as atualizações de status chegam

​Autenticação e escopos

​O ciclo de vida

​1. Criar

​2. Termos de Serviço (por cliente final)

​3. Documentos (opcional)

​4. Enviar ao parceiro de liquidação

​5. Destino de repasse do vendedor (PIX)

​6. Cobrar para este vendedor

​Consultar

​Como as atualizações de status chegam

Autenticação e escopos

O ciclo de vida

1. Criar

2. Termos de Serviço (por cliente final)

3. Documentos (opcional)

4. Enviar ao parceiro de liquidação

5. Destino de repasse do vendedor (PIX)

6. Cobrar para este vendedor

Consultar

Como as atualizações de status chegam