PaymentMethod API

Toss POS에 커스텀 결제 수단을 추가하고 관리하는 API예요. 포인트 결제, 바코드 결제 등 파트너사에서 제공하는 결제 수단을 등록하여 사용할 수 있어요.

주의사항

이 API는 토스POS+프론트환경일 때만 사용이 가능해요. 프론트 키오스크 모드 환경에서는 사용이 불가해요.

Types

PaymentMethodResponse

결제 완료 시 반환되는 응답 객체예요.

{
  approvedAt: string; // 결제 승인 시간
  paymentKey: string; // 결제 고유 ID 중복값을 허용하지 않습니다
}

필드	타입	설명	예시
approvedAt	string	결제 승인 시간	'2024-09-26T17:32:19'
paymentKey	string	결제 고유 ID	'plugin-payment-unique-id'

PluginCancelledPaymentDto

결제 취소 시 반환되는 응답 객체예요.

{
  cancelledAt: string; // 결제 취소 시간
}

필드	타입	설명	예시
cancelledAt	string	결제 취소 시간	'2024-09-26T17:32:19'

PluginPrice

결제 금액 정보를 나타내는 객체예요.

{
  amountMoney: number; // 지불액
  taxMoney: number; // 부가가치세
  supplyMoney: number; // 공급가액
  tipMoney: number; // 봉사료
  taxExemptMoney: number; // 면세금액
}

필드	타입	설명	예시
amountMoney	number	지불액	10000
taxMoney	number	부가가치세	1000
supplyMoney	number	공급가액	9000
tipMoney	number	봉사료	0
taxExemptMoney	number	면세금액	0

Methods

add

Toss POS에 새로운 결제 수단을 등록해요.

주요 기능

• 결제 수단 등록 및 관리
• 결제 이벤트 처리
• 결제 취소 이벤트 처리

콜백 함수

• payCallback: 결제 시 실행되는 콜백
  • 사용자 취소 시 undefined 반환
• cancelCallback: 결제 취소 시 실행되는 콜백
  • 사용자 취소 시 undefined 반환

import { posPluginSdk } from "@tossplace/pos-plugin-sdk";

posPluginSdk.paymentMethod.add({
  data: {
    id: "test-card", // 결제 수단 고유 ID
    image: "https://static.toss.im/icons/png/4x/icon-barcode-scan2.png", // 결제 수단 아이콘 (30x30)
    paymentName: "포인트결제", // 결제 수단 표시명
  },
  payCallback: async (order: PluginOrder, price: PluginPrice) => {
    // 결제 처리 로직
    return {
      approvedAt: "2024-09-26T17:32:19",
      paymentKey: "plugin-payment-unique-id",
    };
  },
  cancelCallback: async (order: PluginOrder, payment: PluginPayment) => {
    // 결제 취소 처리 로직
    return {
      cancelledAt: "2024-09-26T17:45:55",
    };
  },
});

Parameters

파라미터	타입	필수	설명
data.id	string	O	결제 수단의 고유 ID. 다른 결제 수단과 중복되지 않아야 해요
data.paymentName	string	O	POS에 표시할 결제 수단 이름
data.image	string	O	결제 수단 아이콘 URL (30x30)
payCallback	(order: PluginOrder, price: PluginPrice, ui: Ui) => Promise<PaymentMethodResponse | undefined>	O	결제할 때 실행돼요
cancelCallback	(order: PluginOrder, payment: PluginPayment, ui: Ui) => Promise<PluginCancelledPaymentDto | undefined>	O	결제를 취소할 때 실행돼요

payCallback

항목	타입	설명
order	PluginOrder	결제 대상 주문
price	PluginPrice	결제할 금액 정보
ui	Ui	바코드 팝업을 띄울 수 있는 UI 제어 객체
반환값	Promise<PaymentMethodResponse | undefined>	결제 결과. 사용자가 취소하면 undefined를 반환해요

cancelCallback

항목	타입	설명
order	PluginOrder	취소 대상 주문
payment	PluginPayment	취소할 결제 정보
ui	Ui	바코드 팝업을 띄울 수 있는 UI 제어 객체
반환값	Promise<PluginCancelledPaymentDto | undefined>	취소 결과. 사용자가 취소하면 undefined를 반환해요

Response

반환값이 없어요.