PortOne REST API

고객 API

구독 결제의 대상이 되는 고객과 그 결제수단에 관한 API 입니다.

구독 고객 다건 조회

get/customers

조건에 맞는 구독 고객 리스트를 조회합니다.

구독 고객 등록

post/customers

빌링키와 함께 구독 고객을 등록합니다. 이미 있는 고객이면 입력한 필드만 갱신합니다. 이미 빌링키가 있는 고객이면 새 빌링키로 교체하며, 이전 빌링키는 해지하지 않습니다.

구독 고객 조회

get/customers/{customerId}

주어진 아이디로 구독 고객을 조회합니다.

구독 고객 정보 수정

patch/customers/{customerId}

구독 고객의 정보를 수정합니다. 입력하지 않은 필드는 기존 값을 유지하며, 아이디와 빌링키는 바꿀 수 없습니다.

고객의 인보이스 다건 조회

get/customers/{customerId}/invoices

한 고객의 모든 구독 인보이스를 청구 일시 역순으로 조회합니다.

구독 고객 결제수단 해지

post/customers/{customerId}/payment-method/revoke

고객의 현재 빌링키를 해지합니다. 구독은 유지되지만 빌링키가 없는 동안에는 청구일이 와도 인보이스를 만들지 않습니다. 빌링키를 다시 등록하면 지난 회차는 청구하지 않고 다음 청구일부터 청구합니다.

고객의 구독 다건 조회

get/customers/{customerId}/subscriptions

한 고객의 구독을 생성일 역순으로 조회합니다.

타입 정의

API 요청/응답의 각 필드에서 사용되는 타입 정의들을 확인할 수 있습니다

Country: "AD" | "AE" | "AF" | ...

국가

CreateSubscriptionCustomerBody: { storeId, id, name, ... }

구독 고객 등록 입력 정보

CreateSubscriptionCustomerError: ForbiddenError | InvalidRequestError | SubscriptionAlreadyExistsError | ...

CreateSubscriptionCustomerResponse: { customer, subscription }

구독 고객 등록 성공 응답

Currency: "KRW" | "USD" | "JPY" | ...

통화

ForbiddenError: { type, message }

요청이 거절된 경우

GetSubscriptionCustomerError: ForbiddenError | InvalidRequestError | SubscriptionCustomerNotFoundError | ...

GetSubscriptionCustomerInvoicesBody: { storeId, page, from, ... }

고객의 인보이스 다건 조회 입력 정보

GetSubscriptionCustomerInvoicesError: ForbiddenError | InvalidRequestError | SubscriptionCustomerNotFoundError | ...

GetSubscriptionCustomerInvoicesResponse: { items, page }

고객의 인보이스 다건 조회 성공 응답

GetSubscriptionCustomerResponse: { customer }

구독 고객 조회 성공 응답

GetSubscriptionCustomerSubscriptionsBody: { storeId, page, status }

고객의 구독 다건 조회 입력 정보

GetSubscriptionCustomerSubscriptionsError: ForbiddenError | InvalidRequestError | SubscriptionCustomerNotFoundError | ...

GetSubscriptionCustomerSubscriptionsResponse: { items, page }

고객의 구독 다건 조회 성공 응답

GetSubscriptionCustomersBody: { storeId, page, metadata }

구독 고객 다건 조회 입력 정보

GetSubscriptionCustomersError: ForbiddenError | InvalidRequestError | UnauthorizedError

GetSubscriptionCustomersResponse: { items, page }

구독 고객 다건 조회 성공 응답

InvalidRequestError: { type, message }

요청된 입력 정보가 유효하지 않은 경우

허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.

Locale: "KO_KR" | "EN_US" | "ZH_CN" | ...

결제 언어

Map_String: { [key: string]: string }

PageInfo: { number, size, totalCount }

반환된 페이지 결과 정보

PageInput: { number, size }

다건 조회 API 에 사용되는 페이지 입력 정보

PaymentProductType: "PHYSICAL" | "DIGITAL"

상품 유형

RevokeSubscriptionCustomerPaymentMethodBody: { storeId, reason }

구독 고객 결제수단 해지 입력 정보

RevokeSubscriptionCustomerPaymentMethodError: ForbiddenError | InvalidRequestError | SubscriptionBillingKeyHasSchedulesError | ...

RevokeSubscriptionCustomerPaymentMethodResponse: { customer }

구독 고객 결제수단 해지 성공 응답

Subscription: { id, customerId, items, ... }

SubscriptionAlreadyExistsError: { type, message }

같은 아이디의 구독이 이미 존재하는 경우

SubscriptionBillingKeyAlreadyRegisteredError: { type, message, customerId }

다른 구독 고객이 이미 사용 중인 빌링키인 경우

SubscriptionBillingKeyHasSchedulesError: { type, message }

해지하려는 빌링키에 예약 결제가 걸려 있는 경우

SubscriptionBillingKeyModeMismatchError: { type, message, customerMode, ... }

구독 고객 모드와 다른 모드의 빌링키인 경우

SubscriptionBillingKeyNotFoundError: { type, message }

구독에 사용할 수 있는 빌링키가 아닌 경우

SubscriptionBillingKeyRevokeFailedError: { type, message, pgCode, ... }

빌링키 해지가 실패한 경우

SubscriptionCurrencyMismatchError: { type, message }

담긴 상품들의 통화가 다른 경우

SubscriptionCustomer: { id, name, email, ... }

구독 고객

구독 결제의 대상이 되는 고객입니다. 고객당 빌링키는 하나입니다.

SubscriptionCustomerBillingKeyMethod: "CARD" | "PAYPAL"

구독 고객 빌링키 결제수단

SubscriptionCustomerCard: { issuerName, number }

구독 고객 카드 정보

SubscriptionCustomerCreateSubscriptionInput: { id, items, discounts, ... }

함께 만들 구독 정보

SubscriptionCustomerEmailRequiredError: { type, message }

인보이스 메일을 보내려는데 구독 고객의 이메일이 없는 경우

SubscriptionCustomerHasNoBillingKeyError: { type, message }

구독 고객에게 사용 가능한 빌링키가 없는 경우

SubscriptionCustomerMode: "LIVE" | "TEST"

구독 고객 모드

SubscriptionCustomerNotFoundError: { type, message }

요청된 구독 고객이 존재하지 않는 경우

SubscriptionCustomerStatus: "ACTIVE"

구독 고객 상태

SubscriptionDiscountAlreadyAppliedError: { type, message }

같은 구독 할인이 이미 붙어 있는 경우

SubscriptionDiscountApplication: { discountId, appliesTo, duration }

구독에 붙일 할인

SubscriptionDiscountAppliesTo: SubscriptionDiscountAppliesToProducts | SubscriptionDiscountAppliesToSubscription

SubscriptionDiscountAppliesToProducts: { type, productIds }

지정한 상품 항목에만 적용

SubscriptionDiscountAppliesToSubscription: { type }

인보이스 전체에 적용

SubscriptionDiscountArchivedError: { type, message }

구독 할인이 보관된 경우

SubscriptionDiscountCurrencyMismatchError: { type, message }

구독 할인의 통화가 구독의 통화와 다른 경우

SubscriptionDiscountDuration: SubscriptionDiscountDurationCycles | SubscriptionDiscountDurationForever | SubscriptionDiscountDurationOnce

SubscriptionDiscountDurationCycles: { type, count }

지정한 회차만큼 적용

SubscriptionDiscountDurationForever: { type }

소진 없이 계속 적용

SubscriptionDiscountDurationOnce: { type }

한 회차만 적용

SubscriptionDiscountNotFoundError: { type, message }

요청된 구독 할인이 존재하지 않는 경우

SubscriptionDiscountProductsNotInSubscriptionError: { type, message, productIds }

구독 할인의 적용 대상 상품이 구독에 담겨 있지 않은 경우

SubscriptionDiscountRedeemByPassedError: { type, message }

구독 할인의 적용 마감일이 지난 경우

SubscriptionDiscountType: "PERCENT" | "AMOUNT"

구독 할인 유형

SubscriptionDiscountUsage: { discountId, appliedAt, remainingCount, ... }

구독 할인 사용 현황

구독에 붙어 있는 할인의 적용 범위·지속 방식과 남은 회차, 상태입니다. 할인 금액 조건은 할인 아이디로 조회합니다.

SubscriptionDiscountUsageStatus: "ACTIVE" | "EXHAUSTED" | "REMOVED"

구독 할인 사용 상태

SubscriptionEndReason: "CANCELED" | "ONE_TIME_EXHAUSTED" | "END_DATE_REACHED"

구독 종료 사유

SubscriptionInterval: { unit, count }

구독 주기

SubscriptionIntervalMismatchError: { type, message }

담긴 정기 상품들의 청구 주기가 서로 다르거나, 시작한 구독의 청구 주기와 다른 경우

SubscriptionIntervalUnit: "DAY" | "WEEK" | "MONTH" | ...

구독 주기 단위

SubscriptionInvoice: { id, subscriptionId, customerId, ... }

구독 인보이스

SubscriptionInvoiceDiscountLine: { discountId, name, type, ... }

구독 인보이스 할인 내역

인보이스 발행 시점의 할인 조건을 그대로 담습니다. 원본 할인이 이후에 바뀌어도 변하지 않습니다.

SubscriptionInvoiceItem: { productId, name, unitPrice, ... }

구독 인보이스 항목

SubscriptionInvoiceMethod: "CARD_BILLING" | "PAYPAL_BILLING"

구독 인보이스 결제 수단

SubscriptionInvoicePayment: { paymentId, billingKey, failure, ... }

구독 인보이스 결제 정보

SubscriptionInvoicePaymentFailure: { type, pgCode, pgMessage, ... }

구독 인보이스 결제 실패 정보

SubscriptionInvoicePaymentFailureReason: "INSUFFICIENT_FUNDS_OR_LIMIT_EXCEEDED" | "CARD_UNAVAILABLE" | "CARD_EXPIRED" | ...

구독 인보이스 결제 실패 사유 분류

결제사 실패 메시지를 단어로 묶은 것입니다.

SubscriptionInvoicePaymentFailureType: "PG_PROVIDER" | "BILLING_KEY_NOT_FOUND" | "BILLING_KEY_ALREADY_DELETED" | ...

구독 인보이스 결제 실패 유형

SubscriptionInvoiceRefund: { cancellationId, amount, refundedAt, ... }

구독 인보이스 환불

결제 건이 결제취소 API·콘솔로 취소된 한 건입니다. 부분 취소마다 한 건씩 쌓입니다.

SubscriptionInvoiceSettlement: { method }

구독 인보이스 수동 완납 정보

SubscriptionInvoiceSettlementMethod: "BANK_TRANSFER" | "CARD" | "OTHER"

구독 인보이스 수동 완납 방법

SubscriptionInvoiceSource: "AUTO" | "MANUAL"

구독 인보이스 생성 경로

SubscriptionInvoiceStatus: "PENDING" | "PAID" | "FAILED" | ...

구독 인보이스 상태

SubscriptionItem: { productId, quantity }

구독 항목

SubscriptionPaymentOptions: { locale, productType, installmentMonth, ... }

구독 결제 옵션

매 회차 결제 요청에 그대로 실리는 값입니다. 빌링키 결제 예약의 같은 이름 필드와 의미가 같습니다.

SubscriptionProductArchivedError: { type, message }

구독 상품이 보관되어 수정할 수 없는 경우

SubscriptionProductBillingPausedError: { type, message, productIds }

구독 상품의 청구가 중지된 경우

SubscriptionProductNotFoundError: { type, message }

요청된 구독 상품이 존재하지 않는 경우

SubscriptionStatus: "ACTIVE" | "INCOMPLETE" | "PAUSED" | ...

구독 상태

UnauthorizedError: { type, message }

인증 정보가 올바르지 않은 경우

UpdateSubscriptionCustomerBody: { storeId, name, email, ... }

구독 고객 정보 수정 입력 정보

UpdateSubscriptionCustomerError: ForbiddenError | InvalidRequestError | SubscriptionCustomerEmailRequiredError | ...

UpdateSubscriptionCustomerResponse: { customer }

구독 고객 정보 수정 성공 응답