주문 가이드

스텝페이에서 주문은 주문 아이템은 1 : N 의 관계를 가집니다.

예를 들면, 배송비가 있는 실물 상품의 첫 결제 할인, 도입비가 있는 가격 플랜을 주문한 경우에는 아래와 같이 주문 아이템이 생성됩니다.

주문이 생성되면 해당 주문을 결제할 수 있는 페이지의 링크가 생성됩니다. 즉, 사용자에게 결제를 받으려면 주문이 생성되어야 합니다.

연관 가이드

사전 준비 작업

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 타입이 추가됩니다.

주문 아이템 상태 프로세스

주문 아이템의 상태

상태	정의
`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` 사업자 정보 등록

이메일을 통한 청구서 발송은 사업자 정보가 입력되어 있어야 합니다.
사업자 정보는 [포탈 → 설정 → 사업자 정보] 메뉴에서 설정할 수 있습니다.

`STEP 2` 청구서 작성

스텝페이 포탈에서 [청구서 관리 → 새 청구서 작성] 메뉴에서 고객, 상품/플랜, 설정(발송일, 결제 기한, 발송 수단) 정보를 선택한 후 발송 버튼을 클릭하면 청구서가 발송됨과 동시에 주문이 생성됩니다.

`STEP 3` 주문 내역 확인

[포탈 → 전체 주문 내역] 메뉴에서 생성된 주문을 확인할 수 있습니다.

2. 마이스토어를 통한 생성

`STEP 1` 바로 구매하기

상품에서 ‘바로 구매’ 버튼을 클릭하여 결제 화면으로 이동하면 주문이 생성됩니다.

`STEP 2` 장바구니에서 구매하기

상품을 장바구니에 담고 ‘결제 진행’ 버튼을 클릭하여 결제 화면으로 이동하면 주문이 생성됩니다.

`STEP 3` 주문 내역 확인

[포탈 → 전체 주문 내역] 메뉴에서 생성된 주문을 확인할 수 있습니다.

3. API 를 통한 생성

주문을 생성할 때, 주문이 정확하게 연결되고 처리되도록 하기 위해 고객 정보는 필수값 입니다.

customerId: 이는 고객의 고유 숫자 식별자입니다.

customerCode: 이는 고객에게 할당한 고유한 영숫자 코드입니다.

customerUuid: 이는 고객의 고유 식별자(UUID)입니다.
주의할 점은 이들 필드 중 적어도 하나는 주문 생성 요청에 포함되어야 합니다. 식별자들은 고객별로 주문을 정확하게 추적하고 관리하는 데 도움이 됩니다.
이러한 필드가 제공되지 않거나 잘못된 경우, 주문 생성 과정이 실패하거나 오류를 일으킬 수 있습니다.

Request

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

{
  "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를 사용하여 결제 연동을 할 수 있습니다. 결제창 연동 가이드를 참고하여 결제 링크 방식 또는 결제창 연동을 통해 결제를 받고 파라미터로 전달된 Url로 리다이렉트 시킬 수 있습니다.

연동 개발 가이드

웹훅(Webhook)

기타

연관 가이드

사전 준비 작업