StepPay API 상세 참고 문서

공식 문서: https://docs.steppay.kr/docs/ 포털: https://portal.steppay.kr 문의: contact@steppay.kr

1. 인증 (Authentication)

StepPay는 API Key를 사용하여 API 요청을 인증합니다. 인증키가 없거나 만료된 경우 오류가 반환됩니다.

1.1 사전 준비

StepPay 포털에서 회원가입 필수
결제 연동키 발급 후 PG 설정 필요

1.2 인증 키 종류

Secret-Token

항목	내용
용도	V1 API 호출 시 사용
발급	포털 가입 시 자동 생성
위치	포털 → [설정] → '인증키 관리'

⚠️ 보안 주의: 시크릿 키를 웹 프론트에서 사용하면 노출 위험이 있으니, 백엔드에서 연동하시길 권장합니다.

Payment-Key

항목	내용
용도	결제 연동에 사용
발급	PG 설정을 통해 발급

1.3 API 인증 방법

HTTP Header에 Secret-Token을 포함하여 요청합니다.

bash

curl --location 'https://api.steppay.kr/api/v1/subscriptions' \
--header 'Secret-Token: ${Secret-Token}' \
--header 'Content-Type: application/json'

2. 고객 (Customer)

StepPay의 고객 관리 시스템은 결제 주체인 고객 정보를 중앙화하여 관리합니다.

2.1 고객 정보 구성

항목	설명
연락처	이메일, 전화번호
주소	배송 주소 정보
주문/구독 이력	과거 거래 내역
마케팅 동의	마케팅 수신 동의 여부
커스텀 필드	추가 정보 (key-value)

2.2 계정 상태

상태	설명
NORMAL	정상 상태 고객
DORMANT	휴면 상태 고객

휴면 전환 기준: 활성 구독 없이 12개월간 주문/로그인 미실행

2.3 고객 생성 API

기본 고객 생성

bash

POST /api/v1/customers
Header: Secret-Token: {your-token}
Content-Type: application/json

{
  "name": "홍길동",
  "email": "hong@example.com"
}

커스텀 필드 포함 생성

attributes 객체를 통해 key-value 쌍으로 추가 데이터를 전송합니다.

json

{
  "name": "홍길동",
  "email": "hong@example.com",
  "attributes": {
    "company": "회사명",
    "department": "개발팀"
  }
}

2.4 커스텀 필드 유형

타입	설명
TEXT	일반 텍스트
EMAIL	이메일 형식
PASSWORD	비밀번호
PHONE	전화번호
CHECKBOX	체크박스
DROPDOWN	드롭다운 선택
CALENDAR	날짜 선택
NUMBER	숫자
COMMENT	코멘트/설명

설정 위치: 마이스토어 설정 → 가입/로그인 설정 → 회원가입

2.5 소셜 로그인 지원

카카오 로그인
네이버 로그인

각 플랫폼별 REST API 키 또는 클라이언트 인증정보를 마이스토어 설정에 입력합니다.

3. 상품 (Product)

StepPay에서 상품은 판매 항목과 가격 플랜을 의미합니다.

중요: 상품은 가격 플랜과 1:N 관계를 가집니다. 상품 생성 후 반드시 가격 플랜을 생성해야 주문이 가능합니다.

3.1 상품 유형 (5가지)

유형	설명	예시
BOX	배송이 필요한 실물 상품	책, 가전제품, 정기배송
SOFTWARE	SaaS 서비스 및 무형 상품	온라인 콘텐츠, 소프트웨어
INVOICE	청구서 페이지에서 생성되는 인스턴트 상품	즉석 청구
BUNDLE	여러 상품을 묶은 번들 판매 유형	패키지 상품
DRAFT	몰인몰에서 상위 가맹점 승인 대기 중인 상품	승인 대기

3.2 상품 상태 (4가지)

상태	설명
SALE	판매중 - 고객에게 노출되는 상품
OUT_OF_STOCK	재고 부족 상태
UNSOLD	마이스토어에 미노출 상태
WAITING_APPROVAL	몰인몰 승인 대기 중

3.3 상품 옵션

조합형 옵션

여러 옵션값을 조합하여 다중 제품 생성

예: 색상(빨강, 파랑) × 사이즈(S, M, L) = 6개 SKU

3.4 무료 체험 설정

구독 상품에 적용 가능한 무료 체험 기능입니다.

필드	타입	설명
`enabledDemo`	boolean	무료 체험 활성화 여부
`demoPeriod`	number	체험 기간 숫자
`demoPeriodUnit`	string	DAY / WEEK / MONTH / YEAR

3.5 재고 관리

구분	동작
단건 주문	수량만큼 차감
구독	초기 및 매 갱신 시 자동 차감
조합형 옵션	옵션별 개별 관리 가능

3.6 상품 API

bash

# 상품 생성
POST /api/v1/products

# 상품 목록 조회
GET /api/v1/products

# 상품 상세 조회
GET /api/v1/products/{code}

상품 생성 요청 예시

json

{
  "type": "SOFTWARE",
  "status": "SALE",
  "name": "프리미엄 플랜",
  "enabledDemo": true,
  "demoPeriod": 14,
  "demoPeriodUnit": "DAY",
  "useCombination": false
}

응답 필드

필드	설명
`id`	상품 ID
`code`	상품 코드
`type`	상품 유형
`status`	상품 상태
`name`	상품명
`quantity`	재고 수량
`prices`	가격 플랜 목록
`createdAt`	생성 시간
`modifiedAt`	수정 시간

4. 가격 플랜 (Price Plan)

4.1 가격 플랜 유형 (5가지)

ONE_TIME (단건 요금제)

일회성 구매에 대한 설정으로, 고객이 한 번만 청구되고 구독이 갱신되지 않습니다.

FLAT (구독 요금제)

고정 요금의 정기 구독 서비스입니다.

V1 API 사용 시 recurring 객체 정보 필수 입력

BUNDLE (번들 요금제)

여러 상품을 패키지로 묶어 판매합니다.

각 하위 아이템의 가격은 무시되고 번들 전체 가격으로 설정
onetimeBundlePrice 추가 시 첫 결제에 포함

USAGE_BASED (사용량 기반)

실제 사용량에 따른 과금 방식

적용 예시
API 호출 수
클라우드 스토리지
데이터 전송량

UNIT_BASED (계정수 기반)

각 단위 액션에 대한 요금을 정의하며, 베이스 가격이 존재합니다.

4.2 가격 플랜 위젯 (6가지 기능)

위젯	설명
첫 결제 할인	초기 주문 시 할인가 적용
기본료/도입비/설치비	1회성 또는 정기적 추가 과금
구독 만기 지정	만기 날짜 도래 시 자동 만료 처리
후불 결제	다음 결제 예정일에 결제
사용량 기반	사용량에 따른 비례 과금
계정수 기반	단위별 과금

4.3 가격 플랜 생성 API

bash

POST /api/v1/products/{product_id}/prices

요청 예시

json

{
  "plan": "FLAT",
  "type": "RECURRING",
  "price": 29000,
  "unit": "MONTH",
  "basicServing": 1,
  "recurring": {
    "interval": 1,
    "intervalUnit": "MONTH"
  }
}

5. 주문 (Order)

주문과 주문 항목은 1:N 관계를 유지합니다.

5.1 주문 유형 (5가지)

유형	설명
ONE_TIME	단건 결제 - 한 번만 청구, 반복 없음
RECURRING_INITIAL	구독 최초 결제
RECURRING	구독 정기 결제 (초기 이후)
PAYMENT_METHOD	결제 수단 변경 시 생성
ADD_USAGE	사용량/계정수 기반 추가 과금

5.2 주문 항목 유형

유형	설명
SKU	핵심 상품 재고 단위
TAX	세금/부가가치세
FEE	추가 비용 (설치비, 기본료 등)
SHIPPING	배송비
DISCOUNT	할인 금액

5.3 주문 상태 흐름

CREATED → DEPOSIT_WAITING → PAID
                ↓
           CANCELLED
                ↓
      CANCELLATION_REQUEST
                ↓
      CANCELLATION_REFUNDING

배송 관련 상태

ORDER_DELIVERY_PREPARING → ORDER_DELIVERY_STARTED → ORDER_DELIVERY_COMPLETED

5.4 주문 생성 방법

1) API를 통한 주문 생성

최소 하나의 고객 식별자 필요: customerId, customerCode, 또는 customerUuid

bash

POST /api/v1/orders

json

{
  "customerId": 12345,
  "items": [
    {
      "priceId": 100,
      "currency": "KRW",
      "quantity": 1
    }
  ]
}

2) 청구서(Invoice)를 통한 생성

포털 설정에서 사업자 정보 등록 후 청구서 생성

3) 마이스토어를 통한 생성

고객이 '바로 구매' 또는 장바구니 결제로 진행

5.5 결제 연동

주문 생성 후 고유 코드를 받아 결제 페이지로 리다이렉트합니다.

https://payment.steppay.kr/order/{order_code}

6. 구독 (Subscription)

구독은 고객이 공급자의 상품/서비스에 지속적으로 접근하기 위해 반복 결제에 동의하는 계약입니다.

6.1 핵심 관계

RECURRING_INITIAL 주문 (최초 결제)
        ↓ 자동 생성
      구독 (Subscription)
        ↓ 주기적으로 생성
    RECURRING 주문 (정기 결제)

하나의 RECURRING_INITIAL 주문이 여러 구독을 생성할 수 있음

6.2 구독 상태 (7가지)

상태	설명	복구 가능
ACTIVE	사용자가 서비스를 이용할 수 있는 정상 상태	-
UNPAID	결제 실패로 인한 일시 중지	✅
PENDING_CANCEL	취소 대기 중 (예약 취소)	✅
CANCELED	취소됨	❌
PENDING_PAUSE	일시정지 대기 중	✅
PAUSE	일시 중지됨	✅
EXPIRED	만료됨	❌

⚠️ CANCELED, EXPIRED 상태는 다시 복구될 수 없습니다.

6.3 상태 전환 규칙

ACTIVE 상태에서만 취소/일시정지 가능
PENDING_CANCEL → CANCELED
PENDING_PAUSE → PAUSE

6.4 갱신 실패 처리 (자동 재시도)

결제 실패 시 자동 재시도 일정:

재시도	시점
1차	실패 후 1일
2차	실패 후 3일
3차	실패 후 5일
4차	실패 후 10일
5차	실패 후 14일

복구 성공 시: UNPAID → ACTIVE

6.5 선불 vs 후불 구독

항목	선불	후불
취소/만료 시 최종 결제	없음	있음
초기 recurringCount	1	0

6.6 결제 수단 변경

구독의 자동 결제는 PG에서 발급되는 빌링키를 통해 진행됩니다.

변경 프로세스

PAYMENT_METHOD 타입 주문 생성
고객이 결제 페이지에서 새 결제 수단 입력
구독의 결제 수단 자동 업데이트

6.7 주문 취소의 영향

취소 대상	영향
RECURRING_INITIAL	생성된 모든 구독 취소 (환불 무관)
RECURRING	구독에 영향 없음

6.8 구독 생성 흐름

1. 주문 생성 API 호출 (RECURRING_INITIAL)
        ↓
2. 주문번호를 시스템에 저장
        ↓
3. 결제 링크로 고객 리다이렉트
        ↓
4. 결제 완료 후 주문 상세조회로 구독ID 확인
        ↓
5. 웹훅으로 상태 변화 모니터링

6.9 구독 API 목록 (14개)

기능	엔드포인트
구독 목록 조회	`GET /api/v1/subscriptions`
구독 상세 조회	`GET /api/v1/subscriptions/{id}`
구독 항목 추가	`POST /api/v1/subscriptions/{id}/items`
구독 항목 수정	`PUT /api/v1/subscriptions/{id}/items/{itemId}`
구독 항목 삭제	`DELETE /api/v1/subscriptions/{id}/items/{itemId}`
구독 항목 교체	`PUT /api/v1/subscriptions/{id}/items/{itemId}/replace`
구독 일시정지	`POST /api/v1/subscriptions/{id}/pause`
구독 활성화	`POST /api/v1/subscriptions/{id}/activate`
구독 취소	`POST /api/v1/subscriptions/{id}/cancel`
결제수단 변경	`POST /api/v1/subscriptions/{id}/payment-method`
주기 변경	`PUT /api/v1/subscriptions/{id}/interval`
결제일 변경	`PUT /api/v1/subscriptions/{id}/billing-date`
갱신 결제 즉시 실행	`POST /api/v1/subscriptions/{id}/renew`

7. 웹훅 (Webhook)

StepPay는 이벤트 발생 시 지정된 URL로 알림을 보내는 Webhook을 지원합니다.

7.1 지원 버전

버전	상태
Webhook v2	권장
Webhook v1	Deprecated

7.2 웹훅 스키마

Subscription (구독)

필드	타입	설명
`subscriptionId`	number	구독 번호
`status`	string	ACTIVE, INACTIVE, PAUSED, CANCELED 등
`items`	array	구독 항목 배열
`paymentMethod`	object	결제 수단 정보
`currentPeriod`	object	현재 주기 정보

Order (주문)

필드	타입	설명
`id`	number	주문 번호
`code`	string	주문 코드
`type`	string	RECURRING, ONE_TIME 등
`paidAmount`	number	결제 금액
`items`	array	주문 항목 배열
`shipping`	object	배송 정보

Payment (결제)

필드	타입	설명
`paymentId`	number	결제 번호
`status`	string	COMPLETE, CANCELED, FAILED 등
`paidAmount`	number	결제 금액
`paymentGateway`	string	PG사 정보

Customer (고객)

필드	타입	설명
`id`	number	고객 번호
`email`	string	이메일
`phone`	string	전화번호
`shipping`	object	기본 배송 정보

Product & Price (상품/가격)

필드	타입	설명
`code`	string	상품/가격 코드
`type`	string	상품 타입 또는 가격 유형
`price`	number	금액
`recurring`	object	구독 주기 정보

Invoice (청구서)

필드	타입	설명
`id`	number	청구서 번호
`status`	string	청구서 상태
`customerId`	number	고객 번호

Cover (스텝커버)

필드	타입	설명
`id`	number	커버 번호
`customerId`	number	고객 번호
`messageType`	string	REMIND, DATE_CHANGED, PAUSED

8. API Reference

8.1 전체 API 목록 (58개)

벤더 API (3개)

Method	Endpoint	설명
GET	`/api/v1/vendors/{vendorUuid}/children`	하위 벤더 목록 조회
POST	`/api/v1/vendors/{vendorUuid}/children`	하위 벤더 추가
GET	`/api/v1/vendors/{vendorUuid}/children/{childUuid}`	하위 벤더 상세 조회

고객 API (5개)

Method	Endpoint	설명
GET	`/api/v1/customers`	고객 목록 조회
POST	`/api/v1/customers`	고객 생성
GET	`/api/v1/customers/{id}`	고객 상세 조회
PUT	`/api/v1/customers/{id}`	고객 수정
DELETE	`/api/v1/customers/{id}`	고객 삭제

상품 API (11개)

Method	Endpoint	설명
GET	`/api/v1/products`	상품 목록 조회
POST	`/api/v1/products`	상품 생성
GET	`/api/v1/products/{code}`	상품 상세 조회
PUT	`/api/v1/products/{code}`	상품 수정
DELETE	`/api/v1/products/{code}`	상품 삭제
PUT	`/api/v1/products/{code}/status`	게시 상태 변경
GET	`/api/v1/products/{productId}/prices`	가격 플랜 목록
POST	`/api/v1/products/{productId}/prices`	가격 플랜 생성
GET	`/api/v1/products/{productId}/prices/{priceId}`	가격 플랜 상세
PUT	`/api/v1/products/{productId}/prices/{priceId}`	가격 플랜 수정
DELETE	`/api/v1/products/{productId}/prices/{priceId}`	가격 플랜 삭제

주문 API (6개)

Method	Endpoint	설명
GET	`/api/v1/orders`	주문 목록 조회
POST	`/api/v1/orders`	주문 생성
GET	`/api/v1/orders/{code}`	주문 상세 조회
POST	`/api/v1/orders/{code}/cancel`	주문 취소
GET	`/api/v1/orders/{code}/payment-link`	결제 링크 조회
GET	`/api/v1/orders/{code}/shipping`	배송 정보 조회

청구서 API (5개)

Method	Endpoint	설명
GET	`/api/v1/invoices`	청구서 목록 조회
POST	`/api/v1/invoices`	청구서 생성
GET	`/api/v1/invoices/{id}`	청구서 상세 조회
PUT	`/api/v1/invoices/{id}`	청구서 수정
DELETE	`/api/v1/invoices/{id}`	청구서 삭제

구독 API (14개)

Method	Endpoint	설명
GET	`/api/v1/subscriptions`	구독 목록 조회
GET	`/api/v1/subscriptions/{id}`	구독 상세 조회
POST	`/api/v1/subscriptions/{id}/items`	구독 항목 추가
PUT	`/api/v1/subscriptions/{id}/items/{itemId}`	구독 항목 수정
DELETE	`/api/v1/subscriptions/{id}/items/{itemId}`	구독 항목 삭제
PUT	`/api/v1/subscriptions/{id}/items/{itemId}/replace`	구독 항목 교체
POST	`/api/v1/subscriptions/{id}/pause`	구독 일시정지
POST	`/api/v1/subscriptions/{id}/activate`	구독 활성화
POST	`/api/v1/subscriptions/{id}/cancel`	구독 취소
POST	`/api/v1/subscriptions/{id}/payment-method`	결제수단 변경
PUT	`/api/v1/subscriptions/{id}/interval`	주기 변경
PUT	`/api/v1/subscriptions/{id}/billing-date`	결제일 변경
POST	`/api/v1/subscriptions/{id}/renew`	갱신 결제 즉시 실행

사용량 API (3개)

Method	Endpoint	설명
GET	`/api/v1/usage`	사용량/계정 조회
POST	`/api/v1/usage`	사용량/계정 등록
POST	`/api/v1/usage/settle`	사용량 정산

커버 API (11개)

결제 복구 및 관리를 위한 특화 API (상세는 공식 문서 참조)

9. 공통 Request/Response 형식

9.1 Request 형식

http

{METHOD} /api/v1/{endpoint} HTTP/1.1
Host: api.steppay.kr
Secret-Token: {your-secret-token}
Content-Type: application/json

9.2 페이지네이션

목록 조회 API에서 사용되는 공통 파라미터:

파라미터	타입	설명
`page`	number	페이지 번호 (0부터 시작)
`size`	number	페이지당 항목 수
`sort`	string	정렬 기준

10. 주의사항

Secret-Token 보안: 프론트엔드에 절대 노출하지 마세요
HTTPS 필수: 모든 API 호출은 HTTPS로 진행
정기결제 PG 필수: 구독 기능 사용 시 정기결제 가능한 PG 연동 필요
테스트 환경: 실제 결제 전 테스트 모드에서 충분히 테스트
웹훅 검증: Signature를 통한 웹훅 검증 권장

11. 참고 링크

구분	URL
API 문서	https://docs.steppay.kr/docs/
포털	https://portal.steppay.kr
가이드	https://docs.steppay.kr/docs/ (Guides 탭)
API Reference	https://docs.steppay.kr/api-reference

이 문서는 StepPay 공식 문서를 기반으로 작성되었습니다. 정확한 API 스펙은 공식 문서를 참고하세요.

최종 업데이트: 2026년 2월 6일

StepPay API 상세 참고 문서 ​

1. 인증 (Authentication) ​

1.1 사전 준비 ​

1.2 인증 키 종류 ​

Secret-Token ​

Payment-Key ​

1.3 API 인증 방법 ​

2. 고객 (Customer) ​

2.1 고객 정보 구성 ​

2.2 계정 상태 ​

2.3 고객 생성 API ​

기본 고객 생성 ​

커스텀 필드 포함 생성 ​

2.4 커스텀 필드 유형 ​

2.5 소셜 로그인 지원 ​

3. 상품 (Product) ​

3.1 상품 유형 (5가지) ​

3.2 상품 상태 (4가지) ​

3.3 상품 옵션 ​

조합형 옵션 ​

3.4 무료 체험 설정 ​

3.5 재고 관리 ​

3.6 상품 API ​

상품 생성 요청 예시 ​

응답 필드 ​

4. 가격 플랜 (Price Plan) ​

4.1 가격 플랜 유형 (5가지) ​

ONE_TIME (단건 요금제) ​

FLAT (구독 요금제) ​

BUNDLE (번들 요금제) ​

USAGE_BASED (사용량 기반) ​

UNIT_BASED (계정수 기반) ​

4.2 가격 플랜 위젯 (6가지 기능) ​

4.3 가격 플랜 생성 API ​

요청 예시 ​

5. 주문 (Order) ​

5.1 주문 유형 (5가지) ​

5.2 주문 항목 유형 ​

5.3 주문 상태 흐름 ​

배송 관련 상태 ​

5.4 주문 생성 방법 ​

1) API를 통한 주문 생성 ​

2) 청구서(Invoice)를 통한 생성 ​

3) 마이스토어를 통한 생성 ​

5.5 결제 연동 ​

6. 구독 (Subscription) ​

6.1 핵심 관계 ​

6.2 구독 상태 (7가지) ​

6.3 상태 전환 규칙 ​

6.4 갱신 실패 처리 (자동 재시도) ​

6.5 선불 vs 후불 구독 ​

6.6 결제 수단 변경 ​

변경 프로세스 ​

6.7 주문 취소의 영향 ​

6.8 구독 생성 흐름 ​

6.9 구독 API 목록 (14개) ​

7. 웹훅 (Webhook) ​

7.1 지원 버전 ​

7.2 웹훅 스키마 ​

Subscription (구독) ​

Order (주문) ​

Payment (결제) ​

Customer (고객) ​

Product & Price (상품/가격) ​

Invoice (청구서) ​

Cover (스텝커버) ​

8. API Reference ​

8.1 전체 API 목록 (58개) ​

벤더 API (3개) ​

고객 API (5개) ​

상품 API (11개) ​

주문 API (6개) ​

청구서 API (5개) ​

구독 API (14개) ​

사용량 API (3개) ​

커버 API (11개) ​

9. 공통 Request/Response 형식 ​

9.1 Request 형식 ​

9.2 페이지네이션 ​

10. 주의사항 ​

StepPay API 상세 참고 문서

1. 인증 (Authentication)

1.1 사전 준비

1.2 인증 키 종류

Secret-Token

Payment-Key

1.3 API 인증 방법

2. 고객 (Customer)

2.1 고객 정보 구성

2.2 계정 상태

2.3 고객 생성 API

기본 고객 생성

커스텀 필드 포함 생성

2.4 커스텀 필드 유형

2.5 소셜 로그인 지원

3. 상품 (Product)

3.1 상품 유형 (5가지)

3.2 상품 상태 (4가지)

3.3 상품 옵션

조합형 옵션

3.4 무료 체험 설정

3.5 재고 관리

3.6 상품 API

상품 생성 요청 예시

응답 필드

4. 가격 플랜 (Price Plan)

4.1 가격 플랜 유형 (5가지)

ONE_TIME (단건 요금제)

FLAT (구독 요금제)

BUNDLE (번들 요금제)

USAGE_BASED (사용량 기반)

UNIT_BASED (계정수 기반)

4.2 가격 플랜 위젯 (6가지 기능)

4.3 가격 플랜 생성 API

요청 예시

5. 주문 (Order)

5.1 주문 유형 (5가지)

5.2 주문 항목 유형

5.3 주문 상태 흐름

배송 관련 상태

5.4 주문 생성 방법

1) API를 통한 주문 생성

2) 청구서(Invoice)를 통한 생성

3) 마이스토어를 통한 생성

5.5 결제 연동

6. 구독 (Subscription)

6.1 핵심 관계

6.2 구독 상태 (7가지)

6.3 상태 전환 규칙

6.4 갱신 실패 처리 (자동 재시도)

6.5 선불 vs 후불 구독

6.6 결제 수단 변경

변경 프로세스

6.7 주문 취소의 영향

6.8 구독 생성 흐름

6.9 구독 API 목록 (14개)

7. 웹훅 (Webhook)

7.1 지원 버전

7.2 웹훅 스키마

Subscription (구독)

Order (주문)

Payment (결제)

Customer (고객)

Product & Price (상품/가격)

Invoice (청구서)

Cover (스텝커버)

8. API Reference

8.1 전체 API 목록 (58개)

벤더 API (3개)

고객 API (5개)

상품 API (11개)

주문 API (6개)

청구서 API (5개)

구독 API (14개)

사용량 API (3개)

커버 API (11개)

9. 공통 Request/Response 형식

9.1 Request 형식

9.2 페이지네이션

10. 주의사항