인증 결제 연동하기

포트원 V2 SDK는 npm 레지스트리와 CDN을 통해 배포되고 있습니다.

• npm, yarn 등 패키지 매니저를 사용한다면 의존 대상으로 @portone/browser-sdk를 추가하세요.

• 패키지 매니저를 사용하지 않는다면 <script> 요소를 이용하여 CDN에서 SDK를 직접 불러오세요.

• CDN에서 ESM 모듈 형태로도 SDK를 제공하고 있습니다.

npm i @portone/browser-sdk

yarn add @portone/browser-sdk

pnpm add @portone/browser-sdk

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

<script src="https://cdn.portone.io/v2/browser-sdk.js"></script>

import * as PortOne from "https://cdn.portone.io/v2/browser-sdk.esm.js";

SDK의 PortOne.requestPayment() 함수를 호출하여 결제 수단에 따른 결제창을 열 수 있습니다.

먼저, 관리자 콘솔의 결제 연동 페이지에서 Store ID와 사용할 채널의 채널 키를 확인해 주세요.

그리고 아래와 같이 결제 요청 파라미터를 requestPayment() 함수의 첫 인자로 설정하여 호출합니다.

const response = await PortOne.requestPayment({
  // Store ID 설정
  storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec",
  // 채널 키 설정
  channelKey: "channel-key-893597d6-e62d-410f-83f9-119f530b4b11",
  paymentId: `payment-${crypto.randomUUID()}`,
  orderName: "나이키 와플 트레이너 2 SD",
  totalAmount: 1000,
  currency: "CURRENCY_KRW",
  payMethod: "CARD",
});

결제창이 활성화되는 방식은 windowType 파라미터를 통해 명시적으로 설정할 수 있습니다.

PortOne.requestPayment() 함수의 반환값을 통해 결제 요청의 결과를 확인할 수 있습니다.

code != null이면 결제 과정에서 오류가 발생한 것이므로 적절히 처리하여야 합니다.

결제가 성공한 경우 paymentId를 서버에 전달하여 서버 측에서 결제 완료 처리를 진행하도록 합니다. (가상 계좌 결제의 경우 결제가 아직 완료되지 않은 상태일 수 있습니다)

async function requestPayment() {
  const response = await PortOne.requestPayment({
    /* 파라미터 생략 */
  });

  if (response.code != null) {
    // 오류 발생
    return alert(response.message);
  }

  // 고객사 서버에서 /payment/complete 엔드포인트를 구현해야 합니다.
  // (다음 목차에서 설명합니다)
  const notified = await fetch(`${SERVER_BASE_URL}/payment/complete`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    // paymentId와 주문 정보를 서버에 전달합니다
    body: JSON.stringify({
      paymentId: paymentId,
      // 주문 정보...
    }),
  });
}

결과값에 들어 있는 필드는 다음과 같습니다.

PortOne.requestPayment({
  /* 기타 파라미터 생략 */
  redirectUrl: `${BASE_URL}/payment-redirect`,
});

예를 들어 paymentId가 payment-39ecfa97, redirectUrl이 https://example.com/payment-redirect인 경우, 결제 성공 시에 https://example.com/payment-redirect?payment_id=payment-39ecfa97로 리다이렉트됩니다.

paymentId를 서버에 전달하면, 서버는 포트원의 결제 조회 API를 호출하여 해당 결제 건의 상태를 확인하고 결제 완료 처리를 진행하여야 합니다.

PORTONE_API_SECRET 은 V2 전용 시크릿으로, 포트원 콘솔 내 결제연동 탭에서 발급받을 수 있습니다.

Express
// JSON 요청을 처리하기 위해 body-parser 미들웨어 세팅
app.use(bodyParser.json());

// POST 요청을 받는 /payments/complete
app.post("/payment/complete", async (req, res) => {
  try {
    // 요청의 body로 paymentId가 전달되기를 기대합니다.
    const { paymentId, orderId } = req.body;

    // 1. 포트원 결제내역 단건조회 API 호출
    const paymentResponse = await fetch(
      `https://api.portone.io/payments/${paymentId}`,
      { headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` } },
    );
    if (!paymentResponse.ok)
      throw new Error(`paymentResponse: ${paymentResponse.statusText}`);
    const payment = await paymentResponse.json();

    // 2. 고객사 내부 주문 데이터의 가격과 실제 지불된 금액을 비교합니다.
    const order = await OrderService.findById(orderId);
    if (order.amount === payment.amount.total) {
      switch (payment.status) {
        case "VIRTUAL_ACCOUNT_ISSUED": {
          // 가상 계좌가 발급된 상태입니다.
          // 계좌 정보를 이용해 원하는 로직을 구성하세요.
          break;
        }
        case "PAID": {
          // 모든 금액을 지불했습니다! 완료 시 원하는 로직을 구성하세요.
          break;
        }
      }
    } else {
      // 결제 금액이 불일치하여 위/변조 시도가 의심됩니다.
    }
  } catch (e) {
    // 결제 검증에 실패했습니다.
    res.status(400).send(e);
  }
});