AutoTransPay API 는 무통장입금을 자동으로 확인하는 API 입니다. 가맹점 서버가 주문(입금자명·금액)을 API 로 등록해 두면, AutoTransPay 가 사업자 계좌의 은행 입금 알림(문자·앱 푸시)을 해석해 주문과 대조하고, 확실한 입금은 확정한 뒤 서명된 웹훅으로 가맹점 서버에 알려 줍니다. 애매한 입금은 확정하지 않고 '확인 필요'로 남깁니다.
은행 입금 알림 ─▶ 휴대폰(수집기) ─▶ AutoTransPay ─▶ 파싱 ─▶ 스마트매칭 ─▶ 서명 웹훅 ─▶ 가맹점 서버
└▶ 애매하면 '확인 필요' + 텔레그램 1탭 승인이 문서는 테스트 모드에서 실제 은행·휴대폰 없이 전체 흐름을 끝까지 확인하는 과정을 안내합니다.
먼저 할 일 — 입금 계좌와 입금 알림 연결
실제 입금을 자동으로 확인하려면 콘솔에서 이 두 가지가 먼저 끝나 있어야 합니다. 사람이 콘솔에서 하는 일이라 AI 에이전트가 대신할 수 없습니다.
- 콘솔 → 입금 계좌에서 고객이 입금하는 계좌를 등록합니다.
- 그 계좌의 [연결하기] 로 은행 입출금 알림을 받을 번호에 오토페이 공용 수신번호를 추가합니다. 휴대폰을 따로 두거나 앱을 설치할 필요가 없습니다 → 콘솔에서 연결하기. 공용 수신번호가 아직 안 되는 은행 계좌는 내 휴대폰으로 받기로 연결합니다.
아래의 테스트(샌드박스) 연동은 이 단계와 상관없이 바로 진행할 수 있습니다.
가장 빠른 길 — AI 에이전트에게 맡기기
Claude Code·Cursor 같은 AI 에이전트를 쓴다면, 아래 글을 복사해 에이전트에게 그대로 붙여 넣는 것으로 아래 1~6 단계를 한 번에 진행할 수 있습니다. atp_test_… 자리에는 테스트 API 키를 넣습니다 — 콘솔 → 개발자 → AI 에이전트 연결 (MCP) 에서 [새 테스트 키로 채우기] 를 누르면 키가 들어간 글이 바로 나옵니다.
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. 가입하고 조직 만들기
- 무료로 시작하기에서 가입합니다.
- 콘솔에서 조직을 만듭니다. 주문·입금·키·웹훅은 모두 조직 단위로 격리됩니다.
- 가입 직후에는 테스트 모드입니다. 테스트 모드는 요금이 부과되지 않고 사용량 제한도 없습니다.
2. 테스트 API 키 발급
콘솔 → 개발자 → API 키에서 테스트 키를 발급합니다. 키는 발급 직후 한 번만 전체가 표시되니 안전한 곳에 보관하세요.
| 접두사 | 용도 |
|---|---|
atp_test_… |
테스트 모드. 샌드박스 입금 API 사용 가능, 과금 없음 |
atp_live_… |
운영 모드. 실제 은행 입금과 매칭, 월 매칭 건수 기준 과금 |
모든 요청은 Authorization: Bearer <API 키> 헤더로 인증합니다. 아래 예시에서는 키를 환경 변수로 둡니다.
export AUTOTRANSPAY_API_KEY=atp_test_xxxxxxxxxxxxxxxxxxxxxxxx3. 주문 등록
고객이 무통장입금을 선택하면, 결제 대기 주문을 AutoTransPay 에 등록합니다. depositor_name 은 고객이 입력한 입금자명입니다.
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" }
}'{
"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. 샌드박스로 입금 발생시키기
테스트 키로는 실제 은행 없이 가짜 입금을 만들 수 있습니다. 매칭·웹훅 전송은 운영과 똑같이 동작합니다.
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" }'{
"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 에 자동 확정되었습니다. 이름이 다르거나 금액이 다른 경우도 시험해 보세요.
# 이름 일부만 일치하는 입금 → 자동확정하지 않고 "확인 필요"(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탭으로 승인합니다 (스마트매칭 문서)