kokiwa

연동 가이드

서버에서 API로 결제를 생성하면, 입금 시 kokiwa가 웹훅으로 알려 줍니다. 자금은 온체인에서 바로 내 지갑으로 들어가며 kokiwa는 보관하지 않습니다.

먼저 테스트넷에서 무료 테스트 토큰으로 전체 흐름을 확인하세요. 테스트를 참고하세요. 사용자에게 보이는 화면은 결제 체험에서 볼 수 있습니다.

준비

아래 작업은 모두 가맹점 대시보드에서 합니다.

  1. 가입이메일을 인증하고 인증 앱을 연결한 뒤 복구 코드를 저장합니다.
  2. 프로젝트 생성프로젝트는 제품이나 사이트 하나에 해당하며, 수령 주소, API 키, 웹훅을 따로 가집니다.
  3. 수납 설정프로젝트의 수납 설정 페이지에서 체인, 수취 방식, 토큰을 고르고 체인마다 지갑으로 수령 주소를 등록합니다. 수령 주소는 온체인에 기록되며, 등록한 지갑만 변경할 수 있습니다. 등록에는 지갑에서 약간의 가스비가 듭니다. 지갑 하나로 모든 EVM 체인을 등록할 수 있습니다.
  4. API 키 생성키는 한 번만 표시됩니다. 서버 환경 변수에 보관하고 프런트엔드나 앱에는 넣지 마세요.
  5. 웹훅 설정웹훅 페이지에 https 수신 URL을 입력하고 서명 시크릿을 저장한 뒤, 테스트 이벤트 보내기로 수신을 확인합니다.

수납 방식 선택

결제입금 주소
적합한 경우주문: 금액이 정해져 있고 한 번에 결제계정 충전: 금액은 사용자가 정하고 여러 번 가능
주소결제마다 하나, 만료되면 폐기사용자마다 하나, 영구 고정
사용자의 결제 방법체크아웃에서 지갑으로 결제. BNB Chain에서는 전용 주소로 송금도 가능지갑이나 거래소에서 송금
체인8개 전체BNB Chain
gas지갑 결제는 사용자 부담, 송금의 회수는 kokiwa 부담송금은 사용자 부담, 회수는 kokiwa 부담

두 방식을 함께 쓸 수 있습니다.

결제

사용자가 주문할 때 결제를 생성하고, 반환된 checkout_url을 열어 줍니다. 아래 요청은 프로젝트가 USDT를 받을 수 있는 모든 체인을 보여 주고, 사용자가 하나를 고릅니다.

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

입금 주소

customer에는 내 시스템의 사용자 ID를 넣습니다. 같은 사용자로 다시 호출해도 같은 주소가 반환됩니다.

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

입금 확인

결제가 온체인에서 확정되면 kokiwa가 웹훅을 보냅니다. 웹훅만을 근거로 입금 처리하세요. 사용자가 success_url로 돌아온 것을 근거로 삼지 마세요.

  • 결제: payment_intent.paid를 받으면 주문을 결제 완료로 표시합니다.
  • 입금 주소: deposit.confirmed를 받으면 data.deposit.customer의 잔액을 늘립니다.

모든 이벤트의 서명을 검증하고 이벤트 id로 중복을 제거하세요. 웹훅을 참고하세요.

금액

모든 금액은 토큰 수량 문자열입니다(예: "25.00", "24.9125"). 요청, 응답, 웹훅이 모두 같아 체인별 변환이 필요 없습니다. 온체인 정밀도를 그대로 유지하므로 소수 자릿수는 일정하지 않습니다. 부동소수점으로 계산하지 마세요.

환불

자금이 이미 내 지갑에 있으므로 kokiwa에는 환불 API가 없고 결제를 되돌릴 수도 없습니다. 환불은 수령 주소에서 사용자에게 직접 보내세요. transaction.from으로 바로 보내지 말고 사용자에게 환불 주소를 받으세요. 거래소에서 출금한 경우 그 주소는 거래소 주소입니다. 수수료는 돌려받을 수 없습니다.

출시 전 점검

  • API 키는 서버에만 있고 코드 저장소와 로그에는 없다.
  • 웹훅이 서명을 검증하고, 같은 이벤트가 반복되어도 중복 입금 처리하지 않는다.
  • 결제 생성 시 Idempotency-Key를 보내 네트워크 재시도로 두 건이 생기지 않는다.
  • payment_intent.paid_late를 처리해 만료 후 입금을 놓치지 않는다.
  • 메인넷에 수령 주소를 등록했고 sk_live_로 시작하는 키로 교체했다.
  • 수령 주소의 시드 문구를 백업했다.
다음: 테스트

Connect a wallet with WalletConnect