Payment Bridge SDK 사용 가이드

개요

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

설치

``bash
npm install @bucketplace-public/payment-bridge-react


or

pnpm add @bucketplace-public/payment-bridge-react

or

yarn add @bucketplace-public/payment-bridge-react
`

적용

`tsx
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,
});
// ....
}
`

$3

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

`tsx
export interface UsePaymentBridgeReturn {
doPaymentProcess: (param: DoPaymentProcessParam) => void;
isProcessing: boolean;
}
`
- isProcessing - 결제 프로세스가 진행중인지의 여부를 반환합니다.
- doPaymentProcess - 결제 서비스를 호출하여 결제 프로세스를 진행합니다.

`tsx
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: 현재 결제를 진행중인 유저 정보가 암호화된 토큰입니다. 결제 서버에서 본 토큰을 활용해 정상적으로 인증된 경우에만 결제 프로세스가 진행됩니다.

$3

- onSuccess
- 결제인증이 성공하였을 경우 호출됩니다. (PC only)
- Mobile의 경우 해당 콜백이 호출되지 않고, 결제 요청 당시 파라미터로 함께 서버로 넘긴 successRedirectUrl 로 이동하게 됩니다.
- 다음의 파라미터를 넘겨받습니다.

`tsx
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 로 이동하게 됩니다.
- 다음의 파라미터를 넘겨받습니다.

`tsx
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)
- 다음의 파라미터를 넘겨받습니다.

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

- errorCode: 결제 서버에서 에러가 발생하는 경우 내려주는 에러코드입니다.
- message: 결제 프로세스 중 발생한 에러에 대한 상세 설명입니다.
- 해당 callback은 PC인 경우에만 호출됩니다. mobile 환경에서는 callback이 호출되지 않고 결제 서비스의 자체 에러 페이지가 노출됩니다.

> NOTE: fail과 error의 차이는 무엇인가요?

> Fail - 결제 실패는 PG 결제창에서 복합적인 이유로 결제 인증이 실패하거나 유저의 결제 취소하는 등의 케이스에 해당합니다.

Error - 결제 중 발생한 예상치 못한 오류에 해당하는 주로 비정상적인 케이스입니다`. 일반적으로 JS runtime 에러 혹은 API 서버에 4XX, 500에러가 발하는 경우에 해당합니다.