구독 결제 연동하기

연동 흐름

구독 등록 SDK를 사용하면 아래 순서로 구독을 시작합니다.

1. 상품 등록: 구독에 담을 상품을 등록합니다. 상품은 한 번 만들어 두고 여러 구독에서 사용합니다.
2. 구독 사전 등록: 고객과 구독 항목을 담아 구독을 미리 만듭니다. 결제수단이 없으므로 구독은 INCOMPLETE 상태이며 청구되지 않습니다.
3. 구독 등록 SDK 호출: 사전 등록한 구독 아이디와 구독 등록 비밀값으로 requestSubscriptionRegistration을 호출합니다. 고객이 결제창에서 결제수단을 등록하면 그 시각부터 구독이 시작되고 첫 회차를 결제합니다.
4. 결과 확인: 고객사 서버에서 구독 조회 API로 첫 회차 결제 결과를 확인합니다.
5. 웹훅 처리: 구독 결제 웹훅을 검증하고, 조회 API로 최신 상태를 가져와 서비스 제공 여부를 반영합니다.

이후 회차는 포트원이 청구 예정 시각마다 인보이스를 만들어 자동으로 결제하고, 결과를 웹훅으로 알려 줍니다.

1. 상품 등록하기

구독 상품 생성 API로 상품을 등록합니다. 정기 상품(RECURRING)은 청구 주기(interval)가 필요하고, 일회성 상품(ONE_TIME)은 주기 없이 구독의 첫 회차에만 청구합니다.

await fetch("https://api.portone.io/products", {
  method: "POST",
  headers: {
    Authorization: `PortOne ${PORTONE_API_SECRET}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    id: "prd_english",
    name: "영어 심화",
    pricingType: "RECURRING",
    interval: { unit: "MONTH", count: 1 },
    amount: 99000,
    currency: "KRW",
  }),
});

2. 구독 사전 등록하기

구독 사전 등록 API(POST /subscriptions/pre-register)로 구독을 만듭니다. 고객이 없으면 함께 만들고, 이미 있는 고객이면 입력한 필드만 갱신합니다.

const response = await fetch(
  "https://api.portone.io/subscriptions/pre-register",
  {
    method: "POST",
    headers: {
      Authorization: `PortOne ${PORTONE_API_SECRET}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      customer: {
        id: "customer-1234", // 미입력 시 자동 생성됩니다.
        name: "홍길동",
        email: "customer@example.com",
        phoneNumber: "01012345678",
      },
      items: [{ productId: "prd_english", quantity: 1 }],
      discounts: [
        {
          discountId: "disc_welcome10",
          appliesTo: { type: "SUBSCRIPTION" },
          duration: { type: "CYCLES", count: 3 },
        },
      ],
    }),
  },
);
const { subscription, registrationSecret } = await response.json();
// subscription.id 와 registrationSecret 을 결제 페이지 응답 본문으로 브라우저에 전달해 구독 등록 SDK를 호출합니다.

주요 파라미터

3. 구독 등록 SDK 호출하기

브라우저에서 requestSubscriptionRegistration 함수를 호출합니다. 결제 금액, 주문명, 구매자 정보는 SDK가 사전 등록한 구독에서 가져오므로 전달하지 않습니다.

import * as PortOne from "@portone/browser-sdk/v2";

const response = await PortOne.requestSubscriptionRegistration({
  storeId: "store-00000000-0000-0000-0000-000000000000", // 고객사 storeId로 변경해주세요.
  channelKey: "channel-key-00000000-0000-0000-0000-000000000000", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
  subscriptionId: "subscription-0193c1a2", // 구독 사전 등록 API 응답의 구독 아이디
  registrationSecret, // 구독 사전 등록 API 응답의 registrationSecret
  billingKeyMethod: "CARD",
  redirectUrl: "https://example.com/subscription-redirect", // 모바일 등 리디렉션 방식에서 결과를 받을 주소
});

if (response === undefined || response.code !== undefined) {
  // 구독 등록이 끝나지 않았습니다. response.message 로 사유를 안내해 주세요.
  return alert(response?.message);
}

// 결제수단 등록과 첫 회차 결제가 끝났습니다.
// response.subscriptionId, response.paymentId 를 고객사 서버로 전달해 확인해 주세요.
await fetch("/api/subscription/complete", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    subscriptionId: response.subscriptionId,
    paymentId: response.paymentId,
  }),
});

주요 파라미터

응답

리디렉션 방식에서는 위 응답 값이 redirectUrl에 쿼리 파라미터로 붙습니다.

4. 결과 확인하기

SDK는 첫 회차 결제까지 성공했을 때만 성공으로 응답합니다. 결제창을 닫았거나 결제수단 등록에 실패한 경우뿐 아니라, 결제수단은 등록됐지만 첫 회차 결제가 실패했거나 결과를 확인하지 못한 경우에도 실패로 응답합니다.

SDK 응답 값은 브라우저를 거쳐 오므로 그대로 믿지 말고, 고객사 서버에서 구독 조회 API(GET /subscriptions/{subscriptionId})로 상태를 확인합니다.

Express
app.post("/api/subscription/complete", async (req, res) => {
  const { subscriptionId } = req.body;
  // 사전 등록 때 저장해 둔 구독인지, 로그인한 고객의 구독인지 먼저 확인해 주세요.

  const response = await fetch(
    `https://api.portone.io/subscriptions/${encodeURIComponent(subscriptionId)}`,
    { headers: { Authorization: `PortOne ${process.env.PORTONE_API_SECRET}` } },
  );
  if (!response.ok) throw new Error(`구독 조회 실패: ${await response.text()}`);
  const { subscription } = await response.json();

  if (subscription.status === "ACTIVE") {
    // 결제수단 등록과 첫 회차 결제가 끝났습니다. 서비스를 제공합니다.
    return res.status(200).json({ status: "ACTIVE" });
  }
  // 아직 INCOMPLETE 입니다. 결과가 뒤늦게 확정되면 웹훅으로 알려 드립니다.
  res.status(200).json({ status: subscription.status });
});

5. 웹훅 처리하기

첫 회차 이후의 회차는 고객이 결제창에 들어오지 않고 포트원이 자동으로 결제하므로, 결과는 웹훅으로만 받을 수 있습니다. 웹훅을 받으면 아래 순서로 처리합니다.

1. 서명 검증: 포트원이 보낸 웹훅인지 확인합니다. 방법은 V2 결제 웹훅과 같습니다.
2. 조회 API로 상세 확인: 웹훅 본문(data)에는 바뀐 대상의 아이디만 담깁니다. 금액, 상태, 실패 사유 같은 상세 내용은 각 조회 API로 가져와 판단합니다.
3. 고객사 데이터 반영: 조회한 최신 상태를 기준으로 서비스 제공·연장·중단을 처리하고 200으로 응답합니다.

Express
import * as PortOne from "@portone/server-sdk";
import bodyParser from "body-parser";
import express from "express";

const app = express();

async function getPortOne(path) {
  const response = await fetch(`https://api.portone.io${path}`, {
    headers: { Authorization: `PortOne ${process.env.PORTONE_API_SECRET}` },
  });
  if (!response.ok) throw new Error(`조회 실패: ${await response.text()}`);
  return response.json();
}

// 웹훅 검증 시 텍스트로 된 body가 필요합니다.
app.use("/portone-webhook", bodyParser.text({ type: "application/json" }));

app.post("/portone-webhook", async (req, res) => {
  // 1. 서명을 검증합니다. 실패하면 WebhookVerificationError가 발생합니다.
  try {
    await PortOne.Webhook.verify(
      process.env.PORTONE_WEBHOOK_SECRET,
      req.body,
      req.headers,
    );
  } catch (e) {
    if (e instanceof PortOne.Webhook.WebhookVerificationError) {
      return res.status(400).end();
    }
    throw e;
  }

  const { type, data } = JSON.parse(req.body);

  // 2. 아이디로 최신 상태를 조회해 판단합니다.
  switch (type) {
    case "Invoice.Paid": {
      const { invoice } = await getPortOne(
        `/invoices/${encodeURIComponent(data.invoiceId)}`,
      );
      if (invoice.status === "PAID" || invoice.status === "PAID_MANUALLY") {
        // 3. 해당 회차의 서비스를 제공·연장합니다.
        // 같은 웹훅이 다시 올 수 있으므로 invoice.id 기준으로 한 번만 처리해 주세요.
      }
      break;
    }
    case "Invoice.PaymentFailed": {
      const { invoice } = await getPortOne(
        `/invoices/${encodeURIComponent(data.invoiceId)}`,
      );
      if (invoice.status === "FAILED") {
        // invoice.payment?.failure 로 실패 사유를 확인하고 고객에게 결제수단 변경을 안내합니다.
      }
      break;
    }
    case "Subscription.Ended": {
      const { subscription } = await getPortOne(
        `/subscriptions/${encodeURIComponent(data.subscriptionId)}`,
      );
      if (subscription.status === "ENDED") {
        // 서비스 제공을 종료합니다.
      }
      break;
    }
    // 그 밖의 웹훅은 필요한 것만 골라 처리합니다.
  }

  res.status(200).end();
});

웹훅 종류와 발송 시점은 구독 결제 웹훅을 참고해 주세요.

6. 테스트 결제하기

테스트 채널로 구독을 등록하면 실제 결제 없이 전체 흐름을 확인할 수 있습니다.

1. 테스트 채널로 구독 등록: 관리자 콘솔에서 테스트용으로 추가한 채널의 채널 키를 구독 등록 SDK 호출 시 channelKey로 전달합니다. 이렇게 등록한 고객은 테스트 고객이 되며, 이후 회차도 모두 테스트로 결제됩니다.
2. 웹훅 수신 확인: 테스트 고객의 웹훅은 관리자 콘솔에 등록한 테스트 환경 웹훅 주소로 발송됩니다. 고객사 웹훅 수신 서버(웹훅 처리하기 참고)에 Subscription.Activated, Invoice.Paid 웹훅이 도착하는지 확인합니다.
3. 다음 회차 바로 청구: 청구일까지 기다리지 않고 테스트 구독 즉시 청구 API(POST /subscriptions/{subscriptionId}/charge-test)로 다음 회차를 지금 청구해 정기 회차 결제와 웹훅을 확인합니다.
4. 결제 실패 확인: 같은 API에 simulateFailure: true를 넣으면 결제대행사에 요청하지 않고 결제 실패로 처리합니다. Invoice.PaymentFailed 웹훅과 결제 재시도 흐름을 확인할 수 있습니다.

await fetch(
  `https://api.portone.io/subscriptions/${encodeURIComponent(subscriptionId)}/charge-test`,
  {
    method: "POST",
    headers: {
      Authorization: `PortOne ${PORTONE_API_SECRET}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ simulateFailure: false }), // true 면 결제 실패로 처리합니다.
  },
);

지원 결제대행사

구독 등록 SDK를 지원하는 결제대행사는 아래와 같습니다. 결제수단은 카드이며, 페이팔(RT)만 페이팔 계정을 등록합니다(billingKeyMethod: "PAYPAL").

• 토스페이먼츠
• 나이스정보통신
• 스마트로
• KG이니시스
• NHN KCP
• 한국결제네트웍스(KPN)
• 웰컴페이먼츠
• 갤럭시아머니트리
• KG모빌리언스
• KICC
• 페이팔(RT)
• 엑심베이
• 페이레터 해외결제

결제창에서 빌링키를 발급한 뒤 포트원이 그 빌링키로 첫 회차를 결제합니다(등록 후 결제). 단, 엑심베이와 페이레터 해외결제는 결제창 한 번으로 빌링키 발급과 첫 회차 결제를 함께 처리합니다(등록과 함께 결제). 고객사는 어느 방식이든 같은 함수로 호출하며, 포트원이 채널을 보고 방식을 정합니다.

목록에 없는 결제대행사는 구독 등록 SDK를 지원하지 않습니다. 빌링키로 구독 등록하기 방법을 사용해 주세요.

유의사항

• 엑심베이, 페이레터 해외결제는 첫 회차 금액이 0원이면 사용할 수 없습니다.
• 첫 회차 인보이스가 결제 실패(FAILED) 상태인 구독은 엑심베이, 페이레터 해외결제 채널로 다시 등록할 수 없습니다. 다른 채널로 다시 등록하거나 결제 재시도 API로 다시 결제해 주세요.
• 엑심베이는 구독 결제 옵션의 언어(paymentOptions.locale)가 필수입니다. 사전 등록 때 넣지 않았다면 구독 등록 SDK를 호출하기 전에 구독 수정 API로 넣어 주세요.
• 스마트로, 나이스정보통신, 웰컴페이먼츠는 issueId를 꼭 전달해 주세요.