개발자센터
V1
V2
파트너 정산 릴리즈 노트 기술 블로그

정기결제 관련 API

정기결제에 관련된 API 를 확인할 수 있습니다.

⌨ 정기결제예약 다건 조회

GET https://api.portone.io/v2/schedules

정기결제예약 다건 조회

Parameters

Query

store_id
string

하위 상점 ID - 값을 넣지 않으면 Merchant 유저의 기본값으로 설정된 상점의 id가 입력됩니다.

start*
string

결제예약시각(

scheduled_at

) 범위의 시작 - 값을 넣지 않으면 파라미터 end의 90일 전으로 설정됩니다.

end*
string

결제예약시각(

scheduled_at

) 범위의 끝 - 값을 넣지 않으면 현재 시각으로 설정됩니다.

status
array

결제예약 상태 리스트

page
integer

페이지 - 0부터 시작합니다.

limit
integer

페이지 크기 (최대 1000까지 허용)

Responses

200
200 응답

current_page * integer


total_page * integer


total_count * integer


schedules * Array[Schedule]

결제예약정보

Schedule

id * string

결제예약 ID


merchant_id * string

고객사 ID


store_id * string

하위 상점 ID


billing_key * string

빌링키


payment_id * string

결제 ID


status * ScheduleStatus

예약결제 상태
SCHEDULED: 결제 예약
STARTED: 결제 실행
COMPLETED: 실행 완료
CANCELLED: 예약 취소\

"SCHEDULED", "STARTED", "COMPLETED", "CANCELLED"


scheduled_at * string

결제 예약 시각


started_at string

결제 실행 시각 (statusSTARTED로 되었을 경우 제공)


completed_at string

결제 완료 시각 (statusCOMPLETED인 경우 제공)


cancelled_at string

결제 취소 시각 (statusCANCELLED인 경우 제공)


order_name * string

주문명


is_cultural_expense * boolean

문화비 지출 여부


is_escrow * boolean

에스크로 결제 여부


products Array[Product]

상품 정보 (에스크로 결제 시 에스크로 상품 정보로 활용됨)


customer * Customer

구매자 정보


custom_data string

커스텀 데이터


total_amount * integer

결제 금액


tax_free_amount integer

면세 금액


currency * Currency

통화

"KRW", "USD", "EUR", "JPY", "CNY", "VND", "THB", "SGD", "AUD", "HKD", "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BOV", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHE", "CHF", "CHW", "CLF", "CLP", "COP", "COU", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "KES", "KGS", "KHR", "KMF", "KPW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN", "MXV", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SHP", "SLE", "SLL", "SOS", "SRD", "SSP", "STN", "SVC", "SYP", "SZL", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USN", "UYI", "UYU", "UYW", "UZS", "VED", "VES", "VUV", "WST", "XAF", "XAG", "XAU", "XBA", "XBB", "XBC", "XBD", "XCD", "XDR", "XOF", "XPD", "XPF", "XPT", "XSU", "XTS", "XUA", "XXX", "YER", "ZAR", "ZMW", "ZWL"


origin Origin

결제를 요청한 근원에 대한 정보


notice_urls * Array[string]

결제 승인/실패 시 요청을 받을 웹훅 주소입니다. 상점에 설정되어 있는 값보다 우선적으로 적용됩니다.


installment_month integer

할부개월



401
인증 실패

code * string

"UNAUTHORIZED"


params object

에러 세부사항


500
내부 서버 오류

code * string

"PORTONE_ERROR"


params object

에러 세부사항


⌨ 빌링키 정기결제예약 취소

DELETE https://api.portone.io/v2/schedules

빌링키 정기결제예약 취소

Parameters

Query

store_id
string

하위 상점 ID - 값을 넣지 않으면 Merchant 유저의 기본값으로 설정된 상점의 id가 입력됩니다.

billing_key*
string

정기결제예약 빌링키

schedule_id
array

삭제할 정기결제예약 아이디 목록, 비어있을 경우 빌링키로 예약한 모든 예약을 취소함

Responses

200
200 응답

deleted_schedule_ids * Array[string]

삭제된 정기결제예약 아이디 목록


400
400 에러 응답

code * string

"INVALID_REQUEST", "SCHEDULE_ALREADY_PROCESSED"


params object

에러 세부사항


401
인증 실패

code * string

"UNAUTHORIZED"


params object

에러 세부사항


500
내부 서버 오류

code * string

"PORTONE_ERROR"


params object

에러 세부사항


⌨ 정기결제예약 단건 조회

GET https://api.portone.io/v2/schedules/{schedule_id}

정기결제예약 단건 조회

Parameters

Path

schedule_id*
string

정기결제예약 ID

Responses

200
200 응답

schedule * Schedule

결제예약정보

Schedule

id * string

결제예약 ID


merchant_id * string

고객사 ID


store_id * string

하위 상점 ID


billing_key * string

빌링키


payment_id * string

결제 ID


status * ScheduleStatus

예약결제 상태
SCHEDULED: 결제 예약
STARTED: 결제 실행
COMPLETED: 실행 완료
CANCELLED: 예약 취소\

"SCHEDULED", "STARTED", "COMPLETED", "CANCELLED"


scheduled_at * string

결제 예약 시각


started_at string

결제 실행 시각 (statusSTARTED로 되었을 경우 제공)


completed_at string

결제 완료 시각 (statusCOMPLETED인 경우 제공)


cancelled_at string

결제 취소 시각 (statusCANCELLED인 경우 제공)


order_name * string

주문명


is_cultural_expense * boolean

문화비 지출 여부


is_escrow * boolean

에스크로 결제 여부


products Array[Product]

상품 정보 (에스크로 결제 시 에스크로 상품 정보로 활용됨)


customer * Customer

구매자 정보


custom_data string

커스텀 데이터


total_amount * integer

결제 금액


tax_free_amount integer

면세 금액


currency * Currency

통화

"KRW", "USD", "EUR", "JPY", "CNY", "VND", "THB", "SGD", "AUD", "HKD", "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BOV", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHE", "CHF", "CHW", "CLF", "CLP", "COP", "COU", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "KES", "KGS", "KHR", "KMF", "KPW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN", "MXV", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SHP", "SLE", "SLL", "SOS", "SRD", "SSP", "STN", "SVC", "SYP", "SZL", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USN", "UYI", "UYU", "UYW", "UZS", "VED", "VES", "VUV", "WST", "XAF", "XAG", "XAU", "XBA", "XBB", "XBC", "XBD", "XCD", "XDR", "XOF", "XPD", "XPF", "XPT", "XSU", "XTS", "XUA", "XXX", "YER", "ZAR", "ZMW", "ZWL"


origin Origin

결제를 요청한 근원에 대한 정보


notice_urls * Array[string]

결제 승인/실패 시 요청을 받을 웹훅 주소입니다. 상점에 설정되어 있는 값보다 우선적으로 적용됩니다.


installment_month integer

할부개월



401
인증 실패

code * string

"UNAUTHORIZED"


params object

에러 세부사항


404
리소스를 찾을 수 없음

code * string

"SCHEDULE_NOT_FOUND"


params object

에러 세부사항


500
내부 서버 오류

code * string

"PORTONE_ERROR"


params object

에러 세부사항