API 레퍼런스

모든 엔드포인트는 서버에서 호출합니다. 요청과 응답은 JSON입니다. 웹훅 URL과 API 키는 가맹점 대시보드에서 관리합니다.

기본 규칙

오류

실패하면 4xx 또는 5xx를 반환합니다. 오류 종류는 code로 판단하고, message는 디버깅에만 사용하세요.

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

결제

결제는 사용자가 지불할 주문 하나입니다. 사용자가 체크아웃에서 결제하면 결과를 웹훅으로 받습니다.

최소 금액에 못 미치는 체인은 제외되고, 모든 체인이 못 미치면 오류가 납니다. 기본 최소 금액은 5달러이며, 내 수수료는 대시보드의 프로젝트 수수료 항목에서 확인할 수 있습니다.

체인별 토큰과 금액 지정

여러 통화를 받거나 체인마다 금액이 다르면 currency, amount, chains 대신 options를 씁니다. 최대 16개이며 token은 심볼이나 컨트랙트 주소입니다.

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

응답

201과 결제 객체를 반환합니다. checkout_url을 사용자에게 열어 주세요.

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

결제 객체를 반환합니다. 대사하거나 웹훅을 받지 못했을 때 상태를 확인하는 데 씁니다.

결제 상태

입금 주소

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

같은 사용자에게는 항상 같은 주소가 반환되므로 오래 표시해도 됩니다. tokens에 있는 토큰만 입금 처리됩니다.

송금마다 deposit.confirmed를 보냅니다. min_settle_amount보다 적은 송금도 입금되며 상태는 held입니다. 이 주소의 누적액이 최소 금액에 이르면 수령 주소로 함께 회수되고 고정 수수료는 한 번만 부과됩니다.

입금 기록

입금 기록(deposit)은 반영된 온체인 결제 한 건으로, 결제 또는 입금 주소에서 발생합니다. 결제 하나에 여러 건이 있을 수 있습니다.

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

최신순으로 반환합니다.

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 }

체인과 토큰

kokiwa가 지원하는 체인과 통화는 아래와 같습니다. chains와 options[].chain에는 chain 열의 값을, currency에는 통화 열의 값을 넣으세요.

테스트넷은 USDT만 지원합니다. 토큰은 tUSDT이지만 currency는 그대로 USDT를 넣습니다.

이 표는 입력할 수 있는 값의 전체 범위이며, 프로젝트마다 모두 쓸 수 있다는 뜻은 아닙니다. 판매자마다 설정이 다르므로 실제 사용 가능한 체인과 통화는 아래 API로 조회하세요.

이 키의 프로젝트가 현재 네트워크에서 받을 수 있는 항목을 반환합니다.

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

고객

선택 사항입니다. customer 값이 처음 나타나면 고객이 자동 생성됩니다. 대시보드에서 태그로 필터링할 때만 필요합니다.

태그, 메모, deposit_addresses(체인별 입금 주소)를 반환합니다.