무통장 입금대기 연동

가맹점 서비스에서 손님이 무통장 입금을 골랐을 때 써요. 가맹점 서버가 입금대기를 등록하면, 뱅크알람이 입금 문자를 받아 붙이고 웹훅으로 알려요.

1. GET    /v1/sdk/deposits/accounts   입금 계좌 목록 → 손님이 은행 선택
2. POST   /v1/sdk/deposits            입금대기 등록 → 응답의 계좌로 입금 안내
3. 손님 송금 → 은행 입금 문자 → 부트페이가 금액 · 입금자명으로 매칭
4. deposit.matched 웹훅 → GET /v1/sdk/deposits/{id} 로 다시 확인 → 결제 완료

1입금 계좌 목록

{
  "accounts": [
    { "id": "6ad715d43648be5a4eac7d40", "bank_name": "NH농협은행", "account_no": "3120224889861", "holder": "윤태섭", "primary": true },
    { "id": "6ad715d43648be5a4eac7d41", "bank_name": "KB국민은행", "account_no": "675601-01-092472", "holder": "윤태섭", "primary": false }
  ]
}json

id 를 등록 때 account_id 로 보내요. 안 보내면 primary 계좌예요. 주문 전 화면에는 은행 이름만 보여 주고, 계좌번호는 등록 응답으로 안내해요.

2입금대기 등록

curl -X POST "https://api.bootapi.com/v1/sdk/deposits" \
  -H "Authorization: Basic {base64(client_key:secret_key)}" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_order_id": "SHOP-20261020-0042",
    "price": 35000,
    "depositor": "김보람",
    "account_id": "6ad715d43648be5a4eac7d40"
  }'bash

응답

등록 · 조회 응답과 웹훅의 data 는 같은 모양이에요.

{
  "merchant_order_id": "SHOP-20261020-0042",
  "order_number": "26102065578025458162",
  "order_name": "무통장 입금",
  "amount": 35000,
  "status": "awaiting",
  "buyer_name": "김보람",
  "account": { "id": "6ad715d43648be5a4eac7d40", "bank_name": "NH농협은행", "account_no": "3120224889861", "holder": "윤태섭" },
  "deadline": "2026-10-21T14:32:11+09:00",
  "deadline_label": "30분",
  "notify": { "deposit_guide": true, "deposit_paid": true },
  "paid_at": null,
  "deposit": null
}json

같은 merchant_order_id 로 같은 값을 다시 보내면 기존 입금대기를 돌려줘요. 재시도해도 안전해요. 값이 다르면 BANK_DEPOSIT_MERCHANT_ID_CONFLICT 예요.

입금 기한

기한이 지나면 expired 로 닫혀요. 그 뒤 들어온 입금은 deposit.unmatched 로 와요.

deposit.expired 웹훅은 기한 시각에 바로 오지 않고, 그 뒤 첫 등록 · 조회 · 입금 때 와요. 정확한 시각은 deadline 으로 판단해요.

손님이 주문을 취소하거나 다시 주문했다면 취소로 바로 닫아 주세요. 같은 금액 · 이름의 입금대기가 둘 열려 있으면 자동으로 안 붙어요.

구매자 메일 (무료)

buyer_email 을 주면 메일을 보내요.

같은 주문번호로 재시도하면 다시 보내지 않아요.

구매자 알림톡 (유료)

notify 를 켜면 알림톡을 보내요. 건당 6.5원(부가세 별도)이 판매자의 알림톡 충전금에서 빠져요. 잔액이 없으면 안 보내고, 문자로 대신 보내지 않아요.

"notify": { "deposit_guide": true, "deposit_paid": true, "link": "https://shop.example.com/orders/SHOP-20261020-0042" }json

판매자 쪽에서 세 가지가 준비돼야 해요. 안 됐으면 BANK_DEPOSIT_NOTIFY_NOT_READY 로 무엇이 빠졌는지 알려 줘요.

1. 카카오 채널 연결 — 알림 설정 › 카카오
2. 공용 템플릿 「납부 안내」 · 「입금 확인」 채택 — 메시지 › 템플릿
3. 알림톡 충전 — 결제 관리 › 알림톡

notify 를 안 보내면 판매자의 알림 설정을 따라요.

3조회

부트페이 주문번호로 조회해도 돼요.

입금대기 취소

4자동으로 붙는 조건

금액 · 입금자명이 같은 입금대기가 딱 하나이고, 아래가 모두 맞아야 해요. 아니면 판매자가 직접 골라요.

• 은행이 보낸 알림 (은행 앱, 은행 대표번호 문자)
• 입금된 계좌 끝자리가 등록 계좌 중 하나와 같음
• 입금자명이 depositor 와 같음
• 판매자의 뱅크알람 이용이 정지되지 않음

손님이 다른 등록 계좌로 보내도 붙어요.

입금 웹훅

받는 주소는 관리자 쇼핑몰 설정 › 뱅크알람 › 입금 웹훅에서 정하거나, 등록 때 webhook_url 로 보내요. 둘 다 있으면 webhook_url 이 우선이에요.

POST {webhook_url}
X-Bootpay-Webhook-Event: deposit.matched
X-Bootpay-Delivery-Id: 6710b2c4e1a9f3c2d8a1b7e0
X-Bootpay-Timestamp: 1760931731
X-Bootpay-Signature: sha256=9c1e…

{
  "event": "deposit.matched",
  "event_code": 401,
  "idempotency_key": "26102065578025458162:deposit.matched:k_35000_김보람_9861_1401_nh",
  "occurred_at": "2026-10-20T14:02:11+09:00",
  "data": {
    "merchant_order_id": "SHOP-20261020-0042",
    "order_number": "26102065578025458162",
    "amount": 35000,
    "status": "paid",
    "account": { "id": "6ad715d43648be5a4eac7d40", "bank_name": "NH농협은행", "account_no": "3120224889861", "holder": "윤태섭" },
    "paid_at": "2026-10-20T14:01:58+09:00",
    "deposit": { "bank_name": "농협", "account_tail": "9861", "depositor": "김보람", "amount": 35000, "received_at": "2026-10-20T14:01:58+09:00" }
  }
}json

deposit.ambiguous · deposit.unmatched 의 data 는 { deposit, candidates } 예요.

• 2xx 로 답하면 받은 것으로 봐요. 아니면 10번까지 다시 보내요
• 같은 이벤트가 같은 idempotency_key 로 다시 올 수 있어요
• 설정 주소로 10건 연속 실패하면 웹훅이 꺼져요
• 본문을 그대로 믿지 말고 조회 API 결과로 주문을 바꿔요

5웹훅 서명 비밀값

{ "secret": "whsec_3f9c…" }json

이 응답에서만 원문을 보여 줘요. 다시 부르면 새 값으로 바뀌어요. 관리자 뱅크알람 › 입금 웹훅에서도 만들 수 있어요.

서명은 HMAC-SHA256(비밀값, "{X-Bootpay-Timestamp}.{본문}") 이에요.

import crypto from 'node:crypto'

app.post('/bootpay/deposit', express.raw({ type: 'application/json' }), async (req, res) => {
  const timestamp = req.get('X-Bootpay-Timestamp')
  const signature = req.get('X-Bootpay-Signature') || ''
  const body = req.body.toString('utf8')

  // 5분 넘은 요청은 거부
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return res.sendStatus(400)

  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.BOOTPAY_DEPOSIT_WEBHOOK_SECRET)
    .update(`${timestamp}.${body}`)
    .digest('hex')
  if (expected.length !== signature.length || !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
    return res.sendStatus(401)
  }

  const { data } = JSON.parse(body)
  const deposit = await bootpayGet(`/v1/sdk/deposits/${encodeURIComponent(data.merchant_order_id)}`)
  // paid → 결제 완료 · awaiting → 입금 대기 · expired / cancelled → 주문 취소
  res.sendStatus(200)
})javascript

에러 코드

함께 보기

• 뱅크알람으로 입금 확인 — 설정 · 매칭 규칙
• 주문 웹훅 설정 — 쇼핑몰 주문 웹훅(order.*)
• 예제: commerce-example 의 functions/_shared/bank-deposit.js