Início rápido B2B

​

O que a Caratuva faz nesta superfície

• Faz onboarding dos seus vendedores (KYB + PIX) para que cada um receba na própria conta.
• Aceita um payment intent — para um dos seus vendedores — do seu servidor.
• Retorna uma URL hospedada de pagamento que você encaminha ao comprador.
• Faz onboarding do comprador via KYC (obrigatório — sem caminho para pular).
• Coleta o pagamento, executa transferência internacional + câmbio, e repassa o BRL via PIX para o destino cadastrado do vendedor.
• Notifica seu ERP via webhooks assinados a cada mudança de estado.

​

Passo 1 — Emitir uma chave de API

​

Passo 2 — Fazer onboarding de um vendedor

# Crie o vendedor (depois ToS → documentos opcionais → submit KYB)
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" }'

# Após o KYB aprovado, cadastre onde ele recebe (PIX)
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" }'

​

Passo 3 — Cadastrar uma inscrição de webhook

curl -X POST https://api.caratuva.com/v1/webhooks \
  -H "X-API-Key: $CARATUVA_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "url": "https://erp.example.com/webhooks/caratuva",
    "eventTypes": [
      "payment_intent.created",
      "payment_intent.buyer_kyc_approved",
      "payment_intent.on_chain_confirmed",
      "payment_intent.settled",
      "payment_intent.failed",
      "payment_intent.cancelled",
      "payment_intent.expired"
    ]
  }'

​

Passo 4 — Criar um payment intent para o vendedor

curl -X POST https://api.caratuva.com/v1/payments \
  -H "X-API-Key: $CARATUVA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
    "externalId": "INV-2026-00042",
    "sellerExternalId": "merchant-42",
    "amount": "12500.00",
    "currency": "USD",
    "buyer": { "email": "buyer@acme.com", "name": "ACME Imports LLC", "country": "US" },
    "returnUrl": "https://erp.example.com/orders/42/paid",
    "metadata": { "orderId": "42" }
  }'

{
  "id": "ckabc...",
  "status": "awaiting_buyer",
  "hostedPaymentUrl": "https://pay.caratuva.com/r/ckpub..."
}

​

Passo 5 — Encaminhar o link de pagamento

​

Passo 6 — Reconciliar via webhooks

• payment_intent.settled — fundos na conta BRL do vendedor. Marque o pedido como pago no seu sistema. O payload carrega paymentIntentId, externalId e o metadata original (além de source e externalEventId). Para os valores de liquidação (amount, currency, brlSettledAmount, fxRateAtSettlement), faça um GET /v1/payments/{id} ao receber — eles não estão no corpo do webhook.
• payment_intent.failed — falha terminal. O payload carrega o motivo. Estorne o pedido ou exiba erro ao comprador.

​

Modo teste

​

Armadilhas comuns

• Faturar um vendedor que não está readyToCollect. Faça o onboarding do vendedor (KYB + PIX) antes; sellerExternalId precisa referenciar um vendedor aprovado e com PIX cadastrado.
• E-mail do comprador ausente. Obrigatório e precisa ser real — é para lá que vai o magic link.
• Enviar floats. Passe amount como string ("12500.00") para evitar drift de float.
• Re-serializar o body do webhook antes de verificar. A assinatura é computada sobre os bytes brutos. Sempre verifique contra req.rawBody, não JSON.stringify(req.body).
• Reusar Idempotency-Key em operações lógicas distintas. É escopada por organização e colapsa retentativas; não compartilhe entre intents distintos.

​

Para onde ir

• Payment intents — schema completo, códigos de erro, máquina de estados.
• Webhooks — verificação de assinatura, política de retentativa, referência de eventos payment_intent.*.
• Chaves de API — emissão, rotação, revogação.