Referencia de la API

Llama a todos los endpoints desde tu servidor. Las solicitudes y respuestas son JSON. Las URL de webhook y las claves API se gestionan en el panel de comercio.

Convenciones

Errores

Los fallos devuelven 4xx o 5xx. Decide según code; message es solo para depurar.

{
  "error": {
    "code": "amount_below_minimum",
    "message": "options[0].amount is below the minimum",
    "details": { "min_amount": "5.00" }
  }
}

Pagos

Un pago es un pedido que debe pagar el usuario. El usuario paga en el checkout y recibes el resultado por webhook.

Las cadenas donde el importe no llega al mínimo se excluyen; si no queda ninguna, la solicitud falla. El mínimo predeterminado es 5 USD; tus comisiones están en la sección Comisiones del proyecto en el panel.

Indica el token y el importe por cadena

Para aceptar varias monedas, o un importe distinto por cadena, envía options en lugar de currency, amount y chains. Hasta 16 elementos; token es un símbolo o una dirección de contrato.

"options": [
  { "chain": "bsc", "token": "USDT", "amount": "25.00" },
  { "chain": "bsc", "token": "USDC", "amount": "25.00" }
]

Respuesta

Devuelve 201 y el pago. Abre checkout_url para el usuario.

{
  "id": "pi_7Gm4Rk2Wp9Ls1Qv8Bd3Zt6",
  "object": "payment_intent",
  "status": "pending",
  "livemode": true,
  "customer": "user_42",
  "checkout_url": "https://pay.kokiwa.com/p/pi_7Gm4Rk2Wp9Ls1Qv8Bd3Zt6",
  "metadata": { "order_id": "10086" },
  "success_url": "https://your-shop.com/orders/10086",
  "cancel_url": null,
  "created_at": "2026-11-02T08:30:00Z",
  "expires_at": "2026-11-02T09:00:00Z",
  "paid_at": null,
  "paid_option": null,
  "options": [
    {
      "id": "pio_5Hq2Tz8rLw0aVb3Kc9XyN1",
      "chain": "bsc",
      "token": { "symbol": "USDT", "address": "0x55d3…7955", "decimals": 18 },
      "amount": "25.00",
      "received": "0.00",
      "deposit_address": "0x8b1F…c04E"
    },
    {
      "id": "pio_2Mn7Xc4bQe6uJs1Ga8RvK3",
      "chain": "base",
      "token": { "symbol": "USDT", "address": "0xfde4…9bb2", "decimals": 6 },
      "amount": "25.00",
      "received": "0.00",
      "deposit_address": null
    }
  ],
  "deposits": []
}

Devuelve el pago. Úsalo para conciliar o para comprobar el estado si no llega un webhook.

Estado del pago

Direcciones de depósito

{
  "object": "deposit_address",
  "customer": "user_42",
  "chain": "bsc",
  "address": "0x3c9A…71d2",
  "tokens": [
    { "symbol": "USDT", "address": "0x55d3…7955", "decimals": 18, "min_settle_amount": "5.00" }
  ]
}

El mismo usuario siempre recibe la misma dirección, así que puedes mostrarla a largo plazo. Solo se abonan los tokens de tokens.

Cada transferencia envía deposit.confirmed. Las transferencias por debajo de min_settle_amount también se abonan, con estado held; cuando la dirección acumula el mínimo, se barren juntas a tu dirección de cobro con una sola comisión fija.

Depósitos

Un depósito es un pago en la cadena ya abonado, de un pago o de una dirección de depósito. Un pago puede tener varios.

{
  "id": "dep_9Kx2Pa6Wn3Ty8Lq5Rb1Ms4",
  "object": "deposit",
  "status": "settled",
  "method": "wallet",
  "chain": "bsc",
  "customer": "user_42",
  "payment_intent": "pi_7Gm4Rk2Wp9Ls1Qv8Bd3Zt6",
  "token": { "symbol": "USDT", "address": "0x55d3…7955", "decimals": 18 },
  "amount": "25.00",
  "fee": "0.0875",
  "net": "24.9125",
  "usd_value": "25.00",
  "confirmed_at": "2026-11-02T08:41:07Z",
  "transaction": {
    "hash": "0x4e7a…91c3",
    "log_index": 212,
    "block_number": 44718235,
    "block_time": "2026-11-02T08:40:58Z",
    "from": "0x1f9C…a2B0",
    "to": "0x7d3E…09f1",
    "raw_amount": "25000000000000000000"
  },
  "settlement": {
    "tx_hash": "0x4e7a…91c3",
    "by": "payment",
    "settled_at": "2026-11-02T08:40:58Z"
  }
}

Del más reciente al más antiguo.

curl "https://api.kokiwa.com/v1/deposits?tx_hash=0x4e7a…91c3" \
  -H "Authorization: Bearer $KOKIWA_KEY"

{ "object": "list", "data": [ { "id": "dep_9Kx2…", "object": "deposit", ... } ], "has_more": false }

Cadenas y tokens

kokiwa admite las cadenas y monedas siguientes. Usa la columna chain para chains y options[].chain, y la columna de monedas para currency.

La testnet solo admite USDT. El token es tUSDT, pero currency sigue siendo USDT.

Este es el rango completo de valores, no lo que puede aceptar cada proyecto. La configuración varía según el comercio, así que consulta lo disponible con el endpoint de abajo.

Devuelve lo que puede aceptar el proyecto de la clave en la red actual.

{
  "object": "list",
  "livemode": true,
  "currencies": ["USDT"],
  "data": [
    {
      "object": "chain", "chain": "bsc", "name": "BNB Smart Chain", "chain_id": 56, "testnet": false, "native": "BNB",
      "payout_registered": true, "active": true,
      "methods": { "wallet": true, "deposit_address": true },
      "tokens": [
        { "symbol": "USDT", "asset": "USDT", "address": "0x55d398326f99059fF775485246999027B3197955", "decimals": 18, "accepted": true },
        { "symbol": "USDC", "asset": "USDC", "address": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d", "decimals": 18, "accepted": false }
      ]
    }
  ]
}

Clientes

Opcional. Un cliente se crea la primera vez que aparece un valor de customer; solo necesitas estos endpoints para filtrar por etiqueta en el panel.

Devuelve las etiquetas, las notas y deposit_addresses (direcciones de depósito por cadena).