시작하기

무통장입금 자동확인 API 퀵스타트

AI 에이전트에게 붙여 넣는 한 문장부터, 테스트 키 발급·주문 등록·샌드박스 입금·웹훅 수신까지 순서대로 따라 하는 첫 연동 안내.

AutoTransPay API 는 무통장입금을 자동으로 확인하는 API 입니다. 가맹점 서버가 주문(입금자명·금액)을 API 로 등록해 두면, AutoTransPay 가 사업자 계좌의 은행 입금 알림(문자·앱 푸시)을 해석해 주문과 대조하고, 확실한 입금은 확정한 뒤 서명된 웹훅으로 가맹점 서버에 알려 줍니다. 애매한 입금은 확정하지 않고 '확인 필요'로 남깁니다.

흐름
은행 입금 알림 ─▶ 휴대폰(수집기) ─▶ AutoTransPay ─▶ 파싱 ─▶ 스마트매칭 ─▶ 서명 웹훅 ─▶ 가맹점 서버
                                                            └▶ 애매하면 '확인 필요' + 텔레그램 1탭 승인

이 문서는 테스트 모드에서 실제 은행·휴대폰 없이 전체 흐름을 끝까지 확인하는 과정을 안내합니다.

먼저 할 일 — 입금 계좌와 입금 알림 연결

실제 입금을 자동으로 확인하려면 콘솔에서 이 두 가지가 먼저 끝나 있어야 합니다. 사람이 콘솔에서 하는 일이라 AI 에이전트가 대신할 수 없습니다.

  1. 콘솔 → 입금 계좌에서 고객이 입금하는 계좌를 등록합니다.
  2. 그 계좌의 [연결하기] 로 은행 입출금 알림을 받을 번호에 오토페이 공용 수신번호를 추가합니다. 휴대폰을 따로 두거나 앱을 설치할 필요가 없습니다 → 콘솔에서 연결하기. 공용 수신번호가 아직 안 되는 은행 계좌는 내 휴대폰으로 받기로 연결합니다.

아래의 테스트(샌드박스) 연동은 이 단계와 상관없이 바로 진행할 수 있습니다.

가장 빠른 길 — AI 에이전트에게 맡기기

Claude Code·Cursor 같은 AI 에이전트를 쓴다면, 아래 글을 복사해 에이전트에게 그대로 붙여 넣는 것으로 아래 1~6 단계를 한 번에 진행할 수 있습니다. atp_test_… 자리에는 테스트 API 키를 넣습니다 — 콘솔 → 개발자 → AI 에이전트 연결 (MCP) 에서 [새 테스트 키로 채우기] 를 누르면 키가 들어간 글이 바로 나옵니다.

Text
AutoTransPay MCP 서버에 연결해줘: https://www.autotranspay.com/api/mcp (Streamable HTTP, 헤더 Authorization: Bearer atp_test_…)
먼저 get_account 로 입금 계좌 등록과 입금 알림 연결 상태를 확인하고, 안 됐으면 내가 콘솔에서 할 일을 먼저 알려줘.
AutoTransPay 연동해줘. 주문 생성 시 입금 대기 주문을 등록하고, 웹훅으로 결제 완료 처리해. 서명 검증 포함, 샌드박스로 끝까지 테스트해줘.
연결 방법과 API 는 https://www.autotranspay.com/docs/mcp 를 읽어.

에이전트가 MCP 서버를 연결해 문서를 읽고, 주문 등록·웹훅 수신·서명 검증 코드를 프로젝트에 맞게 만든 뒤 샌드박스 입금으로 끝까지 테스트합니다. 자세한 내용은 MCP 연동에 있습니다. 직접 하려면 아래 순서대로 진행하세요.

1. 가입하고 조직 만들기

  1. 무료로 시작하기에서 가입합니다.
  2. 콘솔에서 조직을 만듭니다. 주문·입금·키·웹훅은 모두 조직 단위로 격리됩니다.
  3. 가입 직후에는 테스트 모드입니다. 테스트 모드는 요금이 부과되지 않고 사용량 제한도 없습니다.

2. 테스트 API 키 발급

콘솔 → 개발자 → API 키에서 테스트 키를 발급합니다. 키는 발급 직후 한 번만 전체가 표시되니 안전한 곳에 보관하세요.

접두사 용도
atp_test_… 테스트 모드. 샌드박스 입금 API 사용 가능, 과금 없음
atp_live_… 운영 모드. 실제 은행 입금과 매칭, 월 매칭 건수 기준 과금

모든 요청은 Authorization: Bearer <API 키> 헤더로 인증합니다. 아래 예시에서는 키를 환경 변수로 둡니다.

Shell
export AUTOTRANSPAY_API_KEY=atp_test_xxxxxxxxxxxxxxxxxxxxxxxx

3. 주문 등록

고객이 무통장입금을 선택하면, 결제 대기 주문을 AutoTransPay 에 등록합니다. depositor_name 은 고객이 입력한 입금자명입니다.

Shell
curl https://www.autotranspay.com/api/v1/orders \
  -H "Authorization: Bearer $AUTOTRANSPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_number": "ORD-1042",
    "amount": 122500,
    "depositor_name": "홍길동",
    "customer": { "phone": "010-1234-5678" },
    "metadata": { "cart_id": "c_981" }
  }'
응답 201
{
  "id": "5f0c9a52-7d1e-4a8b-9c3f-2b6e8d4a1c07",
  "object": "order",
  "livemode": false,
  "order_number": "ORD-1042",
  "amount": 122500,
  "currency": "KRW",
  "depositor_name": "홍길동",
  "alt_names": [],
  "customer": { "phone": "01012345678", "email": null },
  "bank_account_id": null,
  "status": "pending",
  "expires_at": null,
  "matched_at": null,
  "match_method": null,
  "deposit_id": null,
  "metadata": { "cart_id": "c_981" },
  "created_at": "2026-09-29T05:12:03.412+00:00"
}
팁

주문 등록은 멱등합니다. 네트워크 오류로 같은 요청을 다시 보내도 같은 order_number·같은 내용이면 기존 주문이 200 으로 돌아옵니다. 자세한 내용은 핵심 개념을 참고하세요.

4. 웹훅 엔드포인트 등록

콘솔 → 개발자 → 웹훅에서 수신 URL 을 등록하고 구독할 이벤트(deposit.matched 등)를 고릅니다. 등록하면 whsec_… 로 시작하는 서명 키가 발급됩니다.

  • 운영 웹훅 URL 은 https:// 만 허용됩니다.
  • 로컬 개발 서버(내 PC)의 주소도 터널(ngrok·cloudflared) 없이 테스트 모드에 그대로 등록할 수 있습니다. 오토페이는 로컬 주소로 보내지 않으니, AI 에이전트가 MCP get_webhook_request 로 받은 서명된 요청을 직접 보내 시험합니다 → 웹훅 문서.
  • 등록 후 테스트 전송 버튼을 누르면 서명된 ping 이벤트가 전송되어 수신·서명 검증 코드를 바로 점검할 수 있습니다.

5. 샌드박스로 입금 발생시키기

테스트 키로는 실제 은행 없이 가짜 입금을 만들 수 있습니다. 매칭·웹훅 전송은 운영과 똑같이 동작합니다.

Shell
curl https://www.autotranspay.com/api/v1/sandbox/deposits \
  -H "Authorization: Bearer $AUTOTRANSPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "order_number": "ORD-1042" }'
응답 201
{
  "id": "a3e1b7c2-4d5f-4a6b-8c9d-0e1f2a3b4c5d",
  "object": "deposit",
  "livemode": false,
  "amount": 122500,
  "depositor_name": "홍길동",
  "bank_code": "WOORI",
  "bank_account_id": null,
  "occurred_at": "2026-09-29T05:13:40.118+00:00",
  "received_at": "2026-09-29T05:13:40.201+00:00",
  "status": "matched",
  "review_reason": null,
  "order_id": "5f0c9a52-7d1e-4a8b-9c3f-2b6e8d4a1c07",
  "candidates": [
    {
      "order_id": "5f0c9a52-7d1e-4a8b-9c3f-2b6e8d4a1c07",
      "order_number": "ORD-1042",
      "depositor_name": "홍길동",
      "amount": 122500,
      "score": 100,
      "amount_match": true,
      "reasons": ["이름:exact"]
    }
  ],
  "confidence": 1,
  "flags": [],
  "created_at": "2026-09-29T05:13:40.201+00:00"
}

status: "matched" — 입금이 주문 ORD-1042 에 자동 확정되었습니다. 이름이 다르거나 금액이 다른 경우도 시험해 보세요.

Shell
# 이름 일부만 일치하는 입금 → 자동확정하지 않고 "확인 필요"(weak_name)
curl https://www.autotranspay.com/api/v1/sandbox/deposits \
  -H "Authorization: Bearer $AUTOTRANSPAY_API_KEY" -H "Content-Type: application/json" \
  -d '{ "amount": 122500, "depositor_name": "김성" }'

# 실제 은행 문자 원문으로 파서까지 검증
curl https://www.autotranspay.com/api/v1/sandbox/deposits \
  -H "Authorization: Bearer $AUTOTRANSPAY_API_KEY" -H "Content-Type: application/json" \
  -d '{ "text": "우리 09/28 23:14\n*456789\n입금 122,500원\n홍길동" }'

6. 웹훅 수신

매칭이 확정되면 등록한 URL 로 아래와 같은 이벤트가 POST 됩니다.

요청 헤더
POST /webhooks/autotranspay HTTP/1.1
Content-Type: application/json
User-Agent: AutoTransPay-Webhook/1.0
AutoTransPay-Signature: t=1790658820,v1=5b1f0c…e93a
AutoTransPay-Event-Id: evt_3f9a1c0e7b2d4e8f9a6b5c4d3e2f1a0b
AutoTransPay-Event-Type: deposit.matched
본문
{
  "id": "evt_3f9a1c0e7b2d4e8f9a6b5c4d3e2f1a0b",
  "object": "event",
  "type": "deposit.matched",
  "livemode": false,
  "created_at": "2026-09-29T05:13:40.342+00:00",
  "data": {
    "order": {
      "id": "5f0c9a52-7d1e-4a8b-9c3f-2b6e8d4a1c07",
      "order_number": "ORD-1042",
      "amount": 122500,
      "depositor_name": "홍길동",
      "metadata": { "cart_id": "c_981" }
    },
    "deposit": {
      "id": "a3e1b7c2-4d5f-4a6b-8c9d-0e1f2a3b4c5d",
      "amount": 122500,
      "depositor_name": "홍길동",
      "bank_code": "WOORI",
      "occurred_at": "2026-09-29T05:13:40.118+00:00"
    },
    "match": { "method": "auto", "actor": null, "amount_matches": true }
  }
}

가맹점 서버는 ① AutoTransPay-Signature 를 검증하고 ② data.order.order_number 의 주문을 결제 완료로 바꾼 뒤 ③ 2xx 로 응답하면 됩니다. 언어별 서명 검증 코드는 웹훅 문서에 있습니다.

주의

이미 처리한 이벤트가 다시 와도 반드시 2xx 로 응답하세요. 409·410·422 는 "이 입금확인을 거절한다"는 뜻으로 해석되어, 첫 전송이었다면 매칭이 되돌려집니다. 응답 규약 참고.

7. 운영 전환 체크리스트

테스트가 끝났다면 콘솔 개요의 연동 3단계와 같은 순서로 운영에 들어갑니다.

1. 입금 알림 연결: 입금 계좌를 등록하고, 은행 입출금 알림을 받을 번호에 오토페이 공용 수신번호를 추가합니다 (공용 수신번호가 아직 안 되는 은행은 내 휴대폰으로 받기) (입금 알림 연결 문서)

  • 콘솔에서 입금 계좌를 등록합니다 (은행·계좌번호·예금주).
  • 입금 계좌의 [연결하기] 로 은행 입출금 알림을 받을 번호에 오토페이 공용 수신번호를 추가합니다 (은행·동의 → 번호 받기 → 인증번호 → 확인 입금) → 콘솔에서 연결하기.
  • 공용 수신번호가 아직 안 되는 은행 계좌는 입금 계좌의 내 휴대폰으로 받기로 알림 받는 휴대폰을 연결합니다 → 내 휴대폰으로 받기.

2. 연동 (AI 에이전트·MCP): AI 에이전트에 “AutoTransPay 연동해줘” — 마지막에 운영 키·웹훅을 서버에 넣으면 됩니다 (MCP 연동 문서)

  • atp_live_… 운영 키를 발급해 서버 환경 변수(AUTOTRANSPAY_API_KEY)에 넣습니다. 테스트 키와 데이터가 완전히 분리되어 있으니, 운영 키로 주문을 새로 등록해야 합니다.
  • 운영 모드용 웹훅 엔드포인트를 따로 등록하고 새 서명 키를 서버 환경 변수(AUTOTRANSPAY_WEBHOOK_SECRET)에 넣은 뒤 재배포합니다.
  • 콘솔의 테스트 전송으로 운영 웹훅이 200 을 돌려주는지 확인합니다.

3. 끝: 1·2단계를 마치면 입금이 자동으로 확정됩니다 (스마트매칭 문서)

  • 도입 초기에는 조직 설정에서 자동확정을 끄거나(auto_confirm: false) 자동확정 금액 상한(auto_max_amount)을 두고, 텔레그램 알림방에서 1탭 승인으로 운영해 보세요 → 권장 설정.
  • 적은 금액으로 실제 입금을 한 번 해 보고, 콘솔 입금 내역과 웹훅 수신 로그를 확인합니다.

선택 · 텔레그램 알림: 확인이 필요한 입금을 바로 알려 주고 1탭으로 승인합니다 (스마트매칭 문서)

다음 단계

  • 스마트매칭 — 어떤 입금이 자동확정되고 어떤 입금이 사람 확인으로 가는지
  • API 레퍼런스 — 전체 엔드포인트
  • MCP 연동 — AI 에이전트에게 "AutoTransPay 연동해줘" 한마디로 끝내기