> For the complete documentation index, see [llms.txt](https://developers.payssam.kr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.payssam.kr/development/split-bill.md).

# 나눠서 결제

## 나눠서 결제

나눠서 결제는 기존 V2 API의 청구서(`billId`)를 여러 번 결제하는 방식입니다.\
각 결제 건은 고유한 `paymentId`를 가집니다. \
\
하나의 청구서를 분할하여 여러 차례 나누어 결제하거나, 결제건별로 부분취소가 가능합니다.\ <br>

### 기존 결제와 차이점

| 구분     | 기존 단건 결제           | 나눠서 결제                      |
| ------ | ------------------ | --------------------------- |
| 구조     | `billId` 1개당 결제 1건 | `billId` 1개에 여러 `paymentId` |
| 승인 동기화 | 청구서당 1회            | 결제 건별로 여러 번                 |
| 결제 취소  | 청구서 전체 취소          | `paymentId`를 지정해 개별 취소      |
| 상태 조회  | 단건 승인 결과           | `payments` 배열의 전체 결제 내역     |

### 핵심 연동 포인트

`billId`는 청구서를 식별합니다. `paymentId`는 해당 청구서의 개별 결제를 식별합니다.

`billId`와 `paymentId` 조합은 결제 건을 고유하게 식별합니다. \
승인 동기화 콜백을 받으면 두 값을 함께 저장하세요.

{% hint style="warning" %}

{% endhint %}

### 처리 흐름

{% stepper %}
{% step %}

#### 청구서를 생성합니다

`POST /bill`을 호출해 청구서를 발송하거나 결제 URL을 생성합니다.

`sendType`은 `TALK` 또는 `URL`을 사용합니다.
{% endstep %}

{% step %}

#### 승인 동기화를 수신합니다

결제가 승인되면 등록한 `callbackUrl`로 결과가 전달됩니다.

콜백마다 `paymentId`를 확인하고 결제 건을 저장하세요. 정상 처리 후 성공 응답을 반환하세요.
{% endstep %}

{% step %}

#### 필요하면 개별 결제를 취소합니다

`POST /bill/cancel` 요청의 `bill` 객체에 취소할 `paymentId`를 포함합니다.

특정 결제 건만 취소할 수 있습니다.
{% endstep %}

{% step %}

#### 결제 내역을 조회합니다

`POST /bill/read/detail`을 호출해 청구서의 전체 결제 내역을 확인합니다.

응답의 `payments` 배열에서 누적 결제와 각 결제 상태를 확인하세요.
{% endstep %}
{% endstepper %}

### API 목록

| API    | Method / URI             | 용도                               |
| ------ | ------------------------ | -------------------------------- |
| 청구서 생성 | `POST /bill`             | 청구서를 발송하거나 결제 URL을 생성합니다.        |
| 승인 동기화 | `POST {callbackUrl}`     | 승인 결과와 `paymentId`를 파트너사에 전달합니다. |
| 결제 취소  | `POST /bill/cancel`      | `paymentId`를 지정해 결제 건을 취소합니다.    |
| 청구서 파기 | `POST /bill/destroy`     | 결제가 진행되지 않은 청구서를 파기합니다.          |
| 상세 조회  | `POST /bill/read/detail` | 청구서의 전체 결제 내역을 조회합니다.            |

### 주요 파라미터

#### `paymentId`

승인 동기화 콜백에서 전달하는 결제 고유 번호입니다.

개별 결제 취소 시 필수입니다. `billId`와 함께 저장하세요.

#### `payments`

상세 조회 응답에 포함되는 결제 내역 목록입니다.

각 항목에서 다음 정보를 확인할 수 있습니다.

* `paymentTotalAmount`: 결제 금액
* `paymentStatus`: 결제 상태
* `doneApprovedAt`: 승인 완료 일시

### 개발 유의사항

#### 콜백 중복 처리

동일한 `billId`의 콜백이 여러 번 전달될 수 있습니다.

`paymentId`를 기본 키 또는 고유 키로 관리하세요. 이미 처리한 `paymentId`는 중복 반영하지 마세요.

#### 부분 취소

전체 청구서가 아닌 특정 결제 건을 취소할 수 있습니다.

취소 요청 시 반드시 대상 결제의 `paymentId`를 포함하세요.

#### 테스트 환경

개발 환경인 `stg.paymint.co.kr`에서는 20,000원 이상만 청구서를 생성할 수 있습니다.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.payssam.kr/development/split-bill.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.