# 고객 목록 조회 Source: https://docs.steppay.kr/api-reference/고객-api/고객-목록-조회 /steppay_v1.json get /api/v1/customers 고객 목록을 반환합니다. Pagination 형태로 지원됩니다. # 고객 삭제 Source: https://docs.steppay.kr/api-reference/고객-api/고객-삭제 /steppay_v1.json delete /api/v1/customers/{id} 고객 정보를 삭제할 때 호출합니다. # 고객 상세 조회 Source: https://docs.steppay.kr/api-reference/고객-api/고객-상세-조회 /steppay_v1.json get /api/v1/customers/{id} 고객 상세정보를 반환합니다. # 고객 생성 Source: https://docs.steppay.kr/api-reference/고객-api/고객-생성 /steppay_v1.json post /api/v1/customers 고객을 생성할 때 호출합니다. # 고객 수정 Source: https://docs.steppay.kr/api-reference/고객-api/고객-수정 /steppay_v1.json put /api/v1/customers/{id} 고객 정보를 수정할 때 호출합니다. 파라미터로 전달된 정보로 고객 정보가 치환됩니다. # 결제수단 변경 Source: https://docs.steppay.kr/api-reference/구독-api/결제수단-변경 /steppay_v1.json put /api/v1/subscriptions/{subscriptionId}/payment-method 구독의 결제수단을 변경할 때 호출합니다. 변경을 위한 주문이 생성됩니다. # 결제일 변경 Source: https://docs.steppay.kr/api-reference/구독-api/결제일-변경 /steppay_v1.json post /api/v1/subscriptions/{subscriptionId}/change-pay-datetime 다음 결제일을 변경합니다. # 구독 갱신 결제 Source: https://docs.steppay.kr/api-reference/구독-api/구독-갱신-결제 /steppay_v1.json post /api/v1/subscriptions/{id}/renew 다음 결제일과 상관없이 현재 시점으로 구독을 갱신시킵니다. 결제가 진행되며, 구독 시작, 끝 시점이 갱신됩니다. # 구독 목록 조회 Source: https://docs.steppay.kr/api-reference/구독-api/구독-목록-조회 /steppay_v1.json get /api/v1/subscriptions 구독 목록을 반환합니다. # 구독 상세 조회 Source: https://docs.steppay.kr/api-reference/구독-api/구독-상세-조회 /steppay_v1.json get /api/v1/subscriptions/{id} 구독의 상세 정보를 반환합니다. # 구독 일시 정지 Source: https://docs.steppay.kr/api-reference/구독-api/구독-일시-정지 /steppay_v1.json post /api/v1/subscriptions/{subscriptionId}/pause 구독을 일시정지 합니다. 활성화 상태의 구독만 일시정지 할 수 있습니다. # 구독 주기 변경 Source: https://docs.steppay.kr/api-reference/구독-api/구독-주기-변경 /steppay_v1.json put /api/v1/subscriptions/{subscriptionId}/interval 구독 주기를 변경합니다. # 구독 취소 Source: https://docs.steppay.kr/api-reference/구독-api/구독-취소 /steppay_v1.json post /api/v1/subscriptions/{subscriptionId}/cancel 구독을 취소합니다. 활성화, 일시정지, 결제실패 상태의 구독만 취소할 수 있습니다. # 구독 항목 교체 Source: https://docs.steppay.kr/api-reference/구독-api/구독-항목-교체 /steppay_v1.json put /api/v1/subscriptions/{subscriptionId}/items 구독 항목을 파라미터로 전달한 데이터로 교체합니다. # 구독 항목 삭제 Source: https://docs.steppay.kr/api-reference/구독-api/구독-항목-삭제 /steppay_v1.json delete /api/v1/subscriptions/{subscriptionId}/items/{itemId} 구독 항목을 삭제할 때 호출합니다. # 구독 항목 수정 Source: https://docs.steppay.kr/api-reference/구독-api/구독-항목-수정 /steppay_v1.json put /api/v1/subscriptions/{subscriptionId}/items/{itemId} 특정 구독 항목을 수정할 때 사용합니다. # 구독 항목 추가 Source: https://docs.steppay.kr/api-reference/구독-api/구독-항목-추가 /steppay_v1.json post /api/v1/subscriptions/{subscriptionId}/items 구독 항목을 추가할 때 호출합니다. # 구독 항목에서 사용할 수 있는 옵션 가져오기 Source: https://docs.steppay.kr/api-reference/구독-api/구독-항목에서-사용할-수-있는-옵션-가져오기 /steppay_v1.json get /api/v1/subscriptions/{subscriptionId}/items/{itemId}/options 구독 항목에서 사용할 수 있는 옵션 목록을 반환합니다. # 구독 활성화 Source: https://docs.steppay.kr/api-reference/구독-api/구독-활성화 /steppay_v1.json post /api/v1/subscriptions/{subscriptionId}/active 구독을 다시 활성화 시킵니다. 일시정지 및 취소 대기중 상태만 변경가능합니다. # 하위 벤더 목록 조회 Source: https://docs.steppay.kr/api-reference/벤더-api/하위-벤더-목록-조회 /steppay_v1.json get /api/v1/vendors/{vendorUuid}/children # 하위 벤더 상세 조회 Source: https://docs.steppay.kr/api-reference/벤더-api/하위-벤더-상세-조회 /steppay_v1.json get /api/v1/vendors/{vendorUuid}/children/{childUuid} # 하위 벤더 추가 Source: https://docs.steppay.kr/api-reference/벤더-api/하위-벤더-추가 /steppay_v1.json post /api/v1/vendors/{vendorUuid}/children # 사용량 정산 Source: https://docs.steppay.kr/api-reference/사용량-api/사용량-정산 /steppay_v1.json get /api/v1/subscriptions/{subscriptionId}/calculate 구독 중간에 사용량과 예상 결제 금액을 확인할 때 사용합니다. # 사용량/계정 등록 API Source: https://docs.steppay.kr/api-reference/사용량-api/사용량계정-등록-api /steppay_v1.json post /api/v1/usages 사용량 또는 계정을 등록할 때 사용합니다. # 사용량/계정 조회 API Source: https://docs.steppay.kr/api-reference/사용량-api/사용량계정-조회-api /steppay_v1.json get /api/v1/usages 사용량 또는 계정을 조회할 때 사용합니다. # 가격 삭제 Source: https://docs.steppay.kr/api-reference/상품-api/가격-삭제 /steppay_v1.json delete /api/v1/products/{id}/prices/{priceId} 가격을 삭제할 때 호출합니다. # 가격플랜 목록 조회 Source: https://docs.steppay.kr/api-reference/상품-api/가격플랜-목록-조회 /steppay_v1.json get /api/v1/products/{id}/prices 특정 상품의 가격플랜 목록을 반환합니다. # 가격플랜 상세 조회 Source: https://docs.steppay.kr/api-reference/상품-api/가격플랜-상세-조회 /steppay_v1.json get /api/v1/products/{id}/prices/{priceId} 가격플랜의 상세 정보를 반환합니다. # 가격플랜 생성 Source: https://docs.steppay.kr/api-reference/상품-api/가격플랜-생성 /steppay_v1.json post /api/v1/products/{id}/prices 가격플랜을 생성할 때 호출합니다. # 가격플랜 수정 Source: https://docs.steppay.kr/api-reference/상품-api/가격플랜-수정 /steppay_v1.json put /api/v1/products/{id}/prices/{priceId} 가격플랜을 수정할 때 호출합니다. 파라미터로 전달된 정보로 가격플랜 정보가 치환됩니다. 연관 주문이 존재한다면 이름과 설명만 수정됩니다. # 상품 게시 상태 변경 Source: https://docs.steppay.kr/api-reference/상품-api/상품-게시-상태-변경 /steppay_v1.json patch /api/v1/products/{id}/status 상품 게시 상태를 변경할 때 호출합니다. SALE, OUT_OF_STOCK, UNSOLD 사용 가능 # 상품 목록 조회 Source: https://docs.steppay.kr/api-reference/상품-api/상품-목록-조회 /steppay_v1.json get /api/v1/products # 상품 삭제 Source: https://docs.steppay.kr/api-reference/상품-api/상품-삭제 /steppay_v1.json delete /api/v1/products/{id} 상품을 삭제할 때 호출합니다. # 상품 상세 조회 Source: https://docs.steppay.kr/api-reference/상품-api/상품-상세-조회 /steppay_v1.json get /api/v1/products/{code} 상품 상세정보를 반환합니다. # 상품 생성 Source: https://docs.steppay.kr/api-reference/상품-api/상품-생성 /steppay_v1.json post /api/v1/products 상품을 생성할 때 호출합니다. # 상품 수정 Source: https://docs.steppay.kr/api-reference/상품-api/상품-수정 /steppay_v1.json put /api/v1/products/{id} 상품을 수정할 때 호출합니다. 파라미터로 전달된 정보로 가격플랜 정보가 치환됩니다. # 세션 생성 Source: https://docs.steppay.kr/api-reference/인증-api/세션-생성 /steppay_v1.json get /api/v1/session/{customerId} 고객 연동을 위한 세션을 생성합니다. 세션 연동을 위한 키를 리턴합니다. # 배송 정보 조회 Source: https://docs.steppay.kr/api-reference/주문-api/배송-정보-조회 /steppay_v1.json get /api/v1/delivery/orders/{orderIdOrCode} 주문의 배송 정보가 조회됩니다. # 주문 결제링크 리다이렉트 Source: https://docs.steppay.kr/api-reference/주문-api/주문-결제링크-리다이렉트 /steppay_v1.json get /api/v1/orders/{idOrCode}/pay 직접 제어 하고 싶은 경우 응답에 포함된 Location 헤더를 확인하여 리다이렉트될 URI을 가져와 처리하시면 됩니다. 우측의 API 테스트 툴에서는 302 리다이렉트가 제대로 표현되지 않습니다. # 주문 목록 조회 Source: https://docs.steppay.kr/api-reference/주문-api/주문-목록-조회 /steppay_v1.json get /api/v1/orders 주문 목록을 반환합니다. # 주문 상세 조회 Source: https://docs.steppay.kr/api-reference/주문-api/주문-상세-조회 /steppay_v1.json get /api/v1/orders/{orderIdOrCode} 주문 상세정보를 반환합니다. # 주문 생성 Source: https://docs.steppay.kr/api-reference/주문-api/주문-생성 /steppay_v1.json post /api/v1/orders 주문을 생성할 때 호출합니다. customerId, customCode 또는 customerUuid 중 하나는 필수로 입력해야 합니다. # 주문 취소 Source: https://docs.steppay.kr/api-reference/주문-api/주문-취소 /steppay_v1.json patch /api/v1/orders/{orderIdOrCode}/cancel 주문을 취소할 때 호출합니다. 결제가 완료된 주문건은 환불되며, 그렇지 않은 주문은 취소됩니다. # 청구서 목록 조회 Source: https://docs.steppay.kr/api-reference/청구서-api/청구서-목록-조회 /steppay_v1.json get /api/v1/invoices 청구서 목록을 반환합니다. # 청구서 삭제 Source: https://docs.steppay.kr/api-reference/청구서-api/청구서-삭제 /steppay_v1.json delete /api/v1/invoices/{id} 청구서를 삭제할 때 호출합니다. # 청구서 상세 조회 Source: https://docs.steppay.kr/api-reference/청구서-api/청구서-상세-조회 /steppay_v1.json get /api/v1/invoices/{id} 청구서의 상세정보를 반환합니다. # 청구서 생성 Source: https://docs.steppay.kr/api-reference/청구서-api/청구서-생성 /steppay_v1.json post /api/v1/invoices 청구서를 생성할 때 호출합니다. # 청구서 수정 Source: https://docs.steppay.kr/api-reference/청구서-api/청구서-수정 /steppay_v1.json put /api/v1/invoices/{id} 청구서를 수정할 때 호출합니다. 파라미터로 전달된 정보로 청구서가 치환됩니다. # idKey 알아내기 API Source: https://docs.steppay.kr/api-reference/커버-api/idkey-알아내기-api /steppay_v1.json get /api/v1/cover/order/{token}/idKey 특정 토큰에서 결제된 idKey를 알아냅니다. 결제수단을 변경할 때 사용합니다. # 가격 플랜 정보 등록 API Source: https://docs.steppay.kr/api-reference/커버-api/가격-플랜-정보-등록-api /steppay_v1.json post /api/v1/cover/price 가격 플랜 정보를 스텝커버에 등록할 때 사용합니다. # 고객 정보 등록 API Source: https://docs.steppay.kr/api-reference/커버-api/고객-정보-등록-api /steppay_v1.json post /api/v1/cover/customer 고객 정보를 스텝커버에 등록할 때 사용합니다. # 구독 정보 등록 API Source: https://docs.steppay.kr/api-reference/커버-api/구독-정보-등록-api /steppay_v1.json post /api/v1/cover/subscription 구독 정보를 스텝커버에 등록할 때 사용합니다. # 구독 취소 API Source: https://docs.steppay.kr/api-reference/커버-api/구독-취소-api /steppay_v1.json put /api/v1/cover/subscription/{subscriptionId}/cancel 구독이 취소되었을 때 사용합니다. 진행중이던 시나리오가 있다면 멈춥니다. # 구독 활성 API Source: https://docs.steppay.kr/api-reference/커버-api/구독-활성-api /steppay_v1.json put /api/v1/cover/subscription/{subscriptionId}/active 구독이 활성화 되었을 때 사용합니다. 진행중이던 시나리오가 있다면 멈춥니다. # 복구 시작 API Source: https://docs.steppay.kr/api-reference/커버-api/복구-시작-api /steppay_v1.json post /api/v1/cover/recovery 결제 복구 시나리오를 실행합니다. # 상품 정보 등록 API Source: https://docs.steppay.kr/api-reference/커버-api/상품-정보-등록-api /steppay_v1.json post /api/v1/cover/product 상품 정보를 스텝커버에 등록할 때 사용합니다. # 주문 성공 API Source: https://docs.steppay.kr/api-reference/커버-api/주문-성공-api /steppay_v1.json patch /api/v1/cover/order/success/{orderId} 주문을 성공 상태로 바꿉니다. 결제 복구 시나리오가 멈춥니다. # 주문 정보 등록 API Source: https://docs.steppay.kr/api-reference/커버-api/주문-정보-등록-api /steppay_v1.json post /api/v1/cover/order 주문 정보를 스텝커버에 등록할 때 사용합니다. # 주문 취소 API Source: https://docs.steppay.kr/api-reference/커버-api/주문-취소-api /steppay_v1.json patch /api/v1/cover/order/cancel/{orderId} 주문을 취소 상태로 바꿉니다. 결제 복구 시나리오가 멈춥니다. # 인증 가이드 Source: https://docs.steppay.kr/docs/01_인증 스텝페이는 계정의 API Key를 사용하여 API 요청을 인증합니다. 요청에 인증키가 포함되어 있지 않거나 인증 키가 만료된 경우에는 인증 오류를 반환합니다. API 인증키는 스텝페이 포탈에 가입된 회원에게 제공됩니다. ## 사전 준비 작업 * API 인증키를 발급받으려면 스텝페이 포탈에서 회원가입이 필요합니다. * 결제 연동키 발급 후 스텝페이 포탈에서 [PG 설정](/docs/07-0_결제#사전-준비-작업)이 필요합니다. ## 인증 키 설정 스텝페이에서 사용하는 인증 키는 두 가지 종류가 있습니다. API 인증키는 스텝페이 포탈의 \[설정] 메뉴의 '인증키 관리'에서 확인할 수 있습니다. ![인증키\_관리.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=01_auth\&name=setting_secret_token.png) ### 1. Secret-Token Secret-Token은 V1 API 호출 시 필요한 인증 키입니다. Secret-Token은 스텝페이 포탈에 가입하면 별도의 절차 없이 모든 고객에게 생성되는 키 입니다. > Secret-Token은 HTTP Request 요청 시 필요한 값입니다. 시크릿 키를 웹 프론트에서 사용하게 되면 노출 위험이 있으니, 백엔드에서 연동하시길 권장드립니다. ### 2. Payment-Key Payment-Key를 사용하여 결제를 연동하는 경우, PG 설정을 통해 사용하고자 하는 PG가 설정되어 있어야 합니다. ![인증키\_관리.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=01_auth\&name=setting_pg.png) ## API 인증 스텝페이 V1 API를 사용하려면 HTTP Header에 Secret-Token을 전달해야 합니다. ```bash theme={null} curl --location 'https://api.steppay.kr/api/v1/subscriptions' \ --header 'Secret-Token:${Secret-Token}' ``` # 고객 가이드 Source: https://docs.steppay.kr/docs/02_고객 고객은 일반적으로 실제 결제를 수행하는 주체를 의미합니다. 이는 제품이나 서비스의 최종 사용자와 결제 주체가 다를 수 있다는 것을 의미합니다. 고객 정보에는 기본적으로 연락처, 주소, 주문 내역, 구독 내역, 마케팅 수신 동의 여부가 포함되며, [커스텀 필드](#커스텀-필드-설정-방법)를 통해 추가 정보를 저장하여 관리할 수 있습니다. ### 계정 상태 고객의 계정 상태는 정상 상태인 경우 `NORMAL`로 표시되고, 휴면 정책에 따라 휴면 고객의 상태는 `DORMANT`로 표시됩니다.\ 고객 계정이 휴면 상태로 전환되기 위한 기본 조건은 활성 구독이 없어야 합니다. 만약 고객이 최근 11개월 동안 주문이나 로그인을 하지 않았다면, 휴면 계정 전환 예정에 대한 알림을 고객의 이메일로 발송합니다. 만약 고객이 12개월 동안 주문이나 로그인을 하지 않는 경우, 고객 계정은 휴면 상태로 전환되며, 이에 대한 알림을 고객의 이메일로 보내게 됩니다.
상태 명칭
NORMAL 정상
DORMANT 휴면
## 연관 가이드 * [인증 가이드](/docs/01_인증) * [주문 가이드](/docs/05_주문) * [구독 가이드](/docs/06_구독) ## 사전 준비 작업 * [Secret-Token 확인하기](/docs/01_인증#1-secret-token) ## API 사용 예시 ### 고객 생성 * Request ```bash theme={null} curl --request POST \ --url https://api.steppay.kr/api/v1/customers \ --header 'Secret-Token: b9412897585074d04d11cc2384f2a50425aa8cb0f78bd23ee3e3d4cb65a1e55c' \ --header 'accept: */*' \ --header 'content-type: application/json' \ --data ' { "name": "STEPPAY", "email": "test@steppay.kr" } ``` * Response ```json theme={null} { "id": 242443, "name": "STEPPAY", "email": "test@steppay.kr", "phone": null, "code": "customer_75zcznodv", "marketingSms": false, "marketingEmail": false, "marketingKakao": false, "createdAt": "2023-06-19T02:34:15.399478" } ``` ### 커스텀 필드를 포함한 고객 생성 커스텀 필드를 사용하려면 먼저 [커스텀 필드 설정](#커스텀-필드-설정-방법)을 해야합니다.\ 설정`attributes`에 커스텀 필드에 대한 정보 입력하고, `key-value` 형식으로 입력합니다. 여기서 `key`에 설정된 커스텀 필드의 키 값이며, `value`는 JSON 형식으로 입력해야 합니다. * Request ```bash theme={null} curl --request POST \ --url https://api.steppay.kr/api/v1/customers \ --header 'Secret-Token: b9412897585074d04d11cc2384f2a50425aa8cb0f78bd23ee3e3d4cb65a1e55c' \ --header 'accept: */*' \ --header 'content-type: application/json' \ --data ' { "name": "STEPPAY", "email": "test@steppay.kr" ... "attributes": { "bfl9no1mg3w": "\"demo text\"" } ``` ## 스텝페이 포탈 사용 예시 스텝페이 포탈에서 고객을 생성하는 방법은 간단합니다. 1. \[고객 관리 → 새 고객 추가] 메뉴로 이동합니다. 2. 아래와 같이 필수 필드에 값을 채우고 추가 버튼 클릭합니다. > 필수 필드 외 커스텀 필드에 대한 설정은 아래 [커스텀 필드 설정](#커스텀-필드-설정-방법)에서 확인할 수 있습니다. > ![create\_customer.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=02_customer\&name=create_customer.png) ## 연동 가이드 ### 고객 연동 방법 * **가맹점에 기존 고객이 없는 경우** * 가맹점의 고객이 추가될때, 스텝페이 고객도 추가되어야 합니다. * 즉, 가맹점의 고객과 스텝페이의 고객 정보가 동기화 되어야 합니다. * **가맹점에 기존 고객이 있는 경우** * 가맹점에 기존 고객의 정보를 스텝페이 고객에 추가해야 합니다. * 기존 고객 정보를 스텝페이에 추가하기 위해 엑셀 업로드 또는 고객 등록 API를 반복 호출하여 추가할 수 있습니다. ### 고객 엑셀 업로드 기능 1. \[고객 관리 → 전체 고객 내역] 메뉴로 이동합니다. 2. `고객 대량 업로드` 버튼 클릭합니다. 3. 아래와 같이 고객 정보에 대한 엑셀 파일을 업로드하여 고객을 추가합니다. ![create\_customer\_excel.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=02_customer\&name=create_customer_excel.png) ### 커스텀 필드 설정 방법 스텝페이에서는 고객을 생성할 때 다양한 형태로 저장할 수 있도록 빌더를 제공합니다.\ 기본적인 회원 가입 필드(아이디, 이름, 휴대폰 번호, 이메일, 비밀번호, 마케팅 수신 동의)의 필드명을 변경하거나 활성화/비활성화 할 수 있고, 필수 입력 여부 설정을 통해 고객 데이터의 기본 구조를 자유롭게 설정할 수 있습니다.\ 또한, 고객의 추가 정보를 수집하고 저장하기 위해 커스텀 필드를 제공하며, 이 필드들은 필요에 따라 언제든지 추가, 수정, 또는 삭제가 가능합니다.\ 추가할 수 있는 커스텀 필드 타입은 아래와 같습니다. | 타입 | 명칭 | | -------- | ------ | | TEXT | 텍스트 | | EMAIL | 이메일 | | PASSWORD | 비밀번호 | | PHONE | 휴대폰 번호 | | CHECKBOX | 체크박스 | | DROPDOWN | 드롭다운 | | CALENDAR | 캘린더 | | NUMBER | 숫자 | | COMMENT | 안내 문구 | **커스텀 필드 설정 방법은 아래와 같습니다.** 1. \[마이스토어 설정 → 가입/로그인 설정 → 회원가입] 메뉴로 이동합니다. 2. 아래와 같이 커스텀 필드들을 자유롭게 설정합니다. 3. 추가한 커스텀 필드에 대한 key 값을 복사하여 고객 생성 API 사용 시 해당 key 값을 커스텀 필드에 추가합니다. 4. 새로운 고객을 생성하면, 추가된 커스텀 키 값을 확인할 수 있습니다. ![custom\_field.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=02_customer\&name=customer_custom_field.png) ## 소셜 로그인 설정 1. 카카오/네이버 애플리케이션을 생성합니다. * 애플리케이션 키 값을 확인합니다. * 필수동의 사항을 아래에서 확인 후 동일하게 체크합니다. * 화면의 Redirect URL 값을 복사하여 애플리케이션 RedirectUrl(CallbackUrl)에 등록합니다. 2. \[마이스토어 설정 → 가입/로그인 설정 → 소셜 로그인] 메뉴로 이동합니다. 3. 카카오/네이버 소셜 로그인을 설정합니다. * 카카오 소셜 로그인을 위해 REST API 키를 입력합니다. * 네이버 소셜 로그인을 위해 클라이언트 ID와 클라이언트 시크릿을 입력합니다. ### 소셜 로그인 필수동의 사항 * 카카오 로그인 필수동의 사항 ![custom\_field.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=02_customer\&name=kakao_required_check.png) * 네이버 로그인 필수동의 사항 ![custom\_field.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=02_customer\&name=naver_required_check.png) # 상품 가이드 Source: https://docs.steppay.kr/docs/03_상품 스텝페이에서 상품은 판매할 아이템과 가격 플랜을 의미합니다. 상품의 주요 속성에는 상품 유형, 상품 상태, 상품 옵션이 있으며, 상품은 가격 플랜과 밀접하게 연결이 됩니다. 상품의 주요 속성에는 [상품 유형](#상품-유형), [상품 상태](#상품-상태), [상품 옵션](#상품-옵션)이 있으며, 상품은 가격 플랜과 밀접하게 연결이 됩니다. 상품은 가격 플랜과 1:N 관계이기 때문에 하나의 상품이 여러 개의 가격 플랜을 가질 수 있습니다.\ 예를들면 하나의 상품에 단건 가격 플랜, 구독 가격 플랜이 생성 될 수 있습니다. 또한 하나의 상품에 여러 구독 가격 플랜을 설정할 수 있습니다. 예를들어 주 단위 결제, 월 단위 결제, 연 단위 결제를 따로 설정할 수 있습니다.\ 상품과 가격 플랜은 API를 통해 각각 생성할 수는 있지만, 가격 플랜이 없는 상품을 주문할 수는 없습니다. **따라서 상품 생성 API를 통해 상품 생성 후 반드시 가격 플랜을 생성해야 합니다.** ## 연관 가이드 * [가격 플랜 가이드](/docs/04-0_가격플랜) ## 사전 준비 작업 * [Secret-Token 확인하기](/docs/01_인증#1-secret-token) ## 상품의 주요 속성 ### 상품 유형 스텝페이의 상품은 네 가지 유형의 상품을 지원합니다. | 타입 | 상태 | 설명 | | ---------- | ------------- | ----------------------------------------------------------------------------------------------------------- | | `BOX` | 배송 상품 | 실물로 판매되는 배송 상품입니다. 예를 들어, 책이나 가전 제품, 정기배송 상품이 이 유형에 해당합니다. | | `SOFEWARE` | 무형 상품, 서비스 포함 | SaaS 서비스나 무형의 상품입니다. 예를 들어, 온라인 콘텐츠 구독이 이 유형에 해당합니다. | | `INVOICE` | 청구서 상품 | 빠르게 발송하기 위한 인스턴트 상품으로 청구서 페이지에서 생성되는 상품 유형입니다. | | `BUNDLE` | 번들 상품 | 여러 개의 상품을 묶어서 번들로 판매할 수 있는 유형입니다.
번들 상품은 여러 개의 가격 플랜을 포함할 수 있으며, 번들에 포함된 가격 플랜이 아닌 최종 설정한 가격이 사용됩니다. | | `DRAFT` | 사전 승인 상품 | 몰인몰(앱스토어에서 몰인몰 구매 필요)에서 상위 가맹점의 승인을 대기중인 상품 유형입니다. | ### 상품 상태 스텝페이의 상품은 네 가지 유형의 상품 상태를 지원합니다. | 타입 | 상태 | 설명 | | ------------------ | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `SALE` | 판매중 | 판매중인 상품은 고객에게 노출되는 상품으로, 주문 API를 통해 주문이 가능하고 마이스토어 상품이 노출되는 상태 입니다. | | `OUT_OF_STOCK` | 품절 | 품절은 상품의 재고가 없는 상태입니다.
재고 부족 시 구독 가격플랜을 가진 상품의 정기 결제가 안될 수 있으므로, 주기적으로 재고 관리를 해야합니다.
또한, 조합형 옵션을 가진 상품에는 각각의 옵션도 재고를 관리 할 수 있습니다. | | `UNSOLD` | 미게시 | 미게시 상태의 상품은 마이스토어 상점에 노출되지 않는 상태입니다. | | `WAITING_APPROVAL` | 승인대기 | 몰인몰(앱스토어에서 몰인몰 구매 필요)에서 상위 가맹점의 승인을 대기중인 상태입니다. | ## 상품 생성 및 관리 ### 상품 옵션 스텝페이의 상품은 옵션 추가 기능을 제공합니다. 이 옵션은 사이즈, 색상, 패키지 유형 등 다양한 형태로 설정될 수 있습니다. 사용자는 상품을 생성할 때 이러한 옵션을 정의하고 추가할 수 있습니다. 옵션에는 두가지 타입이 있습니다. * `조합형 옵션` * 여러가지 옵션을 조합하여 여러 옵션을 생성할 수 있습니다. * 예를 들어, '사이즈'와 '색상'이라는 두 가지 옵션명이 있다면, 각각 '사이즈' 옵션값 (라지, 미디움)과 '색상' 옵션값 (빨강, 노랑)이 서로 조합되어 총 4가지의 제품 옵션을 생성합니다. 조합된 옵션에 대한 가격과 재고를 조합 옵션별로 관리 할 수 있습니다. * `독립형 옵션` * 개발 예정입니다. ### 무료 체험 설정 * 스텝페이의 구독 상품에는 무료 체험 여부를 적용할 수 있습니다. 무료 체험은은 일, 주, 월, 년 단위로 설정 할 수 있습니다. * V1 API를 통해 무료 체험을 적용하기 위해서는 `enabledDemo` 필드를 ‘true’로 지정 한 후 `demoPeriod`(체험 기간) `demoPeriodUnit`(체험 기간 단위)를 적절하게 입력합니다. ### 상품 재고 관리 스텝페이의 모든 상품은 재고를 설정하여 재고를 파악 할 수 있습니다. 서비스 상품의 경우에는 재고를 설정하지 않으면 자동으로 재고가 무제한으로 설정됩니다.\ 또한, 상품 옵션을 설정 한 경우에도 각각의 옵션에 대한 재고를 설정할 수 있습니다. 재고는 다음과 같이 반영됩니다. * 단건 가격 플랜에서 고객이 해당 상품을 주문 할 때 수량 만큼 차감 됩니다. * 구독 가격 플랜에서 첫 주문 시 수량 만큼 차감 후, 구독이 갱신될 때 동일 수량 만큼 자동 차감됩니다. * 구독 주기 이전에 주문 수량을 변경하면 구독이 갱신될 때 변경된 수량만큼 차감됩니다. * 상품 재고가 없을 시 상품 상태가 품절 상태로 변경됩니다. * 조합형 옵션을 설정한 경우 각각의 옵션 마다 재고를 지정 할 수 있습니다. 해당 옵션이 품절 되었을 때 해당 옵션의 상태가 품절 상태로 변하며, 다른 옵션의 재고가 있을 시 상품의 상태가 품절 상태로 변하지 않습니다. * V1 API에서 `quantity` 필드를 통해 상품의 재고를 설정할 수 있습니다. ‘null’값 입력 시 재고가 무한대로 설정됩니다. * 상품 옵션 또한 동일하게 해당 옵션의 `quantity` 필드를 통해 재고를 설정할 수 있습니다. ## 스텝페이 포탈 사용 예시 * \[포탈 → 상품관리 → 새상품 등록] 메뉴로 이동합니다. * 상품의 기본 정보를 입력하고 저장합니다. 포탈에서 상품을 생성할 때 [가격 플랜](/docs/04-0_가격플랜)과 함께 생성하지 않으면 임시저장 상태가 됩니다. > V1 API를 통해 상품을 생성하면 가격 플랜이 상품과 함께 생성되지 않기 때문에 포탈에서 오류가 발생합니다.\ > **V1 API를 통해 상품을 생성하는 경우에는 반드시 가격 플랜도 함께 생성해야 합니다.** ![create\_product.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=03_product\&name=create_product.png) ## API 사용 예시 ### 상품 생성 * Request ```bash theme={null} curl --request POST \ --url https://api.steppay.kr/api/v1/products \ --header 'Secret-Token: {Secret-Token}' \ --header 'accept: */*' \ --header 'content-type: application/json' \ --data ' { "type": "SOFTWARE", "status": "SALE", "enabledDemo": false, "demoPeriodUnit": "DAY", "useCombination": true, "name": "TEST_PRODUCT", } ' ``` * Response ```json theme={null} { "id": 6878, "code": "product_L6ySWX1F2", "type": "SOFTWARE", "status": "SALE", "name": "TEST_PRODUCT", "subTitle": null, "featuredImageUrl": "", "imageUrls": [], "description": "", "summary": null, "reasonOfReject": null, "sku": null, "quantity": null, "combinedProducts": [], "optionGroups": [], "useCombination": true, "optionCombinations": [], "prices": [], "createdAt": "2023-06-19T01:54:14.656027", "modifiedAt": "2023-06-19T01:54:14.656027", "enabledDemo": false, "demoPeriod": 7, "demoPeriodUnit": "DAY", "categories": [], "vendorUuid": "{Vendor UUID}", "productOrder": 0, "isOnetimePurchasable": false, "eventBadge": [], "notice": null, "useWidget": { "useDemo": false, "useEventBadge": false, "useOnetimePurchasable": false, "useNotice": false }, "groupId": null, "countrySetting": null } ``` ### 상품 생성 - 옵션 추가 상품의 옵션을 추가하기 위해 우선 상품 옵션을 정의해야 합니다. 각 옵션은 이름과 값으로 구성됩니다. 예를 들면, 색상 옵션을 추가하는 경우 옵션명은 "색상"이고 값은 "블랙", "화이트" 등이 될 수 있습니다. * Request ```bash theme={null} curl --request POST \ --url https://api.steppay.kr/api/v1/products \ --header 'Secret-Token: {Secret-Token}' \ --header 'accept: */*' \ --header 'content-type: application/json' \ --data ' { "type": "BOX", "status": "SALE", "enabledDemo": false, "demoPeriodUnit": "DAY", "optionGroups": [ { "type": "SELECT", "options": [ { "name": "BLACK", "quantity": 10, "addQuantity": 1000 }, { "name": "WHITE", "addQuantity": 10, "price": 2000 } ], "name": "COLOR } ], "useCombination": true, "name": "OPTION_PRODUCT", } ' ``` ### 상품 목록 조회 * Request ```bash theme={null} curl --request GET \ --url https://api.steppay.kr/api/v1/products \ --header 'Secret-Token: {Secret-Token}' \ --header 'accept: */*' ``` * Response ```json theme={null} { "content": [ { "id": 6879, "code": "product_VQyHoGO8c", "type": "SOFTWARE", "status": "SALE", "name": "[API]TEST_PRODUCT", "quantity": null, "featuredImageUrl": "", "prices": [], "createdAt": "2023-06-19T01:55:11", "modifiedAt": "2023-06-19T01:55:11", "description": "", "categories": [], "vendorUuid": "{Vendor UUID}", "enabledDemo": false, "isOnetimePurchasable": null, "productOrder": 0, "countrySetting": null } ... ] } ``` ### 상품 상세 조회 * Request ```bash theme={null} curl --request GET \ --url https://api.steppay.kr/api/v1/products/product_VQyHoGO8c \ --header 'Secret-Token: {Secret-Token}' \ --header 'accept: */*' ``` * Response ```json theme={null} { "id": 6879, "code": "product_VQyHoGO8c", "type": "SOFTWARE", "status": "SALE", "name": "[API]TEST_PRODUCT", "subTitle": null, "featuredImageUrl": "", "imageUrls": [], "description": "", "summary": null, "reasonOfReject": null, "sku": null, "quantity": null, "combinedProducts": [], "optionGroups": [], "useCombination": true, "optionCombinations": [], "prices": [], "createdAt": "2023-06-19T01:55:11", "modifiedAt": "2023-06-19T01:55:11", "enabledDemo": false, "demoPeriod": 7, "demoPeriodUnit": "DAY", "categories": [], "vendorUuid": "{Vendor UUID}", "productOrder": 0, "isOnetimePurchasable": false, "eventBadge": [], "notice": null, "useWidget": { "useDemo": false, "useEventBadge": false, "useOnetimePurchasable": false, "useNotice": false }, "groupId": null, "countrySetting": null } ``` # 가격 플랜 가이드 Source: https://docs.steppay.kr/docs/04-0_가격플랜 스텝페이의 가격 플랜은 상품의 가격을 유연하게 설정할 수 있도록 가격 플랜을 제공합니다. 가격 플랜은 크게 단건, 구독, 번들로 나뉘며 해당 유형을 인지하고 상품을 생성해야 합니다. 스텝페이의 가격 플랜은 상품의 가격을 유연하게 설정할 수 있도록 가격 플랜을 제공합니다. 가격 플랜은 크게 **단건, 구독, 번들**로 나뉘며 해당 유형을 인지하고 상품을 생성해야 합니다. 하나의 상품에는 여러 가격 플랜이 설정 가능합니다. 가격 플랜 위젯을 통해 다양한 형태의 가격 정책을 하나의 상품에 설정하여 필요에 맞게 적용할 수 있습니다. ## 연관된 가이드 * [인증 가이드](/docs/01_인증) * [상품 가이드](/docs/03_상품) * [사용량 기반 요금제 가이드](/docs/04-1_사용량) * [계정수 기반 요금제 가이드](/docs/04-2_계정수) ## 사전 준비 작업 * [Secret-Token 확인하기](/docs/01_인증#1-secret-token) ## 가격 플랜 유형 스텝페이의 가격 플랜은 크게 5가지 유형이 있습니다.
Type Name
ONE\_TIME 단건 요금제
FLAT 구독 요금제
BUNDLE 번들 요금제
USAGE\_BASED 사용량 기반
UNIT\_BASED 계정수 기반
### 단건 플랜 단건 가격 플랜은 한 번의 단일 구매에 대한 설정입니다. 이는 일회성 제품이나 서비스에 적용되며, 이 옵션은 고객이 한 번만 청구되고 구독이 갱신되거나 금액이 재청구되지 않습니다. ### 구독 플랜 구독 가격 플랜은 고정된 요금의 구독 서비스를 의미합니다. 이 플랜은 고객에게 정기적으로 청구되는 서비스에 적합합니다. 예를 들어 쿠팡로켓 와우 또는 유튜브 뮤직과 같은 서비스에 사용될 수 있습니다. V1 API를 통해 구독(FLAT) 가격 플랜을 생성하는 경우에는 구독 주기에 해당하는 recurring(object)에 대한 정보를 필수로 입력해야 합니다. ### 번들 플랜 번틀 가격 플랜은 여러개의 상품이나 서비스를 하나의 패키지로 묶어 판매하는 상품입니다. 번들 상품은 각각의 하위 아이템들의 가격은 무시되고 번들 전체 가격으로 설정됩니다. (단, 사용량 기반 가격 플랜을 제외)\ 또한, `ontimeBundlePrice`(번들 단건 가격)값 추가 시 첫 결제 금액에서는 해당 가격이 포함되어 결제됩니다. 번들 플랜의 상품을 주문하면 번들에 포함된 하위 상품들이 주문 아이템에 추가됩니다. ## 가격 플랜 위젯 스텝페이에서는 다양한 가격 플랜 위젯을 제공하여 간편하게 가격 플랜을 생성할 수 있습니다. ### ✔️ 첫 결제 할인 고객이 상품 첫 구매 시, 최초 주문 시에 할인가로 제공할 수 있습니다. 첫 결제 할인은 상품별로 지정 가능합니다. ### ✔️ 기본료/도입비/설치비 기본료, 도입비, 설치비가 필요한 경우에 해당 위젯을 추가하여 1회성 또는 정기적으로 추가 과금 할 수 있습니다. ### ✔️ 구독 종료되는 만기 지정 구독은 기본적으로 관리자 또는 고객이 구독을 취소하기 전까지 유지됩니다. 해당 위젯을 추가하면 구독 만기 날짜를 지정할 수 있습니다. 구독 만기 날짜가 도래하면 해당 구독은 자동으로 만료 처리가 됩니다. ### ✔️ 후불 결제 해당 위젯을 추가하면 상품에 대한 결제를 후불로 지급할 수 있으며, 결제 시점은 다음 결제 예정일입니다. 후불 결제 위젯을 사용하는 구독을 취소하는 경우에는 후불 결제가 한 번 일어난 뒤 구독이 취소됩니다. ### ✔️ 사용량 기반 사용량 기반 요금제는 사용량에 따른 과금을 기반으로 합니다. Saas 서비스나 클라우드 스토리지와 같이 사용량이 늘어날수록 요금이 증가하는 서비스에 이 플랜이 사용됩니다. ### ✔️ 계정수 기반 계정수 기반 요금제는 건당 과금을 기반으로 합니다. 이 플랜은 특정 작업이나 API 호출 등 각 단위 액션에 대한 요금을 정의하는데 사용됩니다. 베이스 가격이 존재하므로, 단위 수에 따라 총 요금이 계산됩니다. ## 스텝페이 포탈 사용 예시 * \[포탈] → \[상품관리] → \[새상품 등록] 메뉴로 이동합니다. * 상품의 기본 정보를 입력하고 다음으로 이동합니다. * 플랜 정보와 가격 설정, 플랜 위젯을 입력하고 저장합니다. ![create\_product.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=04_price_plan\&name=create_plan.png) ## 스텝페이 API 사용 예시 ### 가격 플랜 생성 * Request ```bash theme={null} curl --request POST \ --url https://api.steppay.kr/api/v1/products/{product_id}/prices \ --header 'Secret-Token: {Secret-Token}' \ --header 'accept: */*' \ --header 'content-type: application/json' \ --data ' { "plan": { "name": "ONE_TIME-PRICE_PLAN", "description": "" }, "type": "ONE_TIME", "price": 0, "unit": "case", "basicServing": 1000 } ' ``` * Response ```json theme={null} { "id": 10064, "code": "price_oTuP3PA9O", "price": 0, "unit": "case", "planName": "ONE_TIME-PRICE_PLAN", "planDescription": "", "type": "ONE_TIME", "enabledFirstSalePrice": false, "firstSalePrice": 0, "claimMethodType": "PRE", "whenToClaimType": "FIRST_PAYMENT", "billingDate": 1, "maximumPurchaseQuantity": 0, "membershipExpirationDate": 0, "membershipExpirationDateType": null, "setupOption": null, "options": [], "volumes": [], "additionalBilling": null, "recurring": null, "createdAt": "2023-06-19T01:45:42.470396", "modifiedAt": "2023-06-19T01:45:42.470396", "plan": { "name": "ONE_TIME-PRICE_PLAN", "description": "", "detailDescription": null, "isHiddenFromShop": false, "adminName": null }, "firstSale": { "enabled": false, "price": 0 }, "claim": { "methodType": "PRE", "whenToClaimType": "FIRST_PAYMENT", "billingDate": 1, "provideStartDay": null }, "basicServing": 0, "bundlePrices": [], "onetimeBundlePrice": 0, "order": 0 } ``` # 사용량 기반 요금제 가이드 Source: https://docs.steppay.kr/docs/04-1_사용량 사용량/계정수 기반 요금제는 사용자가 실제로 사용한 양에 따라 요금이 부과되는 가격 플랜입니다. API 호출 횟수, 스토리지 사용량, 등록된 계정수 등에 따라 결제 금액이 산정되는 요금제를 만들때 유용합니다. 사용량/계정수 기반 요금제는 사용자가 실제로 사용한 양에 따라 요금이 부과되는 가격 플랜입니다. API 호출 횟수, 스토리지 사용량, 등록된 계정수 등에 따라 결제 금액이 산정되는 요금제를 만들때 유용합니다. 고객의 사용 기록은 연동 개발, 혹은 스텝페이 관리자 페이지(포탈)을 통해 미터링 되며 플랜 옵션에 따라 정기적으로 갱신 결제됩니다. 최대 사용량을 제한함으로써 고객이 일정 유닛 이상 기능을 사용하지 못하게 제한할 수도 있으며 현재 사용량을 조회하여 고객에게 안내할 수도 있습니다. 스텝페이에서는 다양한 요금제 지원을 위해 사용량/계정수 템플릿을 여러 옵션의 조합으로 구성할 수 있습니다. 만드려는 요금제에 따라 사용량/계정수, 선불/후불, 구간별 건당과금/고정요금 등을 자유롭게 선택, 조합하여 유연한 요금 플랜을 설계할 수 있습니다. ## 연관된 가이드 * [인증 가이드](/docs/01_인증) * [상품 가이드](/docs/03_상품) * [가격 플랜 가이드](/docs/04-0_가격플랜) * [구독 가이드](/docs/06_구독) ## 사전 준비 작업 * [Secret-Token 확인하기](/docs/01_인증#1-secret-token) > 현재 V1 API를 통해 사용량 템플릿을 생성할 수 없기 때문에 사용량 가격 플랜은 포탈에서 생성해야 합니다. ## 레코드와 쿼타 **사용량 기록은 고객이 얼마의 유닛을 사용 했는지를 나타내는 ‘레코드’와 고객에게 할당된 최대 사용 유닛을 뜻하는 ‘쿼타’로 이루어져 있습니다.** 레코드와 쿼타는 등록 시간과 증감 유닛수를 가지고 있는 시계열(Time series) 자료형입니다. 레코드와 쿼타의 변화량을 사용량 기록 API 를 통해 등록하면 스텝페이에서는 각 값의 시간에 따른 누적 합(accumulated sum)을 관리하며 요금 산정 및 사용량 제한에 사용됩니다. 아래 표는 쿼타-레코드 기록의 예시입니다. | 시간 | 쿼타 | 쿼타 누적 합 | 레코드 | 레코드 누적 합 | | -- | -- | ------- | --- | -------- | | t0 | +5 | 5 | 0 | 0 | | t1 | 0 | 5 | +2 | 2 | | t3 | -2 | 3 | +1 | 3 | | … | … | … | … | … | * 레코드 누적 합은 쿼타 누적 합보다 항상 작거나 같아야합니다. * 모든 쿼타를 다 채웠다면 추가 레코드를 기록하기 위해서는 반드시 쿼타를 증가시켜야 합니다. * 쿼타는 선불 청구 방식에서는 필수값이지만 후불 청구 방식에서는 연동 시스템에 따라 사용하거나 기록하지 않을 수 있습니다. * 반대로 후불 청구방식에서 레코드는 필수 요소이지만 쿼타는 선택적으로 사용 가능합니다. * 쿼타를 지정하지 않은 후불 청구 방식의 경우 쿼타는 무한대로 간주됩니다. ## 사용량 사용량 기반 과금 플랜과 계정수 기반 과금 플랜은 모두 레코드와 쿼타에 기반해 결제해야 할 금액을 산정한다는 점에서 공통점이 있지만 그 동작 방식에서 몇가지 차이점이 있습니다. 사용량 기반 과금 플랜은 API 호출 횟수, 네트워크 트래픽과 같은 측정할 수 있는 양에 따라 결제 금액을 산정하는 과금 모델입니다. **사용량 기반 과금 플랜에서는 기록한 레코드 혹은 쿼타의 누적 합(cumulative sum)이 곧 사용량 유닛이 됩니다.** 사용 유닛 구간에 따른 단위 사용량 당 금액에 기반하여 결제 금액이 산정됩니다. 사용량 과금은 기본적으로 구간을 나누어 특정 구간에 과금 템플릿을 적용하게 됩니다. 이 템플릿을 사용량 테이블이라고도 합니다. 스텝페이에서 지원하는 사용량 템플릿은 크게 두 가지가 있습니다. 1. 구간별 고정 요금 템플릿 2. 구간별 건당 과금 템플릿 고정 요금 템플릿은 사용량 구간에 대해 고정된 요금을 과금합니다. 건당 과금 템플릿은 사용량 구간에 대해 건당 요금을 과금합니다. 사용량 기반 과금의 결제는 정해진 구독 주기 동안 사용량이 합산되어 결제됩니다. 사용량 기반 과금 플랜의 레코드 누적 합은 시간에 따라 지속되는 양이 아니므로, 구독 갱신시 초기화 되며 다음 주기의 쿼타-레코드 기록에 따라 금액이 다시 산정됩니다. ## 사용량 과금 템플릿 ### 구간별 고정 요금 템플릿 구간별 고정 요금 템플릿이란, 사용 유닛에 대해 정해진 구간 별로 고정 금액을 청구하는 방식입니다. 이 요금제는 정해진 사용 유닛 구간에 해당하는 고정 요금을 지불하게 됩니다. 특정 구간을 넘어서면 다음 구간의 요금과 합산되어 누적된 금액이 결제됩니다. ![range\_template.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=04_price_plan\&name=04-1_usage/range_template.png) 예를 들어, API 호출 구간에 대해 고정 사용량 요금제를 아래와 같이 만들 수 있습니다. ![range\_template\_example.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=04_price_plan\&name=04-1_usage/range_template_example.png) * `1,000유닛`을 사용한 경우, 0원이 결제됩니다. * `1,500유닛`을 사용한 경우, 20,000원이 결제됩니다. * `12,000유닛`을 사용한 경우, 40,000원이 결제됩니다. * `150,000유닛`을 사용한 경우, 80,000원이 결제됩니다. ### 구간별 건당 과금 템플릿 구간별 건당 과금 템플릿이란, 사용 유닛의 구간에 대해 건당 금액을 청구하는 방식입니다. 이 요금제는 정해진 구간에 대해 건당 요금을 부과하게 됩니다. 전체 사용 건수가 특정 구간을 넘어서면 다음 구간의 요금으로 건당 요금이 부과됩니다. ![range\_template\_example.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=04_price_plan\&name=04-1_usage/count_template.png) 예를 들어, API 사용량을 건당 사용량 요금제로 만들면 아래와 같이 만들 수 있습니다. ![range\_template\_example.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=04_price_plan\&name=04-1_usage/count_template_example.png) * `1,000유닛`을 사용한 경우, 총 0원이 결제됩니다. * `1,500유닛`을 사용한 경우, (0원 \_ 1,000건) + (10원 \_ 500건)을 합산하여 총 5,000원이 결제 됩니다. * `12,000유닛`을 사용한 경우, (0원 \_ 1,000건) + (10원 \_ 9,000건) + (5원 \* 2,000건)을 합산하여 총 100,000원이 결제됩니다. * `150,000유닛`을 사용한 경우, (0원 \_ 1,000건 + 10원 \_ 9,000건 + 5원 \_ 40,000건 + 2원 \_ 50,000건 + 1원 \* 50,000건)을 합산하여 총 440,000원이 결제됩니다. ## 사용량/계정수 API | 기능 | Method | Endpoint | | --------- | ------ | ---------------------------- | | 사용량/계정 기록 | POST | /v1/usages | | 사용량 정산 | GET | /v1/subscriptions//calculate | ### 사용량/계정수 - 사용량 기록 사용자가 서비스를 구독하고 주문을 완료하면, 해당 주문의 정보를 통해 시작된 구독의 ID와 구독 항목 ID를 받을 수 있습니다. 이 ID 정보를 사용하여 '사용량/계정 기록 API'를 호출하면, 시스템은 전송한 계정 수 만큼의 사용량을 기록합니다. ### 사용량/계정수 - 정산 '사용량 정산 API'를 호출하면 현재까지의 사용량과 그에 따른 예상 결제 금액을 확인할 수 있습니다. ### 첫 결제 할인 사용량 템플릿에 ‘첫 결제 할인’ 플랜 위젯을 적용하는 경우, 플랜의 기본 금액에 대해 할인된 가격으로 결제됩니다. 현재 사용량 합계에 대한 할인은 제공되지 않습니다. ### 사용량/계정수 구독 취소 사용량 구독을 취소하는 경우 플랜의 기본 금액에 대해 환불되며, 이미 사용한 계정수에 대해서는 따로 환불 처리를 하지 않으면 후불 결제됩니다. 사용량 환불을 원하는 경우에는 취소된 구독의 ‘관련 주문 탭’에서 사용량 주문을 환불 처리해야 합니다. ### 계정수 사용량 알림 #### ✔️ 결제 예정 알림 정해진 구독 주기 동안의 사용량이 합산되어 결제되는 ‘사용량 기반 상품'의 경우, 결제 예정일 7일 전에 안내 메일이 발송됩니다. 고객은 계정 수가 얼마나 되고, 어떤 과금에 의하여 결제 금액이 과금되는지 상세 내역을 확인할 수 있습니다. #### ✔️ 주문 완료 알림 결제 완료시 주문 완료 메일이 발송됩니다. 고객은 사용량이 얼마나 되고, 어떤 과금에 의하여 결제 금액이 과금되는지 상세 내역을 확인할 수 있습니다. # 계정수 기반 요금제 가이드 Source: https://docs.steppay.kr/docs/04-2_계정수 사용량/계정수 기반 요금제는 사용자가 실제로 사용한 양에 따라 요금이 부과되는 가격 플랜입니다. API 호출 횟수, 스토리지 사용량, 등록된 계정수 등에 따라 결제 금액이 산정되는 요금제를 만들때 유용합니다. 사용량/계정수 기반 요금제는 사용자가 실제로 사용한 양에 따라 요금이 부과되는 가격 플랜입니다. API 호출 횟수, 스토리지 사용량, 등록된 계정수 등에 따라 결제 금액이 산정되는 요금제를 만들때 유용합니다. 고객의 사용 기록은 연동 개발, 혹은 스텝페이 관리자 페이지(포탈)을 통해 미터링 되며 플랜 옵션에 따라 정기적으로 갱신 결제됩니다. 최대 사용량을 제한함으로써 고객이 일정 유닛 이상 기능을 사용하지 못하게 제한할 수도 있으며 현재 사용량을 조회하여 고객에게 안내할 수도 있습니다. 스텝페이에서는 다양한 요금제 지원을 위해 사용량/계정수 템플릿을 여러 옵션의 조합으로 구성할 수 있습니다. 만드려는 요금제에 따라 사용량/계정수, 선불/후불, 구간별 건당과금/고정요금 등을 자유롭게 선택, 조합하여 유연한 요금 플랜을 설계할 수 있습니다. ## 연관된 가이드 * [인증 가이드](/docs/01_인증) * [상품 가이드](/docs/03_상품) * [가격 플랜 가이드](/docs/04-0_가격플랜) * [구독 가이드](/docs/06_구독) ## 사전 준비 작업 * [Secret-Token 확인하기](/docs/01_인증#1-secret-token) > 현재 V1 API를 통해 사용량 템플릿을 생성할 수 없기 때문에 사용량 가격 플랜은 포탈에서 생성해야 합니다. ## 레코드와 쿼타 **사용량 기록은 고객이 얼마의 유닛을 사용 했는지를 나타내는 ‘레코드’와 고객에게 할당된 최대 사용 유닛을 뜻하는 ‘쿼타’로 이루어져 있습니다.** 레코드와 쿼타는 등록 시간과 증감 유닛수를 가지고 있는 시계열(Time series) 자료형입니다. 레코드와 쿼타의 변화량을 사용량 기록 API 를 통해 등록하면 스텝페이에서는 각 값의 시간에 따른 누적 합(accumulated sum)을 관리하며 요금 산정 및 사용량 제한에 사용됩니다. 아래 표는 쿼타-레코드 기록의 예시입니다. | 시간 | 쿼타 | 쿼타 누적 합 | 레코드 | 레코드 누적 합 | | -- | -- | ------- | --- | -------- | | t0 | +5 | 5 | 0 | 0 | | t1 | 0 | 5 | +2 | 2 | | t3 | -2 | 3 | +1 | 3 | | … | … | … | … | … | * 레코드 누적 합은 쿼타 누적 합보다 항상 작거나 같아야합니다. * 모든 쿼타를 다 채웠다면 추가 레코드를 기록하기 위해서는 반드시 쿼타를 증가시켜야 합니다. * 쿼타는 선불 청구 방식에서는 필수값이지만 후불 청구 방식에서는 연동 시스템에 따라 사용하거나 기록하지 않을 수 있습니다. * 반대로 후불 청구방식에서 레코드는 필수 요소이지만 쿼타는 선택적으로 사용 가능합니다. * 쿼타를 지정하지 않은 후불 청구 방식의 경우 쿼타는 무한대로 간주됩니다. ## 계정수 사용량 기반 과금 플랜과 계정수 기반 과금 플랜은 모두 레코드와 쿼타에 기반해 결제해야 할 금액을 산정한다는 점에서 공통점이 있지만 그 동작 방식에서 몇가지 차이점이 있습니다. * 계정수 기반 과금 플랜은 스토리지 사용량, 등록된 계정수와 같이 한번 기록한 양이 삭제되기 전까지 지속되는 형태의 값에 따른 과금 모델을 만들 때 사용합니다. * 계정수 기반 과금 플랜에서는 기록한 레코드 혹은 쿼타의 시간에 따른 증/감을 통해 구축된 그래프의 면적이 사용 유닛이 됩니다. * 1 유닛이란 1 계정수를 한 주기의 전체 기간 동안 사용했을 때의 사용량입니다. * 구독 주기의 중간에 쿼타-레코드의 증감이 있다면 그로 인해 생기는 직사각형의 가로 길이는 아래의 계산으로 산정됩니다.\ `(주기 종료까지 남은 기간) / (전체 주기)` * 계정수 기반 과금 플랜의 레코드 누적 합은 시간에 따라 지속되는 양이므로 구독 갱신시에도 초기화되지 않습니다. * 다음 주기의 레코드는 마지막으로 기록된 누적 합 부터 시작합니다. ![unit\_price.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=04_price_plan\&name=04-2_unit/unit_price.png) ## 청구 방식 (선불/후불 플랜) 사용량 기반 과금 플랜과 계정수 기반 과금 플랜 모두 선불 혹은 후불 청구 옵션을 사용할 수 있습니다. 하지만 청구 옵션에 따라 결제 금액을 산정하는 방식에 차이점이 있습니다. ### 선불 플랜 ![unit\_pre\_price.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=04_price_plan\&name=04-2_unit/unit_pre_price.png) 사용량/계정수 기반 선불 과금 플랜은 구독 주기 시작 시점에서 고객이 사용할 유닛을 미리 정하고 해당 금액에 대해 선 과금하는 방식입니다. 즉, 선불 청구 방식에서는 쿼타-레코드 페어에서 쿼타 기반으로 과금되며, 레코드는 미터링을 위해 선택적으로 사용할 수 있습니다.\ 선불 플랜에서 쿼타를 추가하면 남은 구독 기간에 따라 추가된 양에 대한 결제 금액이 등록된 결제수단으로 즉시 결제됩니다. 쿼타를 감소하는 경우에는 구독 메모란에 환불 예정 금액이 표시되며, 감소분에 대해 환불이 필요한 경우에 사용할 수 있습니다. ### 후불 플랜 ![unit\_post\_price.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=04_price_plan\&name=04-2_unit/unit_post_price.png) 사용량/게정수 기반 후불 과금 플랜은 구독의 주기동안 고객의 사용량을 취합하여 주기 종료 시점에 후 청구하는 방식입니다. 따라서 후불 청구 방식에서는 레코드 기반으로 과금되며 쿼타는 미터링을 위해 선택적으로 사용됩니다. ## 사용량/계정수 API | 기능 | Method | Endpoint | | --------- | ------ | ---------------------------- | | 사용량/계정 기록 | POST | /api/v1/usages | | 사용량 정산 | GET | /v1/subscriptions//calculate | ### 사용량/계정수 - 사용량 기록 사용자가 서비스를 구독하고 주문을 완료하면, 해당 주문의 정보를 통해 시작된 구독의 ID와 구독 항목 ID를 받을 수 있습니다. 이 ID 정보를 사용하여 '사용량/계정 기록 API'를 호출하면, 시스템은 전송한 계정 수 만큼의 사용량을 기록합니다. ### 사용량/계정수 - 정산 '사용량 정산 API'를 호출하면 현재까지의 사용량과 그에 따른 예상 결제 금액을 확인할 수 있습니다. ### 사용량/계정수 구독 취소 사용량 구독을 취소하는 경우 플랜의 기본 금액에 대해 환불되며, 이미 사용한 계정수에 대해서는 따로 환불 처리를 하지 않으면 후불 결제됩니다. 사용량 환불을 원하는 경우에는 취소된 구독의 ‘관련 주문 탭’에서 사용량 주문을 환불 처리해야 합니다. ### 계정수 사용량 알림 #### ✔️ 결제 예정 알림 정해진 구독 주기 동안의 계졍 수가 일할 합산되어 결제되는 ‘계정수 기반 상품'의 경우, 결제 예정일 7일 전에 안내 메일이 발송됩니다. 고객은 계정 수가 얼마나 되고, 어떤 과금에 의하여 결제 금액이 과금되는지 상세 내역을 확인할 수 있습니다. #### ✔️ 주문 완료 알림 결제 완료시 주문 완료 메일이 발송됩니다. 고객은 사용량이 얼마나 되고, 어떤 과금에 의하여 결제 금액이 과금되는지 상세 내역을 확인할 수 있습니다. # 주문 가이드 Source: https://docs.steppay.kr/docs/05_주문 스텝페이에서 주문과 주문 아이템의 관계, 주문 생성 방법, 주문 타입 및 상태에 대한 상세 가이드 스텝페이에서 주문은 주문 아이템은 1 : N 의 관계를 가집니다. 예를 들면, 배송비가 있는 실물 상품의 첫 결제 할인, 도입비가 있는 가격 플랜을 주문한 경우에는 아래와 같이 주문 아이템이 생성됩니다. 주문이 생성되면 해당 주문을 결제할 수 있는 페이지의 링크가 생성됩니다. 즉, 사용자에게 결제를 받으려면 주문이 생성되어야 합니다. ## 연관 가이드 * [상품 가이드](/docs/03_상품) * [가격 플랜 가이드](/docs/04-0_가격플랜) ## 사전 준비 작업 * [Secret-Token 확인하기](/docs/01_인증#1-secret-token) * 스텝페이 포탈 또는 API를 통해 상품이 생성되어 있어야 합니다. * 스텝페이 포탈 또는 API를 통해 가격 플랜이 생성되어 있어야 합니다. ## Order ### 주문 타입 | 타입 | 정의 | 설명 | | ------------------- | ----------------- | ------------------------------------------------------- | | `ONE_TIME` | 단건 주문 | 한 번만 청구되며, 반복적인 청구나 갱신이 발생하지 않습니다. | | `RECURRING_INITIAL` | 갱신 주문(최초 주문) | 반복 청구되는 주문의 첫 번째 주문을 의미합니다. | | `RECURRING` | 갱신 주문 | RECURRING\_INITIAL 주문 다음에 나오며, 주기적으로 청구되는 주문을 의미합니다. | | `PAYMENT_METHOD` | 결제수단 변경 주문 | 고객이 결제 수단을 바꾸는 경우에 이 타입의 주문이 생성됩니다. | | `ADD_USAGE` | 사용량/계정수 과금을 위한 주문 | 사용량이나 계정 수에 따라 과금되는 시스템에서 선불 사용량을 늘릴 때 이 타입의 주문이 사용됩니다. | ### 주문 아이템 타입 | 타입 | 정의 | 생성 주체 | | ---------- | -------- | ---------------- | | `SKU ` | 재고 관리 상품 | 재고 관리를 위한 상품 아이템 | | `TAX ` | 부가세 | 청구서, 마이스토어, API | | `FEE ` | 기타 비용 | 구독 갱신, API | | `SHIPPING` | 배송비 | 마이스토어, API | | `DISCOUNT` | 할인 | API | * `SKU`: SKU는 Stock Keeping Unit의 약자로, 상품의 최소 단위를 나타냅니다. 주문이 최초로 생성될 때 주문 아이템의 타입은 SKU로 설정됩니다. * `TAX`: 이 타입은 상품에 적용되는 세금(부가세 등)을 나타냅니다. 상품에 세금이 별도로 적용되는 경우, 주문 아이템에 TAX 타입이 추가됩니다. * `FEE`: 이 타입은 기타 요금을 나타냅니다. 이는 상품 구매 외에 발생하는 추가 비용을 포함하며, 예를 들어 도입비나 기본료 등이 여기에 해당합니다. * `SHIPPING`: 이 타입은 배송비를 나타냅니다. 주문 상품에 배송비가 부과되는 경우, 주문 아이템에 SHIPPING 타입이 추가됩니다. * `DISCOUNT`: 이 타입은 주문에 적용되는 할인을 나타냅니다. 상품이나 주문 전체에 할인이 적용되는 경우(청구 할인, 첫 결제 할인 등), 주문 아이템에 DISCOUNT 타입이 추가됩니다. ### 주문 아이템 상태 프로세스 ![order\_item\_flow.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=05_order\&name=order_item_flow.png) ### 주문 아이템의 상태 | 상태 | 정의 | | ------------------------------------- | --------------------- | | `CREATED ` | 결제 대기중 (생성됨) | | `DEPOSIT_WAITING ` | 입금 대기 | | `CANCELLED ` | 취소 완료 | | `PAID ` | 결제 완료 | | `CANCELLATION_REQUEST ` | 취소 요청 | | `CANCELLATION_REQUEST_DENIED ` | 취소 요청 거부 | | `CANCELLATION_REFUNDING ` | 환불 진행 중 | | `CANCELLATION_REFUNDED ` | 전액 환불 | | `CANCELLATION_REFUNDED_PARTIALLY ` | 부분 환불 | | `ORDER_DELIVERY_PREPARING ` | 배송 준비 중 | | `ORDER_DELIVERY_SUSPENDED ` | 배송 준비 중 중지하고 취소로 갈 경우 | | `ORDER_DELIVERY_ON_THE_WAY ` | 배송 중 | | `ORDER_DELIVERY_COMPLETED ` | 배송 완료 | | `EXCHANGE_REQUEST ` | 교환 요청 | | `EXCHANGE_REQUEST_REJECTED ` | 교환 요청 거부 | | `EXCHANGE_COLLECTION_PREPARING ` | 교환 수거 준비중 | | `EXCHANGE_COLLECTION_ON_THE_WAY ` | 교환 수거중 | | `EXCHANGE_COLLECTION_COMPLETED ` | 교환 수거 완료 | | `EXCHANGE_DELIVERY_PREPARING ` | 교환 배송 준비중 | | `EXCHANGE_DELIVERY_ON_THE_WAY ` | 교환 배송 진행중 | | `EXCHANGE_DELIVERY_COMPLETED ` | 교환 배송 완료 | | `EXCHANGE_REJECT_DELIVERY_PREPARING ` | 교환 거부 제품 재배송 준비중 | | `EXCHANGE_REJECT_DELIVERY_ON_THE_WAY` | 교환 거부 제품 재배송 진행중 | | `EXCHANGE_REJECT_DELIVERY_COMPLETED ` | 교환 거부 제품 재배송 완료 | | `EXCHANGE_REJECTED ` | 교환 거부 | | `RETURN_REQUEST ` | 반품 요청 | | `RETURN_REQUEST_REJECTED ` | 반품 요청 거부 | | `RETURN_COLLECTION_PREPARING ` | 반품 수거 준비중 | | `RETURN_COLLECTION_ON_THE_WAY ` | 반품 수거중 | | `RETURN_COLLECTION_COMPLETED ` | 반품 수거 완료 | | `RETURN_REJECT_DELIVERY_PREPARING ` | 반품 거부 제품 배송 준비중 | | `RETURN_REJECT_DELIVERY_ON_THE_WAY ` | 반품 거부 제품 배송 진행중 | | `RETURN_REJECT_DELIVERY_COMPLETED ` | 반품 거부 제품 배송 완료 | | `RETURN_REJECTED ` | 반품 거부 | | `PAYMENT_FAILURE ` | 결제 실패 | ## 주문 생성 ### 주문 타입의 생성 주체 주문은 주문 타입에 따라 생성되는 경로가 다릅니다. 타입은 아래와 같이 5가지가 있습니다. | 타입 | 정의 | 생성 주체 | | ------------------ | -------- | --------------- | | ONE\_TIME | 단건 요금제 | 청구서, 마이스토어, API | | RECURRING\_INITIAL | 구독 첫 결제 | 청구서, 마이스토어, API | | RECURRING | 구독 갱신 결제 | 구독 갱신, API | | PAYMENT\_METHOD | 결제 수단 변경 | 마이스토어, API | | ADD\_USAGE | 사용량 추가 | API | ### 1. 청구서를 통한 생성 #### `STEP 1` 사업자 정보 등록 * 이메일을 통한 청구서 발송은 사업자 정보가 입력되어 있어야 합니다. * 사업자 정보는 \[포탈 → 설정 → 사업자 정보] 메뉴에서 설정할 수 있습니다. ![setting\_business\_info.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=05_order\&name=setting_business_info.png) #### `STEP 2` 청구서 작성 * 스텝페이 포탈에서 \[청구서 관리 → 새 청구서 작성] 메뉴에서 고객, 상품/플랜, 설정(발송일, 결제 기한, 발송 수단) 정보를 선택한 후 발송 버튼을 클릭하면 청구서가 발송됨과 동시에 주문이 생성됩니다. ![create\_invoice.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=05_order\&name=create_invoice.png) #### `STEP 3` 주문 내역 확인 * \[포탈 → 전체 주문 내역] 메뉴에서 생성된 주문을 확인할 수 있습니다. ![invoice\_list.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=05_order\&name=invoice_list.png) ### 2. 마이스토어를 통한 생성 #### `STEP 1` 바로 구매하기 * 상품에서 '바로 구매' 버튼을 클릭하여 결제 화면으로 이동하면 주문이 생성됩니다. ![mystore\_product.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=05_order\&name=mystore_product.png) #### `STEP 2` 장바구니에서 구매하기 * 상품을 장바구니에 담고 '결제 진행' 버튼을 클릭하여 결제 화면으로 이동하면 주문이 생성됩니다. ![mystore\_cart.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=05_order\&name=mystore_cart.png) #### `STEP 3` 주문 내역 확인 * \[포탈 → 전체 주문 내역] 메뉴에서 생성된 주문을 확인할 수 있습니다. ### 3. API 를 통한 생성 > 주문을 생성할 때, 주문이 정확하게 연결되고 처리되도록 하기 위해 고객 정보는 필수값 입니다. > > * `customerId`: 이는 고객의 고유 숫자 식별자입니다. > * `customerCode`: 이는 고객에게 할당한 고유한 영숫자 코드입니다. > * `customerUuid`: 이는 고객의 고유 식별자(UUID)입니다.\ > 주의할 점은 이들 필드 중 적어도 하나는 주문 생성 요청에 포함되어야 합니다. 식별자들은 고객별로 주문을 정확하게 추적하고 관리하는 데 도움이 됩니다.\ > 이러한 필드가 제공되지 않거나 잘못된 경우, 주문 생성 과정이 실패하거나 오류를 일으킬 수 있습니다. * Request ```bash theme={null} curl --request POST \ --url https://api.steppay.kr/api/v1/orders \ --header 'Secret-Token: {Secret-Token}' \ --header 'accept: */*' \ --header 'content-type: application/json' \ --data ' { "items": [ { "currency": "KRW", "minimumQuantity": 0, "productCode": "product_VQyHoGO8c", "priceCode": "price_0V4zUJ5bv" } ], "customerId": {Customer Id} } ' ``` * Response ```json theme={null} { "orderId": 183682, "orderCode": "order_15XqwcM1f", "type": "ONE_TIME", "paidAmount": 0, "returnedAmount": 0, "leftAmount": 0, "discountedAmount": 0, "productName": "[API]TEST_PRODUCT", "items": [ { "id": 208679, "code": "order_item_ve2dE7xEm", "paidAmount": 0, "currency": "KRW", "quantity": 0, "price": { ... }, "product": { ... }, "type": "SKU", "status": "CREATED", "featuredImageUrl": "", "selectedProductOptionLabel": "", "selectedProductOptionIds": [], "createdAt": "2023-06-19T06:19:55.403711", "canceledDateTime": null, "orderItemCode": "order_item_ve2dE7xEm", "modifiedAt": "2023-06-19T06:19:55.403711", "orderedProductType": "SOFTWARE", "orderedProductName": "[API]TEST_PRODUCT", "orderedPlanName": "[API]BASIC_PLAN", "discountName": null, "relatedOrderItemId": null, "priceSetupType": null, "demoCycle": null, "usedCount": null, "deliveryCode": null, "histories": null, "unitChangeHistory": null, "unitCount": null, "minimumQuantity": 0, "parentOrderItemCode": null } ], "customer": { ... }, "paymentDate": null, "paymentDueDate": null, "purchaseDeadline": null, "shipping": null, "createdAt": "2023-06-19T06:19:55.317836", "modifiedAt": "2023-06-19T06:19:55.317836", "payment": null, "orderLogs": [], "code": "order_15XqwcM1f", "idKey": "1687155595516RTWz7FvxD98jr2ya", "subscriptions": [], "parentSubscription": null, "relatedOrders": [], "calculateStartDate": null, "calculateEndDate": null, "childOrders": [] } ``` ## 연동 가이드 주문이 생성되었다면, 해당 주문의 `order_code`를 사용하여 결제 연동을 할 수 있습니다. [결제창 연동 가이드](/docs/07-1_Managed_결제#최초-결제)를 참고하여 결제 링크 방식 또는 결제창 연동을 통해 결제를 받고 파라미터로 전달된 Url로 리다이렉트 시킬 수 있습니다. # 구독 가이드 Source: https://docs.steppay.kr/docs/06_구독 구독 생성, 생명주기, 상태 관리, 결제 수단 변경 및 연동 방법에 대한 종합 가이드 구독은 고객이 공급자의 상품, 서비스 또는 컨텐츠에 지속적으로 접근하기 위해 반복 결제에 동의하는 공급자와 소비자간의 계약입니다. 구독자가 특정 금액이 월간, 연간 등의 일정 주기로 결제하는 것에 동의하게 되면 공급자는 이후 사용자의 인터렉션 없이 등록된 결제 수단에서 결제를 발생할 수 있게 됩니다. 스텝페이는 공급자와 구독 계약을 체결하고 반복 결제를 발생하기 위해 필요한 모든 과정을 SaaS 형태로 제공하고 있습니다. ![subscription\_flow.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=06_subscription\&name=subscription_flow.png) 스텝페이에서 구독(Subscription) 이란 일정 주기로 가격이 결정된 `RECURRING` 타입의 주문(Order) 을 생성하는 엔티티입니다. 구독(Subscription)은 `RECURRING_INITIAL` 타입의 주문(Order)이 결제되면 자동으로 생성되며 이후 주기적으로 `RECURRING` 타입의 주문(Order)을 생성하기 때문에 `RECURRING_INITIAL` 타입의 주문은 구독과 일대다 관계를 가짐과 동시에, 구독은 `RECURRING` 타입의 주문과 일대다 관계를 가집니다. `RECURRING_INITIAL` 타입의 주문(Order) 을 결제할 때 고객이 사용한 결제수단이 구독(Subscription) 의 결제수단으로 등록되며, 갱신 결제에 해당 결제수단이 이용됩니다. 결제 수단 변경을 하려면 고객이 변경하고자 하는 결제수단으로 다시 결제를 진행해야 합니다. ## 연관 가이드 * [상품 가이드](/docs/03_상품) * [가격 플랜 가이드](/docs/04-0_가격플랜) * [주문 가이드](/docs/05_주문) * [웹훅 가이드](/docs/08_웹훅) ## 사전 준비 작업 * 구독 가격 플랜 담긴 주문이 생성되어 있어야 합니다. * 정기 결제 가능한 PG 가 연동되어 있어야 합니다. * [\[설정 → 결제 설정 → PG 연동관리\]](/docs/07-0_결제#사전-준비-작업) 메뉴에서 테스트 모드로 추가할 수 있습니다. * 실 결제를 위해서는 PG사와 빌링 결제 계약이 필요합니다. ## 구독의 생성 `FLAT`, `BUNDLE`, `USAGE_BASED`, `UNIT_BASED` 타입의 가격 플랜이 포함된 주문을 결제하면 구독이 자동으로 생성됩니다.\ 구독은 고객과의 계약이기 때문에 API 를 통해 생성할 수 없으며, 최초 1번 고객이 수동으로 결제하는 방법으로만 생성할 수 있습니다.\ 구독의 주기는 가격 플랜의 속성과 상품의 무료 체험과 같은 일부 속성들에 의해 결정됩니다.\ 만약 여러 개의 주문 아이템이 포함되어 있는 `RECURRING_INITIAL` 주문이 결제되면 구독 묶음을 결정하는 요소에 의해 구독이 여러개 생길 수 있습니다. 다음은 주문 아이템들이 구독 묶음으로 결정되는 속성들입니다. | **필드** | **설명** | | --------------------------- | -------------------------------------- | | **Current Period End Date** | 현재 결제 주기의 종료 날짜 (예: 첫 번째 주기 종료 날짜) | | **Interval** | 구독 주기 (예: 1개월) | | **Expiry Date** | 서비스나 구독이 만료되는 날짜 (특정 날짜에 만료되는 경우) | | **Provide Start Day** | 주기 내에서 서비스 제공이 시작되는 날 (해당하는 경우) | | **Billing Date** | 결제 주기와 관계없이 매월 특정한 결제일 (예: 매월 5일 결제) | | **Trial End** | 무료 체험 기간이 끝나는 날짜 | | **Expiry Recurring Count** | 만료되기 전까지 허용된 최대 갱신 횟수 (예: 10번 갱신 후 만료) | | **Claim Method Type** | 결제 방식 (선불 또는 후불) | ## 구독의 생명주기 구독의 생명주기는 구독의 상태가 어떻게 변하는지를 나타냅니다. 각 상태는 특정 이벤트에 의해 변경될 수 있습니다. 구독의 생명주기는 스텝페이에서 자동으로 관리되지만 연동 개발하고 있는 시스템과 통합하려면 구독의 상태 변경과 시스템 상태를 동기화 해야합니다. 예를들면, 구독이 일시정지 되었을 때 해당 고객의 SaaS 소프트웨어의 사용이 중지되어야 할 수 있습니다. 시스템과 통합하는 자세한 방법은 [연동 가이드](#연동-가이드)를 참고하세요. 다음은 구독의 상태 및 이벤트에 대한 개요입니다. ### 구독 상태 * `ACTIVE`: 구독이 활성화 상태이며, 사용자가 서비스를 이용할 수 있는 상태입니다. * `UNPAID`: 스케쥴 된 주문이 결제 실패하여 서비스 이용이 일시 중지된 상태입니다. 구독이 이 상태가 되면 [복구 프로세스](#갱신-실패에-대한-재시도-정책)가 동작하게 됩니다. * `PENDING_CANCEL`: 사용자가 구독 취소를 요청했으나, 아직 최종 취소 상태로 전환되지 않은 상태입니다. 구독 취소 API 또는 스텝페이 포탈에서 구독 취소 옵션으로 특정일 취소 또는 현제 주기 종료 후 취소 옵션을 선택하면 구독이 이 상태로 변경됩니다. * `CANCELED`: 구독이 최종적으로 취소된 상태입니다. 구독 취소 API 또는 스텝페이 포탈에서 구독 취소 옵션으로 즉시 취소 옵션을 선택하거나 취소 요청일이 되면 구독이 이 상태로 변경됩니다. 취소된 구독은 다시 복구될 수 없습니다. * `PENDING_PAUSE`: 사용자가 구독 일시정지를 요청했으나, 아직 최종 일시정지 상태로 전환되지 않은 상태입니다. 구독 일시정지 API 또는 스텝페이 포탈에서 구독 일시정지 옵션으로 특정일 일시정지 또는 현제 주기 종료 후 일시정지 옵션을 선택하면 구독이 이 상태로 변경됩니다. * `PAUSE`: 구독이 일시 중지된 상태입니다. * `EXPIRED`: [복구 프로세스](#갱신-실패에-대한-재시도-정책) 에도 구독 복구를 실패하거나 만료일을 지정한 구독의 경우 만료일이 도래하면 구독이 만료된 상태입니다. 만료된 구독은 다시 복구될 수 없습니다. > 취소 또는 만료된 구독은 다시 복구될 수 없습니다. 👉 [구독 상태 다이어그램](https://stately.ai/registry/editor/embed/a9412bc7-80ce-4239-bdad-823519d878d1?machineId=1c4af9a6-b8b2-41e9-ae0d-0e949411ddf3\&mode=Design) 을 확인해보세요. ### 주문 취소가 구독에 미치는 영향 구독을 생성한 주문 (RECURRING\_INITIAL) 이 취소되면 해당 주문에 의해 생성된 모든 구독이 취소됩니다. 하지만 구독이 취소되어도 해당 구독과 관련된 주문이 환불되는 것은 아닙니다. 구독 취소와 함께 이미 결제된 주문을 취소하기 위해서는 별도로 주문 취소 API를 사용해야 합니다. 이와 반대로 구독에 의해 생성된 주문(RECURRING) 은 환불 혹은 취소되어도 구독은 취소되지 않습니다. 주문 환불과 함께 구독 또한 취소 하려면 별도로 구독 취소 API를 사용해야 합니다. ### 선불 구독과 후불 구독 선불 구독과 후불 구독은 주기적으로 RECURRING 주문을 생성한다는 점에서는 동일하지만 동작 방식에 약간의 차이가 있습니다. 선불 구독은 만료되거나 취소될 때 추가적인 결제가 일어나지 않지만 후불 구독의 경우 마지막 RECURRING 주문을 생성한 뒤 취소 혹은 만료됩니다. 또 한가지 다른 점은 갱신 횟수를 세는 방식입니다. 구독 상세 API를 통해 알아낼 수 있는 갱신 횟수(`recurringCount`)가 구독 최초 생성 시 선불 구독의 경우 1, 후불 구독의 경우 0으로 시작됩니다. ### 갱신 실패에 대한 재시도 정책 카드 유효기간 만료, 잔액 부족 등의 사유로 갱신 결제가 실패한 경우 복구 프로세스가 시작됩니다. 구독이 결제 실패되면 구독은 그 즉시 `UNPAID` 상태가 됩니다. 기본적으로 복구 프로세스는 최초 결제 실패 일로부터 1일, 3일, 5일, 10일, 14일 후에 결제를 재시도 하는 정책으로 동작합니다. 복구 프로세스를 통해 구독이 복구되면 구독의 상태는 `ACTIVE` 상태로 돌아옵니다. 연동하는 시스템은 구독의 상태를 웹훅을 통해 관찰하고 있어야 하며 구독을 복구하기 위해 고객의 결제 수단을 변경하는 방법을 제공해야 할 수도 있습니다. ## 결제 수단 변경 구독은 내부적으로 PG에서 발급되는 빌링키를 통해 결제됩니다. 자동으로 갱신되는 결제에 대한 결제 수단을 변경하기 위해서는 새로운 빌링키 발급이 필요합니다. 스텝페이서는 PAYMENT\_METHOD 타입의 주문을 통해 빌링키 발급이 이루어집니다. 결제수단 변경 API를 이용하여 PAYMENT\_METHOD 타입의 주문을 생성할 수 있고 새로운 결제 수단을 등록하기 위해서는 고객의 결제 정보를 받아야 하므로 결제 링크를 생성하여 고객을 결제 페이지로 리다이렉션 해야합니다. 고객이 결제 정보를 입력하면 구독의 결제 수단이 업데이트 됩니다. ## 연동 가이드 스텝페이 구독의 생명주기를 연동 개발하고자 하는 시스템(이하 시스템)과 동기화 하기 위해서 시스템은 스텝페이 구독번호를 시스템의 결제 주체에 맵핑해야 합니다. 구독은 주문이 결제되었을 때 생성되므로 시스템은 먼저 주문 생성 API를 통해 얻을수 있는 주문 번호를 저장한 뒤 결제 성공 리디렉션을 처리해야 합니다. ### 결제 링크 생성 후 주문 코드 확인 스텝페이 API 로 주문을 생성하고 결제 주체(Organization)에 주문 번호를 맵핑한 뒤 결제 링크로 고객을 리디렉트합니다. 주문이 완료되면 구독이 생성됩니다. 구독 번호는 결제 성공 리디렉션에서 주문 코드를 통해 확인할 수 있습니다. ```tsx theme={null} async generateLink(name: string, plan: Plan, userId: number): Promise { const user = await this.userService.getUser(userId) // Retrieves the StepPay product/price code corresponding to the plan selected by the customer. let planItem = this.PLAN[plan] // StepPay order creation const order = await this.steppayService.createOrder( user.steppayId, planItem, // { productCode: string, priceCode: string }[] ) // Mapping of the payment entity in the system and the StepPay order number await this.organizationRepository.save({ name, plan, owner: user, steppayOrderId: order.data.orderId }) return this.steppayService.generateLink(order.data.orderId) // redirection } ``` ### 결제 완료 리디렉션 처리 ```tsx theme={null} // Payment completion redirection async processPayment(order: SteppayOrder): Promise { // Find the payment entity by the redirected order number const organization = await this.organizationRepository.findOne({ where: { steppayOrderId: order.orderId } }) if (!organization) { throw new NotFoundException() } // Map all subscription numbers created by the order organization.subscriptions = order.subscriptions.map(subscription => new SubscriptionEntity( organization, subscription.id, )) // Retrieve subscription item number and product code for usage tracking const items = order.subscriptions.flatMap(subscription => subscription.items) .map(item => ({ id: item.id, productCode: item.productCode })) // Map the detailed metering items of the payment entity and the StepPay subscription item number organization.items = new ItemEmbedable( items.find(items => items.productCode === this.PRODUCT_CODE).id ) organization.status = 'ACTIVE' await this.organizationRepository.save(organization) return organization } ``` ### 구독 웹훅 스텝페이 구독과 결제 주체의 맵핑이 완료되었으면 이제 구독 웹훅을 통해 상태를 동기화 해야 합니다. 스텝페이 구독의 상태 변경에 따른 처리는 시스템의 고객 정책에 따라 달라질 수 있습니다. 웹훅에 대한 자세한 내용은 [웹훅 가이드](/docs/08_웹훅)를 참고하세요. ```tsx theme={null} @Get() async handleSubscriptionWebhook( @Body() body: { id: number, status : string } ) { this.organizationService.updateStatus(body) } ``` # 결제 가이드 Source: https://docs.steppay.kr/docs/07-0_결제 관리형(Managed) 결제는 스텝페이의 결제화면을 사용하여 결제하는 방법입니다. 관리형 결제는 부가세 처리, 배송비 처리, 구독 생성, 결제 금액 검증, 스케쥴링 등 다양한 자동화 기능을 스텝페이에서 관리하고 제공합니다. ![managed\_payment.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=07_payment\&name=managed_payment.png) 👉 [관리형 결제 자세히보기](/docs/07-1_Managed_결제) 👉 [관리형 결제 Demo](https://api.steppay.kr/api/public/orders/test) ## 연관 가이드 * [인증 가이드](/docs/01_인증) ## 사전 준비 작업 * [Secret-Token 확인하기](/docs/01_인증#1-secret-token) * [Payment-Key 확인하기](/docs/01_인증#2-payment-key) * 스텝페이 포탈에서 PG 설정을 통해 사용하고자 하는 PG가 설정되어 있어야 합니다. ![setting\_pg.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=01_auth\&name=setting_pg.png) > 테스트 환경에서 생성된 구독들은 실 서비스 환경으로 변경하여도 실 서비스 환경으로 적용되지 않습니다. 변경 후 새롭게 생성되는 구독들만 적용됩니다. ## 지원하는 PG 및 결제수단 ### 카카오페이 (*KAKAO*) * 일반결제 (*CARD*) * 빌링결제 (*CARD\_BILL*) ### 나이스페이 (*NICE*) * 일반결제 (*CARD*) * 빌링결제 (*CARD\_BILL*) * 실시간 계좌이체 (*BANK*) * 가상계좌 (*VBANK*) * CMS 계좌이체 (*CMS\_BILL*) ### 다날 (*DANAL*) * 일반결제 (CARD) * 빌링결제 (CARD\_BILL) ### 토스 (*TOSS*) * 일반결제 (CARD) * 빌링결제 (CARD\_BILL) * 실시간 계좌이체 (*BANK*) * 가상계좌 (*VBANK*) ### KG 이니시스 (*KG*) * 일반결제 (CARD) * 빌링결제 (CARD\_BILL) * 실시간 계좌이체 (*BANK*) * 가상계좌 (*VBANK*) ### 블루월넛 (*BLUEWALNUT)* * 일반결제 (CARD) * 빌링결제 (CARD\_BILL) * 실시간 계좌이체 (*BANK*) * 가상계좌 (*VBANK*) ### 페이플 * 일반결제 (CARD) * 빌링결제 (CARD\_BILL) ### 페이플 글로벌 * 일반결제 (CARD) * 빌링결제 (CARD\_BILL) ### 헥토파이낸셜 * 일반결제 (CARD) * 빌링결제 (CARD\_BILL) * 내통장 단건결제 (CMS) * 내통장 빌링 (CMS\_BILL) # 관리형(Managed) 결제 가이드 Source: https://docs.steppay.kr/docs/07-1_Managed_결제 관리형(Managed) 결제는 결제 페이지 부터 스케쥴링, 구독, 배송 등의 서비스를 제공해주는 결제 서비스입니다. 구독에 대한 관리형 결제에서는 최초 결제 프로세스와 갱신 결제 프로세스를 구분하여 설명합니다. ## 연관 가이드 * [인증 가이드](/docs/01_인증) * [주문 가이드](/docs/05_주문) * [구독 가이드](/docs/06_구독) ## 사전 준비 작업 관리형 결제를 위해서는 다음의 과정을 거쳐 결제 URL을 생성할 수 있습니다. * [Secret-Token 확인하기](/docs/01_인증#1-secret-token) * 주문이 생성되어 있어야 합니다. * 주문 생성 API의 Response에 `orderCode`를 확인하여 `orderCode`로 결제 URL요청이 가능합니다. * 주문 생성 API의 Response에 `idKey`를 확인하여 `idKey`로 결제 조회가 가능합니다. ## 최초 결제 최초 결제는 단건 또는 구독 상품의 첫 결제를 의미합니다. 최초 결제를 위해서는 결제 링크 또는 결제창 연동이 필요하니다. ### 1) 결제 링크 > **주문 생성 후, 주문 코드로 결제 링크를 생성할 수 있습니다.** > `https://api.steppay.kr/api/public/orders/${order_code}/pay` * Request ```jsx theme={null} curl --request GET \ --url 'https://api.steppay.kr/api/v1/orders/order_1234/pay?successUrl=https%3A%2F%2Fportal.steppay.kr%2F' \ --header 'Secret-Token: {Secret-Token}' \ --header 'accept: */*' ``` **Query params** * successUrl: 결제 성공시 해당 주소로 리다이렉트 됩니다. * errorUrl: 결제 실패/에러 발생 시 해당 주소로 리다이렉트 됩니다. * cancelUrl: 결제 취소(결제창을 닫았을 경우)시 해당 주소로 리다이렉트 됩니다. * Response | 상태 | 정의 | | ---- | ----------- | |  302 | 결제링크로 리다이렉트 | |  404 | 정보를 찾지 못함 | #### 결제 링크 생성 예시 전달된 파라미터로 결제 결과가 전달될 때 주문 코드가 파라미터로 전달됩니다.\ 결제 요청 url이 다음과 같다고 가정하겠습니다. `https://api.steppay.kr/api/public/orders/order_1234/pay?successUrl=https://{your-site.com}` * 결제 성공 결과는 `https://{your-site.com}?order_code=order_1234&status=success`로 전달됩니다. * `order_code`는 주문 코드를 나타내며, `status`는 결제의 성공 여부를 나타냅니다. * `order_code`는 주문 상세 조회 API를 통해 확인할 수 있습니다. ### 2) 결제창 연동 결제창 연동은 다음과 같은 4가지 흐름으로 진행됩니다. `STEP 1` 연동하려는 페이지에서 스텝페이 결제 화면을 표시합니다. `STEP 2` 성공 또는 실패했을 시 요청한 URL로 REDIRECT되며, Query String에서 정보를 추출합니다. `STEP 3` 추출한 정보로 데이터가 올바른지 검증합니다. `STEP 4` 검증 결과에 따라 사용자에게 적절한 화면을 표시합니다. ### Step1: 결제창 스텝페이에서는 3가지 방법으로 결제 화면을 고객에게 보여줄 수 있습니다. 결제 화면을 호출하면 스텝페이 내의 시스템에서 결제 절차를 진행하게 되고, 결제 과정에서 결제가 성공하거나 실패하면 요청 파라미터의 Redicrect URL로 이동하게 됩니다. #### 1. Redirection 고객의 브라우저에서 결제화면으로 이동하게 합니다. ```jsx theme={null} let params = { successUrl: `${successUrl}`, errorUrl: `${errorUrl}`, }; let url = new URL(`https://api.steppay.kr/api/public/orders/${orderCode}/pay`); url.search = new URLSearchParams(params).toString(); // Redirection window.location.href = url; ``` #### 2. Popup (Tab) 브라우저에서 결제화면을 팝업 창에서 띄우거나 새로운 탭에서 띄웁니다. ```jsx theme={null} let params = { successUrl: `${successUrl}`, errorUrl: `${errorUrl}`, }; let url = new URL(`https://api.steppay.kr/api/public/orders/${orderCode}/pay`); url.search = new URLSearchParams(params).toString(); // 팝업 또는 새 탭 열기 window.open(url, "_blank", "noopener"); ``` #### 3. Iframe Iframe 영역을 생성하고, 브라우저에서 Iframe 태그의 src 값을 수정합니다. ```jsx theme={null} let params = { successUrl: `${successUrl}`, errorUrl: `${errorUrl}`, }; let url = new URL(`https://api.steppay.kr/api/public/orders/${orderCode}/pay`); url.search = new URLSearchParams(params).toString(); document.querySelector("#myIframe").src = url; // Modifies the value inside the iframe. // This will load the URL in the iframe ``` | property | 타입 | 설명 | | ---------- | ------ | -------------------------- | | successUrl | String | 결제 성공 시 Redirect URL | | errorUrl | String | 결제 실패 시 Redirect URL | | orderCode | String | '주문 생성 API'로 생성된 orderCode | ### Step2: 결제화면 Callback 처리 스텝페이의 결제화면에서 결제 성공 또는 실패 시 `successUrl` 또는 `errorUrl` 로 Redicrect 되며, 결제 요청 결과를 Query String으로 전달합니다. `successUrl` 또는 `errorUrl`은 아래와 같은 형식입니다. ```text theme={null} https://{partner-domain}.com/success?order_id=${order_id}&order_code=${order_code}&status=${status} ``` | property | 타입 | 설명 | | ----------- | ------ | -------------------------- | | order\_id | Int | 스텝페이 주문 ID | | order\_code | String | 스텝페이 주문 코드 | | status | String | 결제 결과 (“success”, “error”) | ### Step3: 결제 검증 화면에서 발생한 Redirection이 스텝페이의 결제화면에서 리다이렉션됐는지 확인할 수 있는 결제 검증 API를 개발합니다. 결제 응답의 Query String에 포함된 `order_code`를 사용해서 '주문 조회 API'를 호출합니다.\ '주문 조회 API'의 응답값에 `paymentDate` 프로퍼티 값이 null 이 아닌 경우 결제가 정상적으로 완료되었음을 확인할 수 있습니다. #### 검증 API 호출 예시 ```jsx theme={null}
``` # 결제 SDK 가이드 Source: https://docs.steppay.kr/docs/09-2_결제_SDK 스텝페이는 결제를 위한 Javascript SDK 를 제공하고 있습니다. 결제 영역 Iframe 처리 및 결제 결과를 쉽게 처리할 수 있습니다. ### Step1: SDK 설치 * ` ``` ### Step2: 결제 메소드 호출 requestPay 메소드를 호출합니다. ```jsx theme={null} Steppay.requestPay({ paymentKey: `${PaymentKey}`, paymentGateway: 'KAKAO', paymentMethod: 'CARD', partner: { partnerOrderId : `${Order number managed by the partner}`, partnerUserId: `${Customer number managed by the partner}` }, product : { itemName : `${Product name managed by the partner}`, amount : `${Amount to be paid}`, quantity : `${Total quantity}`, currency : 'KRW' // Fixed }, customer : { userName : `${Customer name managed by the partner}`, phone : `${Customer mobile number managed by the partner}`, email : `${Customer email managed by the partner}` }, }).cancel((d)=>{ console.log("cancel" , d) }).success((d)=>{ console.log("success" , d) }).error((d)=>{ console.log("error" , d) }) ``` | 항목 | 필수 여부 | 타입 | 설명 | | ---------------------- | ----- | ------ | ------------------------------------------------- | | paymentKey | 필수 | String | [paymentKey](/docs/01_인증) | | paymentGateway | 필수 | String | [지원하는 PG 및 결제수단 목록](/docs/07-0_결제#지원하는-pg-및-결제수단) | | paymentMethod | 필수 | String | [지원하는 PG 및 결제수단 목록](/docs/07-0_결제#지원하는-pg-및-결제수단) | | partner.partnerOrderId | 필수 | String | 가맹점에서 관리하는 주문번호 | | partner.partnerUserId | 필수 | String | 가맹점에서 관리하는 고객번호 | | product.itemName | 필수 | String | 상품 이름 | | product.amount | 필수 | Number | 결제 금액 | | product.quantity | 필수 | Number | 수량 | | customer.userName | 필수 | String | 이름 | | customer.phone | 필수 | String | 휴대폰 번호 | | customer.email | 필수 | String | 이메일 | ### Step3: 결제 결과 검증 * 결제 SDK success 콜백에 검증 API 호출합니다. ```jsx theme={null} ~.success((d)=>{ const idKey = d.idKey fetch('Payment verification API URL', { method: 'POST', headers: { "Content-Type": "application/json", }, body: JSON.stringify({ idKey: idKey, status: "success" }), }) .then(response => response.json()) .then(data => { // Show payment completed or failed payment data }) .catch((error) => { console.error('Error:', error); }); console.log("cancel" , d) }).error((d)=>{ // Display error console.log("error" , d) }) ``` #### 스텝페이로 결제 검증 (Node) ```jsx theme={null} // POST body // idkey, status const axios = require("axios"); let config = { method: "get", url: "https://api.steppay.kr/api/payment/receipt/${idKey}", headers: { "Secret-Token": "${secretToken}", }, }; axios .request(config) .then((response) => { const receiptResponse = JSON.stringify(response.data); // If status is successful if (status == "success" && receiptResponse.paymentStatus === "COMPLETE") { // Do some logic } else { // something went wrong } if (status == "error" && receiptResponse.paymentStatus === "FAILED") { // Do some logic } else { // something went wrong } }) .catch((error) => { console.log(error); }); ``` # Iframe 가이드 Source: https://docs.steppay.kr/docs/10-1_Iframe 스텝커버에서 제공하는 다양한 화면의 Iframe 호출 URL, 파라미터 및 postMessage 형식 안내 # Iframe 가이드 ## Iframe 호출 URL 및 파라미터 각각의 파라미터는 대부분 알림톡 또는 postMessage를 통해 동일한 이름으로 전달됩니다. 파라미터는 GET 방식으로 Query String 으로 전달할 수 있습니다. ### 복구 메인 화면 ``` https://cover.steppay.kr/#/?token=1234abcd ``` * `token`: 복구 토큰 (복구 정보를 가져와서 표시합니다.) ### 복구 완료 ``` https://cover.steppay.kr/#/recovery-complete/?token=1234abcd&paymentDate=2021-11-09%2020:08:00paymentInfo=A카드%20123*&useChange=true ``` * `token`: 복구 토큰 (복구 정보를 가져와서 표시합니다.) * `paymentDate`: 결제일 * `paymentInfo`: 결제 수단(카드번호 등) * `useChange`: 구독의 결제수단을 변경할 지 물어보려면 ‘true’로 설정 ### 결제일 변경 ``` https://cover.steppay.kr/#/change-date/?token=1234abcd ``` * `token`: 복구 토큰 -> 복구 정보를 가져와서 표시합니다. * `token`: 복구 토큰 (복구 정보를 가져와서 표시합니다.) ### 결제일 변경 완료 ``` https://cover.steppay.kr/#/change-date-complete/?date=2021-11-09%2020:12:00&productName=상품&price=5000 ``` * `date`: 변경한 결제일 * `productName`: 상품명 * `price`: 상품 가격 ### 나중에 알림 ``` https://cover.steppay.kr/#/delay/?token=1234abcd&useDelay=true ``` * `token`: 복구 토큰 (복구 정보를 가져와서 표시합니다.) * `useDelay`: ‘true’로 설정 ### 결제 실패 ``` https://cover.steppay.kr/#/payment-failed/?token=1234abcd&reason=한도초과 ``` * `token`: 복구 토큰 (복구 정보를 가져와서 표시합니다.) * `reason`: 실패 사유 ## Iframe postMessage 형식 `event.data.action` 으로 어떤 이벤트가 발생했는지 전달되며 나머지 파라미터도 `event.data` 에 포함됩니다. ### payment-complete 파라미터 | 항목 | 설명 | | ----------- | ------------------------- | | paymentInfo | 결제 수단 정보(카드번호 등) | | paymentDate | 결제 시점 | | token | 복구 토큰 | | idKey | 결제정보 idKey | | orderId | 가맹점 주문 ID(partnerOrderId) | ### payment-failed 파라미터 | 항목 | 설명 | | ------ | ------ | | reason | 에러 메세지 | | token | 복구 토큰 | ### change-date 파라미터 | 항목 | 설명 | | ------------ | ------------------------- | | orderId | 가맹점 주문 ID(partnerOrderId) | | selectedDate | 사용자가 선택한 결제일 | ### change-method 파라미터 | 항목 | 설명 | | ------- | ------------ | | token | 복구 토큰 | | orderId | 결제 완료된 주문 ID | ### redirect 파라미터 * 없음 # 환영합니다 Source: https://docs.steppay.kr/index 스텝페이 개발 가이드에 오신 것을 환영합니다. # 국내 최초 구독 결제 플랫폼 스텝페이입니다. ### 스텝페이는 SaaS, 구독 서비스에 로켓을 달아주는 통합 플랫폼을 꿈꿉니다. 스텝페이는 상품 관리, 구독 관리, 결제, 스토어 등 구독 비즈니스 전반을 책임지는 구독 결제 플랫폼입니다.\ 스텝페이에서 지원하는 다양한 요금제와 간편한 구독, 결제 프로세스, 웹훅 연동으로 초기 개발 비용을 줄일 수 있습니다.
## FAQ > 스텝페이 서비스에 대해 궁금한 내용을 알아보세요. * 더 자세한 내용은 [헬프 센터](https://steppay.notion.site/Share-6c3f7304f1a64a719420ea2c8eac0b76)에서 확인해주세요. ## Help > 스텝페이에 대해 더 궁금한 사항은 문의를 남겨주세요. * 개발 및 도입, 기타 문의사항은 [스텝페이 홈페이지 우측 하단 아이콘을 클릭](https://steppay.kr)하여 문의해주시거나 [contact@steppay.kr](mailto:contact@steppay.kr) 로 주시면 빠르게 답변 드리겠습니다.