> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caratuva.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Início rápido B2B

> De zero ao primeiro pagamento liquidado em cinco passos.

Este é o caminho mais curto para um integrador B2B: mantenha seu próprio ERP/sistema de faturamento, deixe que a Caratuva cuide do pagamento + KYC + liquidação internacional, e reconcilie via webhooks. O fluxo completo leva minutos no modo teste e é idêntico em produção.

## O que a Caratuva faz nesta superfície

* Aceita um payment intent 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.

Você mantém o relacionamento com o cliente, a gestão de pedidos e a autoridade sobre os itens. A Caratuva mantém o encanamento regulatório e de liquidação.

## Passo 1 — Emitir uma chave de API

Entre no painel e crie uma chave `pk_test_` para desenvolvimento, mais uma `pk_live_` para produção. Guarde as duas no cofre. O segredo aparece exatamente uma vez na criação.

Veja [Chaves de API](/pt-BR/api-reference/api-keys) para o CRUD completo.

## Passo 2 — Cadastrar uma inscrição de webhook

Antes de criar o primeiro intent, inscreva-se nos eventos `payment_intent.*` que importam. O segredo de assinatura também volta exatamente uma vez.

```bash theme={null}
curl -X POST https://api.caratuva.com/v1/webhook-subscriptions \
  -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"
    ]
  }'
```

Veja [Webhooks](/pt-BR/api-reference/webhooks) para o formato de assinatura, política de retentativa e exemplos por linguagem.

## Passo 3 — Criar um payment intent

Cada intent é um pedido de cobrança de valor específico de comprador específico. `externalId` é sua chave primária — re-POSTar o mesmo valor é seguro.

```bash theme={null}
curl -X POST https://api.caratuva.com/v1/payment-intents \
  -H "X-API-Key: $CARATUVA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
    "externalId": "INV-2026-00042",
    "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" }
  }'
```

A resposta carrega o campo que você de fato precisa:

```json theme={null}
{
  "id": "ckabc...",
  "status": "awaiting_buyer",
  "hostedPaymentUrl": "https://pay.caratuva.com/r/ckpub..."
}
```

Veja [Payment intents](/pt-BR/api-reference/payment-intents) para o schema completo de requisição e resposta.

## Passo 4 — Encaminhar o link de pagamento

E-mail, SMS, ou renderize o `hostedPaymentUrl` na sua UI — qualquer canal que você já usa para engajar o comprador. A Caratuva não envia e-mail automático ao comprador na superfície de payment-intent, porque você é dono do relacionamento.

A página hospedada cuida do login por magic link, KYC, cotação de câmbio e coleta. Seu comprador não sai de `pay.caratuva.com` até o redirect para `returnUrl` após a liquidação.

## Passo 5 — Reconciliar via webhooks

Toda mudança de estado dispara um evento `payment_intent.*`. Os dois eventos que importam para a maioria dos ERPs:

* `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/payment-intents/{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.

Use `X-Caratuva-Delivery-Id` como chave de idempotência — a Caratuva reentrega até sete vezes com backoff exponencial (imediato, 30s, 2m, 10m, 1h, 6h, 24h) e seu endpoint vê o mesmo delivery id em toda tentativa.

## Modo teste

Chaves `pk_test_` rodam o fluxo inteiro de ponta a ponta contra uma instância de pagamento sandbox. As mesmas transições de intent, os mesmos webhooks, os mesmos formatos de resposta — mas KYB e KYC do comprador são aprovados automaticamente e nenhum dinheiro real se move. Use para CI e staging. Veja [Ambientes](/pt-BR/api-reference/environments).

## Armadilhas comuns

* **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](/pt-BR/api-reference/payment-intents) — schema completo, códigos de erro, máquina de estados.
* [Webhooks](/pt-BR/api-reference/webhooks) — verificação de assinatura, política de retentativa, referência de eventos `payment_intent.*`.
* [Chaves de API](/pt-BR/api-reference/api-keys) — emissão, rotação, revogação.