무통장 입금 자동 확인 | SMS 기반 1초 자동 매칭 SaaS

개요

LunePay API는 무통장 입금 내역을 자동으로 수집하고, 등록된 주문과 실시간으로 매칭하는 기능을 제공합니다. 이 문서는 개발자가 LunePay 기능을 자신의 서비스에 연동하기 위한 상세한 가이드를 제공합니다.

Base URL

https://api.pay.codelune.dev/api/v1

Content-Type

application/json

인증 (Authentication)

모든 API 요청은 Authorization 헤더에 Bearer 토큰을 포함해야 합니다. 토큰은 대시보드에서 발급받을 수 있습니다.

Header Example

HTTP Header

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

워크스페이스 API

워크스페이스는 계좌와 주문을 관리하는 최상위 단위입니다.

워크스페이스 목록 조회

GET/workspaces

사용자가 소속된 모든 워크스페이스를 조회합니다.

워크스페이스 생성

POST/workspaces

새로운 워크스페이스를 생성합니다.

Request Body

JSON

{
  "name": "쇼핑몰 운영팀"
}

Response (200 OK)

JSON

{
  "id": 1,
  "name": "쇼핑몰 운영팀",
  "owner_id": 1,
  "is_active": true,
  "created_at": "2024-02-12T09:00:00+09:00"
}

계좌 API

워크스페이스에 연동된 은행 계좌를 관리합니다.

계좌 목록 조회

GET/workspaces/{id}/bank-accounts

Query Parameter	Type	Description
`is_active`	boolean	활성 상태 필터 (true/false)
`limit`	integer	한 페이지 당 개수 (기본: 50)
`offset`	integer	오프셋 (기본: 0)

계좌 등록

POST/workspaces/{id}/bank-accounts

새로운 계좌 정보를 등록합니다.

Request Body

JSON

{
  "bank_code": "004",
  "bank_name": "국민은행",
  "account_number": "123-456-789012",
  "account_holder": "홍길동"
}

Response (201 Created)

JSON

{
  "id": 1,
  "workspace_id": 1,
  "bank_code": "004",
  "bank_name": "국민은행",
  "account_number": "123-456-789012",
  "account_holder": "홍길동",
  "is_active": true,
  "phone_number_id": null,
  "created_at": "2024-02-12T10:00:00+09:00"
}

주문 API

입금 확인이 필요한 주문 정보를 등록하고 관리합니다.

주문 목록 조회

GET/workspaces/{id}/orders

Query Parameter	Type	Description
`status`	string	PENDING, MATCHED, CANCELLED, EXPIRED
`limit`	integer	조회 개수 (기본: 50)

주문 등록

POST/workspaces/{id}/orders

입금 대기 중인 주문을 생성합니다.

Request Body

JSON

{
  "order_number": "A-2024-0001",
  "amount": 14510,
  "depositor_name": "홍길동",
  "customer_email": "buyer@example.com",
  "customer_phone": "01012345678",
  "memo": "무통장 입금",
  "expires_at": null
}

Response (201 Created)

JSON

{
  "id": 1,
  "workspace_id": 1,
  "order_number": "A-2024-0001",
  "amount": 14510,
  "depositor_name": "홍길동",
  "status": "PENDING",
  "customer_email": "buyer@example.com",
  "customer_phone": "01012345678",
  "memo": "무통장 입금",
  "expires_at": null,
  "matched_at": null,
  "created_at": "2024-02-12T11:00:00+09:00",
  "updated_at": "2024-02-12T11:00:00+09:00"
}

주문 수정

PATCH/workspaces/{id}/orders/{order_id}

주문 정보를 수정하거나 상태를 변경합니다.

JSON

{
  "depositor_name": "김철수",
  "status": "CANCELLED"
}

입금 API

은행으로부터 수집된 입금 내역을 조회하거나 수동으로 등록합니다.

입금 내역 조회

GET/workspaces/{id}/deposits

Query Parameter	Type	Description
`is_matched`	boolean	매칭 여부 (true/false)
`bank_account_id`	integer	특정 계좌 필터링

수동 입금 등록

POST/workspaces/{id}/deposits

관리자가 수동으로 입금 내역을 등록할 때 사용합니다.

Request Body

JSON

{
  "bank_account_id": 1,
  "amount": 14510,
  "depositor_name": "홍길동",
  "deposited_at": "2024-02-01T11:05:00+09:00",
  "raw_sms": null
}

Response (201 Created)

JSON

{
  "id": 1,
  "bank_account_id": 1,
  "amount": 14510,
  "depositor_name": "홍길동",
  "deposited_at": "2024-02-01T11:05:00+09:00",
  "matched_order_id": null,
  "is_matched": false,
  "raw_sms": null,
  "created_at": "2024-02-12T11:05:00+09:00"
}

매칭 API

입금 내역과 주문을 수동으로 연결하거나 해제합니다.

수동 매칭

POST/workspaces/{id}/matches/manual

특정 입금 내역과 주문을 강제로 매칭합니다.

JSON

{
  "deposit_id": 120,
  "order_id": 55
}

Response

JSON

{
  "success": true,
  "message": "매칭 완료: 입금 #120 ↔ 주문 #55",
  "deposit_id": 120,
  "order_id": 55
}

매칭 해제

POST/workspaces/{id}/matches/{deposit_id}/unmatch

기존 매칭을 해제하고 주문을 PENDING 상태로 되돌립니다.

JSON

{
  "success": true,
  "message": "매칭 해제 완료: 입금 #120 (주문 #55 → PENDING)",
  "deposit_id": 120,
  "order_id": 55
}

SMS 웹훅

Android 앱 등에서 수신한 SMS 데이터를 서버로 전송하여 입금 처리를 수행합니다.
※ 인증 토큰이 필요하지 않은 Public API 입니다.

SMS 전송

POST/webhooks/bank-sms

Request Body

JSON

{
  "raw_sms": "[Web발신]\n국민 02/01 11:05\n110-***-000000\n입금 14,510원\n잔액 532,513원\n홍길동",
  "sender": "15881234",
  "received_at": "2024-02-01T11:05:00+09:00"
}

Response (Success)

JSON

{
  "success": true,
  "message": "입금 14510원 (홍길동) → 주문 #55 자동 매칭",
  "deposit_id": 123
}

오류 코드

API 요청 시 발생할 수 있는 주요 오류 코드입니다.

Status Code	Error Type	Description
400	Bad Request	입력값 오류 또는 매칭 조건 불가 (예: 워크스페이스에 해당 계좌가 없음)
401	Unauthorized	인증 토큰이 없거나 만료됨
404	Not Found	요청한 리소스(워크스페이스, 계좌, 주문 등)를 찾을 수 없음