레퍼런스

API 레퍼런스

AutoTransPay 입금확인 REST API v1 레퍼런스입니다. 인증, 오류 형식, 요청 한도, 페이지네이션과 주문·입금·이벤트·도구·수집기 엔드포인트를 다룹니다.

AutoTransPay API 는 무통장입금 주문을 등록·조회하고 입금 확인 결과를 받아 오는 REST API 입니다. 요청·응답 본문은 모두 JSON(UTF-8)입니다. 기계가 읽을 수 있는 스펙은 OpenAPI 3.1 JSON으로도 제공합니다.

BASEhttps://www.autotranspay.com/api/v1
참고

https://autotranspay.com(www 없음)은 www 주소로 308 리디렉션됩니다. 리디렉션을 따라가지 않거나 다른 호스트로 Authorization 헤더를 넘기지 않는 클라이언트가 많으니, 항상 www 주소를 쓰세요.

인증

모든 요청에 API 키를 Authorization 헤더로 보냅니다. (X-API-Key: <키> 헤더도 허용합니다.)

Shell
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 상태 코드와 함께 아래 형식의 본문을 돌려줍니다.

JSON
{
  "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 는 최신순으로 정렬되고 같은 형식을 씁니다.

JSON
{ "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 를 함께 담고 있어, 같은 시각에 생긴 항목이 페이지 경계에서 빠지지 않습니다.

Shell
# 다음 페이지 — 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 로 인코딩하세요.


주문

주문 객체의 필드는 핵심 개념을 참고하세요.

주문 등록

POST/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 도). 멱등 재등록 때는 처음 값이 남고 응답에는 싣지 않음
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": "홍길동",
    "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" }
  }'
응답 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": "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 가 아니거나 허용 도메인 밖.

주문 목록

GET/api/v1/orders
파라미터 설명
status pending · matched · canceled · expired 중 하나 (생략 시 전체)
limit 1~100, 기본 20
starting_after 이전 응답의 next_cursor
Shell
curl "https://www.autotranspay.com/api/v1/orders?status=pending&limit=50" \
  -H "Authorization: Bearer $AUTOTRANSPAY_API_KEY"
응답 200
{
  "object": "list",
  "data": [
    { "id": "5f0c9a52-7d1e-4a8b-9c3f-2b6e8d4a1c07", "object": "order", "order_number": "ORD-1042", "status": "pending", "…": "…" }
  ],
  "has_more": false,
  "next_cursor": null
}

주문 조회

GET/api/v1/orders/{id}

{id} 자리에 주문 ID(uuid) 또는 주문번호를 넣을 수 있습니다.

Shell
curl https://www.autotranspay.com/api/v1/orders/ORD-1042 \
  -H "Authorization: Bearer $AUTOTRANSPAY_API_KEY"

응답은 주문 객체입니다. 없으면 404 resource_missing.

주문 취소

POST/api/v1/orders/{id}/cancel

대기(pending)·만료(expired) 주문을 취소합니다. 이후 들어오는 입금은 이 주문과 매칭되지 않습니다. {id} 는 주문 ID 또는 주문번호입니다. 이미 취소된 주문은 그대로 돌려줍니다.

Shell
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.


입금

입금 객체의 필드는 핵심 개념을 참고하세요.

입금 목록

GET/api/v1/deposits
파라미터 설명
status 쉼표로 여러 개: unmatched, review, matched, ignored. 기본값 review,unmatched (처리가 필요한 입금)
limit 1~100, 기본 20
starting_after 이전 응답의 next_cursor
Shell
curl "https://www.autotranspay.com/api/v1/deposits?status=review" \
  -H "Authorization: Bearer $AUTOTRANSPAY_API_KEY"
응답 200
{
  "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
}

입금 조회

GET/api/v1/deposits/{id}
Shell
curl https://www.autotranspay.com/api/v1/deposits/0b7e6d5c-4a3b-4c2d-9e1f-8a7b6c5d4e3f \
  -H "Authorization: Bearer $AUTOTRANSPAY_API_KEY"

응답은 입금 객체입니다.

입금 수동 매칭

POST/api/v1/deposits/{id}/match

확인 필요(review)·미매칭(unmatched) 입금을 주문에 확정합니다. 확정 즉시 deposit.matched 웹훅이 발송되며 data.match.method 는 manual 입니다. 금액이 달라도 확정할 수 있으니 주의하세요.

파라미터 타입 설명
order_id string (uuid) 확정할 주문 ID
order_number string 또는 주문번호 (둘 중 하나 필수)
Shell
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건)를 모두 사용 — 요금제를 올리면 바로 확정 가능

입금 무시

POST/api/v1/deposits/{id}/ignore

주문과 무관한 입금(개인 송금, 환불 입금 등)으로 처리합니다. 무시한 입금은 이후 역매칭 대상에서도 빠집니다.

Shell
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.


이벤트

웹훅으로 보낸 이벤트를 다시 조회합니다. 웹훅 유실 대비 대사용입니다 → 웹훅.

이벤트 목록

GET/api/v1/events
파라미터 설명
type deposit.matched · deposit.review_required · order.expired
limit 1~100, 기본 20
starting_after 이전 응답의 next_cursor
Shell
curl "https://www.autotranspay.com/api/v1/events?type=deposit.matched&limit=100" \
  -H "Authorization: Bearer $AUTOTRANSPAY_API_KEY"
응답 200
{
  "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
}

이벤트 조회

GET/api/v1/events/{id}
Shell
curl https://www.autotranspay.com/api/v1/events/evt_3f9a1c0e7b2d4e8f9a6b5c4d3e2f1a0b \
  -H "Authorization: Bearer $AUTOTRANSPAY_API_KEY"

응답은 이벤트 객체(object, id, type, livemode, data, created_at)입니다. data 형식은 웹훅 이벤트 종류와 같습니다.


도구

문자 해석 미리보기

POST/api/v1/parse

은행 알림 원문을 어떻게 해석하는지 미리 봅니다. 저장·매칭은 하지 않습니다. 새 은행·새 알림 형식을 연결하기 전에 확인할 때 쓰세요.

파라미터 타입 설명
text string 알림 원문, 1~4000자 (필수)
Shell
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" }'
응답 200
{
  "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 미만이면 자동확정하지 않습니다.

샌드박스 입금

POST/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_…)으로 인증합니다. 자세한 설정은 입금 알림 연결을 참고하세요.

알림 수집

POST/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.

하트비트

POST/api/v1/collect/heartbeat

수집기 생존 신호입니다. 본문의 원시값 필드(최대 20개)가 상태로 저장됩니다. 응답: { "object": "heartbeat", "ok": true, "server_time": "…" }.