결제위젯 React Native SDK는 React Native 환경에서 사용할 수 있는 결제위젯 메서드를 제공합니다. SDK를 추가하고 메서드를 사용하는 방법을 알아봅니다.
결제위젯 React Native SDK를 설치하기 전에 최소 요구 사항을 확인하세요.
- Node 18.0.0 이상
- react-native-webview 11.0.0 이상
npm 또는 yarn으로 토스페이먼츠 결제위젯 React Native SDK를 설치하세요.
# npm
npm install @tosspayments/widget-sdk-react-native
# yarn
yarn add @tosspayments/widget-sdk-react-native
AndroidManifest.xml
파일에 아래 설정을 추가해주세요.
<application
android:usesCleartextTraffic="true"
android:hardwareAccelerated="false"
//...
>
아래 예시 코드를 React Native 프로젝트에 넣어서 바로 결제위젯을 테스트해보세요.
import React, { useState } from 'react';
import {Button, Alert} from 'react-native';
import { PaymentWidgetProvider,
usePaymentWidget,
AgreementWidget,
PaymentMethodWidget } from '@tosspayments/widget-sdk-react-native';
import type {
AgreementWidgetControl,
PaymentMethodWidgetControl,
AgreementStatus,
} from '@tosspayments/widget-sdk-react-native';
// ...
export default function App() {
return (
<>
{/* 스크롤이 필요한 경우 ScrollView로 감싸주세요. */}
{/* <ScrollView> */}
<PaymentWidgetProvider
clientKey={`test_gck_docs_Ovk5rk1EwkEbP0W43n07xlzm`}
customerKey={``}
>
<CheckoutPage />
</PaymentWidgetProvider>
{/* </ScrollView> */}
</>
);
}
function CheckoutPage() {
const paymentWidgetControl = usePaymentWidget();
const [paymentMethodWidgetControl, setPaymentMethodWidgetControl] =
useState<PaymentMethodWidgetControl | null>(null);
const [agreementWidgetControl, setAgreementWidgetControl] =
useState<AgreementWidgetControl | null>(null);
return (
<>
<PaymentMethodWidget
selector="payment-methods"
onLoadEnd={() => {
paymentWidgetControl
.renderPaymentMethods(
'payment-methods',
{value: 50_000},
{
variantKey: 'DEFAULT',
},
)
.then(control => {
setPaymentMethodWidgetControl(control);
});
}}
/>
<AgreementWidget
selector="agreement"
onLoadEnd={() => {
paymentWidgetControl
.renderAgreement('agreement', {
variantKey: 'DEFAULT',
})
.then(control => {
setAgreementWidgetControl(control);
});
}}
/>
<Button
title="결제요청"
onPress={async () => {
if (paymentWidgetControl == null || agreementWidgetControl == null) {
Alert.alert('주문 정보가 초기화되지 않았습니다.');
return;
}
const agreeement = await agreementWidgetControl.getAgreementStatus();
if (agreeement.agreedRequiredTerms !== true) {
Alert.alert('약관에 동의하지 않았습니다.');
return;
}
paymentWidgetControl.requestPayment?.({
orderId: '',
orderName: '토스 티셔츠 외 2건',
});
}}
/>
<Button
title="선택된 결제수단"
onPress={async () => {
if (paymentMethodWidgetControl == null) {
Alert.alert('주문 정보가 초기화되지 않았습니다.');
return;
}
Alert.alert(
`선택된 결제수단: ${JSON.stringify(
await paymentMethodWidgetControl.getSelectedPaymentMethod(),
)}`,
);
}}
/>
<Button
title="결제 금액 변경"
onPress={() => {
if (paymentMethodWidgetControl == null) {
Alert.alert('주문 정보가 초기화되지 않았습니다.');
return;
}
paymentMethodWidgetControl.updateAmount(100_000).then(() => {
Alert.alert('결제 금액이 100000원으로 변경되었습니다.');
});
}}
/>
</>
);
}
토스페이먼츠 결제위젯입니다.
import {PaymentWidgetProvider} from '@tosspayments/widget-sdk-react-native'
export default function App() {
return <PaymentWidgetProvider
clientKey={'test_gck_docs_Ovk5rk1EwkEbP0W43n07xlzm'}
customerKey={''}
options={{
brandpay: {redirectUrl: '{{REDIRECT_URL}}'},
}}
>
<CheckoutPage />
</PaymentWidgetProvider>
}
- clientKey 필수
API 키 메뉴에서 확인할 수 있는 결제위젯 연동 키 > 클라이언트 키입니다.
- customerKey 필수
고객 ID입니다. 다른 사용자가 이 값을 알게 되면 악의적으로 사용될 수 있습니다. 자동 증가하는 숫자 또는 이메일・전화번호・사용자 아이디와 같이 유추가 가능한 값은 안전하지 않습니다. UUID와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자
-
,_
,=
,.
,@
를 최소 1개 이상 포함한 최소 2자 이상 최대 50자 이하의 문자열이어야 합니다.비회원 결제에는
PaymentWidget.ANONYMOUS
를 사용하세요. - options 선택
결제위젯 옵션입니다.
interface PaymentWidgetOptions {brandpay?: PaymentWidgetBrandpayOptions;} - brandpay
결제위젯에 브랜드페이를 추가할 때 설정합니다.
redirectUrl
은 Access Token 발급 과정에서 임시 인증 코드를 받을 URL입니다.interface PaymentWidgetBrandpayOptions {redirectUrl: string;}
결제 UI를 렌더링하는 메서드입니다.
function renderPaymentMethods({
selector: string,
amount: Amount,
options?: RenderPaymentMethodsOptions
}): Promise<PaymentMethodWidgetControl>
- selector
결제 UI를 렌더링할 컴포넌트의 식별자입니다.
- amount
결제 금액 정보입니다. 결제 금액, 통화, 국가 정보가 들어가는
Amount
입니다.interface Amount {value: number;currency?: string;country?: string;}} - value
결제 금액입니다.
- currency
결제 통화입니다. 기본 값은
KRW
입니다. PayPal에서 사용할 수 있는 통화는USD
입니다. - country
결제한 국가입니다. 기본 값은
KR
입니다. ISO-3166의 두 자리 국가 코드를 모두 지원합니다. - options
결제위젯의 렌더링 옵션입니다.
interface RenderPaymentMethodsOptions {variantKey?: string;} - variantKey
멀티 결제 UI를 사용할 때 설정합니다. 렌더링하고 싶은 결제 UI의 키 값을 넣으세요.
이용약관 UI를 렌더링하는 메서드입니다. 이용약관 UI에는 토스페이먼츠의 필수 이용약관이 있습니다. 결제위젯 어드민에서 내 상점의 필수 약관, 회원·비회원 약관, 영문 약관 등 약관을 자유롭게 커스터마이징할 수 있습니다.
function renderAgreement({
selector: string,
options?: RenderAgreementOptions
}): Promise<AgreementWidgetControl>
- selector
이용약관 UI를 렌더링할 컴포넌트의 식별자입니다.
- options
이용약관 UI의 렌더링 옵션입니다.
interface RenderAgreementOptions {variantKey?: string;} - variantKey
렌더링하고 싶은 이용약관의 키 값을 넣으세요. 결제 UI의
variantKey
와 독립적으로 사용됩니다. 이용약관은 결제위젯 어드민에서 추가할 수 있어요.
고객이 선택한 결제수단의 결제창을 띄우는 메서드입니다.
function requestPayment({
paymentInfo: PaymentInfo
}): Promise<Result | undefined>
- paymentInfo
결제 정보가 담긴
PaymentInfo
입니다.interface PaymentInfo {orderId: string;orderName: string;customerEmail?: string;customerName?: string;appScheme?: string;taxFreeAmount?: number;taxExemptionAmount?: string;cultureExpense?: boolean;useEscrow?: boolean;escrowProducts?: EscrowProduct[];customerMobilePhone?: string;showCustomerMobilePhone?: boolean;mobileCarrier?: string[];products?: Product[];shipping?: Shipping;paymentMethodOptions?: {payPal?: {setTransactionContext: any;};};} - orderId
주문을 구분하는 ID입니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자
-
,_
,=
로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다. - orderName
주문명입니다. 예를 들면
생수 외 1건
같은 형식입니다. 최대 길이는 100자입니다. - customerEmail
고객의 이메일입니다. 이메일을 파라미터로 전달하면 해당 이메일로 결제 내용을 통보합니다. 최대 길이는 100자입니다.
- customerName
고객의 이름입니다. 최대 길이는 100자입니다.
- appScheme
내 상점의 앱 스킴을 지정하면 외부 앱(페이북/ISP)에서 상점 앱으로 돌아올 수 있습니다. 예를 들면
testapp://
같은 형태입니다. - taxFreeAmount
결제할 금액 중 면세 금액입니다. 값을 넣지 않으면 기본값인
0
으로 설정됩니다.* 면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점인 경우에는 적용되지 않습니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.
- taxExemptionAmount
과세를 제외한 결제 금액(컵 보증금 등)입니다. 값을 넣지 않으면 기본값인
0
으로 설정됩니다. 카드 결제 또는 간편결제로 계좌이체할 때 사용하세요.* 과세 제외 금액이 있는 카드 결제는 부분 취소가 안 됩니다.
- cultureExpense
가상계좌, 계좌이체 결제일 때 적용할 수 있는 문화비(도서, 공연 티켓, 박물관·미술관 입장권 등) 지출 여부입니다.
- useEscrow
가상계좌, 계좌이체 결제일 때 적용할 수 있는 에스크로 사용 여부입니다. 값을 주지 않으면 결제창에서 고객이 직접 에스크로 결제 여부를 선택합니다.
- escrowProducts
각 상품의 상세 정보 객체를 담는 배열입니다. 가상계좌, 계좌이체에서 에스크로를 사용하는 상점이라면 필수 파라미터입니다.
interface EscrowProduct {id: string;name: string;code: string;unitPrice: number;quantity: number;} - id
상품의 ID입니다. 이 값은 유니크해야 합니다.
- name
상품 이름입니다.
- code
상점에서 사용하는 상품 관리 코드입니다.
- unitPrice
상품의 가격입니다. 전체를 합한 가격이 아닌 상품의 개당 가격입니다.
- quantity
상품 구매 수량입니다.
- customerMobilePhone
고객의 휴대폰 번호입니다. 가상계좌 결제에는 입금 안내가 전송되고, 퀵계좌결제창에서는 고객의 휴대폰 번호를 자동 완성합니다.
- showCustomerMobilePhone
가상계좌 결제창에서 휴대폰 번호 입력 필드 노출 여부입니다.
false
를 넘기면 가상계좌 결제창에서 휴대폰 번호 입력 필드를 보여주지 않습니다. 기본값은true
입니다. - mobileCarrier
휴대폰 결제창에서 선택할 수 있는 통신사를 제한합니다. 배열에 통신사 코드를 추가하면 해당 통신사 코드만 선택할 수 있는 결제창이 뜹니다.
- products
고객이 구매한 각 상품의 상세 정보 객체를 담는 배열입니다. 예를 들어 고객이 세 가지 종류의 상품을 구매했다면 길이가 3인 배열이어야 합니다.
products
정보는 필수가 아니지만 이 정보를 보내려면 아래 항목은 모두 필수입니다.interface Product {name: string;quantity: number;unitamount: number;currency: string;description: string;}- name 필수 · string
상품 이름입니다.
- quantity 필수 · number
상품 구매 수량입니다.
- unitAmount 필수 · number
상품의 가격입니다. 전체를 합한 가격이 아닌 상품의 개당 가격입니다.
- currency 필수 · string
상품 가격의 통화입니다.
- description 필수 · string
상품에 대한 부가적인 설명입니다.
- name 필수 · string
- shipping
고객이 구매한 각 상품의 배송 정보 객체입니다.
interface Shipping {fullName: string;address: Address;} - fullName
고객의 이름입니다.
- address
배송지 주소입니다. 각 항목의 자세한 설명은 JavaScript SDK를 참고하세요.
interface Address {country: string;line1?: string;line2?: string;area1?: string;area2: string;postalCode?: string;} - paymentMethodOptions
결제수단의 추가 파라미터를 담는 객체입니다. 결제수단이나 결제사 별로 파라미터를 제공합니다. PayPal을 연동할 때는
paypal
을 사용합니다. - payPal
PayPal의 추가 파라미터를 담는 객체입니다.
setTransactionContext
는 PayPal에서 추가로 요청하는 STC(Set Transaction Context) 정보를 객체로 전달하는 필드입니다. 이 정보는 PayPal에서 부정거래, 결제 취소, 환불 등 리스크 관리에 활용합니다. 결제 거래의 안전성과 신뢰성을 확보하려면 이 정보를 전달해야 합니다. PayPal STC 문서를 참고해서 업종에 따라 필요한 파라미터를 추가해주세요. 문서의 표에 있는 ‘Data Field Name’ 컬럼 값을 객체의 ‘key’로, ‘Description’에 맞는 값을 객체의 ‘value’로 넣어주시면 됩니다.* 이 정보는 토스페이먼츠에서 관리하지 않습니다.
interface Result {
success?: Success;
fail?: Fail;
}
- success interface Success {paymentKey: string;orderId: string;amount: number;paymentType: PaymentType;additionalParameters?: Record<string, string>;}
- paymentKey
- orderId
주문 ID입니다. 결제 요청에 담아 보낸 값입니다.
- amount
결제 금액입니다.
- additionalParameters
브랜드페이를 사용하고 있다면 필요한 파라미터입니다.
- paymentType
결제 유형입니다.
NORMAL
,BRANDPAY
,KEYIN
중 하나입니다.NORMAL
: 일반 결제입니다. 코어 결제 승인 API를 호출해서 결제를 완료하세요.BRANDPAY
: 브랜드페이 결제입니다. 브랜드페이 결제 승인 API를 호출해서 결제를 완료하세요.KEYIN
: 키인 결제입니다. 코어 결제 승인 API를 호출해서 결제를 완료하세요.
- fail
결제 실패 결과 정보입니다.
interface Fail {code: string;message: string;orderId?: string;} - code
에러 코드입니다. SDK 에러가 돌아옵니다.
failUrl
로 전달되는 에러, 공통 SDK 에러, 결제위젯 SDK 에러가 모두 포함됩니다. - message
에러 메시지입니다.
- orderId
주문 ID입니다. 결제 요청에 담아 보낸 값입니다.
변경된 결제 금액을 UI에 업데이트하는 메서드입니다.
결제 금액이 바뀌면 할부 적용, 즉시 할인 적용 여부도 바뀔 수 있습니다. updateAmount()
메서드로 결제 금액을 변경하고 결제위젯의 할인 정보도 업데이트하세요.
function updateAmount(amount: number): Promise<void>
- amount
새로운 결제 금액입니다.
고객이 선택한 결제수단을 전달하는 메서드입니다.
function getSelectedPaymentMethod(): Promise<PaymentMethod>
interface PaymentMethod {
type: PaymentType;
method?: string;
easypay?: { provider: string };
paymentMethodKey?: string;
}
- type
결제 타입 정보입니다.
NORMAL
(일반결제),BRANDPAY
(브랜드페이),KEYIN
(키인 결제),CUSTOM
(커스텀 결제수단) 중 하나입니다.type PaymentType = 'NORMAL' | 'BRANDPAY' | 'KEYIN' | 'CUSTOM'; - method
결제수단입니다.
카드
,가상계좌
,간편결제
,휴대폰
,계좌이체
,문화상품권
,도서문화상품권
,게임문화상품권
중 하나입니다. - easypay
결제수단이
간편결제
일 때 반환되는 간편결제 정보입니다. - provider
선택한 간편결제사 코드입니다.
- paymentMethodKey
결제 타입이
CUSTOM
일 때 반환되는 커스텀 결제수단 키입니다.
고객의 필수 이용약관에 동의 상태를 나타내는 메서드입니다. 메서드를 호출하면 약관 데이터 객체가 돌아옵니다.
function getAgreementStatus(): Promise<AgreementStatus>
interface AgreementStatus {
agreedRequiredTerms: boolean;
terms: AgreementTerm[];
}
- agreedRequiredTerms
고객이 모든 필수 약관에 동의했는지 알려줍니다.
- terms
개별 약관에 동의했는지 알려줍니다.
interface AgreementTerm {id: string;agreed: boolean;required: boolean;} - id
약관의 식별자입니다.
- agreed
약관의 고객 동의 여부입니다.
- required
약관의 필수 여부입니다.