Referência da API

Chame todos os endpoints do seu servidor. Requisições e respostas são JSON. URLs de webhook e chaves de API são gerenciadas no painel do comerciante.

Convenções

Erros

Falhas retornam 4xx ou 5xx. Decida por code; message serve só para depuração.

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

Pagamentos

Um pagamento é um pedido a ser pago pelo usuário. O usuário paga no checkout e você recebe o resultado por webhook.

Redes em que o valor fica abaixo do mínimo são excluídas; se não sobrar nenhuma, a requisição falha. O mínimo padrão é 5 USD; suas taxas estão na seção Taxas do projeto no painel.

Definir token e valor por rede

Para aceitar várias moedas, ou um valor diferente por rede, envie options em vez de currency, amount e chains. Até 16 itens; token é um símbolo ou endereço de contrato.

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

Resposta

Retorna 201 e o pagamento. Abra checkout_url para o usuário.

{
  "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": []
}

Retorna o pagamento. Use para conciliação ou para verificar o status quando um webhook não chegar.

Status do pagamento

Endereços 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" }
  ]
}

O mesmo usuário sempre recebe o mesmo endereço, então você pode mostrá-lo a longo prazo. Só os tokens em tokens são creditados.

Cada transferência envia deposit.confirmed. Transferências abaixo de min_settle_amount também são creditadas, com status held; quando o endereço acumula o mínimo, são varridas juntas para seu endereço de recebimento com uma única taxa fixa.

Depósitos

Um depósito é um pagamento on-chain creditado, vindo de um pagamento ou de um endereço de depósito. Um pagamento pode ter vários.

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

Do mais novo ao mais antigo.

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 }

Redes e tokens

A kokiwa aceita as redes e moedas abaixo. Use a coluna chain em chains e options[].chain, e a coluna de moedas em currency.

A testnet aceita apenas USDT. O token é tUSDT, mas currency continua sendo USDT.

Esta é a faixa completa de valores, não o que cada projeto pode aceitar. A configuração varia por lojista, então consulte o que está disponível no endpoint abaixo.

Retorna o que o projeto da chave pode aceitar na rede atual.

{
  "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. Um cliente é criado na primeira vez que um valor de customer aparece; você só precisa destes endpoints para filtrar por tag no painel.

Retorna as tags, as notas e deposit_addresses (endereços de depósito por rede).