Payment API

Toss POS의 결제 정보를 관리하는 API예요. 다양한 결제 수단을 지원하며, 각각의 결제 유형에 따라 다른 정보를 처리해요.

결제 유형

CARD: 카드 결제 정보
CASH: 현금 결제 정보
EXTERNAL: 외부 결제 정보
- 플러그인 내부에서 결제하는 경우 사용
- CARD, CASH 타입의 결제 취소는 Toss POS를 통해 처리

Types

PluginPaymentDto

결제 생성을 위한 데이터 전송 객체(DTO)예요. Toss POS에서만 결제를 생성할 수 있어요.

CARDCASHEXTERNAL

{
    /** 결제수단 */
    sourceType: 'CARD';
    orderId: string;
    /** 지불액 */
    amountMoney: number;
    /** 부가가치세 */
    taxMoney: number;
    /** 승인번호 */
    approvedNo: string;
    /** 승인일시 */
    approvedAt: string;
    /** 플러그인에서 발행시킨 payment의 unique한 값 중복되지 않도록 주의해주세요 */
    paymentKey: string;
    /** 공급가액 */
    supplyMoney: number;
    /** 봉사료 */
    tipMoney: number;
    /** 면세 금액. 값을 지정하지 않으면 기본으로 0원이 지정됨 */
    taxExemptMoney?: number;
    /**
     * 완료처리여부
     * default: true
     * 테이블 주문인 경우 결제가 완료되면 주문이 완료처리되어 테이블이 자동으로 비워집니다
     * false로 설정하면 결제가 완료되어도 테이블은 비워지지 않습니다
     */
    autocomplete?: boolean;
    cardDetails: {
        /** 할부개월 수 */
        installmentMonth: PluginPaymentInstallment;
        cardType: 'CREDIT' | 'DEBIT' | 'PREPAID' | 'FOREIGN';
        /** 발급사명 */
        cardBrand: string;
        /** 발급사 코드 */
        cardBrandId?: string;
        /** 카드번호 */
        cardNo: string;
        /** 매입사명 */
        source?: string;
        /** 매입사 코드 */
        sourceId?: string;
        /** 선불카드일 때 잔액 */
        balance?: number;
        /** VAN사 */
        van?: VanType;
    };
}

{
    /** 결제수단 */
    sourceType: 'CASH';
    orderId: string;
    /** 지불액 */
    amountMoney: number;
    /** 부가가치세 */
    taxMoney: number;
    /** 승인번호 */
    approvedNo: string;
    /** 승인일시 */
    approvedAt: string;
    /** 플러그인에서 발행시킨 payment의 unique한 값 중복되지 않도록 주의해주세요 */
    paymentKey: string;
    /** 공급가액 */
    supplyMoney: number;
    /** 봉사료 */
    tipMoney: number;
    /** 면세 금액. 값을 지정하지 않으면 기본으로 0원이 지정됨 */
    taxExemptMoney?: number;
    /**
     * 완료처리여부
     * default: true
     * 테이블 주문인 경우 결제가 완료되면 주문이 완료처리되어 테이블이 자동으로 비워집니다
     * false로 설정하면 결제가 완료되어도 테이블은 비워지지 않습니다
     */
    autocomplete?: boolean;
    /** 현금영수증 정보 */
    cashReceipt?: {
        /** 현금영수증 식별번호 */
        identityNumber: string;
        /**
         * 현금영수증 발급 유형
         * CONSUMER: 개인
         * BUSINESSES: 사업자
         */
        issuerType: 'CONSUMER' | 'BUSINESSES';
        /**
         * PHONE: 휴대폰번호
         * BUSINESS_NUMBER: 사업자번호
         * CARD: 현금영수증 카드
         */
        issuanceType: 'PHONE' | 'BUSINESS_NUMBER' | 'CARD';
        /** 자진 발급 여부 */
        selfIssuance: boolean;
    };
}

{
    /** 결제수단 */
    sourceType: 'EXTERNAL';
    orderId: string;
    /** 지불액 */
    amountMoney: number;
    /** 부가가치세 */
    taxMoney: number;
    /** 승인번호 */
    approvedNo: string;
    /** 승인일시 */
    approvedAt: string;
    /** 플러그인에서 발행시킨 payment의 unique한 값 중복되지 않도록 주의해주세요 */
    paymentKey: string;
    /** 공급가액 */
    supplyMoney: number;
    /** 봉사료 */
    tipMoney: number;
    /** 면세 금액. 값을 지정하지 않으면 기본으로 0원이 지정됨 */
    taxExemptMoney?: number;
    /**
     * 완료처리여부
     * default: true
     * 테이블 주문인 경우 결제가 완료되면 주문이 완료처리되어 테이블이 자동으로 비워집니다
     * false로 설정하면 결제가 완료되어도 테이블은 비워지지 않습니다
     */
    autocomplete?: boolean;
}

PluginPayment

POS에서 생성된 결제 정보를 나타내는 객체예요.

{
  /** 결제수단 */
  sourceType: 'CARD';
  id: string;
  orderId: string;
  /** 결제상태 */
  state: 'APPROVED' | 'COMPLETED' | 'CANCELLED';
  /** 지불액 */
  amountMoney: number;
  /** 부가가치세 */
  taxMoney: number;
  /** 공급가액 */
  supplyMoney: number;
  /** 봉사료 */
  tipMoney: number;
  /** 면세 금액. 값을 지정하지 않으면 기본으로 0원이 지정됨 */
  taxExemptMoney?: number;
  /** 승인번호 */
  approvedNo: string;
  /** 승인일시 */
  approvedAt: string;
  /** 취소거래인 경우에만 값 존재 */
  cancelledAt?: string;
  /** 플러그인에서 발행시킨 payment의 unique한 값 중복되지 않도록 주의해주세요 */
  paymentKey: string;
  /** 현금영수증 정보. 계좌이체가 추가되면서 현금 결제가 아니어도 발행될 수 있어요 */
  cashReceipt?: {
    /** 현금영수증 식별번호 */
    identityNumber: string;
    /** CONSUMER: 개인, BUSINESSES: 사업자 */
    issuerType: 'CONSUMER' | 'BUSINESSES';
    /** PHONE: 휴대폰번호, BUSINESS_NUMBER: 사업자번호, CARD: 현금영수증 카드 */
    issuanceType: 'PHONE' | 'BUSINESS_NUMBER' | 'CARD';
    /** 자진 발급 여부 */
    selfIssuance: boolean;
  };
  cardDetails: {
    /** 할부개월 수 */
    installmentMonth: PluginPaymentInstallment;
    cardType: 'CREDIT' | 'DEBIT' | 'PREPAID' | 'FOREIGN';
    /** 발급사명 */
    cardBrand: string;
    /** 발급사 코드 */
    cardBrandId?: string;
    /** 카드번호 */
    cardNo: string;
    /** 매입사명 */
    source?: string;
    /** 매입사 코드 */
    sourceId?: string;
    /** 선불카드일 때 잔액 */
    balance?: number;
    /** VAN사 */
    van?: VanType;
  };
}

{
  /** 결제수단 */
  sourceType: 'CASH';
  id: string;
  orderId: string;
  /** 결제상태 */
  state: 'APPROVED' | 'COMPLETED' | 'CANCELLED';
  /** 지불액 */
  amountMoney: number;
  /** 부가가치세 */
  taxMoney: number;
  /** 공급가액 */
  supplyMoney: number;
  /** 봉사료 */
  tipMoney: number;
  /** 면세 금액. 값을 지정하지 않으면 기본으로 0원이 지정됨 */
  taxExemptMoney?: number;
  /** 승인번호 */
  approvedNo: string;
  /** 승인일시 */
  approvedAt: string;
  /** 취소거래인 경우에만 값 존재 */
  cancelledAt?: string;
  /** 플러그인에서 발행시킨 payment의 unique한 값 중복되지 않도록 주의해주세요 */
  paymentKey: string;
  /** 현금영수증 정보. 계좌이체가 추가되면서 현금 결제가 아니어도 발행될 수 있어요 */
  cashReceipt?: {
    /** 현금영수증 식별번호 */
    identityNumber: string;
    /** CONSUMER: 개인, BUSINESSES: 사업자 */
    issuerType: 'CONSUMER' | 'BUSINESSES';
    /** PHONE: 휴대폰번호, BUSINESS_NUMBER: 사업자번호, CARD: 현금영수증 카드 */
    issuanceType: 'PHONE' | 'BUSINESS_NUMBER' | 'CARD';
    /** 자진 발급 여부 */
    selfIssuance: boolean;
  };
}

{
  /** 결제수단 */
  sourceType: 'EXTERNAL';
  id: string;
  orderId: string;
  /** 결제상태 */
  state: 'APPROVED' | 'COMPLETED' | 'CANCELLED';
  /** 지불액 */
  amountMoney: number;
  /** 부가가치세 */
  taxMoney: number;
  /** 공급가액 */
  supplyMoney: number;
  /** 봉사료 */
  tipMoney: number;
  /** 면세 금액. 값을 지정하지 않으면 기본으로 0원이 지정됨 */
  taxExemptMoney?: number;
  /** 승인번호 */
  approvedNo: string;
  /**
   * 승인일시
   */
  approvedAt: string;
  /** 취소거래인 경우에만 값 존재 */
  cancelledAt?: string;
  /** 플러그인에서 발행시킨 payment의 unique한 값 중복되지 않도록 주의해주세요 */
  paymentKey: string;
  /** 현금영수증 정보. 계좌이체가 추가되면서 현금 결제가 아니어도 발행될 수 있어요 */
  cashReceipt?: {
    /** 현금영수증 식별번호 */
    identityNumber: string;
    /** CONSUMER: 개인, BUSINESSES: 사업자 */
    issuerType: 'CONSUMER' | 'BUSINESSES';
    /** PHONE: 휴대폰번호, BUSINESS_NUMBER: 사업자번호, CARD: 현금영수증 카드 */
    issuanceType: 'PHONE' | 'BUSINESS_NUMBER' | 'CARD';
    /** 자진 발급 여부 */
    selfIssuance: boolean;
  };
  externalDetails: {
    /** 결제가 발생 된 플러그인 or 기타결제 원천 (ex ZERO PAY...) */
    source?: string;
    /** 결제수단 */
    sourceId?: string;
  };
}

{
  /** 결제수단. VAN을 통한 바코드/QR 간편결제 */
  sourceType: 'BARCODE';
  id: string;
  orderId: string;
  /** 결제상태 */
  state: 'APPROVED' | 'COMPLETED' | 'CANCELLED';
  /** 지불액 */
  amountMoney: number;
  /** 부가가치세 */
  taxMoney: number;
  /** 공급가액 */
  supplyMoney: number;
  /** 봉사료 */
  tipMoney: number;
  /** 면세 금액. 값을 지정하지 않으면 기본으로 0원이 지정됨 */
  taxExemptMoney?: number;
  /** 승인번호 */
  approvedNo: string;
  /** 승인일시 */
  approvedAt: string;
  /** 취소거래인 경우에만 값 존재 */
  cancelledAt?: string;
  /** 플러그인에서 발행시킨 payment의 unique한 값 중복되지 않도록 주의해주세요 */
  paymentKey: string;
  /** 현금영수증 정보. 계좌이체가 추가되면서 현금 결제가 아니어도 발행될 수 있어요 */
  cashReceipt?: {
    /** 현금영수증 식별번호 */
    identityNumber: string;
    /** CONSUMER: 개인, BUSINESSES: 사업자 */
    issuerType: 'CONSUMER' | 'BUSINESSES';
    /** PHONE: 휴대폰번호, BUSINESS_NUMBER: 사업자번호, CARD: 현금영수증 카드 */
    issuanceType: 'PHONE' | 'BUSINESS_NUMBER' | 'CARD';
    /** 자진 발급 여부 */
    selfIssuance: boolean;
  };
  externalDetails: {
    /** 할부개월 수 */
    installmentMonth: PluginPaymentInstallment;
    /** 발급사명 (예: 토스페이, 네이버체크, 카카오페이머니) */
    source: string;
    /** 간편결제 구분자 (예: KKF, SG2, ZRP) */
    sourceId: string;
    sourceType?: 'CARD' | 'BANK_TRANSFER' | 'OTHER_GIFT_CARD' | 'POINT' | 'COUPON' | 'OTHER';
    /** 매입사명 */
    cardBrand?: string;
    cardNo?: string;
  };
}

{
  /** 결제수단 */
  sourceType: 'ACCOUNT_TRANSFER';
  id: string;
  orderId: string;
  /** 결제상태 */
  state: 'APPROVED' | 'COMPLETED' | 'CANCELLED';
  /** 지불액 */
  amountMoney: number;
  /** 부가가치세 */
  taxMoney: number;
  /** 공급가액 */
  supplyMoney: number;
  /** 봉사료 */
  tipMoney: number;
  /** 면세 금액. 값을 지정하지 않으면 기본으로 0원이 지정됨 */
  taxExemptMoney?: number;
  /** 승인번호 */
  approvedNo: string;
  /** 승인일시 */
  approvedAt: string;
  /** 취소거래인 경우에만 값 존재 */
  cancelledAt?: string;
  /** 플러그인에서 발행시킨 payment의 unique한 값 중복되지 않도록 주의해주세요 */
  paymentKey: string;
  /** 현금영수증 정보. 계좌이체가 추가되면서 현금 결제가 아니어도 발행될 수 있어요 */
  cashReceipt?: {
    /** 현금영수증 식별번호 */
    identityNumber: string;
    /** CONSUMER: 개인, BUSINESSES: 사업자 */
    issuerType: 'CONSUMER' | 'BUSINESSES';
    /** PHONE: 휴대폰번호, BUSINESS_NUMBER: 사업자번호, CARD: 현금영수증 카드 */
    issuanceType: 'PHONE' | 'BUSINESS_NUMBER' | 'CARD';
    /** 자진 발급 여부 */
    selfIssuance: boolean;
  };
  accountTransfer: {
    /** 은행코드 */
    bankCode: number;
    /** 계좌번호 */
    accountNumber: string;
  };
}

PluginPaymentInstallment

할부개월 수를 나타내는 두 자리 문자열이에요. '00'부터 '99'까지 쓸 수 있어요.

type PluginPaymentInstallment = '00' | '01' | ... | '99';

값	설명
`'00'`	일시불. 현금IC의 경우 일반거래
`'01'`	1개월 할부. 현금IC의 경우 간소화 거래(비밀번호 입력 생략)
`'02'` 이상	해당 개월 수의 할부

VanType

카드 결제를 처리한 VAN사예요. PluginPaymentDto와 PluginPayment의 cardDetails.van이 이 타입을 사용해요.

type VanType = 'NICE' | 'KIS' | 'SMARTRO' | 'KOVAN';

Methods

add

주문에 결제 정보를 추가해요. 결제가 완료된 후 실행해요.

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

const order = { id: orderId };
const pluginPayment = await posPluginSdk.payment.add(order, paymentDto);

Parameters

파라미터	타입	필수	설명
`order.id`	`string`	O	결제를 추가할 주문의 ID
`paymentDto`	`PluginPaymentDto`	O	등록할 결제 정보

Response

Promise<PluginPayment> — 등록된 결제 정보예요. 생성할 수 있는 결제는 CARD·CASH·EXTERNAL 세 가지라서, 반환값도 이 중 하나의 형태로 내려와요.

getPayment

결제 정보를 조회해요.

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

const payment = await posPluginSdk.payment.getPayment(paymentId);

Parameters

파라미터	타입	필수	설명
`paymentId`	`string`	O	조회할 결제의 ID

Response

Promise<PluginPayment> — 조회한 결제 정보예요. POS에서 만들어진 결제까지 조회되므로 BARCODE·ACCOUNT_TRANSFER 형태도 내려올 수 있어요.

cancel

주문의 결제를 취소해요.

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

const order = { id: orderId };
const payment = { id: paymentId };
await posPluginSdk.payment.cancel(order, payment);

Parameters

파라미터	타입	필수	설명
`order.id`	`string`	O	취소할 결제가 속한 주문의 ID
`payment.id`	`string`	O	취소할 결제의 ID

Response

반환값이 없어요.

on

결제 상태 변경 이벤트를 수신하기 위한 핸들러를 등록해요.

Parameters

파라미터	타입	필수	설명
`event`	`'paid'` \| `'cancel'` \| `'before-cancel'`	O	구독할 이벤트
`callback`	`(paymentId: string, orderId: string) => void`	O	`paid`·`cancel` 이벤트의 콜백
`callback`	`(payload: { order: PluginOrder; payment: PluginPayment }) => Promise<void>`	O	`before-cancel` 이벤트의 콜백

Response

반환값이 없어요.

paid

결제가되었을 때 실행돼요.
order의 결제가 완료되었을때 발생되는 것이 아닌 order에 결제가 발생할때 마다 발생해요.
- 한 주문을 3번에 나누어 분할결제했다면 paid가 3번 발생해요.
order.paymentPrice.paymentUnpaidValue가 0원이라면 전체 결제가 완료된 건이에요.

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

posPluginSdk.payment.on('paid', (paymentId: string, orderId: string) => {
    // 결제 처리 로직
});

cancel

결제가 취소되었을 때 실행돼요.
order가 취소되었을때 발생되는 것이 아닌 결제가 취소가 되었을 때 발생해요.
- 한 주문을 3번에 나누어 분할결제했고 3건을 모두 취소한다면 cancel 이벤트가 3번 발생해요.
order.paymentPrice.paymentPaidValue가 0원이라면 전체 취소가 완료된 건이에요.

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

posPluginSdk.payment.on('cancel', (paymentId: string, orderId: string) => {
    // 결제 취소 처리 로직
});

before-cancel

협력사 전용 기능

before-cancel 이벤트는 허락된 협력사만 사용할 수 있어요. 이 기능을 사용하려면 토스플레이스에 문의해주세요.

결제가 취소되기 직전에 실행돼요.
콜백은 Promise<void>를 반환하며, 반환된 Promise가 완료된 후 실제 취소가 진행돼요.
- 취소 전에 처리해야 하는 로직(외부 결제 취소 등)을 여기에서 수행할 수 있어요.
콜백에는 paymentId, orderId 대신 order(PluginOrder), payment(PluginPayment) 객체가 함께 전달돼요.

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

posPluginSdk.payment.on('before-cancel', async ({ order, payment }) => {
    // 결제 취소 전 처리 로직
});

Payment API ​

결제 유형 ​

Types ​

PluginPaymentDto ​

PluginPayment ​

PluginPaymentInstallment ​

VanType ​

Methods ​

add ​

Parameters ​

Response ​

getPayment ​

Parameters ​

Response ​

cancel ​

Parameters ​

Response ​

on ​

Parameters ​

Response ​

paid ​

cancel ​

before-cancel ​

Payment API

결제 유형

Types

PluginPaymentDto

PluginPayment

PluginPaymentInstallment

VanType

Methods

add

Parameters

Response

getPayment

Parameters

Response

cancel

Parameters

Response

on

Parameters

Response

paid

cancel

before-cancel