Crie uma credencial em Painel → Desenvolvedores.
Escolha as permissões e guarde os dois segredos exibidos uma única vez: a chave de API e o
segredo de callback.
1
Consulte seu saldo
A permissão read basta. Envie o token no cabeçalho Authorization; cookies
e sessão web não são necessários.
2
Confira o custo
Envie os dados do pagamento a POST /quotes. O retorno informa o débito
total, incluindo tarifas e spread.
3
Crie e acompanhe a operação
Use POST /operations com uma Idempotency-Key persistente e o teto de
débito revisado. Salve o ID retornado e acompanhe até concluir.
Uma chamada, três linguagens
GET /balances
202 significa “aceita para processamento”.
Confirme o resultado pelo recurso da operação. processing e
review exigem acompanhamento; não crie outro pagamento por presumir falha.
Autenticação por token
Envie Authorization: Bearer cc_live_… em todas as chamadas. Mantenha
credenciais no backend e crie uma chave para cada integração. Revogar ou expirar uma chave
bloqueia novas chamadas; operações aceitas continuam seu processamento.
Permissões disponíveis
Permissão
O que permite
read
Consultar saldo, conta, tarifas, recursos e eventos; simular e consultar pagamentos.
payments:write
Iniciar operações que debitam o saldo.
cards:write
Emitir e recarregar cartões; exige também payments:write.
deposits:write
Preparar endereços para depósitos cripto.
webhooks:write
Gerenciar, testar e rotacionar webhooks; reenviar entregas.
Gerenciar chaves
Até 10 chaves ativas por conta. Emissão, revogação e configuração de IP ficam no painel do
titular e usam a proteção de senha/2FA da conta.
Controle de acesso às saídas
A regra é configurada por conta em Desenvolvedores e vale para todas as suas chaves e
modalidades de saída da API.
DESATIVADA · PADRÃO
Qualquer IP autenticado
Uma chave válida, com permissão e saldo, pode iniciar saídas de qualquer endereço IP.
ATIVADA
Somente IPs cadastrados
Uma origem fora da lista recebe 403 IP_NOT_ALLOWED antes de qualquer
débito.
Configurar a whitelist
Cadastre até 32 endereços IPv4/IPv6 exatos, sem porta ou CIDR. Use o IP público de saída do
servidor da sua integração. A lista ativa exige ao menos um IP. Consultas, depósitos e
notificações continuam disponíveis.
Repetir uma requisição com segurança
Envie Idempotency-Key em toda criação de operação: de 16 a 128 caracteres,
letras, números, hífen ou sublinhado. Salve essa chave antes da primeira tentativa.
Se acontecer…
O resultado é…
Mesma chave e mesmo payload
A mesma operação, sem outro débito. HTTP 200 e Idempotent-Replayed: true.
Mesma chave, payload diferente
409 IDEMPOTENCY_CONFLICT.
Timeout ou resposta perdida
Consulte a operação ou repita com a mesma chave e o mesmo payload.
cents é um inteiro em centavos de BRL. available_micros,
debit_micros e max_debit_micros são strings decimais:
1000000 corresponde a 1 USDT. Use BigInt ou Decimal. Quantidades dos ativos em
depósitos também são strings decimais.
O teto max_debit_micros é obrigatório e inclui tarifas. Obtenha-o em
/quotes. A cotação é indicativa; o teto protege o valor autorizado. Campos
legados em camelCase, como walletDeltaMicros, são inteiros JSON documentados
nos schemas.
Revise o favorecido e substitua o teto pelo custo que você autorizou em /quotes. O exemplo
não é uma cotação atual.
Cadastre seu endpoint
Cadastre uma URL HTTPS pública em POST /webhooks, selecione os eventos e guarde
o secret retornado. A API oferece criação, consulta, atualização, remoção,
rotação de segredo e evento de teste.
Tipos de evento
Evento
Quando observar
operation.created
Uma operação da API foi aceita e persistida.
operation.updated
O estado, resultado ou devolução da operação mudou.
deposit.updated
Um depósito da conta mudou de estado ou valor creditado.
webhook.test
Teste solicitado pela API; não movimenta saldo.
Responda 2xx após verificar e persistir o evento. Deduplicate pelo event.id;
entregas podem se repetir e chegar fora de ordem. O mesmo ID representa o mesmo evento em
callbacks e webhooks.
Intervalos após a tentativa anterior · timeout de 10s · sem redirecionamentos
Use GET /deliveries para inspecionar tentativas e
POST /deliveries/{id}/retry para reenviar uma entrega com falha ou cancelada.
Desativar ou remover um webhook cancela as pendências; entregas em trânsito podem chegar.
Reativar não reproduz todo o histórico.
Envie a URL no payload
Adicione callback_url ao payload de POST /operations. Você recebe
os eventos dessa operação sem cadastrar um webhook.
Valide com o callback_secret da chave que criou a operação. URL e segredo
ficam associados ao pedido aceito; revogar a chave não interrompe notificações de operações
já aceitas. Callback e webhook podem coexistir.
Sem receptor de eventos? Use polling.
Omitir callback_url e não cadastrar webhooks é uma configuração válida. O processamento
financeiro e as consultas continuam funcionando.
Consultar uma operação
Consulte GET /operations/{id} com intervalo de pelo menos 5 segundos. O
cabeçalho Retry-After indica quando consultar novamente.
processing→completedreviewfailed
review exige conciliação; não repita o pagamento com uma nova chave. Em
operações compostas, confira cada transação: emissão de cartão e recarga podem ter
resultados diferentes. Devoluções posteriores continuam aparecendo no recurso e no extrato.
Polling por cursor
Use GET /events?after=0&limit=100. Depois de persistir os eventos, salve
pagination.next_cursor e passe-o em after. Continue enquanto
has_more for verdadeiro. Eventos são ordenados por sequence, uma
string decimal.
Operações pendentes são observadas aproximadamente a cada 5s; depósitos em cerca de 1–2
minutos. Transições muito rápidas podem aparecer apenas no estado final. O detalhe de uma
operação consulta o estado financeiro na hora.
Validar o corpo original
O cabeçalho X-CriptoCore-Signature contém o timestamp e um HMAC SHA-256. Use o
corpo original em bytes, antes de convertê-lo em JSON. Aceite uma tolerância máxima de 300
segundos e compare em tempo constante.
Node.js · validação de assinatura
import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(rawBody, header, secret) {
const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header || '');
if (!match) return false;
const age = Math.abs(Date.now() / 1000 - Number(match[1]));
if (age > 300) return false;
const expected = createHmac('sha256', secret)
.update(match[1] + '.')
.update(rawBody)
.digest();
const received = Buffer.from(match[2], 'hex');
return received.length === expected.length
&& timingSafeEqual(received, expected);
}
Use o segredo literal ccwh_…. Após verificar, grave o evento com índice único
em id, enfileire o processamento e responda 2xx. Uma repetição válida também
deve receber 2xx.
Formato de erro
HTTP 403
{
"error": {
"code": "IP_NOT_ALLOWED",
"message": "Este IP não está autorizado a realizar saídas pela API.",
"request_id": "identificador-da-requisicao"
}
}
Códigos HTTP
HTTP
Como tratar
400
Corrija os campos; details informa os caminhos inválidos.
401 / 403
Confira credencial, expiração, permissões, whitelist e situação da conta.
404
Recurso inexistente ou pertencente a outra conta.
409 / 422
Leia code e message. Pode haver conflito de idempotência, teto de débito ou regra
financeira.
429
Respeite Retry-After e adicione jitter nas novas tentativas.
500 / 503
Consulte a operação antes de repetir. Preserve chave de idempotência e payload.
Limites e diagnóstico
Limites: 120 chamadas/min por conta, 30 novas operações/min e 20 consultas
de boleto/dia. O serviço também limita 300 chamadas/min por IP. As chaves da mesma conta
compartilham as cotas.
Use X-Request-Id ao investigar uma falha. Nunca registre Authorization ou
segredos em logs. Campos adicionais podem ser incluídos nas respostas; clientes devem
ignorar os desconhecidos.