Guía de integración

Tu servidor crea un cobro con la API y kokiwa te avisa con un webhook cuando llega. Los fondos van directamente a tu billetera en la cadena; kokiwa nunca los retiene.

Antes de empezar

Todo esto se hace en el panel de comercio.

1. RegístrateVerifica tu correo, configura una app de autenticación y guarda los códigos de recuperación.
2. Crea un proyectoUn proyecto es uno de tus productos o sitios web, con sus propias direcciones de cobro, claves API y webhooks.
3. Configura los cobrosEn Ajustes de cobro del proyecto, elige cadenas, métodos de cobro y tokens, y registra una dirección de cobro en cada cadena con tu billetera. La dirección de cobro queda en la cadena y solo la billetera que la registró puede cambiarla. Registrar cuesta un poco de gas; una billetera puede registrar todas las cadenas EVM.
4. Crea una clave APILa clave se muestra una sola vez. Guárdala en una variable de entorno del servidor, nunca en el front-end ni en una app.
5. Configura un webhookEn la página Webhooks, escribe tu URL https, guarda el secreto de firma y pulsa Enviar evento de prueba para confirmar que llega.

Elige cómo cobrar

Puedes usar ambos.

Pago

Crea un pago cuando el usuario hace un pedido y abre para él la checkout_url devuelta. La siguiente solicitud ofrece todas las cadenas en las que el proyecto acepta USDT, y el usuario elige una.

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"
  }'

Dirección de depósito

Pon en customer el ID del usuario en tu sistema. Las llamadas repetidas para el mismo usuario devuelven la misma dirección.

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

Confirma el cobro

Cuando un pago se confirma en la cadena, kokiwa envía un webhook. Abona solo a partir de webhooks, nunca porque el usuario haya vuelto a success_url.

• Pago: con payment_intent.paid, marca el pedido como pagado.
• Dirección de depósito: con deposit.confirmed, suma al saldo de data.deposit.customer.

Verifica la firma de cada evento y elimina duplicados por id de evento, consulta Webhooks.

Importes

Todos los importes son cadenas en unidades del token, como "25.00" o "24.9125", tanto en solicitudes como en respuestas y webhooks, así que no hay conversión por cadena. Los importes conservan la precisión completa de la cadena, por lo que el número de decimales varía. Nunca calcules con coma flotante.

Reembolsos

Los fondos ya están en tu billetera, así que kokiwa no tiene endpoint de reembolso y no puede revertir un pago. Para reembolsar, envía desde tu dirección de cobro al usuario. Pide al usuario una dirección de reembolso en lugar de usar transaction.from, que es la dirección del exchange si retiró desde uno. Las comisiones no se devuelven.

Lista de lanzamiento

• Las claves API solo están en el servidor, no en repositorios de código ni en logs.
• Los webhooks verifican firmas y un evento repetido no se abona dos veces.
• Los pagos se crean con Idempotency-Key, así un reintento de red no crea dos.
• Se gestiona payment_intent.paid_late, así un pago tras la caducidad no se pierde.
• Las direcciones de cobro están registradas en mainnet y usas una clave que empieza por sk_live_.
• La frase semilla de tu dirección de cobro tiene copia de seguridad.