---
title: 핵심 개념
description: 워크스페이스, 주문, 입금, 매칭, 현금영수증의 뜻과 주문 상태가 바뀌는 조건, 상태마다 오는 웹훅을 정리했어요.
sidebar:
  icon: lightbulb
---

## 용어

| 용어 | 뜻 |
| --- | --- |
| 워크스페이스 | 계좌, 주문, 입금, API 키, 웹훅, 구독을 함께 묶는 단위예요. 사업장이나 쇼핑몰마다 하나씩 만들고, 멤버를 초대해 함께 써요. [워크스페이스와 멤버](/workspace) |
| 계좌 | 입금을 받을 은행 계좌예요. 입금 알림 문자를 페이싱크로 보내도록 연결해요. ID는 `bac_`로 시작해요. [계좌 연결](/bank-accounts) |
| 주문 (invoice) | 받을 돈 한 건이에요. 입금자명(`customer.name`)과 금액을 담아요. ID는 `ivc_`로 시작하고, 워크스페이스마다 `#1001`부터 주문번호를 매겨요. |
| 입금 (transaction) | 은행 알림 문자로 들어온 입금 한 건이에요. ID는 `trx_`로 시작해요. |
| 매칭 | 입금 한 건을 주문 한 건에 연결해서 주문을 결제 완료로 바꾸는 일이에요. [매칭 동작 방식](/matching) |
| 현금영수증 | 결제 완료된 주문이나 API 요청으로 발급하는 현금영수증이에요. ID는 `crt_`로 시작해요. [현금영수증 발급](/cash-receipts) |

## 주문 상태 [#주문-상태]

주문은 결제 대기(`PENDING`)로 만들어지고, 아래 조건에 따라 상태가 바뀌어요.

```mermaid
stateDiagram-v2
    [*] --> PENDING: 주문 생성
    PENDING --> PAID: 매칭, 결제 완료 처리
    PENDING --> EXPIRED: 입금 기한 지남
    PENDING --> CANCELED: 취소
    EXPIRED --> PAID: 수동 매칭, 결제 완료 처리
    EXPIRED --> CANCELED: 취소 API
    PAID --> PENDING: 매칭 해제
    PAID --> EXPIRED: 매칭 해제 (기한 지남)
```

| 상태 | 뜻 |
| --- | --- |
| `PENDING` | 결제 대기예요. 입금을 기다려요. 이 상태에서만 주문을 수정할 수 있어요. |
| `PAID` | 결제 완료예요. 입금이 매칭됐거나 결제 완료로 처리했어요. |
| `EXPIRED` | 입금 기한이 지났어요. 자동 매칭 대상에서 빠져요. |
| `CANCELED` | 취소됐어요. 다시 열 수 없어요. |

### 상태가 바뀌는 조건

| 바뀜 | 조건 | 웹훅 |
| --- | --- | --- |
| 생성 → `PENDING` | API, 대시보드, CSV 업로드, [카페24](/cafe24)로 주문을 만들어요. | [`invoice.created`](/api-reference/webhooks/invoice-created) |
| `PENDING` → `PAID` | 입금이 자동으로 매칭되거나, 대시보드에서 직접 매칭하거나, [결제 완료 처리](/api-reference/invoices/mark-as-paid)를 해요. | [`invoice.paid`](/api-reference/webhooks/invoice-paid) |
| `PENDING` → `EXPIRED` | 입금 기한(`expiresAt`)이 지나요. | [`invoice.expired`](/api-reference/webhooks/invoice-expired) |
| `PENDING` → `CANCELED` | [취소 API](/api-reference/invoices/cancel)나 대시보드에서 취소하거나, 카페24에서 입금 전 주문이 취소돼요. | [`invoice.canceled`](/api-reference/webhooks/invoice-canceled) |
| `EXPIRED` → `PAID` | 대시보드에서 만료된 주문에 입금을 직접 매칭하거나, 결제 완료 처리 API를 호출해요. | `invoice.paid` |
| `EXPIRED` → `CANCELED` | 취소 API를 호출해요. 대시보드에서는 만료된 주문을 취소할 수 없어요. | `invoice.canceled` |
| `PAID` → `PENDING` 또는 `EXPIRED` | 대시보드에서 매칭을 해제해요. 입금 기한이 지났으면 `EXPIRED`로 돌아가요. | [`invoice.reopened`](/api-reference/webhooks/invoice-reopened) |

결제 대기 주문의 입금자명, 금액, 입금 기한 같은 내용을 [수정](/api-reference/invoices/update)하면 상태는 그대로이고 [`invoice.updated`](/api-reference/webhooks/invoice-updated)가 와요.

결제 완료된 주문은 취소할 수 없어요. 잘못 매칭됐거나 환불했다면 먼저 매칭을 해제하세요. 취소된 주문은 결제 완료로 바꿀 수 없어요.

### 입금 기한

주문을 만들 때 `expireAfterDays`(1~365일)나 `expiresAt`으로 입금 기한을 정해요. 둘 다 보내지 않으면 기한이 없어서 만료되지 않아요. 카페24 주문은 7일이에요.

기한이 지난 주문은 그 순간부터 자동 매칭 대상에서 빠져요. 상태를 `EXPIRED`로 바꾸고 `invoice.expired`를 보내는 일은 주기적으로 처리해서 조금 늦을 수 있어요.

## 입금 상태

| 상태 | 뜻 |
| --- | --- |
| `MATCHED` | 주문에 매칭됐어요. |
| `UNMATCHED` | 매칭된 주문이 없어요. 자동 매칭에 실패했거나 매칭을 해제한 입금이에요. |
| `HIDDEN` | 매칭되지 않은 입금을 대시보드에서 숨겼어요. |

새 입금이 기록되면 매칭 여부와 관계없이 [`transaction.created`](/api-reference/webhooks/transaction-created)가 와요. 매칭과 매칭 해제는 입금 웹훅이 아니라 `invoice.paid`와 `invoice.reopened`로 알려요.

## 주문과 입금은 1:1이에요

주문 하나에는 입금 하나만 매칭돼요. 고객이 금액을 나눠 보내면 각 입금이 주문 금액과 달라서 매칭되지 않아요. 같은 주문에 두 번 입금하면 두 번째 입금은 매칭되지 않은 채로 남아요. 이런 입금은 [매칭되지 않은 입금](/unmatched-deposits)에서 처리해요.

## 테스트 환경

페이싱크에는 테스트 모드나 테스트용 API 키가 없어요. 연동을 확인하려면 실제 계좌로 작은 금액을 직접 보내 보세요. 웹훅 서버는 대시보드 **웹훅**의 **테스트 이벤트 보내기**로 먼저 확인할 수 있어요. [빠른 시작](/getting-started)에서 순서대로 따라 할 수 있어요.