직접 정산을 위해 만든 암호화폐 결제 API

청구서 만들기

POST 한 번입니다. 금액은 사람이 쓰는 방식 그대로 적고 서버가 해당 자산의 소수 자릿수로 환산하므로, 기본 단위로 손수 변환할 일이 없습니다.

curl -X POST https://api.unheld.io/api/v1/invoices \
  -H "Authorization: Bearer $UNHELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": "11155111",
    "assetType": "native",
    "amountDecimal": "0.05",
    "expiresInSeconds": 900,
    "metadata": { "orderId": "A-1043" }
  }'

응답

{
  "id": "e2b0…",
  "status": "CREATED",
  "receiveAddress": "0x…",
  "expectedAmount": "50000000000000000",
  "minConfirmations": 3,
  "expiresAt": "2026-08-10T14:15:00.000Z",
  "instructions": {
    "chainId": "11155111",
    "to": "0x…",
    "amount": "50000000000000000",
    "assetType": "native"
  }
}

receiveAddress는 판매자의 지갑에서 파생되어 이 청구서에 묶입니다. expectedAmount는 기본 단위입니다. minConfirmations는 저희가 만들어 낸 설정이 아니라 그 체인 자체의 기준값입니다.

인증과 스코프

키는 베어러 토큰이며, 대시보드에서 만들어 한 번만 표시됩니다. 모든 키는 명시적인 스코프 목록을 지니고, 키에 해당 경로의 스코프가 없으면 요청이 거부됩니다.

사용 가능한 스코프

• invoices:write
• invoices:read
• webhooks:write
• webhooks:read
• balances:read
• customers:write
• customers:read
• subscriptions:write
• subscriptions:read

동작하는 가장 좁은 조합만 부여하세요. 청구서만 만드는 키는 고객을 읽을 수 없고, 유출된 읽기 키는 아무것도 움직일 수 없습니다. 이 API에서는 애초에 그럴 수 있는 것이 없기 때문입니다.

검증할 수 있는 웹훅

모든 전달에는 서명이 붙습니다. 서명은 타임스탬프와 원본 본문을 점으로 이은 값을 판매자의 웹훅 비밀 키로 계산한 HMAC-SHA256이며, 16진수 다이제스트로 보내집니다.

전달 검증하기

const signature = crypto
  .createHmac("sha256", webhookSecret)
  .update(`${req.headers["x-timestamp"]}.${rawBody}`)
  .digest("hex");

crypto.timingSafeEqual(
  Buffer.from(signature),
  Buffer.from(req.headers["x-signature"])
);

다이제스트는 일정 시간 비교로 대조하고, 허용 범위를 벗어난 타임스탬프는 거부하며, X-Request-Id를 멱등 키로 다루세요. 재시도는 그 값을 그대로 쓰므로 같은 이벤트가 두 번 도착하는 것은 정상이며, 두 번 처리되어서는 안 됩니다.

청구서 이벤트

결제는 미납에서 완납으로 툭 뒤집히는 것이 아니라 여러 상태를 거쳐 움직이고, 모든 전이가 웹훅입니다. 부족 결제와 초과 결제는 오류가 아니라 그 자체로 하나의 이벤트입니다.

개발자 질문

예제를 가동 중인 API와 대조해 확인한 날짜 2026년 9월 21일.