PortOne 구독결제 API

{
  "id": "prd_english",
  "name": "영어 심화",
  "description": "주 2회 화상 수업",
  "pricingType": "RECURRING",
  "interval": "MONTHLY",
  "amount": 99000,
  "currency": "KRW",
  "metadata": { "category": "class" }
}

• id·description·metadata는 선택입니다. id를 생략하면 자동으로 부여합니다.
• RECURRING이면 interval이 필수이고, ONE_TIME이면 넣을 수 없습니다.
• amount는 1 이상입니다.
• 이미 있는 id면 409입니다.

아카이브된 상품도 조회됩니다. 없으면 404입니다.

{ "page": { "number": 0, "size": 20 }, "archived": false, "metadata": { "category": "class" } }

archived 기본값은 false로 아카이브된 상품은 제외됩니다. 청구가 중지된 상품은 billingPaused: true로 목록에 포함됩니다. metadata는 선택이며 보낸 키-값이 모두 일치하는 상품만 걸러냅니다. 생성일 역순입니다.

{ "name": "영어 심화 (2026)", "description": "…", "amount": 109000 }

• 보낸 필드만 바뀝니다.
• id·pricingType·interval은 바꿀 수 없습니다.
• 금액 변경은 다음 결제부터 적용됩니다. 인보이스는 결제 시점의 가격을 씁니다.
• 아카이브된 상품은 409입니다.

이 상품이 담긴 활성 구독의 인보이스 생성과 결제가 멈추고, 신규 구독 등록도 막힙니다. 구독과 고객 정보는 바뀌지 않습니다. 이미 중지 상태면 아무 일도 하지 않습니다.

이 상품이 담긴 구독은 다음에 도래하는 청구일부터 생성·결제를 재개합니다. 재개하는 시점에 각 구독의 다음 청구 예정일을 지금 이후 첫 회차로 다시 잡으므로, 중지 기간에 지나간 회차는 청구하지 않습니다. 다시 잡은 날짜가 구독 종료일을 넘으면 그 구독은 종료됩니다. 중지 상태가 아니면 아무 일도 하지 않습니다.

목록에서 숨기고 신규 구독 등록을 막습니다. 이미 이 상품을 담고 있는 구독은 계속 청구됩니다. 되돌릴 수 없고 같은 id를 다시 쓸 수 없습니다.

{
  "id": "disc_welcome10",
  "name": "첫 가입 10%",
  "type": "PERCENT",
  "value": 10,
  "appliesTo": { "type": "SUBSCRIPTION" },
  "duration": { "type": "CYCLES", "count": 3 },
  "redeemBy": "2026-12-31"
}

• id·redeemBy·appliesTo는 선택입니다. appliesTo 기본값은 SUBSCRIPTION입니다.
• PRODUCTS로 지정하면 productIds가 하나 이상 필요하고, 그 상품이 있고 아카이브되지 않았어야 합니다.
• duration.type은 ONCE·CYCLES·FOREVER 중 하나이고, CYCLES는 count(1 이상)가 필수입니다.
• PERCENT는 1~100이며 currency를 넣지 않습니다. AMOUNT는 1 이상이고 currency가 필수입니다.
• redeemBy가 오늘(KST)보다 이전이면 거절합니다.

보관된 할인도 조회됩니다. 없으면 404입니다.

{ "page": { "number": 0, "size": 20 }, "archived": false }

archived 기본값은 false입니다. 생성일 역순입니다.

{ "name": "첫 가입 10% (연장)", "redeemBy": "2027-03-31" }

이름과 적용 마감일만 바꿀 수 있습니다. 할인 조건(type·value·currency·duration·appliesTo)은 만든 뒤에 바꿀 수 없습니다 — 조건을 바꾸려면 새 할인을 만들어 주세요.

새로 연결하는 것만 막습니다. 이미 붙어 있는 구독에서는 잔여 회차까지 그대로 적용됩니다. 이미 보관 상태면 아무 일도 하지 않습니다.

다시 신규 연결이 가능해집니다.

{
  "id": "cust_001",
  "name": "홍길동",
  "email": "hong@example.com",
  "phone": "010-1234-5678",
  "businessRegistrationNumber": "1234567890",
  "billingKey": "billing-key-…",
  "metadata": { "grade": "vip" },

  "subscription": {
    "items": [ { "productId": "prd_english", "quantity": 1 } ],
    "discountIds": ["disc_welcome10"]
  }
}

• 고객을 새로 만들거나, 이미 있으면 보낸 필드만 갱신합니다. billingKey는 항상 필수이고 신규 고객이면 name도 필수입니다.
• 빌링키는 그 상점이 소유한 카드 빌링키여야 합니다. 아니면 BillingKeyNotFound입니다.
• 다른 고객이 쓰고 있는 빌링키면 BillingKeyAlreadyRegistered { customerId }입니다.
• 이 API는 등록만 합니다. 살아 있는 빌링키를 가진 고객이면 CustomerHasBillingKey로 거절하므로 교체하려면 먼저 해지해야 합니다. 이미 해지된 빌링키를 들고 있으면 새 빌링키로 바뀝니다.
• subscription을 함께 보내면 구독까지 한 번에 만듭니다. 필드는 구독 생성과 같고, 구독이 실패하면 고객도 만들어지지 않습니다.

없으면 404입니다.

{ "page": { "number": 0, "size": 20 }, "metadata": { "grade": "vip" } }

metadata는 선택입니다. 생성일 역순입니다.

{ "page": { "number": 0, "size": 20 }, "status": "ACTIVE" }

status는 선택입니다. 생성일 역순이고, 고객이 없으면 404입니다.

{
  "page": { "number": 0, "size": 20 },
  "from": "2026-06-09T00:00:00+09:00",
  "to": "2026-09-07T23:59:59+09:00"
}

from·to는 선택이며 billingAt을 기준으로 거릅니다. 기본값은 from 90일 전, to 현재입니다. 그 고객의 모든 구독 인보이스를 billingAt 역순으로 돌려줍니다.

{
  "name": "홍길동",
  "email": "hong@example.com",
  "phone": "010-1234-5678",
  "businessRegistrationNumber": "1234567890",
  "metadata": { "grade": "vip" }
}

모든 필드가 선택이며 보낸 필드만 바뀝니다. id와 빌링키는 바꿀 수 없습니다. 이메일 변경은 다음 결제 결과 인보이스부터 반영됩니다. 사업자번호는 숫자 10자리 형식을 검사합니다.

{ "reason": "고객 요청" }

• reason은 선택이지만 일부 결제사가 필수로 요구하므로 채워 보내시길 권합니다.
• 현재 빌링키를 해지하고 billingKey를 null로 만듭니다. 이미 해지된 빌링키는 성공으로 처리합니다.
• 해지에 실패하면 BillingKeyHasSchedules 또는 BillingKeyRevokeFailed { pgCode, pgMessage }입니다.
• 구독은 ACTIVE로 남지만, 청구일이 와도 빌링키가 없으면 인보이스를 만들지 않고 건너뜁니다.
• 다시 등록하려면 SDK로 빌링키를 새로 발급받아 POST /customers를 호출합니다.

{
  "id": "sub_001",
  "customerId": "cust_001",
  "items": [ { "productId": "prd_english", "quantity": 1 } ],
  "discountIds": ["disc_welcome10"],
  "billStartDate": "2026-10-01",
  "endDate": "2027-09-30",
  "sendInvoiceEmail": true,
  "metadata": { "planName": "basic" }
}

• id·discountIds·billStartDate·endDate·sendInvoiceEmail·metadata는 선택입니다.
• billStartDate 기본값은 오늘이고 지난 날짜는 거절합니다. endDate는 billStartDate와 같거나 뒤여야 합니다.
• 고객에게 유효한 빌링키가 있어야 합니다.
• 담긴 정기 상품은 주기가 모두 같아야 하고, 통화도 모두 같아야 합니다. 아카이브·청구 중지 상품은 담을 수 없습니다.
• 일회성 상품만으로도 만들 수 있으며, 이때는 결제 주기가 없습니다.
• 할인은 있어야 하고, 보관되지 않았고, 적용 마감일 이내여야 합니다. PRODUCTS형은 그 상품이 items에 있어야 하고 같은 할인을 중복 지정할 수 없습니다.
• sendInvoiceEmail 기본값은 고객 이메일이 있으면 true입니다. true인데 이메일이 없으면 CustomerEmailRequired입니다.
• 같은 id로 다시 호출하면 409이고 결제가 다시 나가지 않습니다. id를 지정하지 않는다면 Idempotency-Key로 중복 생성을 막아 주세요.

붙어 있는 할인 목록(각 항목의 잔여 회차와 상태 포함), nextBillingAt, endDate가 함께 내려갑니다. 없으면 404입니다.

{
  "page": { "number": 0, "size": 20 },
  "status": "ACTIVE",
  "customerId": "cust_001",
  "metadata": { "planName": "basic" }
}

status·customerId·metadata가 모두 선택입니다. 생성일 역순입니다.

{
  "items": [ { "productId": "prd_english", "quantity": 2 } ],
  "endDate": "2028-03-31",
  "nextBillingDate": "2026-10-20",
  "sendInvoiceEmail": false,
  "metadata": { "planName": "pro" }
}

• 보낸 필드만 바뀌고, 변경은 다음 결제부터 반영됩니다. 결제 직전까지 바꿀 수 있습니다.
• items는 전체 교체입니다. 추가·삭제·수량 변경을 한 번에 보냅니다.
• 교체해도 주기와 통화는 기존 구독과 같아야 하고, 아카이브·청구 중지 상품은 담을 수 없습니다.
• endDate를 null로 보내면 무기한으로 되돌립니다.
• 종료일을 앞당겨 다음 청구 예정일이 그 날짜를 넘게 되면 남은 청구가 없으므로 구독이 그 자리에서 종료됩니다(END_DATE_REACHED).
• 종료된 구독이면 409입니다.

{ "discountId": "disc_retention20" }

같은 할인이 이미 붙어 있으면 409이고, 다른 할인은 개수 제한 없이 계속 추가할 수 있습니다. PRODUCTS형이면 그 상품이 구독에 담겨 있어야 합니다. 적용 마감일과 보관 여부, 통화 일치를 검사합니다. 잔여 회차는 지속 방식에 따라 초기화됩니다. 다음 결제부터 적용되며 결제 직전까지 추가할 수 있습니다.

구독에 붙어 있는 할인을 discountId·잔여 회차·상태·연결 일시와 함께 돌려줍니다. 제거된 할인은 빠집니다.

지정한 할인 하나만 제거합니다. 다음 결제부터 그 할인이 적용되지 않습니다. 붙어 있지 않으면 아무 일도 하지 않습니다.

본문이 없습니다. 기간을 정하지 않고 중지하며, 중지 중에는 인보이스 생성과 결제가 없습니다. ACTIVE가 아니면 409입니다.

본문이 없습니다. 청구 기준일과 기준 시각을 그대로 유지하므로, 재개한 날짜와 무관하게 원래 정기결제일에 다음 인보이스를 만들어 결제합니다. 재개 시점에 즉시 결제하지 않으며 중지 중 건너뛴 회차도 소급하지 않습니다. 다시 잡은 청구일이 종료일을 넘으면 재개 대신 구독이 종료됩니다. PAUSED가 아니면 409입니다.

즉시 종료합니다. 이후 인보이스는 만들어지지 않습니다. 이미 종료된 구독이면 아무 일도 하지 않습니다.

• 다음 결제 때 만들어질 인보이스를 계산만 해서 보여주고 저장하지 않습니다.
• 구독의 현재 상태(담긴 상품과 현재 가격, 일회성 상품 포함 여부, 할인, 수량)로 계산하므로 결제 직전까지 값이 바뀔 수 있습니다.
• 다음 인보이스를 만들지 않을 상태면 null입니다 — 일시중지·종료, 청구 중지 상품 포함, 빌링키 없음, 종료일 초과.

{
  "page": { "number": 0, "size": 20 },
  "from": "2026-06-09T00:00:00+09:00",
  "to": "2026-09-07T23:59:59+09:00"
}

from·to는 선택이며 billingAt 기준입니다. 기본값은 from 90일 전, to 현재이고 billingAt 역순으로 내려갑니다.

없으면 404입니다.

{
  "subscriptionId": "sub_001",
  "items": [
    { "productId": "prd_english", "quantity": 1 },
    { "name": "교재비", "unitPrice": 15000, "quantity": 1 }
  ],
  "memo": "9월 교재 추가"
}

• subscriptionId와 items가 필수이고 memo는 선택입니다.
• 항목은 productId + quantity로 보내면 단가를 상품에서 채웁니다. 등록된 상품이 아니면 name + unitPrice + quantity로 직접 적습니다.
• 상품으로 보낸 항목은 그 상품이 있어야 하고, 청구가 중지된 상품은 담을 수 없습니다.
• 생성과 동시에 결제합니다.
• 회차가 없고(sequence는 null) 구독의 회차 번호와 다음 청구 예정일도 바뀌지 않습니다.
• 구독에 붙은 할인은 자동으로 적용되지 않습니다.
• 종료된 구독이면 409입니다. 일시중지·미완성 구독에는 청구할 수 있습니다.

• 실패한 인보이스에만 쓸 수 있습니다. 아니면 409입니다.
• 같은 결제 건으로 다시 시도하고 결과를 응답에 담아 돌려줍니다. 이미 결제된 건이면 결제 완료 상태로 맞춥니다.
• 결제에는 고객의 현재 빌링키를 씁니다. 카드를 새로 등록했다면 새 카드로 시도하며, 빌링키가 없으면 CustomerHasNoBillingKey입니다.
• 시도하는 동안 인보이스는 PENDING이라 같은 건에 취소·수동 완납을 할 수 없습니다.
• 첫 회차가 이 요청으로 결제되면 INCOMPLETE였던 구독이 ACTIVE로 돌아갑니다.

• 실패한 인보이스에만 쓸 수 있습니다. 아니면 409입니다.
• 취소 상태로 바뀌고, 그 인보이스에 반영됐던 할인의 잔여 회차를 구독에 돌려줍니다.
• 회차를 다 써서 소진된 할인은 다시 쓸 수 있는 상태가 됩니다.

• 취소된 인보이스에만 쓸 수 있습니다. 아니면 409입니다.
• 구독의 현재 상태(상품의 현재 가격·할인 등)로 같은 회차의 인보이스를 새로 만들어 즉시 결제합니다.
• regenerationSeq가 1 늘어나고 원본은 취소 상태로 남습니다.
• 금액을 직접 받지 않습니다. 금액을 바꾸려면 구독이나 상품·할인을 먼저 고친 뒤 호출해 주세요.
• 같은 원본으로 두 번 호출하면 InvoiceAlreadyRegenerated입니다.
• 회차가 없는 수동 청구는 다시 계산할 기준이 없어 대상이 아닙니다. 같은 내용으로 새로 청구해 주세요.
• 종료된 구독이거나 고객에게 빌링키가 없으면 거절합니다.

{ "memo": "9/5 계좌 입금 확인" }

• 계좌 입금처럼 API 밖에서 받은 대금을 정리할 때 씁니다. memo는 선택입니다.
• 실패한 인보이스에만 쓸 수 있습니다. 아니면 409입니다.
• 수동 완납 상태가 되고 처리 시각이 paidAt에 기록됩니다.
• 이전 결제 실패 사유는 지워지고 결제 정보(payment)도 내려가지 않습니다.
• 첫 회차를 이렇게 처리하면 INCOMPLETE였던 구독이 ACTIVE로 돌아갑니다.