문서 전체를 읽지 않아도 돌아가게 만드는 최소 경로예요. 먼저 동작시키고, 세부는 나중에 보세요.
1. 테스트 키 발급 (2분)
콘솔 → 개발자 → 테스트 키 발급. 심사 전에도 받을 수 있어요. 키는 만들 때 한 번만 보이니 바로 저장하세요.
2. 주문 하나 만들어 보기 (5분)
주문이 생길 때 호출할 엔드포인트예요. 응답에 담긴 금액을 구매자에게 안내하면 돼요.
- merchant_order_id — 우리 시스템의 주문번호. 중복되면 거절돼요
- amount — 받을 금액
- expected_depositor — 주문자명. **넣으면 매칭 정확도가 올라가요**
expected_depositor 를 빠뜨리는 경우가 많은데, 금액과 이름을 함께 보기 때문에 이게 있으면 자동 확정률이 꽤 달라져요.
3. 웹훅 받을 자리 만들기 (10분)
입금이 확인되면 호출될 주소예요. 처음에는 요청을 받아 로그만 찍고 200 을 돌려주는 것으로 시작하세요.
- 서명 검증 — 헤더의 타임스탬프와 본문으로 HMAC 을 계산해 비교해요
- 멱등 처리 — 전달 ID 를 저장하고 이미 있으면 건너뛰어요
- 빠른 응답 — 무거운 일은 뒤로 미루고 바로 200 을 주세요
4. 테스트 입금으로 확인 (5분)
콘솔에서 모의 입금을 만들면 실제와 같은 모양의 웹훅이 가요. 여기서 서명 검증과 멱등 처리가 제대로 도는지 보세요.
5. 실제 키로 교체 (1분)
심사가 끝나면 키만 바꾸면 돼요. 코드는 그대로예요.
자주 막히는 곳
- 서명이 안 맞아요 → 본문을 파싱하기 **전의 원문**으로 계산해야 해요
- 웹훅이 중복으로 와요 → 정상이에요. 멱등 처리로 다루세요
- 웹훅이 안 와요 → https 인지, 사설 IP 가 아닌지 확인하세요