라이브러리 - Toss Payments SDK

Toss Payments SDK

 

 

✅ Toss Payments SDK란?

---

Toss Payments SDK는 웹사이트나 앱에 온라인 결제 기능을 붙일 수 있도록 토스페이먼츠가 제공하는 개발 도구

Toss 앱 자체를 연동하는 도구라기보다, 카드·계좌이체·간편결제 등을 처리하는 PG(Payment Gateway) 서비스를 연동하는 SDK

 

어떤 기능을 제공하나?

Toss Payments SDK를 이용하면 직접 결제 UI와 카드사별 인증 절차를 모두 만들지 않아도 된다.

• 신용·체크카드
• 토스페이, 네이버페이, 카카오페이 등의 간편결제
• 계좌이체
• 가상계좌
• 휴대폰 결제
• 자동결제
• 해외결제

 

✅ Installation

---

npm i @tosspayments/tosspayments-sdk

 

https://docs.tosspayments.com/sdk/v2/js

토스페이먼츠 JavaScript SDK | 토스페이먼츠 개발자센터

 

 

✅ Usage

---

Payments Widgets

import { Form, type MetaFunction } from "react-router";
import type { Route } from "./+types/promote-page";
import { PageHero } from "~/common/components/page-hero";
import SelectPair from "~/common/components/select-pair";
import { Calendar } from "~/common/components/ui/calendar";
import { Label } from "~/common/components/ui/label";
import { useEffect, useRef, useState } from "react";
import type { DateRange } from "react-day-picker";
import { DateTime } from "luxon";
import { Button } from "~/common/components/ui/button";
import {
  loadTossPayments,
  type TossPaymentsWidgets,
} from "@tosspayments/tosspayments-sdk";

export function loader({ request }: Route.LoaderArgs) {
  return { requestUrl: request.url };
}

export function action({ request }: Route.ActionArgs) {
  return { requestMethod: request.method };
}

export const meta: MetaFunction = () => {
  return [
    { title: "Promote Product | wemake" },
    { name: "description", content: "Promote your product" },
  ];
};

const clientKey = "test_gck_docs_Ovk5rk1EwkEbP0W43n07xlzm";
const customerKey = "hQXCTRFORCizlkzGCjBSD"; // userId

export default function PromotePage() {
  const [promotionPeriod, setPromotionPeriod] = useState<
    DateRange | undefined
  >();
  const totalDays =
    promotionPeriod?.from && promotionPeriod.to
      ? DateTime.fromJSDate(promotionPeriod.to).diff(
          DateTime.fromJSDate(promotionPeriod.from),
          "days",
        ).days
      : 0;
  const widgets = useRef<TossPaymentsWidgets | null>(null);
  useEffect(() => {
    const initToss = async () => {
      const toss = await loadTossPayments(clientKey);
      widgets.current = toss.widgets({ customerKey });
      await widgets.current.setAmount({
        value: 0,
        currency: "KRW",
      });
      await widgets.current.renderPaymentMethods({
        selector: "#toss-payment-methods",
      });
      await widgets.current.renderAgreement({
        selector: "#toss-payment-agreement",
      });
    };
    initToss();
  }, [clientKey, customerKey]);
  useEffect(() => {
    if (widgets.current) {
      widgets.current.setAmount({
        value: totalDays * 20000,
        currency: "KRW",
      });
    }
  }, [promotionPeriod]);
  return (
    <div>
      <PageHero
        title="Promote Your Product"
        subtitle="Boost your product's visibility"
      />
      <div className="grid grid-cols-6 gap-10">
        <Form className="col-span-3 mx-auto flex flex-col items-center gap-10">
          <SelectPair
            label="Select a product"
            description="Select the product you want to promote."
            name="product"
            placeholder="Select a product"
            options={[
              {
                label: "AI Dark Mode Maker",
                value: "ai-dark-mode-maker-1",
              },
              {
                label: "AI Dark Mode Maker",
                value: "ai-dark-mode-maker-2",
              },
              {
                label: "AI Dark Mode Maker",
                value: "ai-dark-mode-maker-3",
              },
            ]}
          />
          <div className="flex w-full flex-col items-center gap-2">
            <Label className="flex flex-col gap-1">
              Select a range of dates for promotion
              <small className="text-muted-foreground">
                Minimum duration is 3 days.
              </small>
            </Label>
            <Calendar
              className="min-w-sm"
              mode="range"
              selected={promotionPeriod}
              onSelect={setPromotionPeriod}
              min={3}
              disabled={[{ before: new Date() }]}
            />
          </div>
        </Form>
        <aside className="col-span-3 flex flex-col items-center px-20">
          <div id="toss-payment-methods" className="w-full" />
          <div id="toss-payment-agreement" className="w-full" />
          <Button disabled={totalDays === 0} className="w-full">
            Checkout (
            {(totalDays * 20000).toLocaleString("ko-KR", {
              style: "currency",
              currency: "KRW",
            })}
            )
          </Button>
        </aside>
      </div>
    </div>
  );
}

 

Request Payment

  const handleSubmit = async (e: React.SubmitEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    const product = formData.get("product");
    if (!product || !promotionPeriod?.from || !promotionPeriod.to) return;
    await widgets.current?.requestPayment({
      orderId: crypto.randomUUID(),
      orderName: `wemake promotion for ${product}`,
      customerEmail: "email@naver.com",
      customerName: "somename",
      customerMobilePhone: "01012345678",
      metadata: {
        product,
        promotionFrom: DateTime.fromJSDate(promotionPeriod.from).toISO(),
        promotionTo: DateTime.fromJSDate(promotionPeriod.to).toISO(),
      },
      successUrl: `${window.location.href}/success`,
      failUrl: `${window.location.href}/fail`,
    });
  };

 

Confirm Payment

import z from "zod";
import type { Route } from "./+types/promote-success-page";

// paymentType=NORMAL&orderId=ad00d236-4320-466e-ba48-33d8a327c400&paymentKey=tgen_202607221317267l4k2&amount=60000

const paramsSchema = z.object({
  paymentType: z.string(),
  orderId: z.uuid(),
  paymentKey: z.string(),
  amount: z.coerce.number(),
});

const TOSS_SECRET_KEY = "test_gsk_docs_OaPz8L5KdmQXkzRz3y47BMw6";

export const loader = async ({ request }: Route.LoaderArgs) => {
  const url = new URL(request.url);
  const { success, data } = paramsSchema.safeParse(
    Object.fromEntries(url.searchParams),
  );
  if (!success) {
    return new Response(null, { status: 404 });
  }
  const encryptedSecretKey = `Basic ${Buffer.from(TOSS_SECRET_KEY + ":").toString("base64")}`;
  const response = await fetch(
    `https://api.tosspayments.com/v1/payments/confirm`,
    {
      method: "POST",
      headers: {
        Authorization: encryptedSecretKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        orderId: data.orderId,
        paymentKey: data.paymentKey,
        amount: data.amount,
      }),
    },
  );
  const responseData = await response.json();
  return Response.json({ responseData });
};

 

Toss Docs

 

Toss Docs

 

결제가 진행이 되었지만 success route로 이동하여 정보를 전송하지 못할 상황에 대비하여 토스 관리자 패널에서 api를 호출하도록webhook을 설정해놓아야 한다.

 

https://docs.tosspayments.com/guides/v2/payment-widget/integration?frontend=react

연동하기 | 토스페이먼츠 개발자센터