Pular para o conteúdo principal
As contas conectadas permitem que você — o integrador — execute KYB (empresas) ou KYC (pessoas físicas) em nome dos seus próprios clientes finais, servidor a servidor, sem redirecionar ninguém para um fluxo hospedado. Cada conta conectada é um recebedor no nosso parceiro de liquidação que é 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 vai receber pagamentos e liquidar na sua própria conta bancária/PIX. Na aprovação, a Caratuva provisiona os trilhos de liquidação para que o vendedor fique pronto para repasses.
  • buyer — um pagador que você verifica antes de um pagamento.
Esta é a superfície de onboarding/verificação. A v1 deixa um vendedor conectado pronto para repasses (recebedor verificado + carteira de off-ramp + destino PIX registrado), mas rotear os fundos de um pedido de pagamento para um vendedor conectado — e permitir que um comprador conectado pague sem refazer o KYC — são etapas posteriores. O KYC do comprador para o fluxo de pagamento hospedado permanece inalterado (Buyer KYC).

​
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):
EscopoConcede
connected_accounts:writecreate, ToS, upload-url, submit, payout-config
connected_accounts:readget, 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/connected-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"
  }'
CampoTipoObrigatórioObservações
roleseller | buyersimO que o cliente final fará depois de verificado.
entityTypebusiness | individualsimSeleciona o caminho de verificação no submit.
externalIdstring (1–200)nãoSua 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, taxIdstringnãoDicas 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/connected-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/connected-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/connected-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/connected-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/connected-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/connected-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.

​
Consultar

curl https://api.caratuva.com/v1/connected-accounts/{id} -H "X-API-Key: $CARATUVA_API_KEY"
curl "https://api.caratuva.com/v1/connected-accounts?role=seller&status=approved&limit=50" \
  -H "X-API-Key: $CARATUVA_API_KEY"
O objeto ConnectedAccount inclui status, receiverId, tosAccepted, payoutConfigured 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/connected-accounts/:id (ou GET /v1/connected-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.
Eventos de webhook de saída para mudanças de status de contas conectadas (por exemplo, connected_account.approved) são uma etapa posterior — diferentemente dos pedidos de pagamento, uma conta conectada não está vinculada à linha do tempo de uma fatura. Por enquanto, faça polling nos endpoints de consulta.