🔧 결제 기능 트러블 슈팅 (PortOne Browser SDK v2)

1. 문제 상황

React 결제 페이지에서 PortOne Browser SDK(v2)를 사용하여
일반 결제 / 카카오페이 / 토스페이 결제를 구현하던 중,
토스페이 결제 시 아래와 같은 에러가 발생하였다.

POST https://checkout-service.prod.iamport.co/api/prepare/v2 400 (Bad Request)

결제 실패: 결제 창 호출에 실패하였습니다.
토스페이먼츠의 경우 간편 결제 수단은 필수 입력입니다.

에러는 PortOne.requestPayment() 호출 직후 발생했으며,
브라우저 SDK 내부의 preparePayment 단계에서 실패하였다.

2. 원인 분석

초기 구현에서는 결제 수단에 따라 다음과 같이 처리하고 있었다.

• 일반 결제
  • payMethod: "CARD"
• 카카오페이 / 토스페이
  • payMethod: "EASY_PAY"

그러나 PortOne Browser SDK v2에서는
payMethod: "EASY_PAY"를 사용할 경우,

반드시 어떤 간편결제 수단인지(easyPayProvider)를 함께 전달해야 한다.

특히 토스페이먼츠 채널에서는
easyPayProvider가 누락될 경우 400 Bad Request 에러가 발생한다.

즉, 문제의 원인은 다음과 같았다.

• payMethod: "EASY_PAY"만 전달됨
• easyPayProvider 옵션 누락 ❌

3. 해결 방법

3-1. 결제 수단별 옵션을 명확히 분리

결제 수단에 따라 아래 항목을 명확히 분리하였다.

• channelKey
• payMethod
• easyPayProvider

const getPortOnePayType = () => {
  if (payType === "GENERAL") {
    return {
      channelKey: process.env.REACT_APP_PORTONE_CHANNEL_CARD,
      payMethod: "CARD",
      easyPayProvider: null,
    };
  }

  if (payType === "KAKAOPAY") {
    return {
      channelKey: process.env.REACT_APP_PORTONE_CHANNEL_KAKAOPAY,
      payMethod: "EASY_PAY",
      easyPayProvider: "KAKAOPAY",
    };
  }

  return {
    channelKey: process.env.REACT_APP_PORTONE_CHANNEL_TOSSPAY,
    payMethod: "EASY_PAY",
    easyPayProvider: "TOSSPAY",
  };
};

3-2. requestPayment 호출 시 조건부 옵션 추가

payMethod가 EASY_PAY일 때만
easyPay 옵션을 조건부로 추가하도록 수정하였다.

const paymentRequest = {
  storeId: process.env.REACT_APP_PORTONE_STORE_ID,
  channelKey,
  paymentId,
  orderName,
  totalAmount,
  currency: "CURRENCY_KRW",
  payMethod,
  customer: {
    fullName: user.name,
    email: user.email,
    phoneNumber: user.phone,
  },
};

if (payMethod === "EASY_PAY") {
  paymentRequest.easyPay = { easyPayProvider };
}

const response = await PortOne.requestPayment(paymentRequest);

4. 결과

• 결제 채널별 요구사항을 정확히 반영하여 결제창 정상 호출
• 일반 결제 / 카카오페이 / 토스페이 모두 정상 동작 확인
• 결제 실패 원인을 명확히 분리하여 트러블 슈팅 문서로 정리 가능

5. 정리

• PortOne Browser SDK v2에서는
  EASY_PAY 사용 시 easyPayProvider가 필수
• 에러 메시지는 추상적이므로
  네트워크 탭과 SDK 요구사항을 함께 확인해야 함
• 결제 수단별 설정을 명확히 분리하는 것이 중요