AutoTransPay API 는 무통장입금 주문을 등록·조회하고 입금 확인 결과를 받아 오는 REST API 입니다. 요청·응답 본문은 모두 JSON(UTF-8)입니다. 기계가 읽을 수 있는 스펙은 OpenAPI 3.1 JSON으로도 제공합니다.
https://www.autotranspay.com/api/v1https://autotranspay.com(www 없음)은 www 주소로 308 리디렉션됩니다. 리디렉션을 따라가지 않거나 다른 호스트로 Authorization 헤더를 넘기지 않는 클라이언트가 많으니, 항상 www 주소를 쓰세요.
인증
모든 요청에 API 키를 Authorization 헤더로 보냅니다. (X-API-Key: <키> 헤더도 허용합니다.)
curl https://www.autotranspay.com/api/v1/orders \
-H "Authorization: Bearer atp_test_xxxxxxxxxxxxxxxxxxxxxxxx"- 키의 접두사가 모드를 결정합니다:
atp_test_…테스트,atp_live_…운영. 두 모드의 데이터는 완전히 분리됩니다. - 키가 없거나 폐기되었으면
401 authentication_error입니다. - API 키는 서버에서만 쓰세요. 브라우저·앱 코드에 넣으면 누구나 주문을 조회·조작할 수 있습니다.
- 수집 API(
/collect)는 API 키가 아니라 수집기 토큰(atpc_…)으로 인증합니다 → 입금 알림 연결.
오류
실패한 요청은 HTTP 상태 코드와 함께 아래 형식의 본문을 돌려줍니다.
{
"error": {
"type": "invalid_request_error",
"code": "parameter_invalid",
"message": "amount: 정수(원)로 입력하세요.",
"param": "amount",
"request_id": "req_Xk2c9aP0qLm3Rz7t"
}
}| 필드 | 설명 |
|---|---|
type |
오류 분류 (아래 표) |
code |
구체적인 오류 코드. 코드 분기는 이 값으로 하세요 |
message |
사람이 읽는 설명 (한국어, 바뀔 수 있음) |
param |
문제가 된 파라미터 (있을 때만) |
request_id |
요청 ID. 문의 시 함께 알려 주세요. 모든 응답의 Request-Id 헤더에도 있습니다 |
type |
HTTP | 주요 code |
|---|---|---|
invalid_request_error |
400 | parameter_invalid, invalid_json, bank_account_invalid, return_url_not_allowed, livemode_not_allowed, text_unparsable |
invalid_request_error |
405 | method_not_allowed |
authentication_error |
401 | invalid_api_key |
permission_error |
403 | forbidden (비활성화된 조직 등) |
not_found_error |
404 | resource_missing |
conflict_error |
409 | order_number_conflict, order_already_matched, order_not_pending, deposit_already_handled, livemode_mismatch, quota_exceeded |
rate_limit_error |
429 | rate_limited — 요청이 너무 많음. Retry-After 헤더(초)만큼 기다린 뒤 재시도 |
api_error |
500 | internal_error — 일시적 오류. 재시도해도 안전한 요청이면 재시도 |
요청 한도
| 인증 | 한도 |
|---|---|
| API 키 (공개 API·MCP) | 키마다 분당 600회 |
수집기 토큰 (/collect) |
수집기마다 분당 120회 |
넘으면 429 rate_limited 와 함께 Retry-After(초) 헤더를 돌려줍니다. 그 시간만큼 기다린 뒤 재시도하세요. 요청 본문은 64KB 까지 받습니다.
페이지네이션
목록 API 는 최신순으로 정렬되고 같은 형식을 씁니다.
{ "object": "list", "data": [ … ], "has_more": true, "next_cursor": "2026-09-29T05:12:03.412Z|5f0c9a52-7d1e-4a8b-9c3f-2b6e8d4a1c07" }| 파라미터 | 설명 |
|---|---|
limit |
한 번에 가져올 개수. 1~100, 기본 20 |
starting_after |
이전 응답의 next_cursor 를 그대로 넘기면 다음 페이지를 가져옵니다 |
has_more 가 false 면 next_cursor 는 null 입니다. 커서는 시각과 ID 를 함께 담고 있어, 같은 시각에 생긴 항목이 페이지 경계에서 빠지지 않습니다.
# 다음 페이지 — next_cursor 를 URL 인코딩해서 넘깁니다 (| → %7C)
curl "https://www.autotranspay.com/api/v1/orders?limit=100&starting_after=2026-09-29T05:12:03.412Z%7C5f0c9a52-7d1e-4a8b-9c3f-2b6e8d4a1c07" \
-H "Authorization: Bearer $AUTOTRANSPAY_API_KEY"예전 방식처럼 마지막 항목의 시각(주문·이벤트는 created_at, 입금은 received_at, ISO 8601)을 넘겨도 동작하지만, 같은 시각의 항목이 빠질 수 있어 next_cursor 를 권장합니다. 시각의 + 는 %2B 로 인코딩하세요.
주문
주문 객체의 필드는 핵심 개념을 참고하세요.
주문 등록
/api/v1/orders입금 대기 주문을 등록합니다. 같은 order_number 를 같은 내용으로 다시 보내면 기존 주문을 200 으로 돌려줍니다(멱등). 최초 생성은 201 입니다. 등록 직후 최근 7일 안의 미매칭 입금과 역매칭을 시도하므로, 응답의 status 가 이미 matched 일 수 있습니다.
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
order_number |
string | ✓ | 가맹점 주문번호, 1~100자. 조직·모드 안에서 유일 |
amount |
integer | ✓ | 입금 금액(원), 양의 정수 |
depositor_name |
string | ✓ | 입금자명, 1~60자 |
alt_names |
string[] | 대체 입금자명, 최대 5개 (각 1~60자) | |
customer.phone |
string | 휴대폰 번호 (숫자만 저장). 이름+뒷자리 매칭에 사용 | |
customer.email |
string | 이메일 | |
bank_account_id |
string (uuid) | 이 계좌로 들어온 입금만 매칭 | |
expires_at |
string | 만료 시각, ISO 8601 (시간대 포함). 생략 시 조직 기본값 | |
metadata |
object | 임의 키-값. 웹훅에 그대로 실려 옴 | |
widget.return_url |
string | 결제 위젯 입금 확인 화면의 완료 버튼 주소, 500자 이하. https:// 이고 허용 도메인 안 (테스트 모드는 http://localhost 도). 멱등 재등록 때는 처음 값이 남고 응답에는 싣지 않음 |
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": "홍길동",
"alt_names": ["홍길동엄마"],
"customer": { "phone": "010-1234-5678", "email": "sungah@example.com" },
"expires_at": "2026-10-01T23:59:59+09:00",
"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": "sungah@example.com" },
"bank_account_id": null,
"status": "pending",
"expires_at": "2026-10-01T14:59:59+00:00",
"matched_at": null,
"match_method": null,
"deposit_id": null,
"metadata": { "cart_id": "c_981" },
"created_at": "2026-09-29T05:12:03.412+00:00",
"widget_url": null
}widget_url 은 구매자 입금 안내 화면 주소입니다. 결제 위젯을 켜면 채워지고, 꺼져 있거나 보여 줄 수 있는 계좌가 없으면 null 입니다. 주문 조회·취소·목록 응답의 주문 객체에도 같은 필드가 있습니다. 쇼핑몰 화면 위에 띄우는 방법은 임베드를 보세요. 구매자가 위젯에서 알린 입금자명은 콘솔과 알림 채널에만 표시되고 API 응답에는 싣지 않습니다.
오류 — 409 order_number_conflict: 같은 주문번호가 다른 금액·입금자명으로 이미 있음. 400 bank_account_invalid: 이 조직의 계좌가 아님. 400 return_url_not_allowed(param: widget.return_url): widget.return_url 이 https 가 아니거나 허용 도메인 밖.
주문 목록
/api/v1/orders| 파라미터 | 설명 |
|---|---|
status |
pending · matched · canceled · expired 중 하나 (생략 시 전체) |
limit |
1~100, 기본 20 |
starting_after |
이전 응답의 next_cursor |
curl "https://www.autotranspay.com/api/v1/orders?status=pending&limit=50" \
-H "Authorization: Bearer $AUTOTRANSPAY_API_KEY"{
"object": "list",
"data": [
{ "id": "5f0c9a52-7d1e-4a8b-9c3f-2b6e8d4a1c07", "object": "order", "order_number": "ORD-1042", "status": "pending", "…": "…" }
],
"has_more": false,
"next_cursor": null
}주문 조회
/api/v1/orders/{id}{id} 자리에 주문 ID(uuid) 또는 주문번호를 넣을 수 있습니다.
curl https://www.autotranspay.com/api/v1/orders/ORD-1042 \
-H "Authorization: Bearer $AUTOTRANSPAY_API_KEY"응답은 주문 객체입니다. 없으면 404 resource_missing.
주문 취소
/api/v1/orders/{id}/cancel대기(pending)·만료(expired) 주문을 취소합니다. 이후 들어오는 입금은 이 주문과 매칭되지 않습니다. {id} 는 주문 ID 또는 주문번호입니다. 이미 취소된 주문은 그대로 돌려줍니다.
curl -X POST https://www.autotranspay.com/api/v1/orders/ORD-1042/cancel \
-H "Authorization: Bearer $AUTOTRANSPAY_API_KEY"응답은 status: "canceled" 인 주문 객체입니다. 이미 매칭된 주문은 409 order_already_matched.
입금
입금 객체의 필드는 핵심 개념을 참고하세요.
입금 목록
/api/v1/deposits| 파라미터 | 설명 |
|---|---|
status |
쉼표로 여러 개: unmatched, review, matched, ignored. 기본값 review,unmatched (처리가 필요한 입금) |
limit |
1~100, 기본 20 |
starting_after |
이전 응답의 next_cursor |
curl "https://www.autotranspay.com/api/v1/deposits?status=review" \
-H "Authorization: Bearer $AUTOTRANSPAY_API_KEY"{
"object": "list",
"data": [
{
"id": "0b7e6d5c-4a3b-4c2d-9e1f-8a7b6c5d4e3f",
"object": "deposit",
"livemode": true,
"amount": 50000,
"depositor_name": "홍길동",
"bank_code": "KB",
"bank_account_id": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
"occurred_at": "2026-09-29T05:23:00+00:00",
"received_at": "2026-09-29T05:23:04.551+00:00",
"status": "review",
"review_reason": "ambiguous",
"order_id": null,
"candidates": [
{ "order_id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "order_number": "ORD-1051", "depositor_name": "홍길동", "amount": 50000, "score": 100, "amount_match": true, "reasons": ["이름:exact"] },
{ "order_id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a", "order_number": "ORD-1057", "depositor_name": "홍길동", "amount": 50000, "score": 100, "amount_match": true, "reasons": ["이름:exact"] }
],
"confidence": 0.9,
"flags": [],
"created_at": "2026-09-29T05:23:04.551+00:00"
}
],
"has_more": false,
"next_cursor": null
}입금 조회
/api/v1/deposits/{id}curl https://www.autotranspay.com/api/v1/deposits/0b7e6d5c-4a3b-4c2d-9e1f-8a7b6c5d4e3f \
-H "Authorization: Bearer $AUTOTRANSPAY_API_KEY"응답은 입금 객체입니다.
입금 수동 매칭
/api/v1/deposits/{id}/match확인 필요(review)·미매칭(unmatched) 입금을 주문에 확정합니다. 확정 즉시 deposit.matched 웹훅이 발송되며 data.match.method 는 manual 입니다. 금액이 달라도 확정할 수 있으니 주의하세요.
| 파라미터 | 타입 | 설명 |
|---|---|---|
order_id |
string (uuid) | 확정할 주문 ID |
order_number |
string | 또는 주문번호 (둘 중 하나 필수) |
curl https://www.autotranspay.com/api/v1/deposits/0b7e6d5c-4a3b-4c2d-9e1f-8a7b6c5d4e3f/match \
-H "Authorization: Bearer $AUTOTRANSPAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "order_number": "ORD-1051" }'응답은 status: "matched" 인 입금 객체입니다.
오류 code (409) |
의미 |
|---|---|
order_not_pending |
주문이 이미 매칭되었거나 취소됨 |
deposit_already_handled |
입금이 이미 매칭·무시됨 |
livemode_mismatch |
테스트/운영 모드가 다른 주문과 입금 |
quota_exceeded |
이번 달 Free 요금제 한도(100건)를 모두 사용 — 요금제를 올리면 바로 확정 가능 |
입금 무시
/api/v1/deposits/{id}/ignore주문과 무관한 입금(개인 송금, 환불 입금 등)으로 처리합니다. 무시한 입금은 이후 역매칭 대상에서도 빠집니다.
curl -X POST https://www.autotranspay.com/api/v1/deposits/0b7e6d5c-4a3b-4c2d-9e1f-8a7b6c5d4e3f/ignore \
-H "Authorization: Bearer $AUTOTRANSPAY_API_KEY"응답은 status: "ignored" 인 입금 객체입니다. 이미 처리된 입금은 409 deposit_already_handled.
이벤트
웹훅으로 보낸 이벤트를 다시 조회합니다. 웹훅 유실 대비 대사용입니다 → 웹훅.
이벤트 목록
/api/v1/events| 파라미터 | 설명 |
|---|---|
type |
deposit.matched · deposit.review_required · order.expired |
limit |
1~100, 기본 20 |
starting_after |
이전 응답의 next_cursor |
curl "https://www.autotranspay.com/api/v1/events?type=deposit.matched&limit=100" \
-H "Authorization: Bearer $AUTOTRANSPAY_API_KEY"{
"object": "list",
"data": [
{
"object": "event",
"id": "evt_3f9a1c0e7b2d4e8f9a6b5c4d3e2f1a0b",
"type": "deposit.matched",
"livemode": true,
"data": { "order": { "…": "…" }, "deposit": { "…": "…" }, "match": { "…": "…" } },
"created_at": "2026-09-29T05:13:40.342+00:00"
}
],
"has_more": false,
"next_cursor": null
}이벤트 조회
/api/v1/events/{id}curl https://www.autotranspay.com/api/v1/events/evt_3f9a1c0e7b2d4e8f9a6b5c4d3e2f1a0b \
-H "Authorization: Bearer $AUTOTRANSPAY_API_KEY"응답은 이벤트 객체(object, id, type, livemode, data, created_at)입니다. data 형식은 웹훅 이벤트 종류와 같습니다.
도구
문자 해석 미리보기
/api/v1/parse은행 알림 원문을 어떻게 해석하는지 미리 봅니다. 저장·매칭은 하지 않습니다. 새 은행·새 알림 형식을 연결하기 전에 확인할 때 쓰세요.
| 파라미터 | 타입 | 설명 |
|---|---|---|
text |
string | 알림 원문, 1~4000자 (필수) |
curl https://www.autotranspay.com/api/v1/parse \
-H "Authorization: Bearer $AUTOTRANSPAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "text": "[Web발신]\n[KB]09/28 23:14\n279801**027\n홍길동\n전자금융입금\n122,500\n잔액238,281" }'{
"object": "parse_result",
"kind": "deposit",
"amount": 122500,
"depositor_name": "홍길동",
"balance": 238281,
"bank_code": "KB",
"account_hint": "279801**027",
"occurred_at": "2026-09-28T14:14:00.000Z",
"confidence": 0.9
}kind 는 deposit · withdrawal · unknown 입니다. confidence 가 0.7 미만이면 자동확정하지 않습니다.
샌드박스 입금
/api/v1/sandbox/deposits테스트 키 전용. 가짜 입금을 만들어 매칭·웹훅까지 운영과 똑같이 실행합니다. 운영 키로 호출하면 400 livemode_not_allowed 입니다. 아래 세 방식 중 하나로 보냅니다.
| 방식 | 파라미터 | 용도 |
|---|---|---|
| 주문 그대로 입금 | order_number |
가장 흔한 성공 시나리오 |
| 임의 입금 | amount + depositor_name (+ bank_code) |
이름 불일치·금액 불일치·미매칭 시나리오 |
| 문자 원문 | text |
파서까지 포함한 검증 |
bank_code 를 생략하면 WOORI 입니다. 계좌를 지정한 주문(bank_account_id)을 시험하려면 bank_account_id 를 함께 보내 그 계좌로 들어온 입금으로 만드세요(이 조직의 계좌가 아니면 400). order_number 와 함께 amount·depositor_name 을 주면 그 값으로 덮어씁니다(예: 주문과 다른 금액 입금). 원문이 입금으로 해석되지 않으면 400 text_unparsable.
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" }'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", "amount": 120000 }'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홍길동" }'응답은 201 과 매칭 결과가 반영된 입금 객체입니다.
수집기
휴대폰 수집기가 쓰는 API 입니다. API 키가 아니라 수집기 토큰(atpc_…)으로 인증합니다. 자세한 설정은 입금 알림 연결을 참고하세요.
알림 수집
/api/v1/collect| 파라미터 | 설명 |
|---|---|
text (또는 msg, message, body, content) |
알림 원문 |
from (또는 sender, phone, title) |
발신번호·앱 이름 |
received_at (또는 time, timestamp) |
수신 시각 (선택) |
토큰은 X-Collector-Token 헤더, Authorization: Bearer, 또는 ?token= 으로 보냅니다. 응답은 object: "collect_result" 와 처리 결과(outcome)입니다 → 수집 API.
하트비트
/api/v1/collect/heartbeat수집기 생존 신호입니다. 본문의 원시값 필드(최대 20개)가 상태로 저장됩니다. 응답: { "object": "heartbeat", "ok": true, "server_time": "…" }.