Payment Bridge SDK 사용 가이드

개요

• 결제 프로세스를 쉽게 통합할 수 있도록 설계된 React SDK입니다.
• 다양한 결제 수단을 지원하며, 결제 인증 프로세스를 간편하게 처리할 수 있습니다.
• 본 문서는 SDK의 적용 방법에 대해 설명합니다.

설치

npm install @bucketplace-public/payment-bridge-react
# or
pnpm add @bucketplace-public/payment-bridge-react
# or
yarn add @bucketplace-public/payment-bridge-react

적용

import { usePaymentBridge } from '@bucketplace-public/payment-bridge-react';

function Component() {
  const { doPaymentProcess, isProcessing } = usePaymentBridge({
    // 결제가 성공하였을 때 호출되는 callback
    onSuccess: (payload: PaymentSuccessEventPayload) => void,
    // 결제가 실패하였을 때 호출되는 callback
    onFail: (payload: PaymentFailEventPayload) => void,
    // 결제 중 예상하지 못한 오류가 발생하였을 때 호출되는 callback
    onError: (payload: PaymentErrorEventPayload) => void,
  });
	// ....
}

Returns

usePaymentBridge는 다음 객체를 반환합니다.

export interface UsePaymentBridgeReturn {
  doPaymentProcess: (param: DoPaymentProcessParam) => void;
  isProcessing: boolean;
}

• isProcessing - 결제 프로세스가 진행중인지의 여부를 반환합니다.

• doPaymentProcess - 결제 서비스를 호출하여 결제 프로세스를 진행합니다.

    doPaymentProcess({
      // 주문 API로부터 받아온 결제 인증 url을 전달합니다. (ex. payment.ohou.se/:paymentId/:pgProviderType/ready?paymentToken=somethingtoken )
      paymentAuthUrl: string,
    })

  • paymentAuthUrl
    • 결제 서비스의 url을 전달합니다.
    • 해당 url은 서버에서 내려주게 되며, 다음과 같이 구성되어 있습니다. (ex. https://payment.ohou.se/:paymentId/:pgProviderType/ready?paymentToken=somethingtoken )
      • paymentId: 결제 id로 현재 수행되는 결제정보를 받아오기 위한 식별값입니다.
      • pgProviderType: 유저가 선택한 결제수단에 대응되는 pg 타입(ex. TOSS_PAYMENTS, KAKAO, …)입니다.
      • paymentToken: 현재 결제를 진행중인 유저 정보가 암호화된 토큰입니다. 결제 서버에서 본 토큰을 활용해 정상적으로 인증된 경우에만 결제 프로세스가 진행됩니다.

Params

• onSuccess

  • 결제인증이 성공하였을 경우 호출됩니다. (PC only)

  • Mobile의 경우 해당 콜백이 호출되지 않고, 결제 요청 당시 파라미터로 함께 서버로 넘긴 successRedirectUrl 로 이동하게 됩니다.

  • 다음의 파라미터를 넘겨받습니다.

    export type PaymentSuccessEventPayload = {
      redirectUrl?: string; // 결제 성공시 이동해야 할 url입니다. 해당 url로 이동하여 결제 성공 API를 호출합니다.
      paymentId: string;
      orderId: string;
      requestId: string;
      paymentMethodType: PaymentMethodType;
      authenticationToken: string;
    };

    • redirectUrl은 결제 성공시 이동해야하는 페이지의 url입니다. redirectUrl은 결제 요청 당시 파라미터로 넘겨준 successRedirectUrl(optional) 의 값이 내려옵니다. 즉, successRedirectUrl 을 넘겨주지 않은 경우 null로 응답이 내려옵니다.
      • paymentId - 결제 id
      • orderId - 주문 id
      • authenticationToken - 결제 인증 토큰으로 결제 성공 API에서의 인증에 활용됩니다.
    • redirectUrl과 함께 넘어오는 query string은 각각 별도의 필드로도 내려주고 있습니다. 프로젝트에 따라 원하는 방식으로 활용하시면 됩니다.
    • 해당 callback은 PC인 경우에만 호출됩니다. mobile 환경에서는 callback이 호출되지 않고 redirectUrl로 바로 이동하기 때문에 결제 요청시 successRedirectUrl 를 반드시 지정하여 넘겨주어야 합니다.

• onFail

  • 결제인증이 실패하였을 경우 호출됩니다. (PC only)

  • Mobile의 경우 해당 콜백이 호출되지 않고, 결제 요청 당시 파라미터로 함께 서버로 넘긴 failRedirectUrl 로 이동하게 됩니다.

  • 다음의 파라미터를 넘겨받습니다.

    export type PaymentFailEventPayload = {
      redirectUrl?: string;
      paymentId: string;
      orderId: string;
      failType: PaymentFailType;
      failCode: string;
      failMessage: string;
    };

  • redirectUrl 결제 실패시 이동해야 하는 페이지의 url입니다. redirectUrl은 결제 요청 당시 파라미터로 넘겨준 failRedirectUrl(optional) 의 값이 내려옵니다. 즉, failRedirectUrl 을 넘겨주지 않은 경우 null로 응답이 내려옵니다. 아래 query string과 함께 전달됩니다.

    • paymentId
    • orderId
    • failType - 실패 사유에 해당합니다.
      • USER_CANCEL(유저가 결제를 취소한 경우)
      • ERROR(PG 결제 인증 중 발생한 PG 에러)
    • failCode - 서버에 정의된 실패 코드
    • failMessage - 실패 상세 설명

  • redirectUrl과 함께 넘어오는 query string은 각각 별도의 필드로도 내려주고 있습니다. 프로젝트에 따라 원하는 방식으로 활용하시면 됩니다.

  • 해당 callback은 PC인 경우에만 호출됩니다.mobile 환경에서는 callback이 호출되지 않고 redirectUrl로 바로 이동하기 때문에 결제 요청시 failRedirectUrl 를 반드시 지정하여 넘겨주어야 합니다.

• onError

  • 결제인증 도중 예상치 못한 에러가 발생하였을 때 호출됩니다. (PC Only)

  • 다음의 파라미터를 넘겨받습니다.

    export type PaymentErrorEventPayload = {
      errorCode?: string,
      message: string
    }

  • errorCode: 결제 서버에서 에러가 발생하는 경우 내려주는 에러코드입니다.

  • message: 결제 프로세스 중 발생한 에러에 대한 상세 설명입니다.

  • 해당 callback은 PC인 경우에만 호출됩니다. mobile 환경에서는 callback이 호출되지 않고 결제 서비스의 자체 에러 페이지가 노출됩니다.

  NOTE: fail과 error의 차이는 무엇인가요? Fail - 결제 실패는 PG 결제창에서 복합적인 이유로 결제 인증이 실패하거나 유저의 결제 취소하는 등의 케이스에 해당합니다. Error - 결제 중 발생한 예상치 못한 오류에 해당하는 주로 비정상적인 케이스입니다. 일반적으로 JS runtime 에러 혹은 API 서버에 4XX, 500에러가 발하는 경우에 해당합니다.