---
title: "결제 예약 API"
method: POST
path: "/subscribe/payments/schedule"
tags: ["subscribe"]
---

# 결제 예약 API

`POST /subscribe/payments/schedule`

customer__uid를 이용하여 비인증 결제 요청을 예약할 수 있는 API입니다.<br>비 인증 결제(빌링키) API를 포트원이 대신 수행하는 개념)<br>
     결제 요청에 대한 결과는 notice_url에 설정한 EndPoint URL로 웹훅을 통해 수신(POST request)받을 수 있습니다.<br><br>
     <ul> <li>기존에 빌링키가 등록된 customer_uid가 존재하는 경우 해당 customer_uid와 해당되는 빌링키로 schedule정보가 예약됩니다.(카드정보 선택사항)</li>
     <li>등록된 customer_uid가 없는 경우 빌링키 신규 발급을 먼저 진행한 후 schedule정보를 예약합니다.(카드정보 필수사항)</li>
     <li>예약건 별로 고유의 merchant_uid를 전달해주셔야 합니다.</li>
     <li>schedules의 상세정보(선택정보) <b> buyer_name, buyer_email, buyer_tel, buyer_addr, buyer_postcode</b> 누락시,<br>
     <b>customer_uid</b>에 해당되는 <b>customer_name, customer_email, customer_tel, customer_addr, customer_postcode</b> 정보로 대체됩니다.(둘 다 입력시 buyer_* 정보를 우선합니다)</li>
     <li>슈퍼빌링키의 customer_uid로 요청하는 경우, 결제 시점 해당 스마트 라우팅 그룹 내 채널 비율 설정에 따라 결제를 요청합니다.
     특정 빌링키로 결제를 요청하려면 channel_key에 결제를 희망하는 빌링키의 채널 키를 입력해 주세요.</li></ul>

## Response `200`

정상적으로 예약 등록이 완료되었습니다

- ScheduleResponse — 등록된 결제예약 정보. 바로 아래 ScheduleResult structure를 확인하세요
  - `code` integer — 0이면 정상적인 조회, 0아닌 값이면 message를 확인해봐야 합니다
  - `message` string — code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다
  - `response` ScheduleResultAnnotation[]
    - `customer_uid` string — 빌링키와 매핑되며 고객사에서 채번하는 구매자의 결제 수단 식별 고유번호
    - `merchant_uid` string — 고객사 주문번호
    - `imp_uid` string — 포트원 거래고유번호<br> 예약된 결제가 실행 전 철회되거나 아직 실행 전 예약 상태에 있으면 imp_uid 는 null 입니다.
    - `pg_provider` string — PG사 구분코드<br> 슈퍼빌링키 예약결제 실행 시 라우팅된 결제를 실행한 PG사의 구분코드입니다.
    - `pg_id` string — PG사 상점아이디<br>슈퍼빌링키 예약결제 실행 시 라우팅된 결제를 실행한 PG사의 상점아이디입니다.
    - `customer_id` string — 구매자 ID
    - `schedule_at` integer — 예약결제 실행 예정 시각 UNIX timestamp in seconds
    - `executed_at` integer — 예약결제가 실행된 시각 UNIX timestamp
    - `revoked_at` integer — 예약결제 실행을 철회한 시각 UNIX timestamp
    - `amount` number — 결제금액
    - `currency` string — 통화 e.g.) KRW, USD, VND, ... Default: KRW
    - `name` string — 제품명
    - `buyer_name` string — 주문자명
    - `buyer_email` string — 주문자 Email주소
    - `buyer_tel` string — 주문자 전화번호
    - `buyer_addr` string — 주문자 주소
    - `buyer_postcode` string — 주문자 우편번호
    - `custom_data` string — 예약된 결제가 수행될 때 결제정보와 함께 저장할 추가정보
    - `schedule_status` string — 예약상태 <ul><li>scheduled:예약됨(실행되기 전) </li><li>executed:예약된 결제실행완료 </li><li>revoked:예약철회</li></ul>
    - `payment_status` string — 실행된 결제의 승인 상태 <ul><li> null:아직 예약결제가 실행되지 않음(null 이라는 값의 문자열이 아닌 실제 null 입니다) </li><li> paid:예약결제가 결제승인됨 </li><li>failed:예약결제가 승인실패됨 </li><li> cancelled:예약결제가 결제승인 후 환불됨</li></ul>
    - `fail_reason` string — 실행된 결제가 승인 실패인 경우, 실패사유
    - `promotion_id` string — `promotion-id-`로 시작하며, 프로모션 아이디에 설정된 할인 내용을 적용하여 결제합니다. 비인증 결제 경우 빌링키 발급시 저장된 마스킹된 카드번호를 통해 프로모션 적용 여부가 결정됩니다.

## Other responses

- `401` — 인증 Token이 전달되지 않았거나 유효하지 않은 경우

---

[API](https://skmtc.net/iamport/apis/rest-api.md) · [All operations](https://skmtc.net/iamport/apis/rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/iamport/rest-api/versions/006dfffdec43/schema)