Guia de integração

Seu servidor cria uma cobrança pela API e o kokiwa avisa por webhook quando ela chega. Os fundos vão direto para sua carteira na blockchain; o kokiwa nunca os guarda.

Antes de começar

Tudo isso é feito no painel do comerciante.

1. Cadastre-seVerifique seu e-mail, configure um app autenticador e guarde os códigos de recuperação.
2. Crie um projetoUm projeto é um dos seus produtos ou sites, com endereços de recebimento, chaves de API e webhooks próprios.
3. Configure o recebimentoEm Configurações de recebimento do projeto, escolha redes, formas de recebimento e tokens, e registre um endereço de recebimento em cada rede com sua carteira. O endereço fica registrado na blockchain e só a carteira que o registrou pode alterá-lo. Registrar custa um pouco de gas; uma carteira pode registrar todas as redes EVM.
4. Crie uma chave de APIA chave aparece uma única vez. Guarde-a em uma variável de ambiente do servidor, nunca no front-end ou em um app.
5. Configure um webhookNa página Webhooks, informe sua URL https, guarde o segredo de assinatura e clique em Enviar evento de teste para confirmar a entrega.

Escolha como receber

Você pode usar os dois.

Pagamento

Crie um pagamento quando o usuário fizer um pedido e abra para ele a checkout_url retornada. A requisição abaixo oferece todas as redes em que o projeto aceita USDT, e o usuário escolhe uma.

curl https://api.kokiwa.com/v1/payment_intents \
  -H "Authorization: Bearer $KOKIWA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10086" \
  -d '{
    "currency": "USDT",
    "amount": "25.00",
    "customer": "user_42",
    "metadata": { "order_id": "10086" },
    "success_url": "https://your-shop.com/orders/10086"
  }'

Endereço de depósito

Em customer, informe o ID do usuário no seu sistema. Chamadas repetidas para o mesmo usuário retornam o mesmo endereço.

curl https://api.kokiwa.com/v1/deposit_addresses \
  -H "Authorization: Bearer $KOKIWA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "customer": "user_42" }'

Confirme o recebimento

Quando um pagamento é confirmado na blockchain, o kokiwa envia um webhook. Credite apenas com base em webhooks, nunca porque o usuário voltou para success_url.

• Pagamento: em payment_intent.paid, marque o pedido como pago.
• Endereço de depósito: em deposit.confirmed, some ao saldo de data.deposit.customer.

Verifique a assinatura de cada evento e elimine duplicados pelo id do evento, veja Webhooks.

Valores

Todos os valores são strings em unidades do token, como "25.00" ou "24.9125", em requisições, respostas e webhooks, então não há conversão por rede. Os valores mantêm a precisão completa da blockchain, por isso o número de casas decimais varia. Nunca calcule com ponto flutuante.

Reembolsos

Os fundos já estão na sua carteira, então o kokiwa não tem endpoint de reembolso e não pode reverter um pagamento. Para reembolsar, envie do seu endereço de recebimento para o usuário. Peça um endereço de reembolso em vez de usar transaction.from, que é o endereço da corretora quando o usuário sacou de uma. As taxas não são devolvidas.

Checklist de lançamento

• As chaves de API estão só no servidor, não em repositórios de código nem em logs.
• Os webhooks verificam assinaturas, e um evento repetido não é creditado duas vezes.
• Os pagamentos são criados com Idempotency-Key, então uma nova tentativa de rede não cria dois.
• payment_intent.paid_late é tratado, então um pagamento após a expiração não se perde.
• Os endereços de recebimento estão registrados na mainnet e você passou a usar uma chave que começa com sk_live_.
• A frase-semente do endereço de recebimento tem backup.