핵심 개념
워크스페이스, 주문, 입금, 매칭, 현금영수증의 뜻과 주문 상태가 바뀌는 조건, 상태마다 오는 웹훅을 정리했어요.
용어
| 용어 | 뜻 |
|---|---|
| 워크스페이스 | 계좌, 주문, 입금, API 키, 웹훅, 구독을 함께 묶는 단위예요. 사업장이나 쇼핑몰마다 하나씩 만들고, 멤버를 초대해 함께 써요. 워크스페이스와 멤버 |
| 계좌 | 입금을 받을 은행 계좌예요. 입금 알림 문자를 페이싱크로 보내도록 연결해요. ID는 bac_로 시작해요. 계좌 연결 |
| 주문 (invoice) | 받을 돈 한 건이에요. 입금자명(customer.name)과 금액을 담아요. ID는 ivc_로 시작하고, 워크스페이스마다 #1001부터 주문번호를 매겨요. |
| 입금 (transaction) | 은행 알림 문자로 들어온 입금 한 건이에요. ID는 trx_로 시작해요. |
| 매칭 | 입금 한 건을 주문 한 건에 연결해서 주문을 결제 완료로 바꾸는 일이에요. 매칭 동작 방식 |
| 현금영수증 | 결제 완료된 주문이나 API 요청으로 발급하는 현금영수증이에요. ID는 crt_로 시작해요. 현금영수증 발급 |
주문 상태
주문은 결제 대기(PENDING)로 만들어지고, 아래 조건에 따라 상태가 바뀌어요.
| 상태 | 뜻 |
|---|---|
PENDING |
결제 대기예요. 입금을 기다려요. 이 상태에서만 주문을 수정할 수 있어요. |
PAID |
결제 완료예요. 입금이 매칭됐거나 결제 완료로 처리했어요. |
EXPIRED |
입금 기한이 지났어요. 자동 매칭 대상에서 빠져요. |
CANCELED |
취소됐어요. 다시 열 수 없어요. |
상태가 바뀌는 조건
| 바뀜 | 조건 | 웹훅 |
|---|---|---|
생성 → PENDING |
API, 대시보드, CSV 업로드, 카페24로 주문을 만들어요. | invoice.created |
PENDING → PAID |
입금이 자동으로 매칭되거나, 대시보드에서 직접 매칭하거나, 결제 완료 처리를 해요. | invoice.paid |
PENDING → EXPIRED |
입금 기한(expiresAt)이 지나요. |
invoice.expired |
PENDING → CANCELED |
취소 API나 대시보드에서 취소하거나, 카페24에서 입금 전 주문이 취소돼요. | invoice.canceled |
EXPIRED → PAID |
대시보드에서 만료된 주문에 입금을 직접 매칭하거나, 결제 완료 처리 API를 호출해요. | invoice.paid |
EXPIRED → CANCELED |
취소 API를 호출해요. 대시보드에서는 만료된 주문을 취소할 수 없어요. | invoice.canceled |
PAID → PENDING 또는 EXPIRED |
대시보드에서 매칭을 해제해요. 입금 기한이 지났으면 EXPIRED로 돌아가요. |
invoice.reopened |
결제 대기 주문의 입금자명, 금액, 입금 기한 같은 내용을 수정하면 상태는 그대로이고 invoice.updated가 와요.
결제 완료된 주문은 취소할 수 없어요. 잘못 매칭됐거나 환불했다면 먼저 매칭을 해제하세요. 취소된 주문은 결제 완료로 바꿀 수 없어요.
입금 기한
주문을 만들 때 expireAfterDays(1~365일)나 expiresAt으로 입금 기한을 정해요. 둘 다 보내지 않으면 기한이 없어서 만료되지 않아요. 카페24 주문은 7일이에요.
기한이 지난 주문은 그 순간부터 자동 매칭 대상에서 빠져요. 상태를 EXPIRED로 바꾸고 invoice.expired를 보내는 일은 주기적으로 처리해서 조금 늦을 수 있어요.
입금 상태
| 상태 | 뜻 |
|---|---|
MATCHED |
주문에 매칭됐어요. |
UNMATCHED |
매칭된 주문이 없어요. 자동 매칭에 실패했거나 매칭을 해제한 입금이에요. |
HIDDEN |
매칭되지 않은 입금을 대시보드에서 숨겼어요. |
새 입금이 기록되면 매칭 여부와 관계없이 transaction.created가 와요. 매칭과 매칭 해제는 입금 웹훅이 아니라 invoice.paid와 invoice.reopened로 알려요.
주문과 입금은 1:1이에요
주문 하나에는 입금 하나만 매칭돼요. 고객이 금액을 나눠 보내면 각 입금이 주문 금액과 달라서 매칭되지 않아요. 같은 주문에 두 번 입금하면 두 번째 입금은 매칭되지 않은 채로 남아요. 이런 입금은 매칭되지 않은 입금에서 처리해요.
테스트 환경
페이싱크에는 테스트 모드나 테스트용 API 키가 없어요. 연동을 확인하려면 실제 계좌로 작은 금액을 직접 보내 보세요. 웹훅 서버는 대시보드 웹훅의 테스트 이벤트 보내기로 먼저 확인할 수 있어요. 빠른 시작에서 순서대로 따라 할 수 있어요.