정산

캔디페이에서 결제한 결제건의 정산 정보와 상태를 알려줘요.

Settlement는 가맹점 자신의 계좌로 지급된 주문별 정산 명세입니다. 가맹점이 Seller에게 보내는 지급대행 Payout은 포함하지 않습니다.

Settlement 객체

정산 정보를 담고 있는 객체입니다. 정산 금액, 수수료, 세액, 정산 예정일 등을 자세히 알 수 있어요.


export interface Settlement {
  // 정산 ID. 캔디페이에서 각 정산별로 자동으로 생성해주는 문자열입니다.
  settlementId: string
  // 정산액
  amount: number
  // 정산일시
  settledAt: Date
  // 정산 건에 포함된 내역
  lines: {
    // 주문번호
    orderId: string
    // 거래금액
    transactionAmount: number
    /**
     * 수수료율
     *
     * @max 100
     * @min 0
     */
    feeRate: number
    // 수수료
    feeAmount: number
    // 부가세 (수수료의 10분의 1)
    vatAmount: number
    // 정산된 금액 (거래금액 - 수수료 - 부가세)
    settledAmount: number
  }[]
}

정산 내역 조회

Request

조회날짜 정보를 from과 to params로 전달해야 합니다.

YYYY-MM-DD 형식을 지켜야 하며, from은 to보다 늦을 수 없습니다.


GET https://api.candypay.co.kr/px/settlements?from=YYYY-MM-DD&to=YYYY-MM-DD

Response

조회에 성공하면 Settlement 객체가 배열로 응답됩니다.

특정 정산ID 정보 조회

Request


GET https://api.candypay.co.kr/px/settlements/:settlementId

Response

조회에 성공하면 Settlement 객체가 응답됩니다.

웹훅

정산 완료 시 웹훅을 받을 수 있습니다. body에 JSON으로 Settlement 객체를 담아 전송합니다.

정산 웹훅 API는 추가 계약(무료) 후 사용할 수 있습니다. 추가 계약을 하고 싶다면 캔디페이 공식 이메일(help@atones.co.kr)로 문의해주세요.

아래는 웹훅 예시 데이터입니다.


POST https://계약한_웹훅_엔드포인트
 
{
  "settlementId": "string"
  "amount": number
  "settledAt": "string"
  "lines": [
    {
      "orderId": "string"
      "transactionAmount": number
      "feeRate": number
      "feeAmount": number
      "vatAmount": number
      "settledAmount": number
    },
    {
      "orderId": "string"
      "transactionAmount": number
      "feeRate": number
      "feeAmount": number
      "vatAmount": number
      "settledAmount": number
    }
  ]
}