Tài liệu API

Gọi mọi endpoint từ máy chủ của bạn. Yêu cầu và phản hồi đều là JSON. URL webhook và API key được quản lý trong trang quản trị người bán.

Quy ước cơ bản

Lỗi

Lỗi trả về 4xx hoặc 5xx. Hãy phân nhánh theo code; message chỉ để gỡ lỗi.

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

Thanh toán

Một thanh toán là một đơn hàng người dùng cần trả. Người dùng trả trên trang thanh toán và bạn nhận kết quả qua webhook.

Các chuỗi có số tiền dưới mức tối thiểu sẽ bị loại; nếu không còn chuỗi nào, yêu cầu thất bại. Mức tối thiểu mặc định là 5 USD; phí của bạn nằm ở mục Phí của dự án trong trang quản trị.

Chỉ định token và số tiền cho từng chuỗi

Để nhận nhiều loại tiền hoặc số tiền khác nhau theo chuỗi, hãy gửi options thay cho currency, amount và chains. Tối đa 16 mục; token là ký hiệu hoặc địa chỉ hợp đồng.

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

Phản hồi

Trả về 201 và đối tượng thanh toán. Mở checkout_url cho người dùng.

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

Trả về đối tượng thanh toán. Dùng để đối soát hoặc kiểm tra trạng thái khi không nhận được webhook.

Trạng thái thanh toán

Địa chỉ nạp

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

Cùng một người dùng luôn nhận cùng địa chỉ, nên có thể hiển thị lâu dài. Chỉ các token trong tokens mới được ghi có.

Mỗi khoản chuyển gửi deposit.confirmed. Khoản dưới min_settle_amount vẫn được ghi có với trạng thái held; khi địa chỉ tích đủ mức tối thiểu, chúng được gom cùng lúc về địa chỉ nhận tiền của bạn với một lần phí cố định.

Khoản nạp

Khoản nạp (deposit) là một khoản thanh toán trên chuỗi đã ghi có, từ một thanh toán hoặc địa chỉ nạp. Một thanh toán có thể có nhiều khoản.

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

Mới nhất trước.

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 }

Chuỗi và token

kokiwa hỗ trợ các mạng và loại tiền dưới đây. Dùng cột chain cho chains và options[].chain, dùng cột loại tiền cho currency.

Testnet chỉ có USDT. Token là tUSDT, nhưng currency vẫn là USDT.

Đây là toàn bộ giá trị có thể dùng, không phải dự án nào cũng dùng được hết. Cấu hình của mỗi doanh nghiệp khác nhau, nên hãy tra cứu những gì thực sự khả dụng bằng API bên dưới.

Trả về những gì dự án của key có thể nhận trên mạng hiện tại.

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

Khách hàng

Tùy chọn. Khách hàng được tạo khi giá trị customer xuất hiện lần đầu; bạn chỉ cần các endpoint này để lọc theo thẻ trong trang quản trị.

Trả về thẻ, ghi chú và deposit_addresses (địa chỉ nạp theo chuỗi).