나눠서 결제

하나의 청구서에서 여러 결제를 처리하는 나눠서 결제 연동을 안내합니다.

나눠서 결제

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

기존 결제와 차이점

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

핵심 연동 포인트

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

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

처리 흐름

1

청구서를 생성합니다

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

sendType은 TALK 또는 URL을 사용합니다.

2

승인 동기화를 수신합니다

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

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

3

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

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

특정 결제 건만 취소할 수 있습니다.

4

결제 내역을 조회합니다

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

응답의 payments 배열에서 누적 결제와 각 결제 상태를 확인하세요.

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원 이상만 청구서를 생성할 수 있습니다.