API 로 직접 연동하기

순서

1. 1

   테스트 키를 발급받아요

   콘솔의 개발자 화면에서 테스트 키를 만들어요. 심사가 끝나기 전에도 테스트 키로 전 과정을 붙여 볼 수 있어요.

2. 2

   주문을 만들 때 호출해요

   주문이 생기면 금액과 주문번호, 주문자명을 보내요. 그 주문에 쓸 금액이 돌아와요 — 구매자에게 그 금액을 안내하면 돼요.

   POST /v1/payment-intents
   {
     "merchant_order_id": "ORD-20261008-001",
     "amount": 30000,
     "expected_depositor": "홍길동"
   }

3. 3

   웹훅 주소를 등록해요

   입금이 확인되면 알림을 받을 주소를 등록해요. https 만 받아요.

4. 4

   웹훅을 받아 처리해요

   서명을 검증하고, 같은 전달 ID 는 한 번만 처리하고, 바로 200 을 돌려줘요. 자세한 건 웹훅 가이드에 정리해 뒀어요.

   POST /your-webhook
   QB-Signature: t=1791392888,v1=...
   QB-Delivery-Id: 7f3a...
   
   { "event": "payment.matched",
     "merchant_order_id": "ORD-20261008-001",
     "amount": 30000 }

5. 5

   테스트 입금으로 확인해요

   실제로 돈을 보내지 않고 모의 입금을 만들어 웹훅까지 확인해요. 여기서 서명 검증과 멱등 처리를 먼저 점검하세요.

6. 6

   실제 키로 바꿔요

   심사가 끝나면 실제 키로 교체해요. 코드는 그대로 두고 키만 바꾸면 돼요.