PortOne으로 정기결제 구현하기


  const session = await stripe.checkout.sessions.create({
    payment_method_types: ['card'],
    line_items: [
      {
        price: priceId,
        quantity: 1
      }
    ],
    mode: 'subscription',
    success_url: `${process.env.BASE_URL}/api/stripe/checkout?session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: `${process.env.BASE_URL}/pricing`,
    customer: team.stripeCustomerId || undefined,
    client_reference_id: user.id.toString(),
    allow_promotion_codes: true,
    subscription_data: {
      trial_period_days: 14
    }
  });
  redirect(session.url!);

session.url

하지만 PortOne에는 subscription mode가 따로 존재하지 않고, 구독형 정기결제, 종량제 과금결제 등 고객사가 원하는 시점에 결제를 일으키기 위한 결제용 비밀 키인 BillingKey를 이용해서 결제, 예약결제 등을 구현해야 합니다.

클라이언트 기반 정기 결제 구현

정기결제를 구현하기 위해서는 주요한 3가지 PortOne API 호출이 있습니다.

빌링키 획득 (SDK)

빌링키로 결제

예약 결제 생성

이 3가지 API로 정기 결제 로직은 다음과 같습니다.

즉 빌링키 획득 SDK로 빌링키를 얻은 후, Server DB에 저장한 후 결제를 진행합니다.

결제 후 결제 정보를 담은 session을 생성합니다. 또한 Team Plan을 update 한 후 PortOne에 예약 결제를 생성합니다.

WebHook 기반 정기결제

하지만 클라이언트 기반 정기 결제 로직은 다음과 같은 문제가 있습니다.

다양한 결제 ( 정기 결제, 정기 결제 취소 ) 에 대응하기 어려움

스크립트 위/변조 시 검증 어려움

클라이언트에서만 결제 완료 확인 시 여러가지 이유(인터넷 연결 끊김, 브라우저 오류 등) 로 DB 동기화 누락 가능성

이러한 문제들을 해결하기 위해 Webhook API에서 다음과 같은 책임을 부여하고자 하였습니다.

결제 검증 로직

성공 시에만 Team Plan update, 예약결제 생성

먼저 WebHook에 대한 개념에 대해 알아보겠습니다. 공식 문서 상 설명은 다음과 같습니다.

💡

Webhook 프로바이더는 해당 이벤트가 발행하면 HTTP POST 요청을 생성하여 callback URL(endpoint)로 이벤트 정보을 보냅니다.

간단히 설명하자면 결제, 취소, 결제 실패 등 유저로부터 Payment 이벤트가 발생할 경우, 지정된 API 주소로 HTTP POST 요청합니다.

saas-starter에서는 다음 용도로 사용합니다.


const signature = request.headers.get('stripe-signature') as string;

let event: Stripe.Event;

try {
  event = stripe.webhooks.constructEvent(payload, signature, webhookSecret);
} catch (err) {
  console.error('Webhook signature verification failed.', err);
  return NextResponse.json(
    { error: 'Webhook signature verification failed.' },
    { status: 400 }
  );
}

switch (event.type) {
  case 'customer.subscription.updated':
  case 'customer.subscription.deleted':
    const subscription = event.data.object as Stripe.Subscription;
    await handleSubscriptionChange(subscription);
    break;
  default:
    console.log(`Unhandled event type ${event.type}`);
}

webhook 에서 온 내용을 검증하고, subscription 상태가 변경되었을 때 handling 하기 위해 사용합니다.

WebHook 기반 정기결제 (빌링키 발급)

PortOne에서는 subscription mode 가 따로 존재하지 않기 때문에 이 부분에 대해서는 로직이 필요합니다. 해당 내용을 코드로 확인해보겠습니다.

빌링키 발급

먼저 PortOne SDK로 빌링키를 발급받은 후 해당 내용들을 추합하여 createPayMentsByBillingKeyAction server action을 실행시킵니다. (createPayMentsByBillingKeyAction에 대해서는 아래에서 설명)

클라이언트 빌링키 발급


  async function handleCheckout() {
    const redirectUrl = window.location.href;
    const billingKey = await createBillingKey({
      redirectUrl: redirectUrl,
    });
    const formData = new FormData();
    formData.append("billingKey", billingKey);
    formData.append("priceId", priceId);

    //발급 후 결제 진행
    await createPayMentsByBillingKeyAction(formData);
  }

  return (
    <form action={handleCheckout}>
      <input type="hidden" name="priceId" value={priceId} />
      <CheckoutButton/>
    </form>

빌링키 발급 로직


export async function createBillingKey({
    redirectUrl,
}: {
    redirectUrl: string;
}) {
    const issueResponse = await PortOne.requestIssueBillingKey({
        storeId: process.env.NEXT_PUBLIC_PORTONE_STORE_ID!,
        channelKey: "channel-key-ab41dd63-057e-41e5-ac2d-4ecd842ce9da",
        billingKeyMethod: "CARD",
        issueId: "issue-id-1234567890",
        issueName: "월간 이용권 정기결제",
        customer:{
            customerId: "customer-id-1234567890",
        },
        redirectUrl: redirectUrl,
    });

빌링키 저장

빌링키 발급에 문제가 없다면 Server DB에 빌링키를 저장합니다.


    if (!issueResponse || issueResponse.code !== undefined) {
        throw new Error(issueResponse?.message || "Failed to create billing key");
    }
    const billingKey = issueResponse.billingKey;
    const response = await fetch(`/api/portone/billingkey`, {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
        },
        body: JSON.stringify({ billingKey: billingKey }),
    });
    
    if (!response.ok) {
        throw new Error("Failed to create billing key");
    }

    return billingKey;

결제 Server Action (createPayMentsByBillingKeyAction)

해당 action에서는 팀을 확인한 후 빌링키와 priceId를 이용해서 결제할 금액에 대해 결제를 진행합니다.


export const createPayMentsByBillingKeyAction = withTeam(async (formData, team) => {
    const priceId = formData.get('priceId') as string;
    const billingKey = formData.get('billingKey') as string;
    await createCheckoutSubscription({ team: team, priceId, billingKey });
});

결제 및 예약 결제 생성 (createCheckoutSubscription)

이때, 팀의 Trial 여부에 따라 process 함수가 달라집니다. process 진행 후 checkout API(redirectUrl)에서 session을 검증하고 dashboard로 redirect 합니다.


export async function createCheckoutSubscription({
  team,
  priceId,
  billingKey
}:{
  team: Team;
  priceId: string;
  billingKey: string;
}){
  let redirectUrl: string | null  = null;
  
  try{
    const { price, product, user } = await validateCheckoutData(team, priceId); 

    const { redirectUrl:_redirectUrl } = team.shouldTrial 
    ? await processTrialSubscription(team, user, price, product, billingKey)
    : await processPayment(team, user, priceId, billingKey);
    redirectUrl = _redirectUrl;
  } catch (error:unknown) {
    if (error instanceof Error) {
      switch(error.message) {
        case 'product_not_found':
          redirectUrl = `/pricing?error=${error.message}&message=${encodeURIComponent(error.message)}`;
        case 'user_not_found':
          redirectUrl = `/sign-up?redirect=checkout&priceId=${priceId}`;
        default:
          redirectUrl = `/pricing?error=${encodeURIComponent(error.message)}`;
      }
    } 
  } finally{
    if(redirectUrl){
      redirect(redirectUrl);
    }
  }
}

각 process 함수는 다음과 같습니다.

Trial을 진행했을 경우 (processPayment)


const paymentId = uuidv4();
  const [_, session] = await createPayMentsAndSessionByBillingKey({
	  team,
	  customerId: user.id.toString(),
	  priceId,
	  billingKey,
	  paymentId
});
  
  if (!session?.id) {
  throw new Error('session_creation_failed');
  }
  
  return { 
  session,
  redirectUrl: `/api/portone/checkout?sessionId=${session.id}`
};

진행하지 않았을 경우 (processTrialSubscription)


//진행하지 않았다면 schedule 생성 후 team 정보 업데이트
const period = price.trialPeriodDays || 14;
const paymentId = uuidv4();
const [_, session] = await createCheckoutScheduleAndSession({
  teamId: team.id.toString(),
  customerId: user.id.toString(),
  priceId,
  billingKey,
  period,
  paymentId
});

//team 정보 업데이트
await db.update(teams).set({
  subscriptionStatus: 'trial',
  productId: product.id,
  planName: product.name,
  shouldTrial: false
}).where(eq(teams.id, team.id));

  return { 
      session,
      redirectUrl: `/api/portone/checkout?sessionId=${session.id}&isTrial=true`
  };
});

WebHook 기반 정기결제 (WebHook 로직)

먼저 Webhook으로부터 온 메세지들을 검증합니다.


export async function POST(req: NextRequest) {
  try {
    const body = await req.text();
    const headers: WebhookUnbrandedRequiredHeaders = {
      "webhook-id": req.headers.get("webhook-id")!,
      "webhook-timestamp": req.headers.get("webhook-timestamp")!,
      "webhook-signature": req.headers.get("webhook-signature")!,
    };

    // 웹훅 메시지를 검증합니다.
    const webhook = await PortOne.Webhook.verify(
      process.env.PORTONE_WEBHOOK_SECRET!,
      body,
      headers,
    );
    console.log(webhook);

다음 결제 시 지정해주었던 PaymentId를 통해 session을 가져와 결제 시 저장해두었던 결제 내역 (session)을 조회해 price, product, billingKey들을 가져옵니다.


 // 결제 관련 정보일 경우만 처리합니다.
    if ( "data" in webhook && "paymentId" in webhook.data) {
      const { paymentId } = webhook.data;
      const paymentResponse = await portone.payment.getPayment({ paymentId: paymentId });

      if (paymentResponse === null || !("id" in paymentResponse)) {
        // 웹훅 정보와 일치하는 결제건이 실제로는 존재하지 않는 경우 
        return NextResponse.json({ message: "Payment not found" }, { status: 200 });
      }

      const { status, amount } = paymentResponse;
      const pyamentId = webhook.data.paymentId;
      
      //session 가져오기
      const _session = await db.select().from(session).where(eq(session.paymentId, pyamentId));

      if(!_session){
        return NextResponse.json(
          { message: "Session not found" }, 
          { status: 400 }
        );
      }
      //session 내 결제정도 획득
      const price = await getPriceById(_session[0].priceId);
      const product = await getProductById(_session[0].productId);
      const billingKey = await getBillingKeyByTeamId(_session[0].teamId);

이 값들을 가지고 저장된 결제된 내용과 PortOne에서 결제된 값 확인한 후, 다음과 같은 로직을 수행합니다.

예약 결제 & session 생성

Team Plan 업데이트


   if (Number(price.unitAmount) * 100 === amount.total) {
        switch (status) {
          case "PAID": {
            const uuid = uuidv4();
            //schedule 생성
            const [schedule,_] = await createCheckoutScheduleAndSession({
              teamId: _session[0].teamId.toString(),
              customerId: _session[0].customerId,
              priceId: _session[0].priceId,
              billingKey: billingKey.key,
              period: price.interval || 30,
              paymentId: uuid
            });

            const schduleId = schedule.schedule.id;
            //team 정보 업데이트
            await db.update(teams).set({
              subscriptionStatus: 'active',
              subscriptionId: schduleId,
              productId: _session[0].productId,
              planName: product.name,
              shouldTrial: false,
            }).where(eq(teams.id, _session[0].teamId));
            
            break;
          }

결제 금액이 불일치 할 경우 위변조가 의심되므로 에러를 반환합니다.


  		return NextResponse.json({ success: true }, { status: 200 });
      } else {
        // 결제 금액이 불일치하여 위/변조 시도가 의심됩니다.
        return NextResponse.json(
          { message: "Payment amount mismatch" }, 
          { status: 400 }
        );
      }
    }

    return NextResponse.json({ success: true }, { status: 200 });

에러 처리

또한 검증에 실패했을 경우 에러를 반환합니다.


  } catch (error) {
    if (error instanceof PortOne.Webhook.WebhookVerificationError) {
      return NextResponse.json(
        { message: "Webhook verification failed" }, 
        { status: 400 }
      );
    }
    
    console.error('Webhook error:', error);
    return NextResponse.json(
      { message: "Internal server error" }, 
      { status: 500 }
    );
  }
}

해당 로직을 그림으로 나타내면 다음과 같습니다.

이렇게 구성하면 결제 검증, 성공 시에만 Team Plan이 업데이트 되고, 예약 결제가 생성되어 실패 시에는 Team Plan이 업데이트 되지 않습니다.

또한 클라이언트 결제 완료 후에 인터넷 연결 끊김, 브라우저 닫힘 등 다양한 문제로 Team Plan 업데이트가 진행되지 않아도 Webhook api 에서 동기화를 진행할 수 있습니다.

추후 다양한 결제 ( 정기 결제, 정기 결제 취소 )에 Webhook을 중심으로 비즈니스 로직을 수행할 수 있습니다.

하지만 이 방식에도 문제가 발생합니다.

그림과 같이 결제가 완료되어 dashboard로 redirect 된 후에도 Team Plan이 업데이트 되어있지 않아 사용자는 Webhook API를 처리하는 동안 이전 버전의 Plan으로 기다리고 있어야 합니다.

낙관적 업데이트 후 결제 검증

이 문제를 해결하기 위해 기존 saas-starter의 코드를 참조하였습니다.

saas-starter의 checkout api입니다.

해당 코드에선 checkout api가 실행되면 해당 Team Plan을 바로 업데이트 합니다.


    const userTeam = await db
      .select({
        teamId: teamMembers.teamId,
      })
      .from(teamMembers)
      .where(eq(teamMembers.userId, user[0].id))
      .limit(1);

    if (userTeam.length === 0) {
      throw new Error('User is not associated with any team.');
    }

    await db
      .update(teams)
      .set({
        stripeCustomerId: customerId,
        stripeSubscriptionId: subscriptionId,
        stripeProductId: productId,
        planName: (plan.product as Stripe.Product).name,
        subscriptionStatus: subscription.status,
        updatedAt: new Date(),
      })
      .where(eq(teams.id, userTeam[0].teamId));

이런 방식에 착안하여 saas-starter-ko에서도 checkout api에서 결제가 정상적으로 완료되었다는 가정 하에(낙관적 업데이트) Team Plan을 선제적으로 업데이트 합니다.


 //Checkout API 중 일부
  const paymentId = _session[0].paymentId;
  const productId = _session[0].productId;
  const priceId = _session[0].priceId;
  const product = await getProductById(productId);

  if(!paymentId || !productId || !priceId){
    return NextResponse.redirect(new URL('/pricing?error=no_verify_session', request.url));
  }

  //team 정보 업데이트
  await db.update(teams).set({
    subscriptionStatus: isTrial === 'true' ? 'trial' : 'active',
    subscriptionId: _session[0].id.toString(),
    productId: productId,
    planName: product.name,
    shouldTrial: false,
  }).where(eq(teams.id, team.id));

이렇게 되면 위의 DB 업데이트 텀은 발생하지 않습니다.

이때 Webhook API에서는 결제 내역을 검증합니다. PAID 시 기존 로직과 동일하지만, 만약 그 외에 상황에서는 Team Plan을 다시 canceled로 돌려 놓습니다.


switch (status) {
  case "PAID": {
    const uuid = uuidv4();
    //schedule 생성
    const [schedule,_] = await createCheckoutScheduleAndSession({
      teamId: _session[0].teamId.toString(),
      customerId: _session[0].customerId,
      priceId: _session[0].priceId,
      billingKey: billingKey.key,
      period: price.interval || 30,
      paymentId: uuid
    });

    const schduleId = schedule.schedule.id;
    //team 정보 업데이트
    await db.update(teams).set({
      subscriptionStatus: 'active',
      subscriptionId: schduleId,
      productId: _session[0].productId,
      planName: product.name,
      shouldTrial: false,
    }).where(eq(teams.id, _session[0].teamId));
    
    break;
  }
	//그 외의 상황
  default:{
    await db.update(teams).set({
      subscriptionStatus: 'canceled',
      subscriptionId: null,
      productId: null,
      planName: null,
      shouldTrial: false,
    }).where(eq(teams.id, _session[0].teamId));
    break;
  }

로직을 그림으로 나타내면 다음과 같습니다.

결론

이렇게 WebHook 기반 결제 시스템, 그리고 낙관적 업데이트를 도입하여 다음과 같은 이점을 얻을 수 있었습니다.

결제 검증

UX 관점에서 사용자가 결제 후 즉시 업그레이드된 Plan을 볼 수 있도록 낙관적 업데이트

안정성 향상: 결제 실패 시 WebHook을 통해 자동으로 Plan 상태를 원래대로 복구

이번 글에서는 Stripe의 Subscription 모델을 PortOne의 빌링키 기반 결제 시스템으로 마이그레이션하는 방법과 그 과정에서 발생한 문제점들을 해결하는 방법에 대해 다루었습니다. 다음 글에서는 다국어 지원 및 OAuth 통합에 대해 다루겠습니다.

목차

도입

Stripe → PortOne 정기결제

클라이언트 기반 정기 결제 구현

WebHook 기반 정기결제

WebHook 기반 정기결제 (빌링키 발급)

WebHook 기반 정기결제 (WebHook 로직)

낙관적 업데이트 후 결제 검증

결론