지급대행

지급대행은 오픈마켓에서 발생한 매출을 캔디페이가 오픈마켓을 대신하여 셀러(입점 판매자)에게 지급하는 서비스입니다. 직접 수많은 셀러에게 정산할 필요 없이, 정산 업무를 캔디페이한테 맡기고 자금 흐름을 더 효율적으로 관리할 수 있어요.

캔디페이와 직접 계약하지 않은 셀러에게 캔디페이가 정산금을 보내야 하기 때문에 리스크 검토 절차가 있습니다. 현재는 캔디페이에 가맹점으로 직접 입점한 셀러에게만 정산금을 지급대행할 수 있도록 운영하고 있어요.

지급대행 API는 셀러별 리스크 검토(현재는 가맹점 입점 과정으로 대체) 및 추가 계약(무료) 후 사용할 수 있습니다. 추가 계약을 하고 싶다면 캔디페이 개발팀 이메일(cto@atones.co.kr)로 문의해주세요. 문의 내용에 지정할 셀러ID, 셀러의 사업자등록증, 셀러의 통장사본을 포함해주세요.

기존 Settlement API는 별도 원장으로 유지됩니다.

Balance 객체


interface Balance {
  pendingAmount: { currency: 'KRW'; value: number }
  availableAmount: { currency: 'KRW'; value: number }
}

pendingAmount는 정산주기가 지나지 않은 정산 예정액입니다. availableAmount는 Payout 또는 가맹점 정산에 사용할 수 있는 금액입니다. 정산 후 취소가 발생하면 availableAmount.value가 음수일 수 있습니다.


GET /balances

Seller 객체

Payout의 destination에는 같은 가맹점에 등록되어 있고 삭제되지 않은 셀러의 id를 사용합니다.


GET    /sellers
GET    /sellers/:sellerId

Payout 객체


interface Payout {
  id: string
  batchId: string
  refPayoutId: string
  destination:
    | { type: 'SELLER'; sellerId: string }
    | { type: 'MERCHANT' }
  payoutDate: string
  amount: {
    currency: 'KRW'
    value: number
  }
  requestedAt: string
  submittedAt: string | null
  statusUpdatedAt: string
  lastResultCheckedAt: string | null
  completedAt: string | null
  status: 'PENDING' | 'SUBMITTING' | 'REQUESTED' | 'COMPLETED' | 'FAILED' | 'CANCELED'
  error: { code: string; message: string } | null
  reconciliationRequired: boolean
}

id: 캔디페이가 발급한 Payout ID입니다.
batchId: 같은 bulk 요청으로 예약된 항목들이 공유하는 ID입니다.
refPayoutId: 가맹점이 발급하는 최대 50자의 고유 ID입니다. 같은 가맹점에서 다시 사용할 수 없습니다.
destination: 셀러 지급이면 SELLER와 Seller ID, 자동 정산이면 MERCHANT입니다. API 요청에서는 셀러만 지정할 수 있습니다.
payoutDate: 캔디페이가 접수 시간과 한국 영업일에 따라 선택한 지급일입니다.
error: Provider의 마지막 오류를 안전하게 정규화한 값입니다. 원본 응답이나 계좌 정보는 포함하지 않습니다.
reconciliationRequired: 장기 처리 중이거나 마지막 조회 오류가 있어 운영 확인이 필요한 상태입니다.

지급대행 요청


POST /payouts

한 번에 1건 이상 100건 이하를 요청할 수 있습니다. 모든 항목은 같은 batchId로 예약됩니다.


[
  {
    "refPayoutId": "merchant-payout-20260813-1",
    "destination": "0198f0cc-0d16-7bd2-8f2c-e9064ad0bb0e",
    "amount": {
      "currency": "KRW",
      "value": 10000
    }
  },
  {
    "refPayoutId": "merchant-payout-20260813-2",
    "destination": "0198f0cc-0d16-7bd2-8f2c-e9064ad0bb0f",
    "amount": {
      "currency": "KRW",
      "value": 25000
    }
  }
]

각 지급액은 1원 이상 10억원 미만의 정수이며 전체 합계가 현재 availableAmount 이하여야 합니다. Seller 소유권, 금액, 잔액, refPayoutId, Provider 지급 슬롯을 한 트랜잭션에서 모두 검증합니다. 하나라도 실패하면 어떤 Payout도 생성되지 않습니다.

검증이 끝나면 모든 항목을 PENDING으로 먼저 기록해 잔액을 예약합니다. 이후 제출은 항목별로 비동기 처리됩니다. 한 항목의 실패나 불확실성이 다른 항목 제출을 막지 않습니다. FAILED 또는 CANCELED가 확정된 항목의 금액만 Balance에 자동으로 복원됩니다.

모든 refPayoutId가 같은 기존 batch에 속하고 ref/destination/amount 집합이 완전히 같으면 기존 batch를 반환합니다. 일부 ref만 중복되거나 내용이 달라지면 전체 요청이 DUPLICATE_REF_PAYOUT_ID로 거절됩니다.

결과 조회 키는 셀러 ID와 지급일입니다. 같은 키를 이미 사용한 요청은 지급일을 자동 변경하지 않고 PAYOUT_PROVIDER_SLOT_CONFLICT로 전체 거절합니다.

응답은 다음 목록 객체입니다.


interface PayoutList {
  hasMore: boolean
  size: number
  nextCursor: string | null
  items: Payout[]
}

단건 조회


GET /payouts/:payoutId

해당 가맹점의 Payout 객체를 반환합니다.

목록 조회


GET /payouts?limit=10&startingAfter={payoutId}&payoutDateGte=2026-08-01&payoutDateLte=2026-08-31

limit: 기본값 10, 최대 10,000입니다.
startingAfter: 직전 응답의 nextCursor입니다.
payoutDateGte, payoutDateLte: YYYY-MM-DD 형식의 지급일 범위입니다.

목록 응답은 hasMore, size, nextCursor, items를 반환합니다.

상태 모델

PENDING: 로컬 예약 완료, Provider 제출 대기
SUBMITTING: Provider 호출을 시작했으나 접수 여부가 불확실할 수 있음
REQUESTED: 접수 완료
COMPLETED: 지급 완료
FAILED: 요청 또는 지급 실패 확정
CANCELED: PG사에서 취소 확정

SUBMITTING 상태에서 응답이 유실되면 같은 요청을 다시 전송하지 않고 주기적인 결과 조회로 상태를 확인합니다. 조회 네트워크 오류나 응답 불일치만으로 지급을 실패 처리하지 않으므로, 이때는 잔액 차감도 유지됩니다.

사용자가 Payout을 취소하는 공개 API는 제공하지 않습니다. PG사에서 외부적으로 취소한 결과는 캔디페이 주기적인 조회를 통해 CANCELED로 반영합니다.