휴대폰 소유확인 연동

전체 흐름

[고객 서버]  POST /v1/verifications (secret)  ──▶  { verificationKey, callNumber, dtmfCode }
                                                         │
[고객 프론트] CallPass.verify({ verificationKey, clientKey, callNumber, dtmfCode, mode })
                                                         │
[사용자]     1877-6421 로 전화 (코드 자동/입력)  ──▶  발신번호로 회선 소유 확인
                                                         │
[결과]       ① webhook(HMAC) 또는 ② 위젯 폴링  ──▶  POST /v1/verifications/{key}/confirm (멱등)

1. 키 발급

고객 포털에서 회원가입(휴대폰·이메일 인증) 후 직접 키를 발급합니다. 발급되는 키는 모두 실서비스(live) 입니다. 발급 즉시 API 키 탭에서 추가 발급·secret 재발급도 셀프로 가능합니다.

2. 서버에서 세션 생성

사용자가 인증을 시작하면 고객 서버가 secret key 로 세션을 생성합니다.

# 요청 (서버 → 콜패스)
curl -X POST https://callpass.kr/v1/verifications \
  -H "Authorization: Basic $(echo -n 'sk_live_xxx:' | base64)" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "01012345678", "orderId": "order-1001", "webhookUrl": "https://shop.example.com/callpass/webhook" }'

# 응답
{ "verificationKey": "vk_live_AbC…", "callNumber": "1877-6421",
  "dtmfCode": "837465", "status": "ready", "ttl": 300 }

응답의 verificationKey / callNumber / dtmfCode 를 프론트로 전달해 위젯에 넘깁니다.

3. 프론트 위젯 연동

SDK 한 줄을 로드하고 CallPass.verify() 를 호출합니다. mode 로 연동 방식을 고릅니다.

<script src="https://callpass.kr/widget/callpass.js"></script>

<div id="callpass-box"></div>
<script>
CallPass.verify({
  verificationKey: "vk_live_AbC…",   // 서버 응답
  clientKey: "ck_live_xxx",
  callNumber: "1877-6421", dtmfCode: "837465",
  mode: "inline", container: "#callpass-box",
  onSuccess: function(d){ location.href = "/signup/done"; },
  onFail: function(d){ alert("발신번호가 일치하지 않습니다"); },
  onExpire: function(){ alert("시간이 초과되었습니다"); }
});
</script>

document.querySelector("#verify-btn").addEventListener("click", function(){
  CallPass.verify({
    verificationKey: "vk_live_AbC…", clientKey: "ck_live_xxx",
    callNumber: "1877-6421", dtmfCode: "837465",
    mode: "modal",
    onSuccess: function(d){ /* 서버 confirm 후 진행 */ },
    onClose: function(){ /* 사용자가 닫음 */ }
  });
});

CallPass.verify({
  verificationKey: "vk_live_AbC…", clientKey: "ck_live_xxx",
  callNumber: "1877-6421", dtmfCode: "837465",
  mode: "popup",
  onSuccess: function(d){ console.log("verified", d.verificationKey); },
  onFail: function(d){}, onExpire: function(){}
});
// 결과는 SDK 가 window.postMessage 로 수신해 콜백을 호출합니다.

CallPass.verify({
  verificationKey: "vk_live_AbC…", clientKey: "ck_live_xxx",
  callNumber: "1877-6421", dtmfCode: "837465",
  mode: "redirect",
  returnUrl: "https://shop.example.com/signup/callpass-return"
});

// 복귀 시: https://shop.example.com/signup/callpass-return?callpass_status=verified&callpass_key=vk_live_AbC…
// 서버에서 callpass_key 로 confirm 하여 최종 확정하세요.

4. 결과 수신 & 최종 확정

방법 A. Webhook (권장)

세션 생성 시 webhookUrl 을 주면, 결과가 확정될 때 HMAC 서명된 POST 가 갑니다.

POST {webhookUrl}
X-CallPass-Signature: <HMAC-SHA256(webhookSecret, body)>
{ "eventId": "evt_…", "type": "verification.verified",
  "verificationKey": "vk_live_AbC…", "phone": "01012345678", "orderId": "order-1001" }

방법 B. 폴링

서버에서 GET /v1/verifications/{key} (secret) 로 상태를 조회합니다. 위젯은 내부적으로 공개 status 를 폴링해 콜백을 호출합니다.

최종 확정 (멱등)

curl -X POST https://callpass.kr/v1/verifications/vk_live_AbC…/confirm \
  -H "Authorization: Basic $(echo -n 'sk_live_xxx:' | base64)"
# → { "verificationKey":"vk_live_AbC…", "status":"verified", "confirmed":true }

API 레퍼런스 (요약)