Bootpay 커머스 매뉴얼

참고

커머스 Enum

상태 코드와 타입 값을 같은 기준표에서 바로 찾아요.

Commerce API(주문, 링크페이, 구독 등)에서 사용하는 상태 코드값 목록이에요.

이럴 때 필요해요

주문·구독·링크페이 API 응답에서 상태 코드를 확인할 때예요.

주고받는 값은 `키`예요

API 응답은 아래 표의 키(문자열) 로 내려와요. 예를 들어 결제가 끝난 주문은 "status": "payment_completed" 예요.

요청 필터도 같은 키로 보내요 — status=payment_completed. 콤마로 여러 개를 넘기거나(status=payment_completed,cancellation_completed) 배열로 넘겨도 돼요.

값 열의 정수는 내부 저장값이에요. 예전 방식대로 숫자로 요청해도 그대로 동작하지만(status=2), 새로 붙이는 코드는 키를 쓰세요. 표에 없는 키를 보내면 요청이 400(INVALID_PARAMETER)으로 거절돼요. 숫자는 표에 없어도 거르지 않고 그대로 조회해요.

키 문자열 필터는 status · approval_status · renewal_status · receipt_status · status_review · request_status · cancel_status · request_type 에만 적용돼요. 그 밖의 필터(예: 주문 목록의 subscription_billing_type, 링크페이 목록의 product_type)는 숫자로 보내야 해요 — 키 문자열은 0 으로 읽혀요.

주문 상태 (status)

값 키 설명
0 order_pending 주문 생성, 결제 대기
1 payment_pending 결제 진행 중
2 payment_completed 결제 완료
3 subscription_request_completed 구독 요청 완료
4 subscription_pending 구독 대기
5 payment_delayed 결제 지연
6 payment_confirm_ready 결제 승인 대기
8 purchase_confirmed 구매 확정
10 cancellation_completed 취소 완료
11 return_completed 반품 완료
12 exchange_completed 교환 완료
13 subscription_terminated 구독 종료
-1 order_expired 주문 만료
-2 payment_failed 결제 실패
-3 payment_authorization_failed 결제 승인 실패
-4 subscription_error 구독 오류
-5 subscription_server_error 구독 서버 오류
-100 order_abandoned 주문 포기

주문 유형 (type)

값 키 설명
1 invoice 링크페이(청구서) 주문
2 shop 쇼핑몰 주문

주문 요청 유형 (order_request_type)

값 키 설명
1 item 일반 상품 주문
2 subscription 구독 회차 결제 주문 (매 회차 청구로 생긴 주문)
3 subscription_requested 구독 신청 주문 (첫 신청 결제)

승인 상태 (approval_status)

취소 요청·구독 신청 등 승인 흐름에서 공통으로 써요. 구독 갱신 승인의 renewal_status도 같은 값을 써요.

값 키 설명
0 approval_pending 요청 접수, 승인 대기 중
1 approval_requested 승인 요청
2 approval_approved_auto 자동 승인
3 approval_approved_manual 관리자 수동 승인
-1 approval_failed 승인 실패
-2 approval_rejected 거절됨
-3 approval_hold_on 보류

취소 요청 상태 (status)

취소 요청 목록 등 order_cancellation_request_history 응답의 status 예요. 주문 status 와 다른 표예요.

값 키 설명
0 cancel_calculated 취소 금액 계산됨 (요청 전)
1 cancel_requested 취소 요청됨, 승인 대기
2 cancel_approved 승인 완료 — 실제 취소가 진행돼요
-1 cancel_approval_failed 승인 처리 실패
-2 cancel_approval_critical_failed 승인 처리 치명적 실패
-10 cancel_rejected 관리자가 거절
-11 cancel_withdrawn 요청자가 철회

구독 요청 유형 (request_type)

구독 요청 이력 응답의 request_type 이에요.

값 키 설명
11 request_pause 일시정지 요청
12 request_resume 재개 요청
21 request_transfer 중도 인수(승계) 요청
31 request_purchase 중도 인수 결제 요청
41 request_termination 중도 해지 요청
42 request_termination_restore 해지 복구 (관리자)
51 request_migrate_plan 플랜 변경 요청
101 request_expired_purchase 만기 인수 요청
111 request_expired_return 만기 반납 요청
121 request_expired_extend 만기 연장 요청

구독 요청 상태 (request_status)

구독 요청 이력 응답의 request_status 예요. 위 승인 상태와 값 체계가 달라요 — 헷갈리지 마세요.

값 키 설명
0 request_requested 요청됨, 관리자 승인 대기
1 request_approved 관리자 승인 완료
2 request_approved_auto 자동 승인 완료
-1 request_rejected 관리자 거절
-2 request_withdrawn 고객이 요청 철회

구독 요청 결제 상태 (payment_status)

요청에 결제가 따라붙는 경우(중도 인수·만기 인수 등) 그 결제 상태예요.

값 키 설명
0 order_pending 결제 대기
2 payment_completed 결제 완료
-2 payment_failed 결제 실패

링크페이 상태 (status)

링크페이(청구서)는 주문 상태와 다른 표​​를 써요. 링크페이 응답의 status는 아래 값이에요.

값 키 설명
1 invoice_available 결제 가능 (링크 생성 후 결제 대기)
2 invoice_order_completed 주문 완료
3 invoice_order_cancelled 주문 취소
-1 invoice_deleted 판매자가 삭제
-2 invoice_expired 유효기간이 지난 링크
-3 invoice_product_unavailable 판매 불가 상품이 포함됨
-10 invoice_abandoned 고객이 결제하지 않고 이탈

링크페이로 결제가 이뤄지면 별도의 주문​​이 생겨요. 그 주문의 상태는 위 주문 상태 표를 따라요.

결제(영수증) 상태 (receipt_status)

주문 응답의 receipt_status 값이에요.

값 키 설명
0 receipt_ready 결제 준비
1 receipt_success 결제 성공
2 receipt_confirm_ready 승인 대기
3 receipt_confirm_doing 승인 진행 중
4 receipt_doing 결제 진행 중
5 receipt_issued 발행 완료
11 receipt_billing_key_published 빌링키 발급
20 receipt_cancelled 결제 취소
21 receipt_cancel_pending 취소 대기
30 receipt_delivered 배송 완료
-1 receipt_fail 결제 실패
-2 receipt_confirm_fail 승인 실패
-3 receipt_vbank_cancelled 가상계좌 취소
-4 receipt_request_failed 요청 실패
-5 receipt_confirm_critical_fail 승인 치명적 실패
-6 receipt_confirm_ready_fail 승인 대기 실패
-11 receipt_billing_key_revoked 빌링키 해지
-20 receipt_cancel_failed 취소 실패
-21 receipt_cancel_critial_failed 취소 치명적 실패
-100 receipt_closed 결제 종료

구독 상태 (status)

자세한 라이프사이클은 구독 개요를 참고해요.

값 키 설명
0 contract_requested_completed 구독 신청 완료, 승인 대기
1 subscribing 구독 중 (정상 결제 진행)
15 auto_terminated 자동 해지 (기간 만료 등)
20 manual_terminated 직접 해지 (사용자 요청)
25 mid_term_transfer_approved 중도 인수 승인
26 mid_term_transfer_requested 중도 인수 요청 — 값은 정의돼 있지만 지금은 어떤 처리도 이 상태로 바꾸지 않아요. 중도 인수 요청은 구독 요청(request_type 21)으로 확인해요
-1 free_trial 무료 체험
-2 temporarily_paused 일시정지
-3 paused_due_to_issue 이슈로 인한 일시정지
-10 first_payment_error 첫 결제 오류
-11 admin_terminated 관리자 해지 (거절은 -12)
-12 rejected 구독 거절

구독 청구(Bill) 상태 (status)

구독 회차별 청구 상태예요.

값 키 설명
1 bill_completed 결제 완료
2 bill_ready 청구 준비
5 bill_pending 결제 보류
6 bill_failure_delayed 결제 실패 후 지연
10 bill_cancelled 청구 취소
11 bill_paused 청구 일시정지
20 bill_terminated 청구 해지
-1 bill_failed 결제 실패
-2 bill_recreate_cancelled 재생성 취소
-11 bill_schedule_cancelled_by_payment_failure 결제 실패로 스케줄 취소
-100 bill_error 청구 오류

구독 유형 (subscription_type)

값 키 설명
1 regular_subscription 정기 구독
4 delivery_subscription 정기 배송 구독
5 rental_lease_subscription 렌탈/리스 구독
6 usage_based_subscription 사용량 기반 구독
7 on_demand_subscription 수시 결제(온디맨드) 구독

구독 결제 주기 (subscription_payment_cycle_type)

값 키 설명
11 1week 1주
12 2weeks 2주
13 3weeks 3주
14 4weeks 4주
16 6weeks 6주
21 1month 1개월
22 2months 2개월
23 3months 3개월
26 6months 6개월
31 1year 1년

구독 결제 방식 (subscription_billing_type)

값 키 설명
0 non_subscription 비구독
1 pay_per_item 건별 결제
2 pay_all_at_once 일괄 결제

구독 금액 조정 타입 (type)

값 키 설명
1 discount 회차별 할인 적용
2 setup_price 추가금액 (설치비 등)
3 cycle_discount 주기 할인 적용
4 cycle_additional_fee 추가 비용 적용
5 recurring_fee 매회차 추가비용 (모든 할인 적용 후)
10 coupon 구독 상품 금액 쿠폰
11 shipping_coupon 배송비 쿠폰

상품 유형 (type)

값 키 설명
0 general_products 일반 상품
1 delivery_products 배송 상품
2 content_products 콘텐츠 상품
3 mobile_coupons 모바일 쿠폰
4 reservation_products 예약 상품
5 online_courses 온라인 강좌
7 crowdfunding_donation_products 크라우드펀딩/기부 상품
8 seminars_workshops 세미나/워크샵
100 all_products 전체 상품

상품 검수 상태 (status_review)

상품의 status_review 값이에요.

값 키 설명
0 auto_confirm 자동 승인
1 waiting 검수 대기
2 pending 검수 보류
3 confirm 검수 승인
4 reject 검수 반려

과세 유형 (tax_type)

값 키 설명
1 taxable 과세
2 compound_taxation 복합 과세
3 tax_free 면세
4 zero_taxation 영세율

할인 방식 (discount_price_type)

상품의 discount_price 를 어떻게 적용할지예요. 보내지 않으면 0 이 저장되고 정액으로 계산돼요.

값 키 설명
1 percentage 퍼센트 — 판매가 = display_price × (100 - discount_price) / 100
2 fixed_price 정액 — 판매가 = display_price - discount_price

배송 유형 (delivery_type)

값 키 설명
1 parcel 택배
2 direct 직접 배송
3 quick 퀵 서비스
4 pickup 매장 수령

발주 상태 (status)

주문 상세 응답 order_purchases[].status 예요. 가맹점이 처리한 단계​​를 나타내요.

이 표는 정수로 내려와요

발주 상태와 배송추적 상태는 키 문자열로 변환되지 않아요. 응답에 정수가 그대로 들어와요.

값 설명
0 주문 생성 전(결제 대기)
1 발주 대기 — 결제가 끝나고 발주가 만들어진 상태
2 발주 확인
3 상품 준비중
4 발송 완료 — 운송장이 등록된 시점
5 배송 완료
-1 발주 취소
-2 발주 오류
-3 발주 무효 (주문 취소로 폐기)

배송추적 상태 (d_ts)

주문 상세 응답 order_purchases[].d_ts 와 tracking_histories[].delivery_tracking_status 예요. 택배사가 알려준 단계​​라 발주 상태와 따로 움직여요.

값 설명
0 추적 없음 — 운송장 등록 전이거나 추적이 끊긴 상태
1 수거 요청
2 수거 대기
3 집화 — 이동 중을 포함해요
4 배송 완료
5 배송 실패 — 반송도 여기예요
6 오류 송장
7 집화 실패
8 집화 취소
배송 완료는 발주 상태도 따라 움직여요

택배사가 배송 완료(4)를 알려주면 발주 상태도 배송 완료(5)로 자동으로 넘어가요.

회원 유형 (membership_type)

membership_type — 고객 목록 조회의 필터 값이에요. 필터로 보낼 때는 값(숫자)만 받아요 — 키 문자열은 0 으로 읽혀요.

값 키 설명
1 member 회원
2 guest 비회원
구독의 `membership_type`은 다른 표예요

이름은 같지만 구독·구독 청구(Bill)·구독 트랜잭션 응답의 membership_type은 아래 값을 써요. 고객의 회원/비회원 구분과 헷갈리지 마세요.

값 키 설명
1 personal 개인
2 business 사업자
3 business_department 사업자 부서

고객 구분 (corporate_type)

개인/기업 구분은 membership_type이 아니라 corporate_type이에요. 그룹 조회 같은 요청에 보낼 때는 값(숫자)만 받아요.

값 키 설명
1 individual 개인
2 business 기업
3 department 부서

성별 (gender)

고객의 gender 값이에요. 키 문자열 없이 숫자로 주고받아요.

값 설명
0 비공개·미지정
1 남성
2 여성
-1 알 수 없음

회원 그룹 상태 (status)

회원 그룹(user_group)과 그룹 권한(user_group_role)의 status예요.

값 키 설명
1 active 활성
0 inactive 비활성
-1 deleted 삭제됨

알림톡 발신프로필 상태 (status)

발신프로필(카카오 채널) 응답의 status예요.

값 키 설명
1 active 사용 가능
2 blocked 차단
3 released 해제

알림톡 템플릿 검수 상태 (inspection_status)

자체 템플릿 응답의 inspection_status예요. 벤더 코드는 카카오 콘솔 표기이고, 필터에는 키·벤더 코드·숫자를 모두 보낼 수 있어요.

값 키 벤더 코드 설명
1 registered REG 카카오에 올라감, 검수 전
2 requested REQ 검수 요청함
3 approved APR 승인 — 이 상태여야 발송돼요
4 kakao_rejected KRR 등록 거절
5 rejected REJ 승인 반려

웹훅 전송 상태 (status)

웹훅 전송 내역 응답의 status예요.

값 키 설명
1 done 전송 성공
2 ready 전송 대기
3 doing 전송 중
-1 failed 전송 실패
알림톡 웹훅 전송 이력은 지금 항상 `ready` 로 와요

알림톡 웹훅 전송 이력의 status 는 전송 결과와 관계없이 ready 로 남아요. 결과는 설정 조회의 last_status·consecutive_failures 로 봐요.

결제 수단 유형

현재 어떤 응답 필드에도 쓰이지 않아요

이 값 집합은 매핑 테이블에만 남아 있고, 이 값을 내려주는 API 필드가 없어요. 연결되는 필드가 확인되기 전까지는 참고용으로만 봐주세요.

값 키 설명
1 card 카드
2 automatic_transfer 자동이체

기간 유형 (duration_type)

값 키 설명
1 week 주
2 month 월
3 year 년

함께 보기