크레딧 내역 조회

기업의 크레딧 사용 및 충전 내역을 조회합니다.

현재 잔액과 함께 모든 크레딧 거래 내역을 최신순으로 반환합니다.

항목	값
메서드	`GET`
경로	`/ai/payments/credits/history`
인증	필요 (기업 토큰)

요청

GET /ai/payments/credits/history HTTP/1.1
Host: api.glowb.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

curl "https://api.glowb.com/ai/payments/credits/history" \
  -H "Authorization: Bearer {access_token}"

const response = await fetch('/ai/payments/credits/history', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});
const result = await response.json();

응답

성공 응답 (200 OK)

{
  "status": 200,
  "code": null,
  "message": "크레딧 내역 조회 성공",
  "data": {
    "remainCredit": 500000,
    "transactions": [
      {
        "id": 10,
        "transactionType": "PAYMENT",
        "transactionTypeName": "결제 충전",
        "amount": 100000,
        "balanceAfter": 500000,
        "collabNo": 123,
        "collabTitle": "여름 신상 캠페인",
        "candyPaymentId": "order_1234567890",
        "description": "캠페인 결제",
        "createdAt": "2024-01-15T10:30:00",
        "occurredAt": "2024-01-15T10:30:00",
        "createdBy": "user123",
        "createdByName": "A브랜드",
        "refundable": true,
        "refundableReason": "모집 시작 전 - 환불 가능",
        "receiptCandyUrl": "https://pay.candypay.co.kr/receipt/candy/...",
        "receiptPerMethodUrls": "https://pay.candypay.co.kr/receipt/card/..."
      },
      {
        "id": 9,
        "transactionType": "CREDIT_USE",
        "transactionTypeName": "크레딧 사용",
        "amount": -50000,
        "balanceAfter": 400000,
        "collabNo": 122,
        "collabTitle": "봄 세일 캠페인",
        "candyPaymentId": null,
        "description": "크레딧 사용",
        "createdAt": "2024-01-14T15:20:00",
        "occurredAt": "2024-01-14T15:20:00",
        "createdBy": "user123",
        "createdByName": "A브랜드",
        "refundable": null,
        "refundableReason": null,
        "receiptCandyUrl": null,
        "receiptPerMethodUrls": null
      },
      {
        "id": 8,
        "transactionType": "PAYMENT",
        "transactionTypeName": "결제 충전",
        "amount": 100000,
        "balanceAfter": 450000,
        "collabNo": null,
        "collabTitle": null,
        "candyPaymentId": "order_0987654321",
        "description": "순수 크레딧 충전",
        "createdAt": "2024-01-13T09:00:00",
        "occurredAt": "2024-01-13T09:00:00",
        "createdBy": "user123",
        "createdByName": "A브랜드",
        "refundable": true,
        "refundableReason": "환불 가능",
        "receiptCandyUrl": "https://pay.candypay.co.kr/receipt/candy/...",
        "receiptPerMethodUrls": "https://pay.candypay.co.kr/receipt/card/..."
      }
    ]
  }
}

응답 스키마

Prop

Type

Transaction 스키마

Prop

Type

occurredAt (발생일) 과 createdAt (기록 시각)

크레딧 원장은 가계부처럼 실제로 돈이 오간 날(occurredAt) 과 서버에 기록된 시각(createdAt) 을 따로 가집니다. 일반 경로(카드 충전, 캠페인 결제 등)에서는 두 값이 같지만, 관리자가 무통장 입금을 뒤늦게 확인해 과거 날짜로 기입하거나 기존 행의 날짜를 정정하면 달라집니다.

필드	의미	변경 가능
`createdAt`	이 행이 서버에 쌓인 시각	불가
`occurredAt`	가계부상 발생일	어드민이 지정·수정 가능

{
  "id": 42,
  "transactionType": "CREDIT_ADD",
  "transactionTypeName": "크레딧 충전",
  "amount": 3000000,
  "createdAt": "2024-02-05T11:20:00",
  "occurredAt": "2024-01-31T00:00:00"
}

위 예시는 1월 31일에 입금된 건을 관리자가 2월 5일에 기록한 경우입니다.

정렬은 createdAt 최신순입니다.

이 API 의 transactions 는 createdAt 내림차순으로 내려갑니다. 과거 날짜로 기입된 행이 섞이면 occurredAt 기준으로는 순서가 어긋나 보이므로, 발생일 순으로 보여줄 화면에서는 프론트에서 occurredAt 으로 다시 정렬하세요.

occurredAt 은 항상 값이 있습니다. 지정하지 않고 저장된 행은 createdAt 과 같은 값으로 채워지므로, 기존 데이터도 포함해 null 이 되지 않습니다.

description 은 표준 라벨입니다

description 은 기업 화면에 그대로 노출되므로 고정된 문구만 들어갑니다. 상세 내역(일괄 제안 인원수, 관리자 대리 결제 여부 등)은 어드민 전용 필드로 분리되어 이 응답에는 내려가지 않습니다.

description	언제
`결제 충전`	카드로 크레딧 충전
`크레딧 충전` / `크레딧 사용`	어드민이 크레딧을 수동 조정
`캠페인 크레딧 충전`	제안 시 크레딧에서 캠페인 예산으로 자동 충전
`캠페인 결제`	캠페인 초기 결제
`캠페인 잔액 환급`	캠페인 종료 시 미사용 예산 환급

잔액이 마이너스로 보일 수 있습니다.

관리자가 입금 확인 전에 캠페인을 결제됨으로 처리하면 부족한 만큼 remainCredit 과 balanceAfter 가 음수가 됩니다. 이는 아직 납부되지 않은 금액이며, 이후 충전이 반영되면 0 이상으로 회복됩니다. 화면에서 음수를 그대로 노출할지 "미결제 금액" 형태로 바꿀지는 프론트에서 결정합니다.

환불 가능 여부 (refundable)

충전 유형	조건	refundable	refundableReason
캠페인 결제	모집 시작 전	`true`	"모집 시작 전 - 환불 가능"
캠페인 결제	모집 시작 후	`false`	"모집이 시작되어 환불 불가"
순수 크레딧 충전	-	`true`	"환불 가능"
기타 거래	-	`null`	`null`

환불 가능 단계

CAMPAIGN_REVIEW (캠페인 검토)
CAMPAIGN_PAYMENT (캠페인비 결제)
CAMPAIGN_GUIDELINE (가이드라인 작성)

CREATOR_RECRUIT (크리에이터 모집) 단계 이후에는 환불이 불가능합니다.

거래 유형 (transactionType)

유형	설명	금액 부호
`PAYMENT`	결제 충전	양수 (+)
`REFUND`	환불	음수 (-)
`CREDIT_USE`	크레딧 사용	음수 (-)
`CREDIT_ADD`	관리자 추가	양수 (+)
`CREDIT_DEDUCT`	관리자 차감	음수 (-)

에러 응답

상태 코드	에러 코드	설명
400	`INVALID_USER`	기업 정보를 찾을 수 없음
401	`UNAUTHORIZED`	인증 토큰 없음 또는 만료
500	`INTERNAL_SERVER_ERROR`	서버 오류

{
  "status": 400,
  "code": "INVALID_USER",
  "message": "기업 정보를 찾을 수 없습니다",
  "data": null
}

GET /ai/payments/credits/history