Pular para o conteúdo principal
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 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. 
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 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. 
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: 
{
  "id": "ckabc...",
  "status": "awaiting_buyer",
  "hostedPaymentUrl": "https://pay.caratuva.com/r/ckpub..."
}
Veja Payment intents para o schema completo de requisição e resposta. 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.

​
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 — 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.