From 042e9469c91d9efbe2ef1ac9bd3769c4500526d5 Mon Sep 17 00:00:00 2001 From: Jeongho Nam Date: Fri, 16 Feb 2024 01:03:51 +0900 Subject: [PATCH] Upgrade `nestia` dependencies. For one month, `typia` and `@nestia/sdk` had been changed a lot, with many new features and fixing trivial bugs. This PR updates those `typia` and `nestia` dependencies, so that accept new features and also avoid potential bugs. --- package.json | 2 +- packages/fake-iamport-server/nestia.config.ts | 5 +- packages/fake-iamport-server/package.json | 10 +- .../api/functional/certifications/index.ts | 6 +- .../functional/certifications/otp/index.ts | 16 +- .../src/api/functional/internal/index.ts | 6 +- .../src/api/functional/payments/index.ts | 14 +- .../src/api/functional/receipts/index.ts | 12 +- .../functional/subscribe/customers/index.ts | 12 +- .../functional/subscribe/payments/index.ts | 14 +- .../src/api/functional/users/index.ts | 8 +- .../src/api/functional/vbanks/index.ts | 14 +- .../nestia.config.ts | 5 +- .../fake-toss-payments-server/package.json | 10 +- .../src/api/functional/internal/index.ts | 8 +- .../v1/billing/authorizations/card/index.ts | 8 +- .../v1/billing/authorizations/index.ts | 8 +- .../src/api/functional/v1/billing/index.ts | 8 +- .../api/functional/v1/cash_receipts/index.ts | 14 +- .../src/api/functional/v1/payments/index.ts | 22 +- .../functional/v1/virtual_accounts/index.ts | 8 +- packages/iamport-server-api/package.json | 6 +- packages/iamport-server-api/swagger.json | 2789 ++++++++++++- packages/payment-api/package.json | 10 +- packages/payment-api/swagger.json | 3684 ++++++++++++++++- packages/payment-backend/nestia.config.ts | 5 +- packages/payment-backend/package.json | 18 +- .../functional/monitors/performance/index.ts | 4 +- .../api/functional/monitors/system/index.ts | 4 +- .../functional/payments/histories/index.ts | 26 +- .../api/functional/payments/internal/index.ts | 6 +- .../functional/payments/reservations/index.ts | 20 +- .../api/functional/payments/webhooks/index.ts | 10 +- .../toss-payments-server-api/package.json | 6 +- .../toss-payments-server-api/swagger.json | 2362 ++++++++++- 35 files changed, 8998 insertions(+), 162 deletions(-) diff --git a/package.json b/package.json index 644d0dd..cbf1d4a 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "private": true, "name": "@samchon/payments", - "version": "6.0.5", + "version": "6.0.6", "description": "Collection of Payment system of Samchon", "scripts": { "package:latest": "node deploy latest", diff --git a/packages/fake-iamport-server/nestia.config.ts b/packages/fake-iamport-server/nestia.config.ts index 9336c88..c1456e1 100644 --- a/packages/fake-iamport-server/nestia.config.ts +++ b/packages/fake-iamport-server/nestia.config.ts @@ -1,10 +1,11 @@ import type { INestiaConfig } from "@nestia/sdk"; import { NestFactory } from "@nestjs/core"; +import { FastifyAdapter } from "@nestjs/platform-fastify"; import { FakeIamportModule } from "./src/FakeIamportModule"; const NESTIA_CONFIG: INestiaConfig = { - input: () => NestFactory.create(FakeIamportModule), + input: () => NestFactory.create(FakeIamportModule, new FastifyAdapter()), output: "src/api", distribute: "../iamport-server-api", swagger: { @@ -31,6 +32,8 @@ const NESTIA_CONFIG: INestiaConfig = { in: "header", }, }, + beautify: true, }, + primitive: false, }; export default NESTIA_CONFIG; diff --git a/packages/fake-iamport-server/package.json b/packages/fake-iamport-server/package.json index deacbd8..1e80129 100644 --- a/packages/fake-iamport-server/package.json +++ b/packages/fake-iamport-server/package.json @@ -1,6 +1,6 @@ { "name": "fake-iamport-server", - "version": "6.0.5", + "version": "6.0.6", "description": "Fake iamport server for testing", "main": "lib/index.js", "typings": "lib/index.d.ts", @@ -38,7 +38,7 @@ }, "homepage": "https://github.com/samchon/fake-iamport-server", "devDependencies": { - "@nestia/sdk": "^2.5.1", + "@nestia/sdk": "^2.5.8", "@types/atob": "^2.1.2", "@types/btoa": "^1.2.3", "@types/cli": "^0.11.19", @@ -57,9 +57,9 @@ "typescript": "^5.3.2" }, "dependencies": { - "@nestia/core": "^2.5.1", + "@nestia/core": "^2.5.8", "@nestia/e2e": "^0.4.1", - "@nestia/fetcher": "^2.5.1", + "@nestia/fetcher": "^2.5.8", "@nestjs/common": "^10.2.8", "@nestjs/core": "^10.2.8", "@nestjs/platform-fastify": "^10.2.8", @@ -70,7 +70,7 @@ "source-map-support": "^0.5.19", "tstl": "^2.5.13", "typescript-transform-paths": "^3.4.6", - "typia": "^5.4.1", + "typia": "^5.4.9", "uuid": "^9.0.0" }, "keywords": [ diff --git a/packages/fake-iamport-server/src/api/functional/certifications/index.ts b/packages/fake-iamport-server/src/api/functional/certifications/index.ts index 09691ac..e270793 100644 --- a/packages/fake-iamport-server/src/api/functional/certifications/index.ts +++ b/packages/fake-iamport-server/src/api/functional/certifications/index.ts @@ -4,7 +4,7 @@ * @nestia Generated by Nestia - https://github.com/samchon/nestia */ //================================================================ -import type { IConnection, Primitive } from "@nestia/fetcher"; +import type { IConnection } from "@nestia/fetcher"; import { PlainFetcher } from "@nestia/fetcher/lib/PlainFetcher"; import type { IIamportCertification } from "../../structures/IIamportCertification"; @@ -41,7 +41,7 @@ export async function at( }); } export namespace at { - export type Output = Primitive>; + export type Output = IIamportResponse; export const METADATA = { method: "GET", @@ -80,7 +80,7 @@ export async function erase( }); } export namespace erase { - export type Output = Primitive>; + export type Output = IIamportResponse; export const METADATA = { method: "DELETE", diff --git a/packages/fake-iamport-server/src/api/functional/certifications/otp/index.ts b/packages/fake-iamport-server/src/api/functional/certifications/otp/index.ts index 76d2df9..37e6dab 100644 --- a/packages/fake-iamport-server/src/api/functional/certifications/otp/index.ts +++ b/packages/fake-iamport-server/src/api/functional/certifications/otp/index.ts @@ -4,7 +4,7 @@ * @nestia Generated by Nestia - https://github.com/samchon/nestia */ //================================================================ -import type { IConnection, Primitive } from "@nestia/fetcher"; +import type { IConnection } from "@nestia/fetcher"; import { PlainFetcher } from "@nestia/fetcher/lib/PlainFetcher"; import type { IIamportCertification } from "../../../structures/IIamportCertification"; @@ -34,7 +34,7 @@ import type { IIamportResponse } from "../../../structures/IIamportResponse"; */ export async function request( connection: IConnection, - input: request.Input, + input: IIamportCertification.ICreate, ): Promise { return PlainFetcher.fetch( { @@ -52,10 +52,8 @@ export async function request( ); } export namespace request { - export type Input = Primitive; - export type Output = Primitive< - IIamportResponse - >; + export type Input = IIamportCertification.ICreate; + export type Output = IIamportResponse; export const METADATA = { method: "POST", @@ -99,7 +97,7 @@ export namespace request { export async function confirm( connection: IConnection, imp_uid: string, - input: confirm.Input, + input: IIamportCertification.IConfirm, ): Promise { return PlainFetcher.fetch( { @@ -117,8 +115,8 @@ export async function confirm( ); } export namespace confirm { - export type Input = Primitive; - export type Output = Primitive>; + export type Input = IIamportCertification.IConfirm; + export type Output = IIamportResponse; export const METADATA = { method: "POST", diff --git a/packages/fake-iamport-server/src/api/functional/internal/index.ts b/packages/fake-iamport-server/src/api/functional/internal/index.ts index c2f26f9..54f9070 100644 --- a/packages/fake-iamport-server/src/api/functional/internal/index.ts +++ b/packages/fake-iamport-server/src/api/functional/internal/index.ts @@ -4,7 +4,7 @@ * @nestia Generated by Nestia - https://github.com/samchon/nestia */ //================================================================ -import type { IConnection, Primitive } from "@nestia/fetcher"; +import type { IConnection } from "@nestia/fetcher"; import { PlainFetcher } from "@nestia/fetcher/lib/PlainFetcher"; import type { IIamportPayment } from "../../structures/IIamportPayment"; @@ -30,7 +30,7 @@ import type { IIamportPayment } from "../../structures/IIamportPayment"; */ export async function webhook( connection: IConnection, - input: webhook.Input, + input: IIamportPayment.IWebhook, ): Promise { return PlainFetcher.fetch( { @@ -48,7 +48,7 @@ export async function webhook( ); } export namespace webhook { - export type Input = Primitive; + export type Input = IIamportPayment.IWebhook; export const METADATA = { method: "POST", diff --git a/packages/fake-iamport-server/src/api/functional/payments/index.ts b/packages/fake-iamport-server/src/api/functional/payments/index.ts index 3234496..a4a8c98 100644 --- a/packages/fake-iamport-server/src/api/functional/payments/index.ts +++ b/packages/fake-iamport-server/src/api/functional/payments/index.ts @@ -4,7 +4,7 @@ * @nestia Generated by Nestia - https://github.com/samchon/nestia */ //================================================================ -import type { IConnection, Resolved, Primitive } from "@nestia/fetcher"; +import type { IConnection } from "@nestia/fetcher"; import { PlainFetcher } from "@nestia/fetcher/lib/PlainFetcher"; import type { IIamportPayment } from "../../structures/IIamportPayment"; @@ -29,7 +29,7 @@ import type { IIamportResponse } from "../../structures/IIamportResponse"; export async function at( connection: IConnection, imp_uid: string, - query: at.Query, + query: IIamportPayment.IQuery, ): Promise { return PlainFetcher.fetch(connection, { ...at.METADATA, @@ -37,8 +37,8 @@ export async function at( }); } export namespace at { - export type Query = Resolved; - export type Output = Primitive>; + export type Query = IIamportPayment.IQuery; + export type Output = IIamportResponse; export const METADATA = { method: "GET", @@ -81,7 +81,7 @@ export namespace at { */ export async function cancel( connection: IConnection, - input: cancel.Input, + input: IIamportPaymentCancel.ICreate, ): Promise { return PlainFetcher.fetch( { @@ -99,8 +99,8 @@ export async function cancel( ); } export namespace cancel { - export type Input = Primitive; - export type Output = Primitive>; + export type Input = IIamportPaymentCancel.ICreate; + export type Output = IIamportResponse; export const METADATA = { method: "POST", diff --git a/packages/fake-iamport-server/src/api/functional/receipts/index.ts b/packages/fake-iamport-server/src/api/functional/receipts/index.ts index 770a30d..3a6e083 100644 --- a/packages/fake-iamport-server/src/api/functional/receipts/index.ts +++ b/packages/fake-iamport-server/src/api/functional/receipts/index.ts @@ -4,7 +4,7 @@ * @nestia Generated by Nestia - https://github.com/samchon/nestia */ //================================================================ -import type { IConnection, Primitive } from "@nestia/fetcher"; +import type { IConnection } from "@nestia/fetcher"; import { PlainFetcher } from "@nestia/fetcher/lib/PlainFetcher"; import type { IIamportReceipt } from "../../structures/IIamportReceipt"; @@ -32,7 +32,7 @@ export async function at( }); } export namespace at { - export type Output = Primitive>; + export type Output = IIamportResponse; export const METADATA = { method: "GET", @@ -65,7 +65,7 @@ export namespace at { export async function create( connection: IConnection, imp_uid: string, - input: create.Input, + input: IIamportReceipt.ICreate, ): Promise { return PlainFetcher.fetch( { @@ -83,8 +83,8 @@ export async function create( ); } export namespace create { - export type Input = Primitive; - export type Output = Primitive>; + export type Input = IIamportReceipt.ICreate; + export type Output = IIamportResponse; export const METADATA = { method: "POST", @@ -126,7 +126,7 @@ export async function erase( }); } export namespace erase { - export type Output = Primitive>; + export type Output = IIamportResponse; export const METADATA = { method: "DELETE", diff --git a/packages/fake-iamport-server/src/api/functional/subscribe/customers/index.ts b/packages/fake-iamport-server/src/api/functional/subscribe/customers/index.ts index d2f3ee5..bc644f3 100644 --- a/packages/fake-iamport-server/src/api/functional/subscribe/customers/index.ts +++ b/packages/fake-iamport-server/src/api/functional/subscribe/customers/index.ts @@ -4,7 +4,7 @@ * @nestia Generated by Nestia - https://github.com/samchon/nestia */ //================================================================ -import type { IConnection, Primitive } from "@nestia/fetcher"; +import type { IConnection } from "@nestia/fetcher"; import { PlainFetcher } from "@nestia/fetcher/lib/PlainFetcher"; import type { IIamportResponse } from "../../../structures/IIamportResponse"; @@ -36,7 +36,7 @@ export async function at( }); } export namespace at { - export type Output = Primitive>; + export type Output = IIamportResponse; export const METADATA = { method: "GET", @@ -78,7 +78,7 @@ export namespace at { export async function create( connection: IConnection, customer_uid: string, - input: create.Input, + input: IIamportSubscription.ICreate, ): Promise { return PlainFetcher.fetch( { @@ -96,8 +96,8 @@ export async function create( ); } export namespace create { - export type Input = Primitive; - export type Output = Primitive>; + export type Input = IIamportSubscription.ICreate; + export type Output = IIamportResponse; export const METADATA = { method: "POST", @@ -141,7 +141,7 @@ export async function erase( }); } export namespace erase { - export type Output = Primitive>; + export type Output = IIamportResponse; export const METADATA = { method: "DELETE", diff --git a/packages/fake-iamport-server/src/api/functional/subscribe/payments/index.ts b/packages/fake-iamport-server/src/api/functional/subscribe/payments/index.ts index d56be2e..54e257f 100644 --- a/packages/fake-iamport-server/src/api/functional/subscribe/payments/index.ts +++ b/packages/fake-iamport-server/src/api/functional/subscribe/payments/index.ts @@ -4,7 +4,7 @@ * @nestia Generated by Nestia - https://github.com/samchon/nestia */ //================================================================ -import type { IConnection, Primitive } from "@nestia/fetcher"; +import type { IConnection } from "@nestia/fetcher"; import { PlainFetcher } from "@nestia/fetcher/lib/PlainFetcher"; import type { IIamportCardPayment } from "../../../structures/IIamportCardPayment"; @@ -41,7 +41,7 @@ import type { IIamportSubscription } from "../../../structures/IIamportSubscript */ export async function onetime( connection: IConnection, - input: onetime.Input, + input: IIamportSubscription.IOnetime, ): Promise { return PlainFetcher.fetch( { @@ -59,8 +59,8 @@ export async function onetime( ); } export namespace onetime { - export type Input = Primitive; - export type Output = Primitive>; + export type Input = IIamportSubscription.IOnetime; + export type Output = IIamportResponse; export const METADATA = { method: "POST", @@ -103,7 +103,7 @@ export namespace onetime { */ export async function again( connection: IConnection, - input: again.Input, + input: IIamportSubscription.IAgain, ): Promise { return PlainFetcher.fetch( { @@ -121,8 +121,8 @@ export async function again( ); } export namespace again { - export type Input = Primitive; - export type Output = Primitive>; + export type Input = IIamportSubscription.IAgain; + export type Output = IIamportResponse; export const METADATA = { method: "POST", diff --git a/packages/fake-iamport-server/src/api/functional/users/index.ts b/packages/fake-iamport-server/src/api/functional/users/index.ts index 30d7e1a..09afa39 100644 --- a/packages/fake-iamport-server/src/api/functional/users/index.ts +++ b/packages/fake-iamport-server/src/api/functional/users/index.ts @@ -4,7 +4,7 @@ * @nestia Generated by Nestia - https://github.com/samchon/nestia */ //================================================================ -import type { IConnection, Primitive } from "@nestia/fetcher"; +import type { IConnection } from "@nestia/fetcher"; import { PlainFetcher } from "@nestia/fetcher/lib/PlainFetcher"; import type { IIamportResponse } from "../../structures/IIamportResponse"; @@ -30,7 +30,7 @@ import type { IIamportUser } from "../../structures/IIamportUser"; */ export async function getToken( connection: IConnection, - input: getToken.Input, + input: IIamportUser.IAccessor, ): Promise { return PlainFetcher.fetch( { @@ -48,8 +48,8 @@ export async function getToken( ); } export namespace getToken { - export type Input = Primitive; - export type Output = Primitive>; + export type Input = IIamportUser.IAccessor; + export type Output = IIamportResponse; export const METADATA = { method: "POST", diff --git a/packages/fake-iamport-server/src/api/functional/vbanks/index.ts b/packages/fake-iamport-server/src/api/functional/vbanks/index.ts index 6e7fff3..cb6b8ba 100644 --- a/packages/fake-iamport-server/src/api/functional/vbanks/index.ts +++ b/packages/fake-iamport-server/src/api/functional/vbanks/index.ts @@ -4,7 +4,7 @@ * @nestia Generated by Nestia - https://github.com/samchon/nestia */ //================================================================ -import type { IConnection, Primitive } from "@nestia/fetcher"; +import type { IConnection } from "@nestia/fetcher"; import { PlainFetcher } from "@nestia/fetcher/lib/PlainFetcher"; import type { IIamportResponse } from "../../structures/IIamportResponse"; @@ -24,7 +24,7 @@ import type { IIamportVBankPayment } from "../../structures/IIamportVBankPayment */ export async function create( connection: IConnection, - input: create.Input, + input: IIamportVBankPayment.ICreate, ): Promise { return PlainFetcher.fetch( { @@ -42,8 +42,8 @@ export async function create( ); } export namespace create { - export type Input = Primitive; - export type Output = Primitive>; + export type Input = IIamportVBankPayment.ICreate; + export type Output = IIamportResponse; export const METADATA = { method: "POST", @@ -76,7 +76,7 @@ export namespace create { */ export async function update( connection: IConnection, - input: update.Input, + input: IIamportVBankPayment.IUpdate, ): Promise { return PlainFetcher.fetch( { @@ -94,8 +94,8 @@ export async function update( ); } export namespace update { - export type Input = Primitive; - export type Output = Primitive>; + export type Input = IIamportVBankPayment.IUpdate; + export type Output = IIamportResponse; export const METADATA = { method: "PUT", diff --git a/packages/fake-toss-payments-server/nestia.config.ts b/packages/fake-toss-payments-server/nestia.config.ts index 50d078b..3d5e61a 100644 --- a/packages/fake-toss-payments-server/nestia.config.ts +++ b/packages/fake-toss-payments-server/nestia.config.ts @@ -1,10 +1,11 @@ import type { INestiaConfig } from "@nestia/sdk"; import { NestFactory } from "@nestjs/core"; +import { FastifyAdapter } from "@nestjs/platform-fastify"; import { FakeTossModule } from "./src/FakeTossModule"; const NESTIA_CONFIG: INestiaConfig = { - input: () => NestFactory.create(FakeTossModule), + input: () => NestFactory.create(FakeTossModule, new FastifyAdapter()), output: "src/api", distribute: "../toss-payments-server-api", swagger: { @@ -31,6 +32,8 @@ const NESTIA_CONFIG: INestiaConfig = { in: "header", }, }, + beautify: true, }, + primitive: false, }; export default NESTIA_CONFIG; diff --git a/packages/fake-toss-payments-server/package.json b/packages/fake-toss-payments-server/package.json index 4170b90..735ebf5 100644 --- a/packages/fake-toss-payments-server/package.json +++ b/packages/fake-toss-payments-server/package.json @@ -1,6 +1,6 @@ { "name": "fake-toss-payments-server", - "version": "6.0.5", + "version": "6.0.6", "description": "Fake toss-payments server for testing", "main": "lib/index.js", "typings": "lib/index.d.ts", @@ -39,7 +39,7 @@ "homepage": "https://github.com/samchon/fake-toss-payments-server", "devDependencies": { "@nestia/e2e": "^0.4.1", - "@nestia/sdk": "^2.5.1", + "@nestia/sdk": "^2.5.8", "@types/atob": "^2.1.2", "@types/btoa": "^1.2.3", "@types/cli": "^0.11.19", @@ -59,8 +59,8 @@ "typescript-transform-paths": "^3.4.6" }, "dependencies": { - "@nestia/core": "^2.5.1", - "@nestia/fetcher": "^2.5.1", + "@nestia/core": "^2.5.8", + "@nestia/fetcher": "^2.5.8", "@nestjs/common": "^10.2.8", "@nestjs/core": "^10.2.8", "@nestjs/platform-fastify": "^10.2.8", @@ -70,7 +70,7 @@ "serialize-error": "^4.1.0", "source-map-support": "^0.5.19", "tstl": "^2.5.13", - "typia": "^5.4.1", + "typia": "^5.4.9", "uuid": "^9.0.0" }, "keywords": [ diff --git a/packages/fake-toss-payments-server/src/api/functional/internal/index.ts b/packages/fake-toss-payments-server/src/api/functional/internal/index.ts index c4f9366..45130e0 100644 --- a/packages/fake-toss-payments-server/src/api/functional/internal/index.ts +++ b/packages/fake-toss-payments-server/src/api/functional/internal/index.ts @@ -4,7 +4,7 @@ * @nestia Generated by Nestia - https://github.com/samchon/nestia */ //================================================================ -import type { IConnection, Primitive } from "@nestia/fetcher"; +import type { IConnection } from "@nestia/fetcher"; import { PlainFetcher } from "@nestia/fetcher/lib/PlainFetcher"; import type { ITossPayment } from "../../structures/ITossPayment"; @@ -31,7 +31,7 @@ import type { ITossPaymentWebhook } from "../../structures/ITossPaymentWebhook"; */ export async function webhook( connection: IConnection, - input: webhook.Input, + input: ITossPaymentWebhook, ): Promise { return PlainFetcher.fetch( { @@ -49,7 +49,7 @@ export async function webhook( ); } export namespace webhook { - export type Input = Primitive; + export type Input = ITossPaymentWebhook; export const METADATA = { method: "POST", @@ -98,7 +98,7 @@ export async function deposit( }); } export namespace deposit { - export type Output = Primitive; + export type Output = ITossPayment; export const METADATA = { method: "PUT", diff --git a/packages/fake-toss-payments-server/src/api/functional/v1/billing/authorizations/card/index.ts b/packages/fake-toss-payments-server/src/api/functional/v1/billing/authorizations/card/index.ts index 50743b5..8b978ad 100644 --- a/packages/fake-toss-payments-server/src/api/functional/v1/billing/authorizations/card/index.ts +++ b/packages/fake-toss-payments-server/src/api/functional/v1/billing/authorizations/card/index.ts @@ -4,7 +4,7 @@ * @nestia Generated by Nestia - https://github.com/samchon/nestia */ //================================================================ -import type { IConnection, Primitive } from "@nestia/fetcher"; +import type { IConnection } from "@nestia/fetcher"; import { PlainFetcher } from "@nestia/fetcher/lib/PlainFetcher"; import type { ITossBilling } from "../../../../../structures/ITossBilling"; @@ -32,7 +32,7 @@ import type { ITossBilling } from "../../../../../structures/ITossBilling"; */ export async function create( connection: IConnection, - input: create.Input, + input: ITossBilling.ICreate, ): Promise { return PlainFetcher.fetch( { @@ -50,8 +50,8 @@ export async function create( ); } export namespace create { - export type Input = Primitive; - export type Output = Primitive; + export type Input = ITossBilling.ICreate; + export type Output = ITossBilling; export const METADATA = { method: "POST", diff --git a/packages/fake-toss-payments-server/src/api/functional/v1/billing/authorizations/index.ts b/packages/fake-toss-payments-server/src/api/functional/v1/billing/authorizations/index.ts index 391275c..d2742aa 100644 --- a/packages/fake-toss-payments-server/src/api/functional/v1/billing/authorizations/index.ts +++ b/packages/fake-toss-payments-server/src/api/functional/v1/billing/authorizations/index.ts @@ -4,7 +4,7 @@ * @nestia Generated by Nestia - https://github.com/samchon/nestia */ //================================================================ -import type { IConnection, Primitive } from "@nestia/fetcher"; +import type { IConnection } from "@nestia/fetcher"; import { PlainFetcher } from "@nestia/fetcher/lib/PlainFetcher"; import type { ITossBilling } from "../../../../structures/ITossBilling"; @@ -34,7 +34,7 @@ export * as card from "./card"; export async function at( connection: IConnection, billingKey: string, - input: at.Input, + input: ITossBilling.ICustomerKey, ): Promise { return PlainFetcher.fetch( { @@ -52,8 +52,8 @@ export async function at( ); } export namespace at { - export type Input = Primitive; - export type Output = Primitive; + export type Input = ITossBilling.ICustomerKey; + export type Output = ITossBilling; export const METADATA = { method: "POST", diff --git a/packages/fake-toss-payments-server/src/api/functional/v1/billing/index.ts b/packages/fake-toss-payments-server/src/api/functional/v1/billing/index.ts index 403aae7..0359a61 100644 --- a/packages/fake-toss-payments-server/src/api/functional/v1/billing/index.ts +++ b/packages/fake-toss-payments-server/src/api/functional/v1/billing/index.ts @@ -4,7 +4,7 @@ * @nestia Generated by Nestia - https://github.com/samchon/nestia */ //================================================================ -import type { IConnection, Primitive } from "@nestia/fetcher"; +import type { IConnection } from "@nestia/fetcher"; import { PlainFetcher } from "@nestia/fetcher/lib/PlainFetcher"; import type { ITossBilling } from "../../../structures/ITossBilling"; @@ -42,7 +42,7 @@ export * as authorizations from "./authorizations"; export async function pay( connection: IConnection, billingKey: string, - input: pay.Input, + input: ITossBilling.IPaymentStore, ): Promise { return PlainFetcher.fetch( { @@ -60,8 +60,8 @@ export async function pay( ); } export namespace pay { - export type Input = Primitive; - export type Output = Primitive; + export type Input = ITossBilling.IPaymentStore; + export type Output = ITossPayment; export const METADATA = { method: "POST", diff --git a/packages/fake-toss-payments-server/src/api/functional/v1/cash_receipts/index.ts b/packages/fake-toss-payments-server/src/api/functional/v1/cash_receipts/index.ts index 0010990..de68704 100644 --- a/packages/fake-toss-payments-server/src/api/functional/v1/cash_receipts/index.ts +++ b/packages/fake-toss-payments-server/src/api/functional/v1/cash_receipts/index.ts @@ -4,7 +4,7 @@ * @nestia Generated by Nestia - https://github.com/samchon/nestia */ //================================================================ -import type { IConnection, Primitive } from "@nestia/fetcher"; +import type { IConnection } from "@nestia/fetcher"; import { PlainFetcher } from "@nestia/fetcher/lib/PlainFetcher"; import type { ITossCashReceipt } from "../../../structures/ITossCashReceipt"; @@ -23,7 +23,7 @@ import type { ITossCashReceipt } from "../../../structures/ITossCashReceipt"; */ export async function create( connection: IConnection, - input: create.Input, + input: ITossCashReceipt.ICreate, ): Promise { return PlainFetcher.fetch( { @@ -41,8 +41,8 @@ export async function create( ); } export namespace create { - export type Input = Primitive; - export type Output = Primitive; + export type Input = ITossCashReceipt.ICreate; + export type Output = ITossCashReceipt; export const METADATA = { method: "POST", @@ -77,7 +77,7 @@ export namespace create { export async function cancel( connection: IConnection, receiptKey: string, - input: cancel.Input, + input: ITossCashReceipt.ICancel, ): Promise { return PlainFetcher.fetch( { @@ -95,8 +95,8 @@ export async function cancel( ); } export namespace cancel { - export type Input = Primitive; - export type Output = Primitive; + export type Input = ITossCashReceipt.ICancel; + export type Output = ITossCashReceipt; export const METADATA = { method: "POST", diff --git a/packages/fake-toss-payments-server/src/api/functional/v1/payments/index.ts b/packages/fake-toss-payments-server/src/api/functional/v1/payments/index.ts index 39f140f..08c4e87 100644 --- a/packages/fake-toss-payments-server/src/api/functional/v1/payments/index.ts +++ b/packages/fake-toss-payments-server/src/api/functional/v1/payments/index.ts @@ -4,7 +4,7 @@ * @nestia Generated by Nestia - https://github.com/samchon/nestia */ //================================================================ -import type { IConnection, Primitive } from "@nestia/fetcher"; +import type { IConnection } from "@nestia/fetcher"; import { PlainFetcher } from "@nestia/fetcher/lib/PlainFetcher"; import type { ITossCardPayment } from "../../../structures/ITossCardPayment"; @@ -43,7 +43,7 @@ export async function at( }); } export namespace at { - export type Output = Primitive; + export type Output = ITossPayment; export const METADATA = { method: "GET", @@ -92,7 +92,7 @@ export namespace at { */ export async function key_in( connection: IConnection, - input: key_in.Input, + input: ITossCardPayment.ICreate, ): Promise { return PlainFetcher.fetch( { @@ -110,8 +110,8 @@ export async function key_in( ); } export namespace key_in { - export type Input = Primitive; - export type Output = Primitive; + export type Input = ITossCardPayment.ICreate; + export type Output = ITossCardPayment; export const METADATA = { method: "POST", @@ -156,7 +156,7 @@ export namespace key_in { export async function approve( connection: IConnection, paymentKey: string, - input: approve.Input, + input: ITossPayment.IApproval, ): Promise { return PlainFetcher.fetch( { @@ -174,8 +174,8 @@ export async function approve( ); } export namespace approve { - export type Input = Primitive; - export type Output = Primitive; + export type Input = ITossPayment.IApproval; + export type Output = ITossPayment; export const METADATA = { method: "POST", @@ -216,7 +216,7 @@ export namespace approve { export async function cancel( connection: IConnection, paymentKey: string, - input: cancel.Input, + input: ITossPaymentCancel.ICreate, ): Promise { return PlainFetcher.fetch( { @@ -234,8 +234,8 @@ export async function cancel( ); } export namespace cancel { - export type Input = Primitive; - export type Output = Primitive; + export type Input = ITossPaymentCancel.ICreate; + export type Output = ITossPayment; export const METADATA = { method: "POST", diff --git a/packages/fake-toss-payments-server/src/api/functional/v1/virtual_accounts/index.ts b/packages/fake-toss-payments-server/src/api/functional/v1/virtual_accounts/index.ts index 1d3d717..7ad39bf 100644 --- a/packages/fake-toss-payments-server/src/api/functional/v1/virtual_accounts/index.ts +++ b/packages/fake-toss-payments-server/src/api/functional/v1/virtual_accounts/index.ts @@ -4,7 +4,7 @@ * @nestia Generated by Nestia - https://github.com/samchon/nestia */ //================================================================ -import type { IConnection, Primitive } from "@nestia/fetcher"; +import type { IConnection } from "@nestia/fetcher"; import { PlainFetcher } from "@nestia/fetcher/lib/PlainFetcher"; import type { ITossVirtualAccountPayment } from "../../../structures/ITossVirtualAccountPayment"; @@ -39,7 +39,7 @@ import type { ITossVirtualAccountPayment } from "../../../structures/ITossVirtua */ export async function create( connection: IConnection, - input: create.Input, + input: ITossVirtualAccountPayment.ICreate, ): Promise { return PlainFetcher.fetch( { @@ -57,8 +57,8 @@ export async function create( ); } export namespace create { - export type Input = Primitive; - export type Output = Primitive; + export type Input = ITossVirtualAccountPayment.ICreate; + export type Output = ITossVirtualAccountPayment; export const METADATA = { method: "POST", diff --git a/packages/iamport-server-api/package.json b/packages/iamport-server-api/package.json index ac17bdb..d0de96f 100644 --- a/packages/iamport-server-api/package.json +++ b/packages/iamport-server-api/package.json @@ -1,6 +1,6 @@ { "name": "iamport-server-api", - "version": "6.0.5", + "version": "6.0.6", "description": "API for Iamport Server", "main": "lib/index.js", "typings": "lib/index.d.ts", @@ -34,7 +34,7 @@ "typescript": "^5.3.2" }, "dependencies": { - "@nestia/fetcher": "^2.5.1", - "typia": "^5.4.1" + "@nestia/fetcher": "^2.5.8", + "typia": "^5.4.9" } } \ No newline at end of file diff --git a/packages/iamport-server-api/swagger.json b/packages/iamport-server-api/swagger.json index 6c80704..db3efef 100644 --- a/packages/iamport-server-api/swagger.json +++ b/packages/iamport-server-api/swagger.json @@ -1 +1,2788 @@ -{"openapi":"3.0.1","servers":[{"url":"http://localhost:10851","description":"fake"},{"url":"https://api.iamport.kr","description":"real"}],"info":{"title":"Iamport API","description":"Built by [fake-iamport-server](https://github.com/samchon/payments/tree/master/packages/fake-iamport-server) with [nestia](https://github.com/samchon/nestia)","version":"6.0.5","license":{"name":"MIT"}},"paths":{"/subscribe/customers/{customer_uid}":{"get":{"tags":[],"parameters":[{"name":"customer_uid","in":"path","schema":{"type":"string"},"description":"고객 (간편 결제 카드) 식별자 키","required":true}],"responses":{"200":{"description":"간편 결제 카드 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportResponseIIamportSubscription"}}}}},"summary":"간편 결제 카드 정보 조회하기","description":"간편 결제 카드 정보 조회하기.\n\n`subscribe.customers.at` 은 고객이 {@link create } 나 혹은 아임포트가 제공하는\n간편 결제 카드 등록 창을 이용하여 저장한 간편 결제 카드 정보를 조회하는 API\n함수이다.","security":[{"bearer":[]}]},"post":{"tags":[],"parameters":[{"name":"customer_uid","in":"path","schema":{"type":"string"},"description":"고객 (간편 결제 카드) 식별자 키","required":true}],"requestBody":{"description":"카드 입력 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportSubscription.ICreate"}}},"required":true},"responses":{"201":{"description":"간편 결제 카드 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportResponseIIamportSubscription"}}}}},"summary":"간편 결제 카드 등록하기","description":"간편 결제 카드 등록하기.\n\n`subscribe.customers.stoer` 는 고객이 자신의 카드를 서버에 등록해두고, 매번 결제가\n필요할 때마다 카드 정보를 반복 입력하는 일 없이, 간편하게 결제를 진행하고자 할 때\n사용하는 API 함수이다.\n\n참고로 `subscribe.customers.create` 는 클라이언트 어플리케이션이 아임포트가 제공하는\n간편 결제 카드 등록 창을 사용하는 경우, 귀하의 백엔드 서버가 이를 실 서비스에서 호출하는\n일은 없을 것이다. 다만, 고객이 간편 결제 카드를 등록하는 상황을 시뮬레이션하기 위하여,\n테스트 자동화 프로그램 수준에서 사용될 수는 있다.","security":[{"bearer":[]}]},"delete":{"tags":[],"parameters":[{"name":"customer_uid","in":"path","schema":{"type":"string"},"description":"고객 (간편 결제 카드) 식별자 키","required":true}],"responses":{"200":{"description":"삭제된 간편 결제 카드 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportResponseIIamportSubscription"}}}}},"summary":"간편 결제 카드 삭제하기","description":"간편 결제 카드 삭제하기.\n\n간편 결제를 위하여 등록한 카드를 제거한다.","security":[{"bearer":[]}]}},"/subscribe/payments/onetime":{"post":{"tags":[],"parameters":[],"requestBody":{"description":"카드 결제 신청 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportSubscription.IOnetime"}}},"required":true},"responses":{"201":{"description":"카드 결제 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportResponseIIamportCardPayment"}}}}},"summary":"카드로 결제하기, 더불어 간편 결제용으로 등록 가능","description":"카드로 결제하기, 더불어 간편 결제용으로 등록 가능.\n\n`subscribe.payments.onetime` 은 카드를 매개로 한 결제를 하고자 할 때 호출하는 API\n함수이다. 더하여 입력 값에 {@link IIamportSubscription.IOnetime.customer_uid } 를\n기입하는 경우, 결제에 사용한 카드를 그대로 간편 결제용 카드\n{@link IIamportSubscription } 로 등록해버린다.\n\n다만, 정히 간편 카드 등록과 결제를 동시에 하고 싶다면,\n`subscribe.payments.onetime` 에 {@link IIamportSubscription.IOnetime.customer_uid }\n를 더하기보다, {@link subscribe.customers.create } 와 {@link subscribe.payments.again }\n을 각각 호출하는 것을 권장한다. 그것이 예외적인 상황에 보다 안전하게 대처할 수 있기\n때문이다.\n\n더하여 `subscribe.payments.onetime` 은 클라이언트 어플리케이션이 아임포트가 제공하는\n결제 창을 그대로 사용하는 경우, 귀하의 백엔드 서버가 이를 실 서비스에서 호출하는 일은\n없을 것이다. 다만, 고객이 카드를 통하여 결제하는 상황을 시뮬레이션하기 위하여, 테스트\n자동화 프로그램 수준에서 사용될 수는 있다.","security":[{"bearer":[]}]}},"/subscribe/payments/again":{"post":{"tags":[],"parameters":[],"requestBody":{"description":"미리 등록한 카드를 이용한 결제 신청 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportSubscription.IAgain"}}},"required":true},"responses":{"201":{"description":"카드 결제 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportResponseIIamportCardPayment"}}}}},"summary":"간편 결제에 등록된 카드로 결제하기","description":"간편 결제에 등록된 카드로 결제하기.\n\n`subscribe.payments.again` 은 고객이 간편 결제에 등록한 카드로 결제를 진행하고자 할 때\n호출하는 API 함수이다. 이는 간편하고 불편하고를 떠나, 본질적으로 카드 결제의 일환이기에,\n리턴값은 일반적인 카드 결제 때와 동일한 {@link IIamportCardPayment } 이다.\n\n그리고 `subscribe.payments.again` 은 결제 수단 중 유일하게, 클라이언트 어플리케이션이\n아임포트가 제공하는 결체 창을 사용할 수 없어, 오직 귀하의 백엔드 서버가 아임포트의 API\n함수를 직접 호출해야하는 경우에 해당한다. 따라서 간편 결제에 관하여 아임포트 서버와\n연동하는 백엔드 서버 및 프론트 어플리케이션을 개발할 때, 반드시 이 상황에 대한 별도의\n설계 및 개발이 필요하니, 이 점을 염두에 두기 바란다.","security":[{"bearer":[]}]}},"/certifications/{imp_uid}":{"get":{"tags":[],"parameters":[{"name":"imp_uid","in":"path","schema":{"type":"string"},"description":"대상 본인인증 정보의 ","required":true}],"responses":{"200":{"description":"본인인증 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportResponseIIamportCertification"}}}}},"summary":"본인인증 정보 열람하기","description":"본인인증 정보 열람하기.\n\n`certiciations.at` 은 본인인증 정보를 열람할 때 사용하는 API 함수이다.\n\n다만 이 API 함수를 통하여 열람한 본인인증 정보 {@link IIamportCertification } 이\n곧 OTP 인증까지 마쳐 본인인증을 모두 마친 레코드라는 보장은 없다. 본인인증의 완결\n여부는 오직, {@link IIamportCertification.certified } 값을 직접 검사해봐야만 알\n수 있기 때문이다.","security":[{"bearer":[]}]},"delete":{"tags":[],"parameters":[{"name":"imp_uid","in":"path","schema":{"type":"string"},"description":"대상 본인인증 정보의 ","required":true}],"responses":{"200":{"description":"삭제된 본인인증 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportResponseIIamportCertification"}}}}},"summary":"본인인증 정보 삭제하기","description":"본인인증 정보 삭제하기.","security":[{"bearer":[]}]}},"/certifications/otp/request":{"post":{"tags":[],"parameters":[],"requestBody":{"description":"본인인증 요청 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportCertification.ICreate"}}},"required":true},"responses":{"201":{"description":"진행 중인 본인인증의 식별자 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportResponseIIamportCertification.IAccessor"}}}}},"summary":"본인인증 요청하기","description":"본인인증 요청하기.\n\n`certifications.otp.request` 는 아임포트 서버에 본인인증을 요청하는 API 함수이다.\n이 API 를 호출하면 본인인증 대상자의 핸드폰으로 OTP 문자가 전송되며, 본인인증\n대상자가 {@link certifications.otp.confirm } 을 통하여 이 OTP 번호를 정확히\n입력함으로써, 본인인증이 완결된다.\n\n또한 본인인증 대상자가 자신의 핸드폰으로 전송된 OTP 문자를 입력하기 전에도,\n여전히해당 본인인증 내역은 {@link certifications.at } 함수를 통하여 조회할 수 있다.\n다만, 이 때 리턴되는 {@link IIamportCertification } 에서 인증의 완결 여부를\n지칭하는 {@link IIamportCertification.certified } 값은 `false` 이다.","security":[{"bearer":[]}]}},"/certifications/otp/confirm/{imp_uid}":{"post":{"tags":[],"parameters":[{"name":"imp_uid","in":"path","schema":{"type":"string"},"description":"대상 본인인증 정보의 ","required":true}],"requestBody":{"description":"OTP 코드","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportCertification.IConfirm"}}},"required":true},"responses":{"201":{"description":"인증 완료된 본인인증 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportResponseIIamportCertification"}}}}},"summary":"본인인증 시 발급된 OTP 코드 입력하기","description":"본인인증 시 발급된 OTP 코드 입력하기.\n\n`certifications.otp.confirm` 는 {@link certifications.otp.request } 를 통하여\n발급된 본인인증 건에 대하여, 본인인증 대상자의 휴대폰으로 전송된 OTP 번호를\n검증하고, 입력한 OTP 번호가 맞거든 해당 본인인증 건을 승인하여 완료 처리해주는\nAPI 함수이다.\n\n이처럼 본인인증을 완료하거든, 해당 본인인증 건 {@link IIamportCertification } 의\n{@link IIamportCertification.certified } 값이 비로소 `true` 로 변경되어,\n비로소 완결된다.","security":[{"bearer":[]}]}},"/internal/webhook":{"post":{"tags":[],"parameters":[],"requestBody":{"description":"웹훅 이벤트 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportPayment.IWebhook"}}},"required":true},"responses":{"201":{"description":""}},"summary":"웹훅 이벤트 더미 리스너","description":"웹훅 이벤트 더미 리스너.\n\n`internal.webhook` 은 실제 아임포트의 서버에는 존재하지 않는 API 로써,\n`fake-impoart-server` 의 {@link Configuration.WEBHOOK_URL } 에 아무런 URL 을 설정하지\n않으면, `fake-iamport-server` 로부터 발생하는 모든 종류의 웹훅 이벤트는 이 곳으로 전달되어\n무의미하게 사라진다.\n\n따라서 `fake-iamport-server` 를 사용하여 아임포트 서버와의 연동을 미리 검증코자 할 때는,\n반드시 {@link Configuration.WEBHOOK_URL } 를 설정하여 웹훅 이벤트가 귀하의 백엔드 서버로\n제대로 전달되도록 하자."}},"/internal/deposit/{imp_uid}":{"put":{"tags":[],"parameters":[{"name":"imp_uid","in":"path","schema":{"type":"string"},"description":"대상 결제의 ","required":true}],"responses":{"201":{"description":""}},"summary":"가상 계좌에 입금하기","description":"가상 계좌에 입금하기.\n\n`internal.deposit` 은 실제 아임포트 결제 서버에는 존재하지 않는 API 로써, 가상 계좌\n결제를 신청한 고객이, 이후 가상 계좌에 목표 금액을 입금하는 상황을 시뮬레이션 할 수 있는\n함수이다.\n\n즉, `internal.deposit` 는 고객이 스스로에게 가상으로 발급된 계좌에 입금을 하고, 그에 따라\n아임포트 서버에서 webhook 이벤트가 발생, 이를 귀하의 백엔드 서버로 전송하는 일련의 상황을\n시뮬레이션하기 위하여 설계된 테스트 함수다.","security":[{"bearer":[]}]}},"/payments/{imp_uid}":{"get":{"tags":[],"parameters":[{"name":"imp_uid","in":"path","schema":{"type":"string"},"description":"대상 결제 기록의 ","required":true},{"name":"query","in":"query","schema":{"$ref":"#/components/schemas/IIamportPayment.IQuery"},"description":"결제 수단이 페이팔인 경우에 사용","required":true}],"responses":{"200":{"description":"결제 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportResponseIIamportPayment"}}}}},"summary":"결제 기록 열람하기","description":"결제 기록 열람하기.\n\n아임포트를 통하여 발생한 결제 기록을 열람한다.","security":[{"bearer":[]}]}},"/payments/cancel":{"post":{"tags":[],"parameters":[],"requestBody":{"description":"결제 취소 입력 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportPaymentCancel.ICreate"}}},"required":true},"responses":{"201":{"description":"취소된 결제 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportResponseIIamportPayment"}}}}},"summary":"결제 취소하기","description":"결제 취소하기.\n\n만약 가상 계좌를 통한 결제였다면, 반드시 환불 계좌 정보를 입력해줘야 한다.","security":[{"bearer":[]}]}},"/receipts/{imp_uid}":{"get":{"tags":[],"parameters":[{"name":"imp_uid","in":"path","schema":{"type":"string"},"description":"귀속 결제의 ","required":true}],"responses":{"200":{"description":"현금 영수증 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportResponseIIamportReceipt"}}}}},"summary":"현금 영수증 조회하기","description":"현금 영수증 조회하기.","security":[{"bearer":[]}]},"post":{"tags":[],"parameters":[{"name":"imp_uid","in":"path","schema":{"type":"string"},"description":"귀속 결제의 ","required":true}],"requestBody":{"description":"현금 영수증 입력 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportReceipt.ICreate"}}},"required":true},"responses":{"201":{"description":"현금 영수증 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportResponseIIamportReceipt"}}}}},"summary":"현금 영수증 발행하기","description":"현금 영수증 발행하기.","security":[{"bearer":[]}]},"delete":{"tags":[],"parameters":[{"name":"imp_uid","in":"path","schema":{"type":"string"},"description":"귀속 결제의 ","required":true}],"responses":{"200":{"description":"취소된 현금 영수증 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportResponseIIamportReceipt"}}}}},"summary":"현금 영수증 취소하기","description":"현금 영수증 취소하기.","security":[{"bearer":[]}]}},"/users/getToken":{"post":{"tags":[],"parameters":[],"requestBody":{"description":"아임포트의 API 및 secret 키 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportUser.IAccessor"}}},"required":true},"responses":{"201":{"description":"유저 인증 토큰 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportResponseIIamportUser"}}}}},"summary":"유저 인증 토큰 발행하기","description":"유저 인증 토큰 발행하기.\n\n아임포트에 가입하여 부여받은 API 및 secret 키를 토대로, 유저 인증 토큰을 발행한다.\n\n단, 아임포트가 발급해주는 유저 인증 토큰에는 유효 시간 {@link IIamportUser.expired_at }\n이 있어, 해당 시간이 지나거든 기 발급 토큰이 만료되어 더 이상 쓸 수 없게 된다. 때문에\n아임포트의 이러한 시간 제한에 구애받지 않고 자유로이 아임포트의 API 를 이용하고 싶다면,\n`iamport-server-api` 에서 제공해주는 {@link IamportConnector } 를 활용하도록 하자."}},"/vbanks":{"post":{"tags":[],"parameters":[],"requestBody":{"description":"가상 계좌 입력 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportVBankPayment.ICreate"}}},"required":true},"responses":{"201":{"description":"가상 계좌 결제 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportResponseIIamportVBankPayment"}}}}},"summary":"가상 계좌 발급하기","description":"가상 계좌 발급하기.","security":[{"bearer":[]}]},"put":{"tags":[],"parameters":[],"requestBody":{"description":"가상 계좌 편집 입력 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportVBankPayment.IUpdate"}}},"required":true},"responses":{"201":{"description":"편집된 가상 계좌 결제 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportResponseIIamportVBankPayment"}}}}},"summary":"가상 계좌 편집하기","description":"가상 계좌 편집하기.","security":[{"bearer":[]}]}}},"components":{"schemas":{"IIamportResponseIIamportSubscription":{"type":"object","properties":{"code":{"type":"number","description":"에러 코드.\n\n값이 0 이면 오류가 없다는 뜻."},"message":{"type":"string","description":"성공 또는 오류 메시지."},"response":{"$ref":"#/components/schemas/IIamportSubscription","description":"응답 데이터, 사실상 본문."}},"nullable":false,"required":["code","message","response"],"description":"아임포트 고유의 응답 데이터."},"IIamportSubscription":{"type":"object","properties":{"pg_provider":{"type":"string"},"pg_id":{"type":"string"},"card_name":{"type":"string"},"card_code":{"type":"string"},"card_number":{"type":"string"},"card_type":{"type":"string"},"customer_name":{"type":"string","nullable":true},"customer_tel":{"type":"string","nullable":true},"customer_email":{"type":"string","nullable":true},"customer_addr":{"type":"string","nullable":true},"customer_postcode":{"type":"string","nullable":true},"inserted":{"type":"number"},"updated":{"type":"number"},"customer_uid":{"type":"string","description":"고객 식별자 키.\n\n아임포트가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키.\n\n다만 고객이라기보다 실제로는 카드의 식별자 키로 써야함."}},"nullable":false,"required":["pg_provider","pg_id","card_name","card_code","card_number","card_type","customer_name","customer_tel","customer_email","customer_addr","customer_postcode","inserted","updated","customer_uid"],"description":"간편 결제 카드 정보."},"IIamportSubscription.ICreate":{"type":"object","properties":{"card_number":{"type":"string","pattern":"\\d{4}-\\d{4}-\\d{4}-\\d{4}","description":"카드 번호.\n\n형식: XXXX-XXXX-XXXX-XXXX"},"expiry":{"type":"string","pattern":"^([0-9]{4})-(0[1-9]|1[012])$","description":"카드 유효기간.\n\n형식: YYYY-MM"},"birth":{"type":"string","pattern":"^(([0-9]{2})(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01]))|(\\d{10})$","description":"생년월일 YYMMDD 또는 사업자등록번호 10자리."},"pwd_2digit":{"type":"string","pattern":"\\d{2}","description":"카드 비밀번호 앞 두 자리."},"cvc":{"type":"string","pattern":"\\d{2}","description":"카드 인증번호 (카드 뒷면 3 자리)."},"customer_name":{"type":"string"},"customer_tel":{"type":"string"},"customer_email":{"type":"string","format":"email"},"customr_addr":{"type":"string"},"customer_postcode":{"type":"string"},"customer_uid":{"type":"string","description":"고객 식별자 키.\n\n아임포트가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키.\n\n다만 고객이라기보다 실제로는 카드의 식별자 키로 써야함."}},"nullable":false,"required":["card_number","expiry","birth","customer_uid"],"description":"간편 결제 카드 입력 정보."},"IIamportSubscription.IOnetime":{"type":"object","properties":{"customer_uid":{"type":"string","description":"고객 식별자 키.\n\n아임포트가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키.\n\n다만 고객이라기보다 실제로는 카드의 식별자 키로 써야함.\n\n이를 생략시 단순 결제로만 그치며, 카드 정보가 간편 결제용으로 등록되지 아니함."},"card_number":{"type":"string","pattern":"\\d{4}-\\d{4}-\\d{4}-\\d{4}","description":"카드 번호.\n\n형식: XXXX-XXXX-XXXX-XXXX"},"expiry":{"type":"string","pattern":"^([0-9]{4})-(0[1-9]|1[012])$","description":"카드 유효기간.\n\n형식: YYYY-MM"},"birth":{"type":"string","pattern":"^(([0-9]{2})(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01]))|(\\d{10})$","description":"생년월일 YYMMDD 또는 사업자등록번호 10자리."},"pwd_2digit":{"type":"string","pattern":"\\d{2}","description":"카드 비밀번호 앞 두 자리."},"cvc":{"type":"string","pattern":"\\d{2}","description":"카드 인증번호 (카드 뒷면 3 자리)."},"customer_name":{"type":"string"},"customer_tel":{"type":"string"},"customer_email":{"type":"string","format":"email"},"customr_addr":{"type":"string"},"customer_postcode":{"type":"string"},"merchant_uid":{"type":"string","description":"주문 식별자 키.\n\n아임포트가 아닌 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키."},"amount":{"type":"number","description":"결제 총액."},"name":{"type":"string","description":"주문 이름."},"currency":{"type":"string","enum":["KRW","USD","EUR","JPY"],"description":"통화 정보."},"tax_free":{"type":"number","description":"면세 공급가액.\n\n기본값은 0 로써, 알아서 amount 의 1/11 로써 부가세 처리됨."},"card_quota":{"type":"number","description":"할부 개월 수.\n\n일시불은 0."},"buyer_name":{"type":"string"},"buyer_email":{"type":"string","format":"email"},"buyer_tel":{"type":"string"},"buyer_addr":{"type":"string"},"buyer_postcode":{"type":"string"},"interest_free_by_merchant":{"type":"boolean","description":"카드할부처리할 때, 할부이자가 발생하는 경우 (카드사 무이자 프로모션 제외).\n\n부과되는 할부이자를 고객대신 가맹점이 지불하고자 PG사와 계약된 경우(현재, 나이스페이먼츠만 지원됨)"},"use_card_point":{"type":"boolean","description":"승인요청시 카드사 포인트 차감하며 결제승인처리할지 flag.\n\nPG사 영업담당자와 계약 당시 사전 협의 필요(현재, 나이스페이먼츠만 지원됨)"},"custom_data":{"type":"string","description":"임의 정보를 기재할 수 있다."},"notice_url":{"type":"string","format":"uri","description":"결제 성공시 통지될 Notification, 웹훅 URL."}},"nullable":false,"required":["card_number","expiry","birth","merchant_uid","amount","name"],"description":"결제 신청 입력 정보."},"IIamportResponseIIamportCardPayment":{"type":"object","properties":{"code":{"type":"number","description":"에러 코드.\n\n값이 0 이면 오류가 없다는 뜻."},"message":{"type":"string","description":"성공 또는 오류 메시지."},"response":{"$ref":"#/components/schemas/IIamportCardPayment","description":"응답 데이터, 사실상 본문."}},"nullable":false,"required":["code","message","response"],"description":"아임포트 고유의 응답 데이터."},"IIamportCardPayment":{"type":"object","properties":{"card_code":{"type":"string","description":"카드 식별자 코드."},"card_name":{"type":"string","description":"카드 이름."},"card_number":{"type":"string","pattern":"\\d{4}-\\d{4}-\\d{4}-\\d{4}","description":"카드 번호."},"card_quota":{"type":"integer","description":"할부 개월 수."},"apply_num":{"type":"string","description":"카드사 승인번호."},"pay_method":{"type":"string","enum":["card","samsung"]},"imp_uid":{"type":"string","description":"결제 정보 {@link IIamportPayment } 의 식별자 키."},"merchant_uid":{"type":"string","description":"주문 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다."},"name":{"type":"string","nullable":true,"description":"주문명, 누락 가능."},"amount":{"type":"number","description":"결제 총액."},"cancel_amount":{"type":"number","description":"결제 취소, 환불 총액."},"currency":{"$ref":"#/components/schemas/IIamportPayment.Currency","description":"통화 단위."},"receipt_url":{"type":"string","format":"uri","description":"영수증 URL."},"cash_receipt_issue":{"type":"boolean","description":"현금 영수증 발행 여부."},"channel":{"type":"string"},"pg_provider":{"type":"string"},"emb_pg_provider":{"type":"string","nullable":true},"pg_id":{"type":"string"},"pg_tid":{"type":"string"},"escrow":{"type":"boolean"},"buyer_name":{"type":"string","nullable":true},"buyer_email":{"type":"string","format":"email","nullable":true},"buyer_tel":{"type":"string","nullable":true},"buyer_addr":{"type":"string","nullable":true},"buyer_postcode":{"type":"string","nullable":true},"customer_uid":{"type":"string","nullable":true},"customer_uid_usage":{"type":"string","nullable":true},"custom_data":{"type":"string","nullable":true},"user_agent":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/IIamportPayment.Status","description":"결제의 현재 (진행) 상태."},"started_at":{"type":"number","description":"결제 신청 일시.\n\n리눅스 타임이 쓰임."},"paid_at":{"type":"number","description":"결제 (지불) 완료 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"failed_at":{"type":"number","description":"결제 실패 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"cancelled_at":{"type":"number","description":"결제 취소 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"fail_reason":{"type":"string","nullable":true},"cancel_reason":{"type":"string","nullable":true},"cancel_history":{"type":"array","items":{"$ref":"#/components/schemas/IIamportPaymentCancel"}}},"nullable":false,"required":["card_code","card_name","card_number","card_quota","apply_num","pay_method","imp_uid","merchant_uid","name","amount","cancel_amount","currency","receipt_url","cash_receipt_issue","channel","pg_provider","emb_pg_provider","pg_id","pg_tid","escrow","buyer_name","buyer_email","buyer_tel","buyer_addr","buyer_postcode","customer_uid","customer_uid_usage","custom_data","user_agent","status","started_at","paid_at","failed_at","cancelled_at","fail_reason","cancel_reason","cancel_history"],"description":"카드 결제 정보."},"IIamportPayment.Currency":{"type":"string","enum":["KRW","USD","EUR","JPY"]},"IIamportPayment.Status":{"type":"string","enum":["paid","ready","failed","cancelled"]},"IIamportPaymentCancel":{"type":"object","properties":{"pg_id":{"type":"string"},"pg_tid":{"type":"string"},"amount":{"type":"number"},"cancelled_at":{"type":"number"},"reason":{"type":"string"},"receipt_url":{"type":"string","format":"uri"}},"nullable":false,"required":["pg_id","pg_tid","amount","cancelled_at","reason","receipt_url"],"description":"결제 취소 정보."},"IIamportSubscription.IAgain":{"type":"object","properties":{"merchant_uid":{"type":"string","description":"주문 식별자 키.\n\n아임포트가 아닌 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키."},"amount":{"type":"number","description":"결제 총액."},"name":{"type":"string","description":"주문 이름."},"currency":{"type":"string","enum":["KRW","USD","EUR","JPY"],"description":"통화 정보."},"tax_free":{"type":"number","description":"면세 공급가액.\n\n기본값은 0 로써, 알아서 amount 의 1/11 로써 부가세 처리됨."},"card_quota":{"type":"number","description":"할부 개월 수.\n\n일시불은 0."},"buyer_name":{"type":"string"},"buyer_email":{"type":"string","format":"email"},"buyer_tel":{"type":"string"},"buyer_addr":{"type":"string"},"buyer_postcode":{"type":"string"},"interest_free_by_merchant":{"type":"boolean","description":"카드할부처리할 때, 할부이자가 발생하는 경우 (카드사 무이자 프로모션 제외).\n\n부과되는 할부이자를 고객대신 가맹점이 지불하고자 PG사와 계약된 경우(현재, 나이스페이먼츠만 지원됨)"},"use_card_point":{"type":"boolean","description":"승인요청시 카드사 포인트 차감하며 결제승인처리할지 flag.\n\nPG사 영업담당자와 계약 당시 사전 협의 필요(현재, 나이스페이먼츠만 지원됨)"},"custom_data":{"type":"string","description":"임의 정보를 기재할 수 있다."},"notice_url":{"type":"string","format":"uri","description":"결제 성공시 통지될 Notification, 웹훅 URL."},"customer_uid":{"type":"string","description":"고객 식별자 키.\n\n아임포트가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키.\n\n다만 고객이라기보다 실제로는 카드의 식별자 키로 써야함."}},"nullable":false,"required":["merchant_uid","amount","name","customer_uid"],"description":"간편 결제 카드로 결제 신청 입력 정보."},"IIamportResponseIIamportCertification":{"type":"object","properties":{"code":{"type":"number","description":"에러 코드.\n\n값이 0 이면 오류가 없다는 뜻."},"message":{"type":"string","description":"성공 또는 오류 메시지."},"response":{"$ref":"#/components/schemas/IIamportCertification","description":"응답 데이터, 사실상 본문."}},"nullable":false,"required":["code","message","response"],"description":"아임포트 고유의 응답 데이터."},"IIamportCertification":{"type":"object","properties":{"imp_uid":{"type":"string","description":"아임포트가 발급해 준 식별자 번호."},"merchant_uid":{"type":"string","nullable":true,"description":"서비스로부터의 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다."},"name":{"type":"string","description":"본인인증대상자 성명."},"gender":{"type":"string","description":"성별."},"birth":{"type":"number","description":"생년월일.\n\n리눅스 타임이 쓰인다."},"birthday":{"type":"string","pattern":"^([0-9]{4})(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$","description":"생년월일, YYYYMMDD 형식."},"foreigner":{"type":"boolean","description":"외국인 여부."},"phone":{"type":"string","description":"본인인증 대상자 핸드폰 번호."},"carrier":{"type":"string","enum":["SKT","KT","LGT"],"description":"본인인증 대상자 통신사 코드."},"certified":{"type":"boolean","description":"OTP 인증 여부."},"certified_at":{"type":"number","description":"OTP 인증 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"unique_key":{"type":"string","description":"뭔지 잘 모름, 용도 아시는 분?"},"unique_in_site":{"type":"string","description":"뭔지 잘 모름, 용도 아시는 분?"},"pg_tid":{"type":"string","description":"뭔지 잘 모름, 용도 아시는 분?"},"pg_provider":{"type":"string","description":"PG 제공자."},"origin":{"type":"string","description":"뭔지 잘 모름, 용도 아시는 분?"},"__otp":{"type":"string","description":"(테스트 전용) OTP 코드.\n\n오직 `fake-iamport-server` 에서만 쓰이는 속성으로써, 본인인증을 시뮬레이션할 때,\n어떠한 OTP 코드가 발급되었는 지를 확인하기 위하여 사용된다. 이를 이용하여\n{@link functional.certifications.otp.confirm } 함수를 호출하면, 본인인증을 완료할\n수 있다."}},"nullable":false,"required":["imp_uid","merchant_uid","name","gender","birth","birthday","foreigner","phone","carrier","certified","certified_at","unique_key","unique_in_site","pg_tid","pg_provider","origin"],"description":"본인 인증 내역.\n\n`IIamportCertification` 은 아임포트의 본인인증 정보를 형상화한 자료구조 인터페이스이다.\n\n단, `IIamportCertification` 레코드의 존재가 곧 본인인증의 완결을 뜻하는 것은 아니다.\n{@link IIamportCertification.certified } 값이 `true` 여야만이 비로소, 본인인증\n대상자가 자신의 핸드폰 번호로 전송된 OTP 를 아임포트의 본인인증 팝업창에 정확히 적어,\n본인인증을 완료했음을 의미한다."},"IIamportCertification.ICreate":{"type":"object","properties":{"name":{"type":"string","description":"본인인증대상자 성명."},"phone":{"type":"string","description":"본인인증 대상자 핸드폰 번호.\n\n핸드폰 번호에 \"-\" 값이 들어가던 아니던 상관 없음.\n\n다만, 내부적으로는 \"-\" 값을 제거하여 처리한다."},"birth":{"type":"string","pattern":"^([0-9]{4})(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$","description":"생년월일.\n\nYYYYMMDD 형식."},"gender_digit":{"type":"string","description":"주민등록 뒷부분 첫 자리."},"carrier":{"type":"string","enum":["SKT","KT","LGT"],"description":"본인인증 대상자 통신사 코드."},"is_mvno":{"type":"boolean","description":"알뜰폰 여부."},"commpany":{"type":"string","description":"가맹점 서비스 명칭 또는 domain URL.\n\nKISA 에서 대상자에게 발송하는 SMS에 안내될 서비스 명칭."},"merchant_uid":{"type":"string","description":"귀사 서비스에서의 본인인증 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다."},"pg":{"type":"string","description":"PG 사 구분자.\n\n다날 상점아이디를 2개 이상 동시에 사용하시려는 경우에 설정하면 된다.\n\n**danal.{상점아이디}** 형태로 지정."}},"nullable":false,"required":["name","phone","birth","gender_digit","carrier"],"description":"본인 인증 입력 정보."},"IIamportResponseIIamportCertification.IAccessor":{"type":"object","properties":{"code":{"type":"number","description":"에러 코드.\n\n값이 0 이면 오류가 없다는 뜻."},"message":{"type":"string","description":"성공 또는 오류 메시지."},"response":{"$ref":"#/components/schemas/IIamportCertification.IAccessor","description":"응답 데이터, 사실상 본문."}},"nullable":false,"required":["code","message","response"],"description":"아임포트 고유의 응답 데이터."},"IIamportCertification.IAccessor":{"type":"object","properties":{"imp_uid":{"type":"string","description":"본인인증정보의 식별자 키."}},"nullable":false,"required":["imp_uid"],"description":"본인인증 정보의 접근자 구조체."},"IIamportCertification.IConfirm":{"type":"object","properties":{"otp":{"type":"string","description":"SMS 로 전송된 본인인증 번호."}},"nullable":false,"required":["otp"],"description":"본인인증 승인을 위한 입력 정보."},"IIamportPayment.IWebhook":{"type":"object","properties":{"imp_uid":{"type":"string","description":"결제 정보 {@link IIamportPayment } 의 식별자 키."},"merchant_uid":{"type":"string","description":"주문 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다."},"status":{"type":"string","enum":["paid","ready","failed","cancelled"],"description":"현재 상태."}},"nullable":false,"required":["imp_uid","merchant_uid","status"],"description":"웹훅 데이터."},"IIamportPayment.IQuery":{"type":"object","properties":{"extension":{"type":"boolean","description":"페이팔의 경우, 이 값을 `true` 로 할 것."}},"nullable":false,"description":"결제 수단이 페이팔인 경우, 페이팔의 구매자 보호정책에 의해 결제 승인 시점에\nPending 상태를 만든 후, 내부 심사등을 통해 최종 결제 완료라고 변경함.\n\n`iamport` 의 기술적 이슈로 해당 상태를 status: failed 로 기록함. 추후\n페이팔에서 최종결제완료로 변경된 경우, `iamport` 에서 `paid` 로 변경 후,\n해당건에 대한 웹훅 발송. `iamport` 를 사용하는 고객사에서는, failed 로 이미\n처리된 결제건에 대한 paid 상태의 웹훅을 받는 문제점이 생김.\n\n이에, `iamport` 에서 제공하는 `/payment/{imp_uid}` 에 query-string 으로\n`extension=true` 옵션을 추가해야 함"},"IIamportResponseIIamportPayment":{"type":"object","properties":{"code":{"type":"number","description":"에러 코드.\n\n값이 0 이면 오류가 없다는 뜻."},"message":{"type":"string","description":"성공 또는 오류 메시지."},"response":{"$ref":"#/components/schemas/IIamportPayment","description":"응답 데이터, 사실상 본문."}},"nullable":false,"required":["code","message","response"],"description":"아임포트 고유의 응답 데이터."},"IIamportPayment":{"oneOf":[{"$ref":"#/components/schemas/IIamportCardPayment"},{"$ref":"#/components/schemas/IIamportTransferPayment"},{"$ref":"#/components/schemas/IIamportVBankPayment"},{"$ref":"#/components/schemas/IIamportPayment.IBasephonekpaykakaopaypaycolpayssgpaytosspayculturelandsmartculturehappymoneybooknlifepoint"}],"description":"결제 정보.\n\n`IIamportPayment` 는 아임포트의 결제 정보를 형상화한 자료구조이자 유니언 타입의\n인터페이스로써, if condition 을 통하여 method 값을 특정하면, 파생 타입이 자동으로\n지정된다.\n\n```typescript\nif (payment.pay_method === \"card\")\n payment.card_number; // payment be IIamportCardPayment\n```"},"IIamportTransferPayment":{"type":"object","properties":{"bank_code":{"type":"string","description":"은행 식별자 코드."},"bank_name":{"type":"string","description":"은행 이름."},"pay_method":{"type":"string","enum":["trans"]},"imp_uid":{"type":"string","description":"결제 정보 {@link IIamportPayment } 의 식별자 키."},"merchant_uid":{"type":"string","description":"주문 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다."},"name":{"type":"string","nullable":true,"description":"주문명, 누락 가능."},"amount":{"type":"number","description":"결제 총액."},"cancel_amount":{"type":"number","description":"결제 취소, 환불 총액."},"currency":{"$ref":"#/components/schemas/IIamportPayment.Currency","description":"통화 단위."},"receipt_url":{"type":"string","format":"uri","description":"영수증 URL."},"cash_receipt_issue":{"type":"boolean","description":"현금 영수증 발행 여부."},"channel":{"type":"string"},"pg_provider":{"type":"string"},"emb_pg_provider":{"type":"string","nullable":true},"pg_id":{"type":"string"},"pg_tid":{"type":"string"},"escrow":{"type":"boolean"},"buyer_name":{"type":"string","nullable":true},"buyer_email":{"type":"string","format":"email","nullable":true},"buyer_tel":{"type":"string","nullable":true},"buyer_addr":{"type":"string","nullable":true},"buyer_postcode":{"type":"string","nullable":true},"customer_uid":{"type":"string","nullable":true},"customer_uid_usage":{"type":"string","nullable":true},"custom_data":{"type":"string","nullable":true},"user_agent":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/IIamportPayment.Status","description":"결제의 현재 (진행) 상태."},"started_at":{"type":"number","description":"결제 신청 일시.\n\n리눅스 타임이 쓰임."},"paid_at":{"type":"number","description":"결제 (지불) 완료 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"failed_at":{"type":"number","description":"결제 실패 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"cancelled_at":{"type":"number","description":"결제 취소 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"fail_reason":{"type":"string","nullable":true},"cancel_reason":{"type":"string","nullable":true},"cancel_history":{"type":"array","items":{"$ref":"#/components/schemas/IIamportPaymentCancel"}}},"nullable":false,"required":["bank_code","bank_name","pay_method","imp_uid","merchant_uid","name","amount","cancel_amount","currency","receipt_url","cash_receipt_issue","channel","pg_provider","emb_pg_provider","pg_id","pg_tid","escrow","buyer_name","buyer_email","buyer_tel","buyer_addr","buyer_postcode","customer_uid","customer_uid_usage","custom_data","user_agent","status","started_at","paid_at","failed_at","cancelled_at","fail_reason","cancel_reason","cancel_history"],"description":"계좌 이체 결제 정보."},"IIamportVBankPayment":{"type":"object","properties":{"vbank_code":{"type":"string","description":"가상 계좌 식별자 코드."},"vbank_name":{"type":"string","description":"가상 게좌 이름"},"vbank_num":{"type":"string","description":"가상 계좌 번호"},"vbank_holder":{"type":"string","description":"가상 계좌 예금주."},"vbank_date":{"type":"number","description":"가상 계좌 입금 만료 기한."},"vbank_issued_at":{"type":"number","description":"가상 계좌 개설 일시."},"pay_method":{"type":"string","enum":["vbank"]},"imp_uid":{"type":"string","description":"결제 정보 {@link IIamportPayment } 의 식별자 키."},"merchant_uid":{"type":"string","description":"주문 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다."},"name":{"type":"string","nullable":true,"description":"주문명, 누락 가능."},"amount":{"type":"number","description":"결제 총액."},"cancel_amount":{"type":"number","description":"결제 취소, 환불 총액."},"currency":{"$ref":"#/components/schemas/IIamportPayment.Currency","description":"통화 단위."},"receipt_url":{"type":"string","format":"uri","description":"영수증 URL."},"cash_receipt_issue":{"type":"boolean","description":"현금 영수증 발행 여부."},"channel":{"type":"string"},"pg_provider":{"type":"string"},"emb_pg_provider":{"type":"string","nullable":true},"pg_id":{"type":"string"},"pg_tid":{"type":"string"},"escrow":{"type":"boolean"},"buyer_name":{"type":"string","nullable":true},"buyer_email":{"type":"string","format":"email","nullable":true},"buyer_tel":{"type":"string","nullable":true},"buyer_addr":{"type":"string","nullable":true},"buyer_postcode":{"type":"string","nullable":true},"customer_uid":{"type":"string","nullable":true},"customer_uid_usage":{"type":"string","nullable":true},"custom_data":{"type":"string","nullable":true},"user_agent":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/IIamportPayment.Status","description":"결제의 현재 (진행) 상태."},"started_at":{"type":"number","description":"결제 신청 일시.\n\n리눅스 타임이 쓰임."},"paid_at":{"type":"number","description":"결제 (지불) 완료 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"failed_at":{"type":"number","description":"결제 실패 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"cancelled_at":{"type":"number","description":"결제 취소 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"fail_reason":{"type":"string","nullable":true},"cancel_reason":{"type":"string","nullable":true},"cancel_history":{"type":"array","items":{"$ref":"#/components/schemas/IIamportPaymentCancel"}}},"nullable":false,"required":["vbank_code","vbank_name","vbank_num","vbank_holder","vbank_date","vbank_issued_at","pay_method","imp_uid","merchant_uid","name","amount","cancel_amount","currency","receipt_url","cash_receipt_issue","channel","pg_provider","emb_pg_provider","pg_id","pg_tid","escrow","buyer_name","buyer_email","buyer_tel","buyer_addr","buyer_postcode","customer_uid","customer_uid_usage","custom_data","user_agent","status","started_at","paid_at","failed_at","cancelled_at","fail_reason","cancel_reason","cancel_history"],"description":"가상 계좌 결제 정보."},"IIamportPayment.IBasephonekpaykakaopaypaycolpayssgpaytosspayculturelandsmartculturehappymoneybooknlifepoint":{"type":"object","properties":{"pay_method":{"type":"string","enum":["phone","kpay","kakaopay","payco","lpay","ssgpay","tosspay","cultureland","smartculture","happymoney","booknlife","point"]},"imp_uid":{"type":"string","description":"결제 정보 {@link IIamportPayment } 의 식별자 키."},"merchant_uid":{"type":"string","description":"주문 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다."},"name":{"type":"string","nullable":true,"description":"주문명, 누락 가능."},"amount":{"type":"number","description":"결제 총액."},"cancel_amount":{"type":"number","description":"결제 취소, 환불 총액."},"currency":{"$ref":"#/components/schemas/IIamportPayment.Currency","description":"통화 단위."},"receipt_url":{"type":"string","format":"uri","description":"영수증 URL."},"cash_receipt_issue":{"type":"boolean","description":"현금 영수증 발행 여부."},"channel":{"type":"string"},"pg_provider":{"type":"string"},"emb_pg_provider":{"type":"string","nullable":true},"pg_id":{"type":"string"},"pg_tid":{"type":"string"},"escrow":{"type":"boolean"},"buyer_name":{"type":"string","nullable":true},"buyer_email":{"type":"string","format":"email","nullable":true},"buyer_tel":{"type":"string","nullable":true},"buyer_addr":{"type":"string","nullable":true},"buyer_postcode":{"type":"string","nullable":true},"customer_uid":{"type":"string","nullable":true},"customer_uid_usage":{"type":"string","nullable":true},"custom_data":{"type":"string","nullable":true},"user_agent":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/IIamportPayment.Status","description":"결제의 현재 (진행) 상태."},"started_at":{"type":"number","description":"결제 신청 일시.\n\n리눅스 타임이 쓰임."},"paid_at":{"type":"number","description":"결제 (지불) 완료 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"failed_at":{"type":"number","description":"결제 실패 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"cancelled_at":{"type":"number","description":"결제 취소 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"fail_reason":{"type":"string","nullable":true},"cancel_reason":{"type":"string","nullable":true},"cancel_history":{"type":"array","items":{"$ref":"#/components/schemas/IIamportPaymentCancel"}}},"nullable":false,"required":["pay_method","imp_uid","merchant_uid","name","amount","cancel_amount","currency","receipt_url","cash_receipt_issue","channel","pg_provider","emb_pg_provider","pg_id","pg_tid","escrow","buyer_name","buyer_email","buyer_tel","buyer_addr","buyer_postcode","customer_uid","customer_uid_usage","custom_data","user_agent","status","started_at","paid_at","failed_at","cancelled_at","fail_reason","cancel_reason","cancel_history"],"description":"결제 기본 (공통) 정보."},"IIamportPaymentCancel.ICreate":{"type":"object","properties":{"imp_uid":{"type":"string","description":"결제 정보 {@link IIamportPayment } 의 식별자 키."},"merchant_uid":{"type":"string","description":"주문 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다."},"amount":{"type":"number","description":"취소 금액, 부분 취소도 가능하다.\n\n누락시 전액 취소."},"checksum":{"type":"number","minimum":0,"nullable":true,"description":"취소 트랜잭션 수행 전, 현재 시점의 취소 가능한 잔액.\n\nAPI요청자가 기록하고 있는 취소가능 잔액과 아임포트가 기록하고 있는 취소가능 잔액이\n일치하는지 사전에 검증하고, 검증에 실패하면 트랜잭션을 수행하지 않는다.\n\n`null` 인 경우에는 검증 프로세스를 생략."},"reason":{"type":"string","description":"취소 사유."},"tax_free":{"type":"number","default":0,"description":"취소요청금액 중 면세금액."},"refund_holder":{"type":"string","description":"환불계좌 예금주."},"refund_bank":{"type":"string","description":"환불계좌 은행 코드."},"refund_account":{"type":"string","description":"환불계좌 계좌번호."},"refund_tel":{"type":"string","description":"환불계좌 예금주 연락처"}},"nullable":false,"required":["imp_uid","merchant_uid","checksum","reason"],"description":"결제 취소 입력 정보."},"IIamportResponseIIamportReceipt":{"type":"object","properties":{"code":{"type":"number","description":"에러 코드.\n\n값이 0 이면 오류가 없다는 뜻."},"message":{"type":"string","description":"성공 또는 오류 메시지."},"response":{"$ref":"#/components/schemas/IIamportReceipt","description":"응답 데이터, 사실상 본문."}},"nullable":false,"required":["code","message","response"],"description":"아임포트 고유의 응답 데이터."},"IIamportReceipt":{"type":"object","properties":{"imp_uid":{"type":"string","description":"귀속 결제의 {@link IIamportPayment.imp_uid }."},"receipt_uid":{"type":"string","description":"현금 영수증의 고유 식별자 ID."},"apply_num":{"type":"string","description":"승인 번호."},"type":{"$ref":"#/components/schemas/IIamportReceipt.Type","description":"발행 타입 (대상)."},"amount":{"type":"number","description":"결제 총액."},"vat":{"type":"number","description":"부가세."},"receipt_url":{"type":"string","format":"uri","description":"현금영수증 조회 URL."},"applied_at":{"type":"number","description":"현금영수증 발행 시간."},"cancelled_at":{"type":"number","description":"현금영수증 취소 시간.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."}},"nullable":false,"required":["imp_uid","receipt_uid","apply_num","type","amount","vat","receipt_url","applied_at","cancelled_at"],"description":"현금 영수증 정보."},"IIamportReceipt.Type":{"type":"string","enum":["person","company"],"description":"현금영수증 발행 타입 (대상)."},"IIamportReceipt.ICreate":{"type":"object","properties":{"imp_uid":{"type":"string","description":"귀속 결제의 {@link IIamportPayment.imp_uid }."},"identifier":{"type":"string","description":"현금영수증 발생대상 식별정보.\n\n - 국세청현금영수증카드\n - 휴대폰번호\n - 주민등록번호\n - 사업자등록번호"},"identifier_type":{"type":"string","enum":["phone","person","business","taxcard"],"description":"현금영수증 발행대상 유형.\n\n - person: 주민등록번호\n - business: 사업자등록번호\n - phone: 휴대폰번호\n - taxcard: 국세청현금영수증카드\n\n일부 PG 사의 경우 이 항목이 없어 된다는데, 어지간하면 그냥 쓰기 바람."},"type":{"type":"string","enum":["person","company"],"description":"현금영수증 발행 타입 (대상).\n\n누락시 person 이 사용됨."},"buyer_name":{"type":"string","description":"구매자 이름.\n\n형금영수증 발행건 사후 추적을 위해 가급 입력하기 바람."},"buyer_email":{"type":"string","description":"구매자 이메일."},"buyer_tel":{"type":"string","description":"구매자 전화번호.\n\n현금영수증 발행건 사후 추적을 위해 가급 입력하기 바람."},"tax_free":{"type":"number","description":"면세 금액."}},"nullable":false,"required":["imp_uid","identifier"],"description":"현금영수증 입력 정보."},"IIamportUser.IAccessor":{"type":"object","properties":{"imp_key":{"type":"string","description":"API 키."},"imp_secret":{"type":"string","description":"Secret 키."}},"nullable":false,"required":["imp_key","imp_secret"],"description":"아임포트에서 부여해 준 API 및 secret 키."},"IIamportResponseIIamportUser":{"type":"object","properties":{"code":{"type":"number","description":"에러 코드.\n\n값이 0 이면 오류가 없다는 뜻."},"message":{"type":"string","description":"성공 또는 오류 메시지."},"response":{"$ref":"#/components/schemas/IIamportUser","description":"응답 데이터, 사실상 본문."}},"nullable":false,"required":["code","message","response"],"description":"아임포트 고유의 응답 데이터."},"IIamportUser":{"type":"object","properties":{"now":{"type":"number","description":"토큰 발행 시간."},"expired_at":{"type":"number","description":"토큰 만료 시간.\n\n리눅스 타임이 기준이며, 이를 JS 에서 사용하려거든, 아래와 같이 변환해야 한다.\n\n```typescript\nnew Date(user.expired_at * 1_000);\n```"},"access_token":{"type":"string","description":"유저 인증 토큰."}},"nullable":false,"required":["now","expired_at","access_token"],"description":"아임포트 유저 인증 정보.\n\n아임포트는 고객사에게 API 및 secret 키 정보, {@link IIamportUser.IAccessor } 를 발급해준다.\n\n하지만 이를 곧장 아임포트의 유저 인증에 사용할 수는 없고, 해당 API 및 secret 키를 토대로 유저\n인증 토큰을 발급받아야 하는데, 이 유저 인증 토큰에는 하필이면 만로 시간이라는 게 존재한다.\n`IIamportUser` 는 바로 이러한 유저 인증 토큰 및 그것의 만료 시간을 형상화한 자료구조\n인터페이스이다.\n\n더하여 이처럼 만료 시간이 존재하는 아임포트의 유저 인증 토큰의 특성상, 이것의 만료 시간이\n초과되지 않도록 관리하는 것은 매우 힘든 일이다. 이에 `iamport-server-api` 에서는 아임포트\n유저 인증 토큰이 만료될 때마다 자동 갱신해주는, {@link IamportConnector } 클래스를 제공한다."},"IIamportVBankPayment.ICreate":{"type":"object","properties":{"merchant_uid":{"type":"string","description":"주문 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다."},"amount":{"type":"number","description":"총액."},"vbank_code":{"type":"string","description":"가상계좌 은행 코드."},"vbank_due":{"type":"number","description":"가상계좌 입금기한, 유닉스 타임."},"vbank_holder":{"type":"string","description":"예금주."},"name":{"type":"string"},"buyer_name":{"type":"string"},"buyer_email":{"type":"string"},"buyer_tel":{"type":"string"},"buyer_addr":{"type":"string"},"buyer_postcode":{"type":"string"},"pg":{"type":"string"},"notice_url":{"type":"string","description":"가상 계좌 입금 정보를 수신할 URL.\n\n누락시 기본 웹훅 URL 사용."},"custom_data":{"type":"string","description":"커스텀 데이터, 자유롭게 사용 가능."},"pg_api_key":{"type":"string","description":"[이니시스 전용] 가맹점 콘솔에서 확인한 API 값."}},"nullable":false,"required":["merchant_uid","amount","vbank_code","vbank_due","vbank_holder"],"description":"가상 계좌 결제 입력 정보.\n\n가상 계좌를 임의 생성할 수 있다.\n\n단, 일부 PG 사 혹은 `fake-iamport-server` 만 가능.\n\n - 세틀뱅크\n - 나이스페이먼츠\n - KG이니시스"},"IIamportResponseIIamportVBankPayment":{"type":"object","properties":{"code":{"type":"number","description":"에러 코드.\n\n값이 0 이면 오류가 없다는 뜻."},"message":{"type":"string","description":"성공 또는 오류 메시지."},"response":{"$ref":"#/components/schemas/IIamportVBankPayment","description":"응답 데이터, 사실상 본문."}},"nullable":false,"required":["code","message","response"],"description":"아임포트 고유의 응답 데이터."},"IIamportVBankPayment.IUpdate":{"type":"object","properties":{"imp_uid":{"type":"string","description":"대상 결제 기록의 {@link IIamportPayment.imp_uid }."},"amount":{"type":"number","description":"수정할 결제 금액."},"vbank_due":{"type":"number","description":"수정할 가상계좌 입금 기한."}},"nullable":false,"required":["imp_uid"],"description":"가상 계좌 결제의 수정 입력 정보.\n\n아직 입금되지 않은 가상계좌의 입금기한 또는 입금금액을 수정할 수 있다.\n\n다만, 세틀뱅크 혹은 `fake-iamport-server` 만 가능."}},"securitySchemes":{"bearer":{"type":"apiKey","name":"Authorization","in":"header"}}}} \ No newline at end of file +{ + "openapi": "3.0.1", + "servers": [ + { + "url": "http://localhost:10851", + "description": "fake" + }, + { + "url": "https://api.iamport.kr", + "description": "real" + } + ], + "info": { + "title": "Iamport API", + "description": "Built by [fake-iamport-server](https://github.com/samchon/payments/tree/master/packages/fake-iamport-server) with [nestia](https://github.com/samchon/nestia)", + "version": "6.0.6", + "license": { + "name": "MIT" + } + }, + "paths": { + "/subscribe/customers/{customer_uid}": { + "get": { + "tags": [], + "parameters": [ + { + "name": "customer_uid", + "in": "path", + "schema": { + "type": "string" + }, + "description": "고객 (간편 결제 카드) 식별자 키", + "required": true + } + ], + "responses": { + "200": { + "description": "간편 결제 카드 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportResponseIIamportSubscription" + } + } + } + } + }, + "summary": "간편 결제 카드 정보 조회하기", + "description": "간편 결제 카드 정보 조회하기.\n\n`subscribe.customers.at` 은 고객이 {@link create } 나 혹은 아임포트가 제공하는\n간편 결제 카드 등록 창을 이용하여 저장한 간편 결제 카드 정보를 조회하는 API\n함수이다.", + "security": [ + { + "bearer": [] + } + ] + }, + "post": { + "tags": [], + "parameters": [ + { + "name": "customer_uid", + "in": "path", + "schema": { + "type": "string" + }, + "description": "고객 (간편 결제 카드) 식별자 키", + "required": true + } + ], + "requestBody": { + "description": "카드 입력 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportSubscription.ICreate" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "간편 결제 카드 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportResponseIIamportSubscription" + } + } + } + } + }, + "summary": "간편 결제 카드 등록하기", + "description": "간편 결제 카드 등록하기.\n\n`subscribe.customers.stoer` 는 고객이 자신의 카드를 서버에 등록해두고, 매번 결제가\n필요할 때마다 카드 정보를 반복 입력하는 일 없이, 간편하게 결제를 진행하고자 할 때\n사용하는 API 함수이다.\n\n참고로 `subscribe.customers.create` 는 클라이언트 어플리케이션이 아임포트가 제공하는\n간편 결제 카드 등록 창을 사용하는 경우, 귀하의 백엔드 서버가 이를 실 서비스에서 호출하는\n일은 없을 것이다. 다만, 고객이 간편 결제 카드를 등록하는 상황을 시뮬레이션하기 위하여,\n테스트 자동화 프로그램 수준에서 사용될 수는 있다.", + "security": [ + { + "bearer": [] + } + ] + }, + "delete": { + "tags": [], + "parameters": [ + { + "name": "customer_uid", + "in": "path", + "schema": { + "type": "string" + }, + "description": "고객 (간편 결제 카드) 식별자 키", + "required": true + } + ], + "responses": { + "200": { + "description": "삭제된 간편 결제 카드 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportResponseIIamportSubscription" + } + } + } + } + }, + "summary": "간편 결제 카드 삭제하기", + "description": "간편 결제 카드 삭제하기.\n\n간편 결제를 위하여 등록한 카드를 제거한다.", + "security": [ + { + "bearer": [] + } + ] + } + }, + "/subscribe/payments/onetime": { + "post": { + "tags": [], + "parameters": [], + "requestBody": { + "description": "카드 결제 신청 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportSubscription.IOnetime" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "카드 결제 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportResponseIIamportCardPayment" + } + } + } + } + }, + "summary": "카드로 결제하기, 더불어 간편 결제용으로 등록 가능", + "description": "카드로 결제하기, 더불어 간편 결제용으로 등록 가능.\n\n`subscribe.payments.onetime` 은 카드를 매개로 한 결제를 하고자 할 때 호출하는 API\n함수이다. 더하여 입력 값에 {@link IIamportSubscription.IOnetime.customer_uid } 를\n기입하는 경우, 결제에 사용한 카드를 그대로 간편 결제용 카드\n{@link IIamportSubscription } 로 등록해버린다.\n\n다만, 정히 간편 카드 등록과 결제를 동시에 하고 싶다면,\n`subscribe.payments.onetime` 에 {@link IIamportSubscription.IOnetime.customer_uid }\n를 더하기보다, {@link subscribe.customers.create } 와 {@link subscribe.payments.again }\n을 각각 호출하는 것을 권장한다. 그것이 예외적인 상황에 보다 안전하게 대처할 수 있기\n때문이다.\n\n더하여 `subscribe.payments.onetime` 은 클라이언트 어플리케이션이 아임포트가 제공하는\n결제 창을 그대로 사용하는 경우, 귀하의 백엔드 서버가 이를 실 서비스에서 호출하는 일은\n없을 것이다. 다만, 고객이 카드를 통하여 결제하는 상황을 시뮬레이션하기 위하여, 테스트\n자동화 프로그램 수준에서 사용될 수는 있다.", + "security": [ + { + "bearer": [] + } + ] + } + }, + "/subscribe/payments/again": { + "post": { + "tags": [], + "parameters": [], + "requestBody": { + "description": "미리 등록한 카드를 이용한 결제 신청 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportSubscription.IAgain" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "카드 결제 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportResponseIIamportCardPayment" + } + } + } + } + }, + "summary": "간편 결제에 등록된 카드로 결제하기", + "description": "간편 결제에 등록된 카드로 결제하기.\n\n`subscribe.payments.again` 은 고객이 간편 결제에 등록한 카드로 결제를 진행하고자 할 때\n호출하는 API 함수이다. 이는 간편하고 불편하고를 떠나, 본질적으로 카드 결제의 일환이기에,\n리턴값은 일반적인 카드 결제 때와 동일한 {@link IIamportCardPayment } 이다.\n\n그리고 `subscribe.payments.again` 은 결제 수단 중 유일하게, 클라이언트 어플리케이션이\n아임포트가 제공하는 결체 창을 사용할 수 없어, 오직 귀하의 백엔드 서버가 아임포트의 API\n함수를 직접 호출해야하는 경우에 해당한다. 따라서 간편 결제에 관하여 아임포트 서버와\n연동하는 백엔드 서버 및 프론트 어플리케이션을 개발할 때, 반드시 이 상황에 대한 별도의\n설계 및 개발이 필요하니, 이 점을 염두에 두기 바란다.", + "security": [ + { + "bearer": [] + } + ] + } + }, + "/certifications/{imp_uid}": { + "get": { + "tags": [], + "parameters": [ + { + "name": "imp_uid", + "in": "path", + "schema": { + "type": "string" + }, + "description": "대상 본인인증 정보의 ", + "required": true + } + ], + "responses": { + "200": { + "description": "본인인증 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportResponseIIamportCertification" + } + } + } + } + }, + "summary": "본인인증 정보 열람하기", + "description": "본인인증 정보 열람하기.\n\n`certiciations.at` 은 본인인증 정보를 열람할 때 사용하는 API 함수이다.\n\n다만 이 API 함수를 통하여 열람한 본인인증 정보 {@link IIamportCertification } 이\n곧 OTP 인증까지 마쳐 본인인증을 모두 마친 레코드라는 보장은 없다. 본인인증의 완결\n여부는 오직, {@link IIamportCertification.certified } 값을 직접 검사해봐야만 알\n수 있기 때문이다.", + "security": [ + { + "bearer": [] + } + ] + }, + "delete": { + "tags": [], + "parameters": [ + { + "name": "imp_uid", + "in": "path", + "schema": { + "type": "string" + }, + "description": "대상 본인인증 정보의 ", + "required": true + } + ], + "responses": { + "200": { + "description": "삭제된 본인인증 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportResponseIIamportCertification" + } + } + } + } + }, + "summary": "본인인증 정보 삭제하기", + "description": "본인인증 정보 삭제하기.", + "security": [ + { + "bearer": [] + } + ] + } + }, + "/certifications/otp/request": { + "post": { + "tags": [], + "parameters": [], + "requestBody": { + "description": "본인인증 요청 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportCertification.ICreate" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "진행 중인 본인인증의 식별자 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportResponseIIamportCertification.IAccessor" + } + } + } + } + }, + "summary": "본인인증 요청하기", + "description": "본인인증 요청하기.\n\n`certifications.otp.request` 는 아임포트 서버에 본인인증을 요청하는 API 함수이다.\n이 API 를 호출하면 본인인증 대상자의 핸드폰으로 OTP 문자가 전송되며, 본인인증\n대상자가 {@link certifications.otp.confirm } 을 통하여 이 OTP 번호를 정확히\n입력함으로써, 본인인증이 완결된다.\n\n또한 본인인증 대상자가 자신의 핸드폰으로 전송된 OTP 문자를 입력하기 전에도,\n여전히해당 본인인증 내역은 {@link certifications.at } 함수를 통하여 조회할 수 있다.\n다만, 이 때 리턴되는 {@link IIamportCertification } 에서 인증의 완결 여부를\n지칭하는 {@link IIamportCertification.certified } 값은 `false` 이다.", + "security": [ + { + "bearer": [] + } + ] + } + }, + "/certifications/otp/confirm/{imp_uid}": { + "post": { + "tags": [], + "parameters": [ + { + "name": "imp_uid", + "in": "path", + "schema": { + "type": "string" + }, + "description": "대상 본인인증 정보의 ", + "required": true + } + ], + "requestBody": { + "description": "OTP 코드", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportCertification.IConfirm" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "인증 완료된 본인인증 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportResponseIIamportCertification" + } + } + } + } + }, + "summary": "본인인증 시 발급된 OTP 코드 입력하기", + "description": "본인인증 시 발급된 OTP 코드 입력하기.\n\n`certifications.otp.confirm` 는 {@link certifications.otp.request } 를 통하여\n발급된 본인인증 건에 대하여, 본인인증 대상자의 휴대폰으로 전송된 OTP 번호를\n검증하고, 입력한 OTP 번호가 맞거든 해당 본인인증 건을 승인하여 완료 처리해주는\nAPI 함수이다.\n\n이처럼 본인인증을 완료하거든, 해당 본인인증 건 {@link IIamportCertification } 의\n{@link IIamportCertification.certified } 값이 비로소 `true` 로 변경되어,\n비로소 완결된다.", + "security": [ + { + "bearer": [] + } + ] + } + }, + "/internal/webhook": { + "post": { + "tags": [], + "parameters": [], + "requestBody": { + "description": "웹훅 이벤트 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportPayment.IWebhook" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "" + } + }, + "summary": "웹훅 이벤트 더미 리스너", + "description": "웹훅 이벤트 더미 리스너.\n\n`internal.webhook` 은 실제 아임포트의 서버에는 존재하지 않는 API 로써,\n`fake-impoart-server` 의 {@link Configuration.WEBHOOK_URL } 에 아무런 URL 을 설정하지\n않으면, `fake-iamport-server` 로부터 발생하는 모든 종류의 웹훅 이벤트는 이 곳으로 전달되어\n무의미하게 사라진다.\n\n따라서 `fake-iamport-server` 를 사용하여 아임포트 서버와의 연동을 미리 검증코자 할 때는,\n반드시 {@link Configuration.WEBHOOK_URL } 를 설정하여 웹훅 이벤트가 귀하의 백엔드 서버로\n제대로 전달되도록 하자." + } + }, + "/internal/deposit/{imp_uid}": { + "put": { + "tags": [], + "parameters": [ + { + "name": "imp_uid", + "in": "path", + "schema": { + "type": "string" + }, + "description": "대상 결제의 ", + "required": true + } + ], + "responses": { + "200": { + "description": "" + } + }, + "summary": "가상 계좌에 입금하기", + "description": "가상 계좌에 입금하기.\n\n`internal.deposit` 은 실제 아임포트 결제 서버에는 존재하지 않는 API 로써, 가상 계좌\n결제를 신청한 고객이, 이후 가상 계좌에 목표 금액을 입금하는 상황을 시뮬레이션 할 수 있는\n함수이다.\n\n즉, `internal.deposit` 는 고객이 스스로에게 가상으로 발급된 계좌에 입금을 하고, 그에 따라\n아임포트 서버에서 webhook 이벤트가 발생, 이를 귀하의 백엔드 서버로 전송하는 일련의 상황을\n시뮬레이션하기 위하여 설계된 테스트 함수다.", + "security": [ + { + "bearer": [] + } + ] + } + }, + "/payments/{imp_uid}": { + "get": { + "tags": [], + "parameters": [ + { + "name": "imp_uid", + "in": "path", + "schema": { + "type": "string" + }, + "description": "대상 결제 기록의 ", + "required": true + }, + { + "name": "query", + "in": "query", + "schema": { + "$ref": "#/components/schemas/IIamportPayment.IQuery" + }, + "description": "결제 수단이 페이팔인 경우에 사용", + "required": true + } + ], + "responses": { + "200": { + "description": "결제 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportResponseIIamportPayment" + } + } + } + } + }, + "summary": "결제 기록 열람하기", + "description": "결제 기록 열람하기.\n\n아임포트를 통하여 발생한 결제 기록을 열람한다.", + "security": [ + { + "bearer": [] + } + ] + } + }, + "/payments/cancel": { + "post": { + "tags": [], + "parameters": [], + "requestBody": { + "description": "결제 취소 입력 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportPaymentCancel.ICreate" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "취소된 결제 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportResponseIIamportPayment" + } + } + } + } + }, + "summary": "결제 취소하기", + "description": "결제 취소하기.\n\n만약 가상 계좌를 통한 결제였다면, 반드시 환불 계좌 정보를 입력해줘야 한다.", + "security": [ + { + "bearer": [] + } + ] + } + }, + "/receipts/{imp_uid}": { + "get": { + "tags": [], + "parameters": [ + { + "name": "imp_uid", + "in": "path", + "schema": { + "type": "string" + }, + "description": "귀속 결제의 ", + "required": true + } + ], + "responses": { + "200": { + "description": "현금 영수증 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportResponseIIamportReceipt" + } + } + } + } + }, + "summary": "현금 영수증 조회하기", + "description": "현금 영수증 조회하기.", + "security": [ + { + "bearer": [] + } + ] + }, + "post": { + "tags": [], + "parameters": [ + { + "name": "imp_uid", + "in": "path", + "schema": { + "type": "string" + }, + "description": "귀속 결제의 ", + "required": true + } + ], + "requestBody": { + "description": "현금 영수증 입력 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportReceipt.ICreate" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "현금 영수증 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportResponseIIamportReceipt" + } + } + } + } + }, + "summary": "현금 영수증 발행하기", + "description": "현금 영수증 발행하기.", + "security": [ + { + "bearer": [] + } + ] + }, + "delete": { + "tags": [], + "parameters": [ + { + "name": "imp_uid", + "in": "path", + "schema": { + "type": "string" + }, + "description": "귀속 결제의 ", + "required": true + } + ], + "responses": { + "200": { + "description": "취소된 현금 영수증 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportResponseIIamportReceipt" + } + } + } + } + }, + "summary": "현금 영수증 취소하기", + "description": "현금 영수증 취소하기.", + "security": [ + { + "bearer": [] + } + ] + } + }, + "/users/getToken": { + "post": { + "tags": [], + "parameters": [], + "requestBody": { + "description": "아임포트의 API 및 secret 키 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportUser.IAccessor" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "유저 인증 토큰 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportResponseIIamportUser" + } + } + } + } + }, + "summary": "유저 인증 토큰 발행하기", + "description": "유저 인증 토큰 발행하기.\n\n아임포트에 가입하여 부여받은 API 및 secret 키를 토대로, 유저 인증 토큰을 발행한다.\n\n단, 아임포트가 발급해주는 유저 인증 토큰에는 유효 시간 {@link IIamportUser.expired_at }\n이 있어, 해당 시간이 지나거든 기 발급 토큰이 만료되어 더 이상 쓸 수 없게 된다. 때문에\n아임포트의 이러한 시간 제한에 구애받지 않고 자유로이 아임포트의 API 를 이용하고 싶다면,\n`iamport-server-api` 에서 제공해주는 {@link IamportConnector } 를 활용하도록 하자." + } + }, + "/vbanks": { + "post": { + "tags": [], + "parameters": [], + "requestBody": { + "description": "가상 계좌 입력 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportVBankPayment.ICreate" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "가상 계좌 결제 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportResponseIIamportVBankPayment" + } + } + } + } + }, + "summary": "가상 계좌 발급하기", + "description": "가상 계좌 발급하기.", + "security": [ + { + "bearer": [] + } + ] + }, + "put": { + "tags": [], + "parameters": [], + "requestBody": { + "description": "가상 계좌 편집 입력 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportVBankPayment.IUpdate" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "편집된 가상 계좌 결제 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportResponseIIamportVBankPayment" + } + } + } + } + }, + "summary": "가상 계좌 편집하기", + "description": "가상 계좌 편집하기.", + "security": [ + { + "bearer": [] + } + ] + } + } + }, + "components": { + "schemas": { + "IIamportResponseIIamportSubscription": { + "type": "object", + "properties": { + "code": { + "type": "number", + "title": "에러 코드", + "description": "에러 코드.\n\n값이 0 이면 오류가 없다는 뜻." + }, + "message": { + "type": "string", + "title": "성공 또는 오류 메시지", + "description": "성공 또는 오류 메시지." + }, + "response": { + "$ref": "#/components/schemas/IIamportSubscription", + "title": "응답 데이터, 사실상 본문", + "description": "응답 데이터, 사실상 본문." + } + }, + "nullable": false, + "required": [ + "code", + "message", + "response" + ], + "description": "아임포트 고유의 응답 데이터." + }, + "IIamportSubscription": { + "type": "object", + "properties": { + "pg_provider": { + "type": "string" + }, + "pg_id": { + "type": "string" + }, + "card_name": { + "type": "string" + }, + "card_code": { + "type": "string" + }, + "card_number": { + "type": "string" + }, + "card_type": { + "type": "string" + }, + "customer_name": { + "type": "string", + "nullable": true + }, + "customer_tel": { + "type": "string", + "nullable": true + }, + "customer_email": { + "type": "string", + "nullable": true + }, + "customer_addr": { + "type": "string", + "nullable": true + }, + "customer_postcode": { + "type": "string", + "nullable": true + }, + "inserted": { + "type": "number" + }, + "updated": { + "type": "number" + }, + "customer_uid": { + "type": "string", + "title": "고객 식별자 키", + "description": "고객 식별자 키.\n\n아임포트가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키.\n\n다만 고객이라기보다 실제로는 카드의 식별자 키로 써야함." + } + }, + "nullable": false, + "required": [ + "pg_provider", + "pg_id", + "card_name", + "card_code", + "card_number", + "card_type", + "customer_name", + "customer_tel", + "customer_email", + "customer_addr", + "customer_postcode", + "inserted", + "updated", + "customer_uid" + ], + "description": "간편 결제 카드 정보." + }, + "IIamportSubscription.ICreate": { + "type": "object", + "properties": { + "card_number": { + "type": "string", + "pattern": "\\d{4}-\\d{4}-\\d{4}-\\d{4}", + "title": "카드 번호", + "description": "카드 번호.\n\n형식: XXXX-XXXX-XXXX-XXXX" + }, + "expiry": { + "type": "string", + "pattern": "^([0-9]{4})-(0[1-9]|1[012])$", + "title": "카드 유효기간", + "description": "카드 유효기간.\n\n형식: YYYY-MM" + }, + "birth": { + "type": "string", + "pattern": "^(([0-9]{2})(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01]))|(\\d{10})$", + "title": "생년월일 YYMMDD 또는 사업자등록번호 10자리", + "description": "생년월일 YYMMDD 또는 사업자등록번호 10자리." + }, + "pwd_2digit": { + "type": "string", + "pattern": "\\d{2}", + "title": "카드 비밀번호 앞 두 자리", + "description": "카드 비밀번호 앞 두 자리." + }, + "cvc": { + "type": "string", + "pattern": "\\d{2}", + "title": "카드 인증번호 (카드 뒷면 3 자리)", + "description": "카드 인증번호 (카드 뒷면 3 자리)." + }, + "customer_name": { + "type": "string" + }, + "customer_tel": { + "type": "string" + }, + "customer_email": { + "type": "string", + "format": "email" + }, + "customr_addr": { + "type": "string" + }, + "customer_postcode": { + "type": "string" + }, + "customer_uid": { + "type": "string", + "title": "고객 식별자 키", + "description": "고객 식별자 키.\n\n아임포트가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키.\n\n다만 고객이라기보다 실제로는 카드의 식별자 키로 써야함." + } + }, + "nullable": false, + "required": [ + "card_number", + "expiry", + "birth", + "customer_uid" + ], + "description": "간편 결제 카드 입력 정보." + }, + "IIamportSubscription.IOnetime": { + "type": "object", + "properties": { + "customer_uid": { + "type": "string", + "title": "고객 식별자 키", + "description": "고객 식별자 키.\n\n아임포트가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키.\n\n다만 고객이라기보다 실제로는 카드의 식별자 키로 써야함.\n\n이를 생략시 단순 결제로만 그치며, 카드 정보가 간편 결제용으로 등록되지 아니함." + }, + "card_number": { + "type": "string", + "pattern": "\\d{4}-\\d{4}-\\d{4}-\\d{4}", + "title": "카드 번호", + "description": "카드 번호.\n\n형식: XXXX-XXXX-XXXX-XXXX" + }, + "expiry": { + "type": "string", + "pattern": "^([0-9]{4})-(0[1-9]|1[012])$", + "title": "카드 유효기간", + "description": "카드 유효기간.\n\n형식: YYYY-MM" + }, + "birth": { + "type": "string", + "pattern": "^(([0-9]{2})(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01]))|(\\d{10})$", + "title": "생년월일 YYMMDD 또는 사업자등록번호 10자리", + "description": "생년월일 YYMMDD 또는 사업자등록번호 10자리." + }, + "pwd_2digit": { + "type": "string", + "pattern": "\\d{2}", + "title": "카드 비밀번호 앞 두 자리", + "description": "카드 비밀번호 앞 두 자리." + }, + "cvc": { + "type": "string", + "pattern": "\\d{2}", + "title": "카드 인증번호 (카드 뒷면 3 자리)", + "description": "카드 인증번호 (카드 뒷면 3 자리)." + }, + "customer_name": { + "type": "string" + }, + "customer_tel": { + "type": "string" + }, + "customer_email": { + "type": "string", + "format": "email" + }, + "customr_addr": { + "type": "string" + }, + "customer_postcode": { + "type": "string" + }, + "merchant_uid": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n아임포트가 아닌 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키." + }, + "amount": { + "type": "number", + "title": "결제 총액", + "description": "결제 총액." + }, + "name": { + "type": "string", + "title": "주문 이름", + "description": "주문 이름." + }, + "currency": { + "type": "string", + "enum": [ + "KRW", + "USD", + "EUR", + "JPY" + ], + "title": "통화 정보", + "description": "통화 정보." + }, + "tax_free": { + "type": "number", + "title": "면세 공급가액", + "description": "면세 공급가액.\n\n기본값은 0 로써, 알아서 amount 의 1/11 로써 부가세 처리됨." + }, + "card_quota": { + "type": "number", + "title": "할부 개월 수", + "description": "할부 개월 수.\n\n일시불은 0." + }, + "buyer_name": { + "type": "string" + }, + "buyer_email": { + "type": "string", + "format": "email" + }, + "buyer_tel": { + "type": "string" + }, + "buyer_addr": { + "type": "string" + }, + "buyer_postcode": { + "type": "string" + }, + "interest_free_by_merchant": { + "type": "boolean", + "title": "카드할부처리할 때, 할부이자가 발생하는 경우 (카드사 무이자 프로모션 제외)", + "description": "카드할부처리할 때, 할부이자가 발생하는 경우 (카드사 무이자 프로모션 제외).\n\n부과되는 할부이자를 고객대신 가맹점이 지불하고자 PG사와 계약된 경우(현재, 나이스페이먼츠만 지원됨)" + }, + "use_card_point": { + "type": "boolean", + "title": "승인요청시 카드사 포인트 차감하며 결제승인처리할지 flag", + "description": "승인요청시 카드사 포인트 차감하며 결제승인처리할지 flag.\n\nPG사 영업담당자와 계약 당시 사전 협의 필요(현재, 나이스페이먼츠만 지원됨)" + }, + "custom_data": { + "type": "string", + "title": "임의 정보를 기재할 수 있다", + "description": "임의 정보를 기재할 수 있다." + }, + "notice_url": { + "type": "string", + "format": "uri", + "title": "결제 성공시 통지될 Notification, 웹훅 URL", + "description": "결제 성공시 통지될 Notification, 웹훅 URL." + } + }, + "nullable": false, + "required": [ + "card_number", + "expiry", + "birth", + "merchant_uid", + "amount", + "name" + ], + "description": "결제 신청 입력 정보." + }, + "IIamportResponseIIamportCardPayment": { + "type": "object", + "properties": { + "code": { + "type": "number", + "title": "에러 코드", + "description": "에러 코드.\n\n값이 0 이면 오류가 없다는 뜻." + }, + "message": { + "type": "string", + "title": "성공 또는 오류 메시지", + "description": "성공 또는 오류 메시지." + }, + "response": { + "$ref": "#/components/schemas/IIamportCardPayment", + "title": "응답 데이터, 사실상 본문", + "description": "응답 데이터, 사실상 본문." + } + }, + "nullable": false, + "required": [ + "code", + "message", + "response" + ], + "description": "아임포트 고유의 응답 데이터." + }, + "IIamportCardPayment": { + "type": "object", + "properties": { + "card_code": { + "type": "string", + "title": "카드 식별자 코드", + "description": "카드 식별자 코드." + }, + "card_name": { + "type": "string", + "title": "카드 이름", + "description": "카드 이름." + }, + "card_number": { + "type": "string", + "pattern": "\\d{4}-\\d{4}-\\d{4}-\\d{4}", + "title": "카드 번호", + "description": "카드 번호." + }, + "card_quota": { + "type": "integer", + "title": "할부 개월 수", + "description": "할부 개월 수." + }, + "apply_num": { + "type": "string", + "title": "카드사 승인번호", + "description": "카드사 승인번호." + }, + "pay_method": { + "type": "string", + "enum": [ + "card", + "samsung" + ] + }, + "imp_uid": { + "type": "string", + "title": "결제 정보 {@link IIamportPayment } 의 식별자 키", + "description": "결제 정보 {@link IIamportPayment } 의 식별자 키." + }, + "merchant_uid": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다." + }, + "name": { + "type": "string", + "nullable": true, + "title": "주문명, 누락 가능", + "description": "주문명, 누락 가능." + }, + "amount": { + "type": "number", + "title": "결제 총액", + "description": "결제 총액." + }, + "cancel_amount": { + "type": "number", + "title": "결제 취소, 환불 총액", + "description": "결제 취소, 환불 총액." + }, + "currency": { + "$ref": "#/components/schemas/IIamportPayment.Currency", + "title": "통화 단위", + "description": "통화 단위." + }, + "receipt_url": { + "type": "string", + "format": "uri", + "title": "영수증 URL", + "description": "영수증 URL." + }, + "cash_receipt_issue": { + "type": "boolean", + "title": "현금 영수증 발행 여부", + "description": "현금 영수증 발행 여부." + }, + "channel": { + "type": "string" + }, + "pg_provider": { + "type": "string" + }, + "emb_pg_provider": { + "type": "string", + "nullable": true + }, + "pg_id": { + "type": "string" + }, + "pg_tid": { + "type": "string" + }, + "escrow": { + "type": "boolean" + }, + "buyer_name": { + "type": "string", + "nullable": true + }, + "buyer_email": { + "type": "string", + "format": "email", + "nullable": true + }, + "buyer_tel": { + "type": "string", + "nullable": true + }, + "buyer_addr": { + "type": "string", + "nullable": true + }, + "buyer_postcode": { + "type": "string", + "nullable": true + }, + "customer_uid": { + "type": "string", + "nullable": true + }, + "customer_uid_usage": { + "type": "string", + "nullable": true + }, + "custom_data": { + "type": "string", + "nullable": true + }, + "user_agent": { + "type": "string", + "nullable": true + }, + "status": { + "$ref": "#/components/schemas/IIamportPayment.Status", + "title": "결제의 현재 (진행) 상태", + "description": "결제의 현재 (진행) 상태." + }, + "started_at": { + "type": "number", + "title": "결제 신청 일시", + "description": "결제 신청 일시.\n\n리눅스 타임이 쓰임." + }, + "paid_at": { + "type": "number", + "title": "결제 (지불) 완료 일시", + "description": "결제 (지불) 완료 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "failed_at": { + "type": "number", + "title": "결제 실패 일시", + "description": "결제 실패 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "cancelled_at": { + "type": "number", + "title": "결제 취소 일시", + "description": "결제 취소 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "fail_reason": { + "type": "string", + "nullable": true + }, + "cancel_reason": { + "type": "string", + "nullable": true + }, + "cancel_history": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IIamportPaymentCancel" + } + } + }, + "nullable": false, + "required": [ + "card_code", + "card_name", + "card_number", + "card_quota", + "apply_num", + "pay_method", + "imp_uid", + "merchant_uid", + "name", + "amount", + "cancel_amount", + "currency", + "receipt_url", + "cash_receipt_issue", + "channel", + "pg_provider", + "emb_pg_provider", + "pg_id", + "pg_tid", + "escrow", + "buyer_name", + "buyer_email", + "buyer_tel", + "buyer_addr", + "buyer_postcode", + "customer_uid", + "customer_uid_usage", + "custom_data", + "user_agent", + "status", + "started_at", + "paid_at", + "failed_at", + "cancelled_at", + "fail_reason", + "cancel_reason", + "cancel_history" + ], + "description": "카드 결제 정보." + }, + "IIamportPayment.Currency": { + "type": "string", + "enum": [ + "KRW", + "USD", + "EUR", + "JPY" + ] + }, + "IIamportPayment.Status": { + "type": "string", + "enum": [ + "paid", + "ready", + "failed", + "cancelled" + ] + }, + "IIamportPaymentCancel": { + "type": "object", + "properties": { + "pg_id": { + "type": "string" + }, + "pg_tid": { + "type": "string" + }, + "amount": { + "type": "number" + }, + "cancelled_at": { + "type": "number" + }, + "reason": { + "type": "string" + }, + "receipt_url": { + "type": "string", + "format": "uri" + } + }, + "nullable": false, + "required": [ + "pg_id", + "pg_tid", + "amount", + "cancelled_at", + "reason", + "receipt_url" + ], + "description": "결제 취소 정보." + }, + "IIamportSubscription.IAgain": { + "type": "object", + "properties": { + "merchant_uid": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n아임포트가 아닌 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키." + }, + "amount": { + "type": "number", + "title": "결제 총액", + "description": "결제 총액." + }, + "name": { + "type": "string", + "title": "주문 이름", + "description": "주문 이름." + }, + "currency": { + "type": "string", + "enum": [ + "KRW", + "USD", + "EUR", + "JPY" + ], + "title": "통화 정보", + "description": "통화 정보." + }, + "tax_free": { + "type": "number", + "title": "면세 공급가액", + "description": "면세 공급가액.\n\n기본값은 0 로써, 알아서 amount 의 1/11 로써 부가세 처리됨." + }, + "card_quota": { + "type": "number", + "title": "할부 개월 수", + "description": "할부 개월 수.\n\n일시불은 0." + }, + "buyer_name": { + "type": "string" + }, + "buyer_email": { + "type": "string", + "format": "email" + }, + "buyer_tel": { + "type": "string" + }, + "buyer_addr": { + "type": "string" + }, + "buyer_postcode": { + "type": "string" + }, + "interest_free_by_merchant": { + "type": "boolean", + "title": "카드할부처리할 때, 할부이자가 발생하는 경우 (카드사 무이자 프로모션 제외)", + "description": "카드할부처리할 때, 할부이자가 발생하는 경우 (카드사 무이자 프로모션 제외).\n\n부과되는 할부이자를 고객대신 가맹점이 지불하고자 PG사와 계약된 경우(현재, 나이스페이먼츠만 지원됨)" + }, + "use_card_point": { + "type": "boolean", + "title": "승인요청시 카드사 포인트 차감하며 결제승인처리할지 flag", + "description": "승인요청시 카드사 포인트 차감하며 결제승인처리할지 flag.\n\nPG사 영업담당자와 계약 당시 사전 협의 필요(현재, 나이스페이먼츠만 지원됨)" + }, + "custom_data": { + "type": "string", + "title": "임의 정보를 기재할 수 있다", + "description": "임의 정보를 기재할 수 있다." + }, + "notice_url": { + "type": "string", + "format": "uri", + "title": "결제 성공시 통지될 Notification, 웹훅 URL", + "description": "결제 성공시 통지될 Notification, 웹훅 URL." + }, + "customer_uid": { + "type": "string", + "title": "고객 식별자 키", + "description": "고객 식별자 키.\n\n아임포트가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키.\n\n다만 고객이라기보다 실제로는 카드의 식별자 키로 써야함." + } + }, + "nullable": false, + "required": [ + "merchant_uid", + "amount", + "name", + "customer_uid" + ], + "description": "간편 결제 카드로 결제 신청 입력 정보." + }, + "IIamportResponseIIamportCertification": { + "type": "object", + "properties": { + "code": { + "type": "number", + "title": "에러 코드", + "description": "에러 코드.\n\n값이 0 이면 오류가 없다는 뜻." + }, + "message": { + "type": "string", + "title": "성공 또는 오류 메시지", + "description": "성공 또는 오류 메시지." + }, + "response": { + "$ref": "#/components/schemas/IIamportCertification", + "title": "응답 데이터, 사실상 본문", + "description": "응답 데이터, 사실상 본문." + } + }, + "nullable": false, + "required": [ + "code", + "message", + "response" + ], + "description": "아임포트 고유의 응답 데이터." + }, + "IIamportCertification": { + "type": "object", + "properties": { + "imp_uid": { + "type": "string", + "title": "아임포트가 발급해 준 식별자 번호", + "description": "아임포트가 발급해 준 식별자 번호." + }, + "merchant_uid": { + "type": "string", + "nullable": true, + "title": "서비스로부터의 식별자 키", + "description": "서비스로부터의 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다." + }, + "name": { + "type": "string", + "title": "본인인증대상자 성명", + "description": "본인인증대상자 성명." + }, + "gender": { + "type": "string", + "title": "성별", + "description": "성별." + }, + "birth": { + "type": "number", + "title": "생년월일", + "description": "생년월일.\n\n리눅스 타임이 쓰인다." + }, + "birthday": { + "type": "string", + "pattern": "^([0-9]{4})(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$", + "title": "생년월일, YYYYMMDD 형식", + "description": "생년월일, YYYYMMDD 형식." + }, + "foreigner": { + "type": "boolean", + "title": "외국인 여부", + "description": "외국인 여부." + }, + "phone": { + "type": "string", + "title": "본인인증 대상자 핸드폰 번호", + "description": "본인인증 대상자 핸드폰 번호." + }, + "carrier": { + "type": "string", + "enum": [ + "SKT", + "KT", + "LGT" + ], + "title": "본인인증 대상자 통신사 코드", + "description": "본인인증 대상자 통신사 코드." + }, + "certified": { + "type": "boolean", + "title": "OTP 인증 여부", + "description": "OTP 인증 여부." + }, + "certified_at": { + "type": "number", + "title": "OTP 인증 일시", + "description": "OTP 인증 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "unique_key": { + "type": "string", + "description": "뭔지 잘 모름, 용도 아시는 분?" + }, + "unique_in_site": { + "type": "string", + "description": "뭔지 잘 모름, 용도 아시는 분?" + }, + "pg_tid": { + "type": "string", + "description": "뭔지 잘 모름, 용도 아시는 분?" + }, + "pg_provider": { + "type": "string", + "title": "PG 제공자", + "description": "PG 제공자." + }, + "origin": { + "type": "string", + "description": "뭔지 잘 모름, 용도 아시는 분?" + }, + "__otp": { + "type": "string", + "title": "(테스트 전용) OTP 코드", + "description": "(테스트 전용) OTP 코드.\n\n오직 `fake-iamport-server` 에서만 쓰이는 속성으로써, 본인인증을 시뮬레이션할 때,\n어떠한 OTP 코드가 발급되었는 지를 확인하기 위하여 사용된다. 이를 이용하여\n{@link functional.certifications.otp.confirm } 함수를 호출하면, 본인인증을 완료할\n수 있다." + } + }, + "nullable": false, + "required": [ + "imp_uid", + "merchant_uid", + "name", + "gender", + "birth", + "birthday", + "foreigner", + "phone", + "carrier", + "certified", + "certified_at", + "unique_key", + "unique_in_site", + "pg_tid", + "pg_provider", + "origin" + ], + "description": "본인 인증 내역.\n\n`IIamportCertification` 은 아임포트의 본인인증 정보를 형상화한 자료구조 인터페이스이다.\n\n단, `IIamportCertification` 레코드의 존재가 곧 본인인증의 완결을 뜻하는 것은 아니다.\n{@link IIamportCertification.certified } 값이 `true` 여야만이 비로소, 본인인증\n대상자가 자신의 핸드폰 번호로 전송된 OTP 를 아임포트의 본인인증 팝업창에 정확히 적어,\n본인인증을 완료했음을 의미한다." + }, + "IIamportCertification.ICreate": { + "type": "object", + "properties": { + "name": { + "type": "string", + "title": "본인인증대상자 성명", + "description": "본인인증대상자 성명." + }, + "phone": { + "type": "string", + "title": "본인인증 대상자 핸드폰 번호", + "description": "본인인증 대상자 핸드폰 번호.\n\n핸드폰 번호에 \"-\" 값이 들어가던 아니던 상관 없음.\n\n다만, 내부적으로는 \"-\" 값을 제거하여 처리한다." + }, + "birth": { + "type": "string", + "pattern": "^([0-9]{4})(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$", + "title": "생년월일", + "description": "생년월일.\n\nYYYYMMDD 형식." + }, + "gender_digit": { + "type": "string", + "title": "주민등록 뒷부분 첫 자리", + "description": "주민등록 뒷부분 첫 자리." + }, + "carrier": { + "type": "string", + "enum": [ + "SKT", + "KT", + "LGT" + ], + "title": "본인인증 대상자 통신사 코드", + "description": "본인인증 대상자 통신사 코드." + }, + "is_mvno": { + "type": "boolean", + "title": "알뜰폰 여부", + "description": "알뜰폰 여부." + }, + "commpany": { + "type": "string", + "title": "가맹점 서비스 명칭 또는 domain URL", + "description": "가맹점 서비스 명칭 또는 domain URL.\n\nKISA 에서 대상자에게 발송하는 SMS에 안내될 서비스 명칭." + }, + "merchant_uid": { + "type": "string", + "title": "귀사 서비스에서의 본인인증 식별자 키", + "description": "귀사 서비스에서의 본인인증 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다." + }, + "pg": { + "type": "string", + "title": "PG 사 구분자", + "description": "PG 사 구분자.\n\n다날 상점아이디를 2개 이상 동시에 사용하시려는 경우에 설정하면 된다.\n\n**danal.{상점아이디}** 형태로 지정." + } + }, + "nullable": false, + "required": [ + "name", + "phone", + "birth", + "gender_digit", + "carrier" + ], + "description": "본인 인증 입력 정보." + }, + "IIamportResponseIIamportCertification.IAccessor": { + "type": "object", + "properties": { + "code": { + "type": "number", + "title": "에러 코드", + "description": "에러 코드.\n\n값이 0 이면 오류가 없다는 뜻." + }, + "message": { + "type": "string", + "title": "성공 또는 오류 메시지", + "description": "성공 또는 오류 메시지." + }, + "response": { + "$ref": "#/components/schemas/IIamportCertification.IAccessor", + "title": "응답 데이터, 사실상 본문", + "description": "응답 데이터, 사실상 본문." + } + }, + "nullable": false, + "required": [ + "code", + "message", + "response" + ], + "description": "아임포트 고유의 응답 데이터." + }, + "IIamportCertification.IAccessor": { + "type": "object", + "properties": { + "imp_uid": { + "type": "string", + "title": "본인인증정보의 식별자 키", + "description": "본인인증정보의 식별자 키." + } + }, + "nullable": false, + "required": [ + "imp_uid" + ], + "description": "본인인증 정보의 접근자 구조체." + }, + "IIamportCertification.IConfirm": { + "type": "object", + "properties": { + "otp": { + "type": "string", + "title": "SMS 로 전송된 본인인증 번호", + "description": "SMS 로 전송된 본인인증 번호." + } + }, + "nullable": false, + "required": [ + "otp" + ], + "description": "본인인증 승인을 위한 입력 정보." + }, + "IIamportPayment.IWebhook": { + "type": "object", + "properties": { + "imp_uid": { + "type": "string", + "title": "결제 정보 {@link IIamportPayment } 의 식별자 키", + "description": "결제 정보 {@link IIamportPayment } 의 식별자 키." + }, + "merchant_uid": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다." + }, + "status": { + "type": "string", + "enum": [ + "paid", + "ready", + "failed", + "cancelled" + ], + "title": "현재 상태", + "description": "현재 상태." + } + }, + "nullable": false, + "required": [ + "imp_uid", + "merchant_uid", + "status" + ], + "description": "웹훅 데이터." + }, + "IIamportPayment.IQuery": { + "type": "object", + "properties": { + "extension": { + "type": "boolean", + "title": "페이팔의 경우, 이 값을 `true` 로 할 것", + "description": "페이팔의 경우, 이 값을 `true` 로 할 것." + } + }, + "nullable": false, + "description": "결제 수단이 페이팔인 경우, 페이팔의 구매자 보호정책에 의해 결제 승인 시점에\nPending 상태를 만든 후, 내부 심사등을 통해 최종 결제 완료라고 변경함.\n\n`iamport` 의 기술적 이슈로 해당 상태를 status: failed 로 기록함. 추후\n페이팔에서 최종결제완료로 변경된 경우, `iamport` 에서 `paid` 로 변경 후,\n해당건에 대한 웹훅 발송. `iamport` 를 사용하는 고객사에서는, failed 로 이미\n처리된 결제건에 대한 paid 상태의 웹훅을 받는 문제점이 생김.\n\n이에, `iamport` 에서 제공하는 `/payment/{imp_uid}` 에 query-string 으로\n`extension=true` 옵션을 추가해야 함" + }, + "IIamportResponseIIamportPayment": { + "type": "object", + "properties": { + "code": { + "type": "number", + "title": "에러 코드", + "description": "에러 코드.\n\n값이 0 이면 오류가 없다는 뜻." + }, + "message": { + "type": "string", + "title": "성공 또는 오류 메시지", + "description": "성공 또는 오류 메시지." + }, + "response": { + "$ref": "#/components/schemas/IIamportPayment", + "title": "응답 데이터, 사실상 본문", + "description": "응답 데이터, 사실상 본문." + } + }, + "nullable": false, + "required": [ + "code", + "message", + "response" + ], + "description": "아임포트 고유의 응답 데이터." + }, + "IIamportPayment": { + "oneOf": [ + { + "$ref": "#/components/schemas/IIamportCardPayment" + }, + { + "$ref": "#/components/schemas/IIamportTransferPayment" + }, + { + "$ref": "#/components/schemas/IIamportVBankPayment" + }, + { + "$ref": "#/components/schemas/IIamportPayment.IBasephonekpaykakaopaypaycolpayssgpaytosspayculturelandsmartculturehappymoneybooknlifepoint" + } + ], + "description": "결제 정보.\n\n`IIamportPayment` 는 아임포트의 결제 정보를 형상화한 자료구조이자 유니언 타입의\n인터페이스로써, if condition 을 통하여 method 값을 특정하면, 파생 타입이 자동으로\n지정된다.\n\n```typescript\nif (payment.pay_method === \"card\")\n payment.card_number; // payment be IIamportCardPayment\n```" + }, + "IIamportTransferPayment": { + "type": "object", + "properties": { + "bank_code": { + "type": "string", + "title": "은행 식별자 코드", + "description": "은행 식별자 코드." + }, + "bank_name": { + "type": "string", + "title": "은행 이름", + "description": "은행 이름." + }, + "pay_method": { + "type": "string", + "enum": [ + "trans" + ] + }, + "imp_uid": { + "type": "string", + "title": "결제 정보 {@link IIamportPayment } 의 식별자 키", + "description": "결제 정보 {@link IIamportPayment } 의 식별자 키." + }, + "merchant_uid": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다." + }, + "name": { + "type": "string", + "nullable": true, + "title": "주문명, 누락 가능", + "description": "주문명, 누락 가능." + }, + "amount": { + "type": "number", + "title": "결제 총액", + "description": "결제 총액." + }, + "cancel_amount": { + "type": "number", + "title": "결제 취소, 환불 총액", + "description": "결제 취소, 환불 총액." + }, + "currency": { + "$ref": "#/components/schemas/IIamportPayment.Currency", + "title": "통화 단위", + "description": "통화 단위." + }, + "receipt_url": { + "type": "string", + "format": "uri", + "title": "영수증 URL", + "description": "영수증 URL." + }, + "cash_receipt_issue": { + "type": "boolean", + "title": "현금 영수증 발행 여부", + "description": "현금 영수증 발행 여부." + }, + "channel": { + "type": "string" + }, + "pg_provider": { + "type": "string" + }, + "emb_pg_provider": { + "type": "string", + "nullable": true + }, + "pg_id": { + "type": "string" + }, + "pg_tid": { + "type": "string" + }, + "escrow": { + "type": "boolean" + }, + "buyer_name": { + "type": "string", + "nullable": true + }, + "buyer_email": { + "type": "string", + "format": "email", + "nullable": true + }, + "buyer_tel": { + "type": "string", + "nullable": true + }, + "buyer_addr": { + "type": "string", + "nullable": true + }, + "buyer_postcode": { + "type": "string", + "nullable": true + }, + "customer_uid": { + "type": "string", + "nullable": true + }, + "customer_uid_usage": { + "type": "string", + "nullable": true + }, + "custom_data": { + "type": "string", + "nullable": true + }, + "user_agent": { + "type": "string", + "nullable": true + }, + "status": { + "$ref": "#/components/schemas/IIamportPayment.Status", + "title": "결제의 현재 (진행) 상태", + "description": "결제의 현재 (진행) 상태." + }, + "started_at": { + "type": "number", + "title": "결제 신청 일시", + "description": "결제 신청 일시.\n\n리눅스 타임이 쓰임." + }, + "paid_at": { + "type": "number", + "title": "결제 (지불) 완료 일시", + "description": "결제 (지불) 완료 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "failed_at": { + "type": "number", + "title": "결제 실패 일시", + "description": "결제 실패 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "cancelled_at": { + "type": "number", + "title": "결제 취소 일시", + "description": "결제 취소 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "fail_reason": { + "type": "string", + "nullable": true + }, + "cancel_reason": { + "type": "string", + "nullable": true + }, + "cancel_history": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IIamportPaymentCancel" + } + } + }, + "nullable": false, + "required": [ + "bank_code", + "bank_name", + "pay_method", + "imp_uid", + "merchant_uid", + "name", + "amount", + "cancel_amount", + "currency", + "receipt_url", + "cash_receipt_issue", + "channel", + "pg_provider", + "emb_pg_provider", + "pg_id", + "pg_tid", + "escrow", + "buyer_name", + "buyer_email", + "buyer_tel", + "buyer_addr", + "buyer_postcode", + "customer_uid", + "customer_uid_usage", + "custom_data", + "user_agent", + "status", + "started_at", + "paid_at", + "failed_at", + "cancelled_at", + "fail_reason", + "cancel_reason", + "cancel_history" + ], + "description": "계좌 이체 결제 정보." + }, + "IIamportVBankPayment": { + "type": "object", + "properties": { + "vbank_code": { + "type": "string", + "title": "가상 계좌 식별자 코드", + "description": "가상 계좌 식별자 코드." + }, + "vbank_name": { + "type": "string", + "description": "가상 게좌 이름" + }, + "vbank_num": { + "type": "string", + "description": "가상 계좌 번호" + }, + "vbank_holder": { + "type": "string", + "title": "가상 계좌 예금주", + "description": "가상 계좌 예금주." + }, + "vbank_date": { + "type": "number", + "title": "가상 계좌 입금 만료 기한", + "description": "가상 계좌 입금 만료 기한." + }, + "vbank_issued_at": { + "type": "number", + "title": "가상 계좌 개설 일시", + "description": "가상 계좌 개설 일시." + }, + "pay_method": { + "type": "string", + "enum": [ + "vbank" + ] + }, + "imp_uid": { + "type": "string", + "title": "결제 정보 {@link IIamportPayment } 의 식별자 키", + "description": "결제 정보 {@link IIamportPayment } 의 식별자 키." + }, + "merchant_uid": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다." + }, + "name": { + "type": "string", + "nullable": true, + "title": "주문명, 누락 가능", + "description": "주문명, 누락 가능." + }, + "amount": { + "type": "number", + "title": "결제 총액", + "description": "결제 총액." + }, + "cancel_amount": { + "type": "number", + "title": "결제 취소, 환불 총액", + "description": "결제 취소, 환불 총액." + }, + "currency": { + "$ref": "#/components/schemas/IIamportPayment.Currency", + "title": "통화 단위", + "description": "통화 단위." + }, + "receipt_url": { + "type": "string", + "format": "uri", + "title": "영수증 URL", + "description": "영수증 URL." + }, + "cash_receipt_issue": { + "type": "boolean", + "title": "현금 영수증 발행 여부", + "description": "현금 영수증 발행 여부." + }, + "channel": { + "type": "string" + }, + "pg_provider": { + "type": "string" + }, + "emb_pg_provider": { + "type": "string", + "nullable": true + }, + "pg_id": { + "type": "string" + }, + "pg_tid": { + "type": "string" + }, + "escrow": { + "type": "boolean" + }, + "buyer_name": { + "type": "string", + "nullable": true + }, + "buyer_email": { + "type": "string", + "format": "email", + "nullable": true + }, + "buyer_tel": { + "type": "string", + "nullable": true + }, + "buyer_addr": { + "type": "string", + "nullable": true + }, + "buyer_postcode": { + "type": "string", + "nullable": true + }, + "customer_uid": { + "type": "string", + "nullable": true + }, + "customer_uid_usage": { + "type": "string", + "nullable": true + }, + "custom_data": { + "type": "string", + "nullable": true + }, + "user_agent": { + "type": "string", + "nullable": true + }, + "status": { + "$ref": "#/components/schemas/IIamportPayment.Status", + "title": "결제의 현재 (진행) 상태", + "description": "결제의 현재 (진행) 상태." + }, + "started_at": { + "type": "number", + "title": "결제 신청 일시", + "description": "결제 신청 일시.\n\n리눅스 타임이 쓰임." + }, + "paid_at": { + "type": "number", + "title": "결제 (지불) 완료 일시", + "description": "결제 (지불) 완료 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "failed_at": { + "type": "number", + "title": "결제 실패 일시", + "description": "결제 실패 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "cancelled_at": { + "type": "number", + "title": "결제 취소 일시", + "description": "결제 취소 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "fail_reason": { + "type": "string", + "nullable": true + }, + "cancel_reason": { + "type": "string", + "nullable": true + }, + "cancel_history": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IIamportPaymentCancel" + } + } + }, + "nullable": false, + "required": [ + "vbank_code", + "vbank_name", + "vbank_num", + "vbank_holder", + "vbank_date", + "vbank_issued_at", + "pay_method", + "imp_uid", + "merchant_uid", + "name", + "amount", + "cancel_amount", + "currency", + "receipt_url", + "cash_receipt_issue", + "channel", + "pg_provider", + "emb_pg_provider", + "pg_id", + "pg_tid", + "escrow", + "buyer_name", + "buyer_email", + "buyer_tel", + "buyer_addr", + "buyer_postcode", + "customer_uid", + "customer_uid_usage", + "custom_data", + "user_agent", + "status", + "started_at", + "paid_at", + "failed_at", + "cancelled_at", + "fail_reason", + "cancel_reason", + "cancel_history" + ], + "description": "가상 계좌 결제 정보." + }, + "IIamportPayment.IBasephonekpaykakaopaypaycolpayssgpaytosspayculturelandsmartculturehappymoneybooknlifepoint": { + "type": "object", + "properties": { + "pay_method": { + "type": "string", + "enum": [ + "phone", + "kpay", + "kakaopay", + "payco", + "lpay", + "ssgpay", + "tosspay", + "cultureland", + "smartculture", + "happymoney", + "booknlife", + "point" + ] + }, + "imp_uid": { + "type": "string", + "title": "결제 정보 {@link IIamportPayment } 의 식별자 키", + "description": "결제 정보 {@link IIamportPayment } 의 식별자 키." + }, + "merchant_uid": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다." + }, + "name": { + "type": "string", + "nullable": true, + "title": "주문명, 누락 가능", + "description": "주문명, 누락 가능." + }, + "amount": { + "type": "number", + "title": "결제 총액", + "description": "결제 총액." + }, + "cancel_amount": { + "type": "number", + "title": "결제 취소, 환불 총액", + "description": "결제 취소, 환불 총액." + }, + "currency": { + "$ref": "#/components/schemas/IIamportPayment.Currency", + "title": "통화 단위", + "description": "통화 단위." + }, + "receipt_url": { + "type": "string", + "format": "uri", + "title": "영수증 URL", + "description": "영수증 URL." + }, + "cash_receipt_issue": { + "type": "boolean", + "title": "현금 영수증 발행 여부", + "description": "현금 영수증 발행 여부." + }, + "channel": { + "type": "string" + }, + "pg_provider": { + "type": "string" + }, + "emb_pg_provider": { + "type": "string", + "nullable": true + }, + "pg_id": { + "type": "string" + }, + "pg_tid": { + "type": "string" + }, + "escrow": { + "type": "boolean" + }, + "buyer_name": { + "type": "string", + "nullable": true + }, + "buyer_email": { + "type": "string", + "format": "email", + "nullable": true + }, + "buyer_tel": { + "type": "string", + "nullable": true + }, + "buyer_addr": { + "type": "string", + "nullable": true + }, + "buyer_postcode": { + "type": "string", + "nullable": true + }, + "customer_uid": { + "type": "string", + "nullable": true + }, + "customer_uid_usage": { + "type": "string", + "nullable": true + }, + "custom_data": { + "type": "string", + "nullable": true + }, + "user_agent": { + "type": "string", + "nullable": true + }, + "status": { + "$ref": "#/components/schemas/IIamportPayment.Status", + "title": "결제의 현재 (진행) 상태", + "description": "결제의 현재 (진행) 상태." + }, + "started_at": { + "type": "number", + "title": "결제 신청 일시", + "description": "결제 신청 일시.\n\n리눅스 타임이 쓰임." + }, + "paid_at": { + "type": "number", + "title": "결제 (지불) 완료 일시", + "description": "결제 (지불) 완료 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "failed_at": { + "type": "number", + "title": "결제 실패 일시", + "description": "결제 실패 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "cancelled_at": { + "type": "number", + "title": "결제 취소 일시", + "description": "결제 취소 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "fail_reason": { + "type": "string", + "nullable": true + }, + "cancel_reason": { + "type": "string", + "nullable": true + }, + "cancel_history": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IIamportPaymentCancel" + } + } + }, + "nullable": false, + "required": [ + "pay_method", + "imp_uid", + "merchant_uid", + "name", + "amount", + "cancel_amount", + "currency", + "receipt_url", + "cash_receipt_issue", + "channel", + "pg_provider", + "emb_pg_provider", + "pg_id", + "pg_tid", + "escrow", + "buyer_name", + "buyer_email", + "buyer_tel", + "buyer_addr", + "buyer_postcode", + "customer_uid", + "customer_uid_usage", + "custom_data", + "user_agent", + "status", + "started_at", + "paid_at", + "failed_at", + "cancelled_at", + "fail_reason", + "cancel_reason", + "cancel_history" + ], + "description": "결제 기본 (공통) 정보." + }, + "IIamportPaymentCancel.ICreate": { + "type": "object", + "properties": { + "imp_uid": { + "type": "string", + "title": "결제 정보 {@link IIamportPayment } 의 식별자 키", + "description": "결제 정보 {@link IIamportPayment } 의 식별자 키." + }, + "merchant_uid": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다." + }, + "amount": { + "type": "number", + "title": "취소 금액, 부분 취소도 가능하다", + "description": "취소 금액, 부분 취소도 가능하다.\n\n누락시 전액 취소." + }, + "checksum": { + "type": "number", + "minimum": 0, + "nullable": true, + "title": "취소 트랜잭션 수행 전, 현재 시점의 취소 가능한 잔액", + "description": "취소 트랜잭션 수행 전, 현재 시점의 취소 가능한 잔액.\n\nAPI요청자가 기록하고 있는 취소가능 잔액과 아임포트가 기록하고 있는 취소가능 잔액이\n일치하는지 사전에 검증하고, 검증에 실패하면 트랜잭션을 수행하지 않는다.\n\n`null` 인 경우에는 검증 프로세스를 생략." + }, + "reason": { + "type": "string", + "title": "취소 사유", + "description": "취소 사유." + }, + "tax_free": { + "type": "number", + "default": 0, + "title": "취소요청금액 중 면세금액", + "description": "취소요청금액 중 면세금액." + }, + "refund_holder": { + "type": "string", + "title": "환불계좌 예금주", + "description": "환불계좌 예금주." + }, + "refund_bank": { + "type": "string", + "title": "환불계좌 은행 코드", + "description": "환불계좌 은행 코드." + }, + "refund_account": { + "type": "string", + "title": "환불계좌 계좌번호", + "description": "환불계좌 계좌번호." + }, + "refund_tel": { + "type": "string", + "description": "환불계좌 예금주 연락처" + } + }, + "nullable": false, + "required": [ + "imp_uid", + "merchant_uid", + "checksum", + "reason" + ], + "description": "결제 취소 입력 정보." + }, + "IIamportResponseIIamportReceipt": { + "type": "object", + "properties": { + "code": { + "type": "number", + "title": "에러 코드", + "description": "에러 코드.\n\n값이 0 이면 오류가 없다는 뜻." + }, + "message": { + "type": "string", + "title": "성공 또는 오류 메시지", + "description": "성공 또는 오류 메시지." + }, + "response": { + "$ref": "#/components/schemas/IIamportReceipt", + "title": "응답 데이터, 사실상 본문", + "description": "응답 데이터, 사실상 본문." + } + }, + "nullable": false, + "required": [ + "code", + "message", + "response" + ], + "description": "아임포트 고유의 응답 데이터." + }, + "IIamportReceipt": { + "type": "object", + "properties": { + "imp_uid": { + "type": "string", + "title": "귀속 결제의 {@link IIamportPayment", + "description": "귀속 결제의 {@link IIamportPayment.imp_uid }." + }, + "receipt_uid": { + "type": "string", + "title": "현금 영수증의 고유 식별자 ID", + "description": "현금 영수증의 고유 식별자 ID." + }, + "apply_num": { + "type": "string", + "title": "승인 번호", + "description": "승인 번호." + }, + "type": { + "$ref": "#/components/schemas/IIamportReceipt.Type", + "title": "발행 타입 (대상)", + "description": "발행 타입 (대상)." + }, + "amount": { + "type": "number", + "title": "결제 총액", + "description": "결제 총액." + }, + "vat": { + "type": "number", + "title": "부가세", + "description": "부가세." + }, + "receipt_url": { + "type": "string", + "format": "uri", + "title": "현금영수증 조회 URL", + "description": "현금영수증 조회 URL." + }, + "applied_at": { + "type": "number", + "title": "현금영수증 발행 시간", + "description": "현금영수증 발행 시간." + }, + "cancelled_at": { + "type": "number", + "title": "현금영수증 취소 시간", + "description": "현금영수증 취소 시간.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + } + }, + "nullable": false, + "required": [ + "imp_uid", + "receipt_uid", + "apply_num", + "type", + "amount", + "vat", + "receipt_url", + "applied_at", + "cancelled_at" + ], + "description": "현금 영수증 정보." + }, + "IIamportReceipt.Type": { + "type": "string", + "enum": [ + "person", + "company" + ], + "description": "현금영수증 발행 타입 (대상)." + }, + "IIamportReceipt.ICreate": { + "type": "object", + "properties": { + "imp_uid": { + "type": "string", + "title": "귀속 결제의 {@link IIamportPayment", + "description": "귀속 결제의 {@link IIamportPayment.imp_uid }." + }, + "identifier": { + "type": "string", + "title": "현금영수증 발생대상 식별정보", + "description": "현금영수증 발생대상 식별정보.\n\n - 국세청현금영수증카드\n - 휴대폰번호\n - 주민등록번호\n - 사업자등록번호" + }, + "identifier_type": { + "type": "string", + "enum": [ + "phone", + "person", + "business", + "taxcard" + ], + "title": "현금영수증 발행대상 유형", + "description": "현금영수증 발행대상 유형.\n\n - person: 주민등록번호\n - business: 사업자등록번호\n - phone: 휴대폰번호\n - taxcard: 국세청현금영수증카드\n\n일부 PG 사의 경우 이 항목이 없어 된다는데, 어지간하면 그냥 쓰기 바람." + }, + "type": { + "type": "string", + "enum": [ + "person", + "company" + ], + "title": "현금영수증 발행 타입 (대상)", + "description": "현금영수증 발행 타입 (대상).\n\n누락시 person 이 사용됨." + }, + "buyer_name": { + "type": "string", + "title": "구매자 이름", + "description": "구매자 이름.\n\n형금영수증 발행건 사후 추적을 위해 가급 입력하기 바람." + }, + "buyer_email": { + "type": "string", + "title": "구매자 이메일", + "description": "구매자 이메일." + }, + "buyer_tel": { + "type": "string", + "title": "구매자 전화번호", + "description": "구매자 전화번호.\n\n현금영수증 발행건 사후 추적을 위해 가급 입력하기 바람." + }, + "tax_free": { + "type": "number", + "title": "면세 금액", + "description": "면세 금액." + } + }, + "nullable": false, + "required": [ + "imp_uid", + "identifier" + ], + "description": "현금영수증 입력 정보." + }, + "IIamportUser.IAccessor": { + "type": "object", + "properties": { + "imp_key": { + "type": "string", + "title": "API 키", + "description": "API 키." + }, + "imp_secret": { + "type": "string", + "title": "Secret 키", + "description": "Secret 키." + } + }, + "nullable": false, + "required": [ + "imp_key", + "imp_secret" + ], + "description": "아임포트에서 부여해 준 API 및 secret 키." + }, + "IIamportResponseIIamportUser": { + "type": "object", + "properties": { + "code": { + "type": "number", + "title": "에러 코드", + "description": "에러 코드.\n\n값이 0 이면 오류가 없다는 뜻." + }, + "message": { + "type": "string", + "title": "성공 또는 오류 메시지", + "description": "성공 또는 오류 메시지." + }, + "response": { + "$ref": "#/components/schemas/IIamportUser", + "title": "응답 데이터, 사실상 본문", + "description": "응답 데이터, 사실상 본문." + } + }, + "nullable": false, + "required": [ + "code", + "message", + "response" + ], + "description": "아임포트 고유의 응답 데이터." + }, + "IIamportUser": { + "type": "object", + "properties": { + "now": { + "type": "number", + "title": "토큰 발행 시간", + "description": "토큰 발행 시간." + }, + "expired_at": { + "type": "number", + "title": "토큰 만료 시간", + "description": "토큰 만료 시간.\n\n리눅스 타임이 기준이며, 이를 JS 에서 사용하려거든, 아래와 같이 변환해야 한다.\n\n```typescript\nnew Date(user.expired_at * 1_000);\n```" + }, + "access_token": { + "type": "string", + "title": "유저 인증 토큰", + "description": "유저 인증 토큰." + } + }, + "nullable": false, + "required": [ + "now", + "expired_at", + "access_token" + ], + "description": "아임포트 유저 인증 정보.\n\n아임포트는 고객사에게 API 및 secret 키 정보, {@link IIamportUser.IAccessor } 를 발급해준다.\n\n하지만 이를 곧장 아임포트의 유저 인증에 사용할 수는 없고, 해당 API 및 secret 키를 토대로 유저\n인증 토큰을 발급받아야 하는데, 이 유저 인증 토큰에는 하필이면 만로 시간이라는 게 존재한다.\n`IIamportUser` 는 바로 이러한 유저 인증 토큰 및 그것의 만료 시간을 형상화한 자료구조\n인터페이스이다.\n\n더하여 이처럼 만료 시간이 존재하는 아임포트의 유저 인증 토큰의 특성상, 이것의 만료 시간이\n초과되지 않도록 관리하는 것은 매우 힘든 일이다. 이에 `iamport-server-api` 에서는 아임포트\n유저 인증 토큰이 만료될 때마다 자동 갱신해주는, {@link IamportConnector } 클래스를 제공한다." + }, + "IIamportVBankPayment.ICreate": { + "type": "object", + "properties": { + "merchant_uid": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다." + }, + "amount": { + "type": "number", + "title": "총액", + "description": "총액." + }, + "vbank_code": { + "type": "string", + "title": "가상계좌 은행 코드", + "description": "가상계좌 은행 코드." + }, + "vbank_due": { + "type": "number", + "title": "가상계좌 입금기한, 유닉스 타임", + "description": "가상계좌 입금기한, 유닉스 타임." + }, + "vbank_holder": { + "type": "string", + "title": "예금주", + "description": "예금주." + }, + "name": { + "type": "string" + }, + "buyer_name": { + "type": "string" + }, + "buyer_email": { + "type": "string" + }, + "buyer_tel": { + "type": "string" + }, + "buyer_addr": { + "type": "string" + }, + "buyer_postcode": { + "type": "string" + }, + "pg": { + "type": "string" + }, + "notice_url": { + "type": "string", + "title": "가상 계좌 입금 정보를 수신할 URL", + "description": "가상 계좌 입금 정보를 수신할 URL.\n\n누락시 기본 웹훅 URL 사용." + }, + "custom_data": { + "type": "string", + "title": "커스텀 데이터, 자유롭게 사용 가능", + "description": "커스텀 데이터, 자유롭게 사용 가능." + }, + "pg_api_key": { + "type": "string", + "title": "[이니시스 전용] 가맹점 콘솔에서 확인한 API 값", + "description": "[이니시스 전용] 가맹점 콘솔에서 확인한 API 값." + } + }, + "nullable": false, + "required": [ + "merchant_uid", + "amount", + "vbank_code", + "vbank_due", + "vbank_holder" + ], + "description": "가상 계좌 결제 입력 정보.\n\n가상 계좌를 임의 생성할 수 있다.\n\n단, 일부 PG 사 혹은 `fake-iamport-server` 만 가능.\n\n - 세틀뱅크\n - 나이스페이먼츠\n - KG이니시스" + }, + "IIamportResponseIIamportVBankPayment": { + "type": "object", + "properties": { + "code": { + "type": "number", + "title": "에러 코드", + "description": "에러 코드.\n\n값이 0 이면 오류가 없다는 뜻." + }, + "message": { + "type": "string", + "title": "성공 또는 오류 메시지", + "description": "성공 또는 오류 메시지." + }, + "response": { + "$ref": "#/components/schemas/IIamportVBankPayment", + "title": "응답 데이터, 사실상 본문", + "description": "응답 데이터, 사실상 본문." + } + }, + "nullable": false, + "required": [ + "code", + "message", + "response" + ], + "description": "아임포트 고유의 응답 데이터." + }, + "IIamportVBankPayment.IUpdate": { + "type": "object", + "properties": { + "imp_uid": { + "type": "string", + "title": "대상 결제 기록의 {@link IIamportPayment", + "description": "대상 결제 기록의 {@link IIamportPayment.imp_uid }." + }, + "amount": { + "type": "number", + "title": "수정할 결제 금액", + "description": "수정할 결제 금액." + }, + "vbank_due": { + "type": "number", + "title": "수정할 가상계좌 입금 기한", + "description": "수정할 가상계좌 입금 기한." + } + }, + "nullable": false, + "required": [ + "imp_uid" + ], + "description": "가상 계좌 결제의 수정 입력 정보.\n\n아직 입금되지 않은 가상계좌의 입금기한 또는 입금금액을 수정할 수 있다.\n\n다만, 세틀뱅크 혹은 `fake-iamport-server` 만 가능." + } + }, + "securitySchemes": { + "bearer": { + "type": "apiKey", + "name": "Authorization", + "in": "header" + } + } + } +} \ No newline at end of file diff --git a/packages/payment-api/package.json b/packages/payment-api/package.json index e0b3b4a..77cf1c5 100644 --- a/packages/payment-api/package.json +++ b/packages/payment-api/package.json @@ -1,6 +1,6 @@ { "name": "@samchon/payment-api", - "version": "6.0.5", + "version": "6.0.6", "description": "API for Payment Backend", "main": "lib/index.js", "typings": "lib/index.d.ts", @@ -34,10 +34,10 @@ "typescript": "^5.3.2" }, "dependencies": { - "@nestia/fetcher": "^2.5.1", + "@nestia/fetcher": "^2.5.8", "@types/node": "^20.11.5", - "iamport-server-api": "^6.0.5", - "toss-payments-server-api": "^6.0.5", - "typia": "^5.4.1" + "iamport-server-api": "^6.0.6", + "toss-payments-server-api": "^6.0.6", + "typia": "^5.4.9" } } \ No newline at end of file diff --git a/packages/payment-api/swagger.json b/packages/payment-api/swagger.json index c038972..6ab9a22 100644 --- a/packages/payment-api/swagger.json +++ b/packages/payment-api/swagger.json @@ -1 +1,3683 @@ -{"openapi":"3.0.1","servers":[{"url":"https://github.com/samchon/nestia","description":"insert your server url"}],"info":{"version":"6.0.5","title":"@samchon/payment-backend","description":"Payment Backend Server","license":{"name":"MIT"}},"paths":{"/monitors/health":{"get":{"tags":[],"parameters":[],"responses":{"200":{"description":""}}}},"/monitors/performance":{"get":{"tags":[],"parameters":[],"responses":{"200":{"description":"## Warning\n\nResponse data have been encrypted.\n\nThe response body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedRoute.G.et](https://github.com/samchon/@nestia/core#encryptedroute) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/IPerformance"}}},"x-nestia-encrypted":true}}}},"/monitors/system":{"get":{"tags":[],"parameters":[],"responses":{"200":{"description":"## Warning\n\nResponse data have been encrypted.\n\nThe response body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedRoute.G.et](https://github.com/samchon/@nestia/core#encryptedroute) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ISystem"}}},"x-nestia-encrypted":true}}}},"/payments/histories/get":{"patch":{"tags":[],"parameters":[],"requestBody":{"description":"## Warning\n\nRequest body must be encrypted.\n\nThe request body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedBody](https://github.com/samchon/@nestia/core#encryptedbody) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n결제 내역의 원천 정보 + 비밀번호","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/IPaymentSource.IAccessor"}}},"required":true,"x-nestia-encrypted":true},"responses":{"201":{"description":"## Warning\n\nResponse data have been encrypted.\n\nThe response body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedRoute.P.atch](https://github.com/samchon/@nestia/core#encryptedroute) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n결제 내역","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/IPaymentHistory"}}},"x-nestia-encrypted":true}},"summary":"결제 내역 상세 조회하기","description":"결제 내역 상세 조회하기."}},"/payments/histories/{id}":{"patch":{"tags":[],"parameters":[{"name":"id","in":"path","schema":{"type":"string","format":"uuid"},"description":"Primary Key","required":true}],"requestBody":{"description":"## Warning\n\nRequest body must be encrypted.\n\nThe request body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedBody](https://github.com/samchon/@nestia/core#encryptedbody) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n결제 내역의 비밀번호","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/IPaymentSource.IPassword"}}},"required":true,"x-nestia-encrypted":true},"responses":{"201":{"description":"## Warning\n\nResponse data have been encrypted.\n\nThe response body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedRoute.P.atch](https://github.com/samchon/@nestia/core#encryptedroute) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n결제 내역","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/IPaymentHistory"}}},"x-nestia-encrypted":true}},"summary":"결제 내역 상세 조회하기","description":"결제 내역 상세 조회하기."}},"/payments/histories":{"post":{"tags":[],"parameters":[],"requestBody":{"description":"## Warning\n\nRequest body must be encrypted.\n\nThe request body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedBody](https://github.com/samchon/@nestia/core#encryptedbody) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n결제 내역 입력 정보","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/IPaymentHistory.ICreate"}}},"required":true,"x-nestia-encrypted":true},"responses":{"201":{"description":"## Warning\n\nResponse data have been encrypted.\n\nThe response body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedRoute.P.ost](https://github.com/samchon/@nestia/core#encryptedroute) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n결제 내역","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/IPaymentHistory"}}},"x-nestia-encrypted":true}},"summary":"결제 내역 발행하기","description":"결제 내역 발행하기."}},"/payments/histories/cancel":{"put":{"tags":[],"parameters":[],"requestBody":{"description":"## Warning\n\nRequest body must be encrypted.\n\nThe request body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedBody](https://github.com/samchon/@nestia/core#encryptedbody) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n결제 취소 내역 입력 정보","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/IPaymentCancelHistory.ICreate"}}},"required":true,"x-nestia-encrypted":true},"responses":{"201":{"description":"## Warning\n\nResponse data have been encrypted.\n\nThe response body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedRoute.P.ut](https://github.com/samchon/@nestia/core#encryptedroute) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/IPaymentHistory"}}},"x-nestia-encrypted":true}},"summary":"결제 취소하기","description":"결제 취소하기."}},"/payments/reservations/get":{"patch":{"tags":[],"parameters":[],"requestBody":{"description":"## Warning\n\nRequest body must be encrypted.\n\nThe request body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedBody](https://github.com/samchon/@nestia/core#encryptedbody) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n간편 결제 수단의 원천 정보 + 비밀번호","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/IPaymentSource.IAccessor"}}},"required":true,"x-nestia-encrypted":true},"responses":{"201":{"description":"## Warning\n\nResponse data have been encrypted.\n\nThe response body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedRoute.P.atch](https://github.com/samchon/@nestia/core#encryptedroute) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n결제 내역","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/IPaymentReservation"}}},"x-nestia-encrypted":true}},"summary":"간편 결제 수단 조회하기","description":"간편 결제 수단 조회하기."}},"/payments/reservations/{id}":{"patch":{"tags":[],"parameters":[{"name":"id","in":"path","schema":{"type":"string","format":"uuid"},"description":"Primary Key","required":true}],"requestBody":{"description":"## Warning\n\nRequest body must be encrypted.\n\nThe request body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedBody](https://github.com/samchon/@nestia/core#encryptedbody) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n비밀번호","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/IPaymentSource.IPassword"}}},"required":true,"x-nestia-encrypted":true},"responses":{"201":{"description":"## Warning\n\nResponse data have been encrypted.\n\nThe response body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedRoute.P.atch](https://github.com/samchon/@nestia/core#encryptedroute) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n간편 결제 수단 정보","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/IPaymentReservation"}}},"x-nestia-encrypted":true}},"summary":"간편 결제 수단 조회하기","description":"간편 결제 수단 조회하기."}},"/payments/reservations":{"post":{"tags":[],"parameters":[],"requestBody":{"description":"## Warning\n\nRequest body must be encrypted.\n\nThe request body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedBody](https://github.com/samchon/@nestia/core#encryptedbody) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n간편 결제 수단 입력 정보","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/IPaymentReservation.ICreate"}}},"required":true,"x-nestia-encrypted":true},"responses":{"201":{"description":"## Warning\n\nResponse data have been encrypted.\n\nThe response body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedRoute.P.ost](https://github.com/samchon/@nestia/core#encryptedroute) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n간편 결제 수단 정보","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/IPaymentReservation"}}},"x-nestia-encrypted":true}},"summary":"간편 결제 수단 등록하기","description":"간편 결제 수단 등록하기."}},"/payments/webhooks/iamport":{"post":{"tags":[],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IIamportPayment.IWebhook"}}},"required":true},"responses":{"201":{"description":""}}}}},"components":{"schemas":{"IPerformance":{"type":"object","properties":{"cpu":{"$ref":"#/components/schemas/process.global.NodeJS.CpuUsage"},"memory":{"$ref":"#/components/schemas/process.global.NodeJS.MemoryUsage"},"resource":{"$ref":"#/components/schemas/process.global.NodeJS.ResourceUsage"}},"nullable":false,"required":["cpu","memory","resource"]},"process.global.NodeJS.CpuUsage":{"type":"object","properties":{"user":{"type":"number"},"system":{"type":"number"}},"nullable":false,"required":["user","system"]},"process.global.NodeJS.MemoryUsage":{"type":"object","properties":{"rss":{"type":"number"},"heapTotal":{"type":"number"},"heapUsed":{"type":"number"},"external":{"type":"number"},"arrayBuffers":{"type":"number"}},"nullable":false,"required":["rss","heapTotal","heapUsed","external","arrayBuffers"]},"process.global.NodeJS.ResourceUsage":{"type":"object","properties":{"fsRead":{"type":"number"},"fsWrite":{"type":"number"},"involuntaryContextSwitches":{"type":"number"},"ipcReceived":{"type":"number"},"ipcSent":{"type":"number"},"majorPageFault":{"type":"number"},"maxRSS":{"type":"number"},"minorPageFault":{"type":"number"},"sharedMemorySize":{"type":"number"},"signalsCount":{"type":"number"},"swappedOut":{"type":"number"},"systemCPUTime":{"type":"number"},"unsharedDataSize":{"type":"number"},"unsharedStackSize":{"type":"number"},"userCPUTime":{"type":"number"},"voluntaryContextSwitches":{"type":"number"}},"nullable":false,"required":["fsRead","fsWrite","involuntaryContextSwitches","ipcReceived","ipcSent","majorPageFault","maxRSS","minorPageFault","sharedMemorySize","signalsCount","swappedOut","systemCPUTime","unsharedDataSize","unsharedStackSize","userCPUTime","voluntaryContextSwitches"]},"ISystem":{"type":"object","properties":{"uid":{"type":"string","description":"Random Unique ID."},"arguments":{"type":"array","items":{"type":"string"},"description":"`process.argv`"},"commit":{"$ref":"#/components/schemas/ISystem.ICommit","description":"Git commit information."},"package":{"$ref":"#/components/schemas/ISystem.IPackage","description":"`package.json`"},"created_at":{"type":"string","description":"Creation time of this system."}},"nullable":false,"required":["uid","arguments","commit","package","created_at"]},"ISystem.ICommit":{"type":"object","properties":{"shortHash":{"type":"string"},"branch":{"type":"string"},"hash":{"type":"string"},"subject":{"type":"string"},"sanitizedSubject":{"type":"string"},"body":{"type":"string"},"author":{"$ref":"#/components/schemas/ISystem.ICommit.IUser"},"committer":{"$ref":"#/components/schemas/ISystem.ICommit.IUser"},"authored_at":{"type":"string"},"commited_at":{"type":"string"},"notes":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}},"nullable":false,"required":["shortHash","branch","hash","subject","sanitizedSubject","body","author","committer","authored_at","commited_at","tags"],"description":"Git commit information."},"ISystem.ICommit.IUser":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"}},"nullable":false,"required":["name","email"],"description":"Git user information."},"ISystem.IPackage":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"description":{"type":"string"},"scripts":{"$ref":"#/components/schemas/Recordstringstring"},"repository":{"type":"object","properties":{"type":{"type":"string","enum":["git"]},"url":{"type":"string"}},"nullable":false,"required":["type","url"]},"author":{"type":"string"},"license":{"type":"string"},"bugs":{"type":"object","properties":{"url":{"type":"string"}},"nullable":false,"required":["url"]},"homepage":{"type":"string"},"devDependencies":{"$ref":"#/components/schemas/Recordstringstring"},"dependencies":{"$ref":"#/components/schemas/Recordstringstring"},"publishConfig":{"type":"object","properties":{"registry":{"type":"string"}},"nullable":false,"required":["registry"]},"main":{"type":"string"},"typings":{"type":"string"},"files":{"type":"array","items":{"type":"string"}}},"nullable":false,"required":["name","version","description","scripts","repository","author","license","bugs","homepage","devDependencies","dependencies"],"description":"NPM package information."},"Recordstringstring":{"type":"object","properties":{},"nullable":false,"description":"Construct a type with a set of properties K of type T"},"IPaymentSource.IAccessor":{"type":"object","properties":{"schema":{"type":"string","description":"DB 스키마 이름"},"table":{"type":"string","description":"DB 테이블 명"},"id":{"type":"string","format":"uuid","description":"참조 레코드의 PK"},"password":{"type":"string","description":"레코드 조회를 위한 비밀번호 입력."}},"nullable":false,"required":["schema","table","id","password"],"description":"접근자 정보.\n\n`IPaymentSource.IAccessor` 는 {@link IPaymentHistory 결제 내역} 내지\n{@link IPaymentReservation 간편 결제 수단 정보}를 조회할 때, 그것의 고유 식별자\nID 가 아닌 원천 레코드 식별자 정보 {@link IPaymentSource } 를 통하여 조회할 때\n사용하는 접근자 정보이다.\n\n다만 `payments-server` 의 모든 개별 레코드는 이를 조회할 시 비밀번호가 필요하기에,\n{@link IPaymentSource } 의 속성들에 비밀번호가 하나 더 추가되었을 뿐이다."},"IPaymentHistory":{"oneOf":[{"$ref":"#/components/schemas/IPaymentHistory.IamportType"},{"$ref":"#/components/schemas/IPaymentHistory.TossType"}],"description":"결제 내역.\n\n`IPaymentHistory` 는 결제 내역을 형상화한 자료구조이자 유니언 타입의 인터페이이다.\n서비스 시스템으로부 결제 사건의 귀속 정보 ({@link IPaymentHistory.ICreate.vendor } +\n{@link IPaymentHistory.ICreate.source }) 를 전달받아, 본 Payment 시스템이 PG 사에\n추가 정보를 취득하여 레코드가 완성된다.\n\n그리고 만일 현 결제 건이 가상계좌와 같이 레코드 생성 시점에 지불이 이루어지지 않은\n경우라면, 사후 {@link IPaymentWebhook 웹훅 이벤트}를 통하여 지불 완료 시각을 뜻하는\n{@link paid_at } 가 설정될 수 있다. 그리고 반대로 이미 결제가 완료된 경우라도,\n환불 등의 이유로 인하여 {@link cancelled_at } 이 사후 기재될 수 있다.\n\n참고로 `if condition` 을 통하여 {@link IPaymentHistory.vendor_code } 값을 특정하면,\n파생 타입이 자동으로 다운 캐스팅 된다.\n\n```typescript\nif (history.vendor_code === \"toss.payments\")\n history.data.paymentKey; // history.data be ITossPayment\n```"},"IPaymentHistory.IamportType":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Primary Key."},"vendor_code":{"type":"string","enum":["iamport"],"description":"벤더사 식별자 코드.\n\n{@link IPaymentVendor.code }와 완전히 동일한 값이되, 단지 union type\nspecialization 을 위해 중복 표기하였을 뿐이다. `if condition` 을 통하여\n{@link IPaymentHistory.data }의 타입을 특정할 수 있다."},"vendor":{"$ref":"#/components/schemas/IPaymentVendoriamport","description":"벤더 정보."},"source":{"$ref":"#/components/schemas/IPaymentSource","description":"원천 래코드 정보."},"data":{"$ref":"#/components/schemas/IIamportPayment","description":"결제 상세 데이터, 벤더별로 데이터 양식이 다르니 주의할 것."},"currency":{"type":"string","description":"통화 단위\n\nKRW, USB, JPY 등."},"price":{"type":"number","minimum":0,"description":"결제 가격."},"refund":{"type":"number","minimum":0,"nullable":true,"description":"결제 취소시의 환불 금액."},"webhook_url":{"type":"string","format":"uri","nullable":true,"description":"결제 정보가 갱신되었을 때, 이를 수신할 URL"},"created_at":{"type":"string","format":"date-time","description":"결제 레코드 생성 일시."},"paid_at":{"type":"string","format":"date-time","nullable":true,"description":"결제 완료 일시."},"cancelled_at":{"type":"string","format":"date-time","nullable":true,"description":"결제 취소 일시."},"cancels":{"type":"array","items":{"$ref":"#/components/schemas/IPaymentCancelHistory"},"description":"결제 취소 내역 리스트."}},"nullable":false,"required":["id","vendor_code","vendor","source","data","currency","price","refund","webhook_url","created_at","paid_at","cancelled_at","cancels"],"description":"아임포트로부터의 결제 내역."},"IPaymentVendoriamport":{"type":"object","properties":{"code":{"type":"string","enum":["iamport"],"description":"벤더사 식별자 코드.\n\n아임포트의 경우에는 `iamport` 를, 토스의 경우에는 `toss.payments` 를 적어주면 된다."},"store_id":{"type":"string","description":"벤더사에 등록한 스토어 ID.\n\n결제 PG 사들은 서비스 주소가 다르거나, 또는 동일한 서비스이되 연결되는 백엔드 서버\n주소가 다르거든, 각기 다른 스토어 계정을 신청해 사용하라고 한다. 이는 요즘같이 MSA\n(Micro Service Architecture) 가 대세인 시대에 매우 불합리한 방식이기는 하지만, 어쨋든\n이러한 이유로 인하여, 한 회사 내지 단체가 복수의 스토어 ID 를 가지는 경우가 왕왕\n있다.\n\n때문에 `payments-server` 는, {@link IPaymentHistory 결제 내역}을 발행하거나\n{@link IPaymentReservation 간편 결제 수단}을 등록할 때 모두, 사용된 스토어의 ID\n를 반드시 기재하도록 하고 있다."},"uid":{"type":"string","description":"벤더사로부터 발급받은 식별자 번호.\n\n결제 PG 사들이 제공하는 팝업창을 이용하여 결제를 진행하거나 혹은 간편 결제 수단을\n등록하거든, 결제 PG 사들은 해당 건에 대하여 별도의 식별자 번호를 발급한다.\n`IPaymentVendor.uid` 는 이처럼 결제 PG 사들이 발급해 준 식별자 번호를 기재하는\n속성이다.\n\n단 예외가 하나 있어, 아임포트는 간편 결제 카드 등록 건에 대하여 별도의 식별자 번호를\n부여하지 않고, 귀하의 서비스에서 발급해 준 ID 를 그대로 사용한다. 때문에 아임포트를\n통한 간편 결제 카드 등록의 건만 예외적으로, `IPaymentVendor.uid` 에\n{@link IPaymentSource.id } 를 동일하게 할당해주어야 한다."}},"nullable":false,"required":["code","store_id","uid"],"description":"벤더사 정보.\n\n`IPaymentVendor` 결제 PG 벤더사에 관련된 정보를 형상화한 자료구조 인터페이스이다."},"IPaymentSource":{"type":"object","properties":{"schema":{"type":"string","description":"DB 스키마 이름"},"table":{"type":"string","description":"DB 테이블 명"},"id":{"type":"string","format":"uuid","description":"참조 레코드의 PK"}},"nullable":false,"required":["schema","table","id"],"description":"원천 레코드 참조 정보.\n\n`IPaymentSource` 는 {@link IPaymentHistory 결제 내역} 및\n{@link IPaymentResrvation 간편 결제 수단}의 원천이 되는 레코드의 참조 정보를 형상화한\n자료구조 인터페이이다. 만일 대상이 {@link IPaymentHistory 결제 내역}이라면 결제의\n근원이 되는 주문에 대한 참조 정보를, 대상이 {@link IPaymentResrvation 간편 결제 수단}\n이라면 이를 기록한 귀사 서비스의 참조 정보를 기입하면 된다."},"IIamportPayment":{"oneOf":[{"$ref":"#/components/schemas/IIamportCardPayment"},{"$ref":"#/components/schemas/IIamportTransferPayment"},{"$ref":"#/components/schemas/IIamportVBankPayment"},{"$ref":"#/components/schemas/IIamportPayment.IBasephonekpaykakaopaypaycolpayssgpaytosspayculturelandsmartculturehappymoneybooknlifepoint"}],"description":"결제 정보.\n\n`IIamportPayment` 는 아임포트의 결제 정보를 형상화한 자료구조이자 유니언 타입의\n인터페이스로써, if condition 을 통하여 method 값을 특정하면, 파생 타입이 자동으로\n지정된다.\n\n```typescript\nif (payment.pay_method === \"card\")\n payment.card_number; // payment be IIamportCardPayment\n```"},"IIamportCardPayment":{"type":"object","properties":{"card_code":{"type":"string","description":"카드 식별자 코드."},"card_name":{"type":"string","description":"카드 이름."},"card_number":{"type":"string","pattern":"\\d{4}-\\d{4}-\\d{4}-\\d{4}","description":"카드 번호."},"card_quota":{"type":"integer","description":"할부 개월 수."},"apply_num":{"type":"string","description":"카드사 승인번호."},"pay_method":{"type":"string","enum":["card","samsung"]},"imp_uid":{"type":"string","description":"결제 정보 {@link IIamportPayment } 의 식별자 키."},"merchant_uid":{"type":"string","description":"주문 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다."},"name":{"type":"string","nullable":true,"description":"주문명, 누락 가능."},"amount":{"type":"number","description":"결제 총액."},"cancel_amount":{"type":"number","description":"결제 취소, 환불 총액."},"currency":{"$ref":"#/components/schemas/IIamportPayment.Currency","description":"통화 단위."},"receipt_url":{"type":"string","format":"uri","description":"영수증 URL."},"cash_receipt_issue":{"type":"boolean","description":"현금 영수증 발행 여부."},"channel":{"type":"string"},"pg_provider":{"type":"string"},"emb_pg_provider":{"type":"string","nullable":true},"pg_id":{"type":"string"},"pg_tid":{"type":"string"},"escrow":{"type":"boolean"},"buyer_name":{"type":"string","nullable":true},"buyer_email":{"type":"string","format":"email","nullable":true},"buyer_tel":{"type":"string","nullable":true},"buyer_addr":{"type":"string","nullable":true},"buyer_postcode":{"type":"string","nullable":true},"customer_uid":{"type":"string","nullable":true},"customer_uid_usage":{"type":"string","nullable":true},"custom_data":{"type":"string","nullable":true},"user_agent":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/IIamportPayment.Status","description":"결제의 현재 (진행) 상태."},"started_at":{"type":"number","description":"결제 신청 일시.\n\n리눅스 타임이 쓰임."},"paid_at":{"type":"number","description":"결제 (지불) 완료 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"failed_at":{"type":"number","description":"결제 실패 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"cancelled_at":{"type":"number","description":"결제 취소 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"fail_reason":{"type":"string","nullable":true},"cancel_reason":{"type":"string","nullable":true},"cancel_history":{"type":"array","items":{"$ref":"#/components/schemas/IIamportPaymentCancel"}}},"nullable":false,"required":["card_code","card_name","card_number","card_quota","apply_num","pay_method","imp_uid","merchant_uid","name","amount","cancel_amount","currency","receipt_url","cash_receipt_issue","channel","pg_provider","emb_pg_provider","pg_id","pg_tid","escrow","buyer_name","buyer_email","buyer_tel","buyer_addr","buyer_postcode","customer_uid","customer_uid_usage","custom_data","user_agent","status","started_at","paid_at","failed_at","cancelled_at","fail_reason","cancel_reason","cancel_history"],"description":"카드 결제 정보."},"IIamportPayment.Currency":{"type":"string","enum":["KRW","USD","EUR","JPY"]},"IIamportPayment.Status":{"type":"string","enum":["paid","ready","failed","cancelled"]},"IIamportPaymentCancel":{"type":"object","properties":{"pg_id":{"type":"string"},"pg_tid":{"type":"string"},"amount":{"type":"number"},"cancelled_at":{"type":"number"},"reason":{"type":"string"},"receipt_url":{"type":"string","format":"uri"}},"nullable":false,"required":["pg_id","pg_tid","amount","cancelled_at","reason","receipt_url"],"description":"결제 취소 정보."},"IIamportTransferPayment":{"type":"object","properties":{"bank_code":{"type":"string","description":"은행 식별자 코드."},"bank_name":{"type":"string","description":"은행 이름."},"pay_method":{"type":"string","enum":["trans"]},"imp_uid":{"type":"string","description":"결제 정보 {@link IIamportPayment } 의 식별자 키."},"merchant_uid":{"type":"string","description":"주문 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다."},"name":{"type":"string","nullable":true,"description":"주문명, 누락 가능."},"amount":{"type":"number","description":"결제 총액."},"cancel_amount":{"type":"number","description":"결제 취소, 환불 총액."},"currency":{"$ref":"#/components/schemas/IIamportPayment.Currency","description":"통화 단위."},"receipt_url":{"type":"string","format":"uri","description":"영수증 URL."},"cash_receipt_issue":{"type":"boolean","description":"현금 영수증 발행 여부."},"channel":{"type":"string"},"pg_provider":{"type":"string"},"emb_pg_provider":{"type":"string","nullable":true},"pg_id":{"type":"string"},"pg_tid":{"type":"string"},"escrow":{"type":"boolean"},"buyer_name":{"type":"string","nullable":true},"buyer_email":{"type":"string","format":"email","nullable":true},"buyer_tel":{"type":"string","nullable":true},"buyer_addr":{"type":"string","nullable":true},"buyer_postcode":{"type":"string","nullable":true},"customer_uid":{"type":"string","nullable":true},"customer_uid_usage":{"type":"string","nullable":true},"custom_data":{"type":"string","nullable":true},"user_agent":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/IIamportPayment.Status","description":"결제의 현재 (진행) 상태."},"started_at":{"type":"number","description":"결제 신청 일시.\n\n리눅스 타임이 쓰임."},"paid_at":{"type":"number","description":"결제 (지불) 완료 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"failed_at":{"type":"number","description":"결제 실패 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"cancelled_at":{"type":"number","description":"결제 취소 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"fail_reason":{"type":"string","nullable":true},"cancel_reason":{"type":"string","nullable":true},"cancel_history":{"type":"array","items":{"$ref":"#/components/schemas/IIamportPaymentCancel"}}},"nullable":false,"required":["bank_code","bank_name","pay_method","imp_uid","merchant_uid","name","amount","cancel_amount","currency","receipt_url","cash_receipt_issue","channel","pg_provider","emb_pg_provider","pg_id","pg_tid","escrow","buyer_name","buyer_email","buyer_tel","buyer_addr","buyer_postcode","customer_uid","customer_uid_usage","custom_data","user_agent","status","started_at","paid_at","failed_at","cancelled_at","fail_reason","cancel_reason","cancel_history"],"description":"계좌 이체 결제 정보."},"IIamportVBankPayment":{"type":"object","properties":{"vbank_code":{"type":"string","description":"가상 계좌 식별자 코드."},"vbank_name":{"type":"string","description":"가상 게좌 이름"},"vbank_num":{"type":"string","description":"가상 계좌 번호"},"vbank_holder":{"type":"string","description":"가상 계좌 예금주."},"vbank_date":{"type":"number","description":"가상 계좌 입금 만료 기한."},"vbank_issued_at":{"type":"number","description":"가상 계좌 개설 일시."},"pay_method":{"type":"string","enum":["vbank"]},"imp_uid":{"type":"string","description":"결제 정보 {@link IIamportPayment } 의 식별자 키."},"merchant_uid":{"type":"string","description":"주문 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다."},"name":{"type":"string","nullable":true,"description":"주문명, 누락 가능."},"amount":{"type":"number","description":"결제 총액."},"cancel_amount":{"type":"number","description":"결제 취소, 환불 총액."},"currency":{"$ref":"#/components/schemas/IIamportPayment.Currency","description":"통화 단위."},"receipt_url":{"type":"string","format":"uri","description":"영수증 URL."},"cash_receipt_issue":{"type":"boolean","description":"현금 영수증 발행 여부."},"channel":{"type":"string"},"pg_provider":{"type":"string"},"emb_pg_provider":{"type":"string","nullable":true},"pg_id":{"type":"string"},"pg_tid":{"type":"string"},"escrow":{"type":"boolean"},"buyer_name":{"type":"string","nullable":true},"buyer_email":{"type":"string","format":"email","nullable":true},"buyer_tel":{"type":"string","nullable":true},"buyer_addr":{"type":"string","nullable":true},"buyer_postcode":{"type":"string","nullable":true},"customer_uid":{"type":"string","nullable":true},"customer_uid_usage":{"type":"string","nullable":true},"custom_data":{"type":"string","nullable":true},"user_agent":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/IIamportPayment.Status","description":"결제의 현재 (진행) 상태."},"started_at":{"type":"number","description":"결제 신청 일시.\n\n리눅스 타임이 쓰임."},"paid_at":{"type":"number","description":"결제 (지불) 완료 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"failed_at":{"type":"number","description":"결제 실패 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"cancelled_at":{"type":"number","description":"결제 취소 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"fail_reason":{"type":"string","nullable":true},"cancel_reason":{"type":"string","nullable":true},"cancel_history":{"type":"array","items":{"$ref":"#/components/schemas/IIamportPaymentCancel"}}},"nullable":false,"required":["vbank_code","vbank_name","vbank_num","vbank_holder","vbank_date","vbank_issued_at","pay_method","imp_uid","merchant_uid","name","amount","cancel_amount","currency","receipt_url","cash_receipt_issue","channel","pg_provider","emb_pg_provider","pg_id","pg_tid","escrow","buyer_name","buyer_email","buyer_tel","buyer_addr","buyer_postcode","customer_uid","customer_uid_usage","custom_data","user_agent","status","started_at","paid_at","failed_at","cancelled_at","fail_reason","cancel_reason","cancel_history"],"description":"가상 계좌 결제 정보."},"IIamportPayment.IBasephonekpaykakaopaypaycolpayssgpaytosspayculturelandsmartculturehappymoneybooknlifepoint":{"type":"object","properties":{"pay_method":{"type":"string","enum":["phone","kpay","kakaopay","payco","lpay","ssgpay","tosspay","cultureland","smartculture","happymoney","booknlife","point"]},"imp_uid":{"type":"string","description":"결제 정보 {@link IIamportPayment } 의 식별자 키."},"merchant_uid":{"type":"string","description":"주문 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다."},"name":{"type":"string","nullable":true,"description":"주문명, 누락 가능."},"amount":{"type":"number","description":"결제 총액."},"cancel_amount":{"type":"number","description":"결제 취소, 환불 총액."},"currency":{"$ref":"#/components/schemas/IIamportPayment.Currency","description":"통화 단위."},"receipt_url":{"type":"string","format":"uri","description":"영수증 URL."},"cash_receipt_issue":{"type":"boolean","description":"현금 영수증 발행 여부."},"channel":{"type":"string"},"pg_provider":{"type":"string"},"emb_pg_provider":{"type":"string","nullable":true},"pg_id":{"type":"string"},"pg_tid":{"type":"string"},"escrow":{"type":"boolean"},"buyer_name":{"type":"string","nullable":true},"buyer_email":{"type":"string","format":"email","nullable":true},"buyer_tel":{"type":"string","nullable":true},"buyer_addr":{"type":"string","nullable":true},"buyer_postcode":{"type":"string","nullable":true},"customer_uid":{"type":"string","nullable":true},"customer_uid_usage":{"type":"string","nullable":true},"custom_data":{"type":"string","nullable":true},"user_agent":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/IIamportPayment.Status","description":"결제의 현재 (진행) 상태."},"started_at":{"type":"number","description":"결제 신청 일시.\n\n리눅스 타임이 쓰임."},"paid_at":{"type":"number","description":"결제 (지불) 완료 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"failed_at":{"type":"number","description":"결제 실패 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"cancelled_at":{"type":"number","description":"결제 취소 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀."},"fail_reason":{"type":"string","nullable":true},"cancel_reason":{"type":"string","nullable":true},"cancel_history":{"type":"array","items":{"$ref":"#/components/schemas/IIamportPaymentCancel"}}},"nullable":false,"required":["pay_method","imp_uid","merchant_uid","name","amount","cancel_amount","currency","receipt_url","cash_receipt_issue","channel","pg_provider","emb_pg_provider","pg_id","pg_tid","escrow","buyer_name","buyer_email","buyer_tel","buyer_addr","buyer_postcode","customer_uid","customer_uid_usage","custom_data","user_agent","status","started_at","paid_at","failed_at","cancelled_at","fail_reason","cancel_reason","cancel_history"],"description":"결제 기본 (공통) 정보."},"IPaymentCancelHistory":{"type":"object","properties":{"reason":{"type":"string","description":"결제 취소 사유."},"price":{"type":"number","minimum":0,"description":"환불 금액."},"created_at":{"type":"string","format":"date-time","description":"레코드 생성 일시.\n\n즉, 결제 취소가 발생한 시각."}},"nullable":false,"required":["reason","price","created_at"],"description":"결제 취소 내역."},"IPaymentHistory.TossType":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Primary Key."},"vendor_code":{"type":"string","enum":["toss.payments"],"description":"벤더사 식별자 코드.\n\n{@link IPaymentVendor.code }와 완전히 동일한 값이되, 단지 union type\nspecialization 을 위해 중복 표기하였을 뿐이다. `if condition` 을 통하여\n{@link IPaymentHistory.data }의 타입을 특정할 수 있다."},"vendor":{"$ref":"#/components/schemas/IPaymentVendortoss.payments","description":"벤더 정보."},"source":{"$ref":"#/components/schemas/IPaymentSource","description":"원천 래코드 정보."},"data":{"$ref":"#/components/schemas/ITossPayment","description":"결제 상세 데이터, 벤더별로 데이터 양식이 다르니 주의할 것."},"currency":{"type":"string","description":"통화 단위\n\nKRW, USB, JPY 등."},"price":{"type":"number","minimum":0,"description":"결제 가격."},"refund":{"type":"number","minimum":0,"nullable":true,"description":"결제 취소시의 환불 금액."},"webhook_url":{"type":"string","format":"uri","nullable":true,"description":"결제 정보가 갱신되었을 때, 이를 수신할 URL"},"created_at":{"type":"string","format":"date-time","description":"결제 레코드 생성 일시."},"paid_at":{"type":"string","format":"date-time","nullable":true,"description":"결제 완료 일시."},"cancelled_at":{"type":"string","format":"date-time","nullable":true,"description":"결제 취소 일시."},"cancels":{"type":"array","items":{"$ref":"#/components/schemas/IPaymentCancelHistory"},"description":"결제 취소 내역 리스트."}},"nullable":false,"required":["id","vendor_code","vendor","source","data","currency","price","refund","webhook_url","created_at","paid_at","cancelled_at","cancels"],"description":"토스 페이먼츠로부터의 결제 내역."},"IPaymentVendortoss.payments":{"type":"object","properties":{"code":{"type":"string","enum":["toss.payments"],"description":"벤더사 식별자 코드.\n\n아임포트의 경우에는 `iamport` 를, 토스의 경우에는 `toss.payments` 를 적어주면 된다."},"store_id":{"type":"string","description":"벤더사에 등록한 스토어 ID.\n\n결제 PG 사들은 서비스 주소가 다르거나, 또는 동일한 서비스이되 연결되는 백엔드 서버\n주소가 다르거든, 각기 다른 스토어 계정을 신청해 사용하라고 한다. 이는 요즘같이 MSA\n(Micro Service Architecture) 가 대세인 시대에 매우 불합리한 방식이기는 하지만, 어쨋든\n이러한 이유로 인하여, 한 회사 내지 단체가 복수의 스토어 ID 를 가지는 경우가 왕왕\n있다.\n\n때문에 `payments-server` 는, {@link IPaymentHistory 결제 내역}을 발행하거나\n{@link IPaymentReservation 간편 결제 수단}을 등록할 때 모두, 사용된 스토어의 ID\n를 반드시 기재하도록 하고 있다."},"uid":{"type":"string","description":"벤더사로부터 발급받은 식별자 번호.\n\n결제 PG 사들이 제공하는 팝업창을 이용하여 결제를 진행하거나 혹은 간편 결제 수단을\n등록하거든, 결제 PG 사들은 해당 건에 대하여 별도의 식별자 번호를 발급한다.\n`IPaymentVendor.uid` 는 이처럼 결제 PG 사들이 발급해 준 식별자 번호를 기재하는\n속성이다.\n\n단 예외가 하나 있어, 아임포트는 간편 결제 카드 등록 건에 대하여 별도의 식별자 번호를\n부여하지 않고, 귀하의 서비스에서 발급해 준 ID 를 그대로 사용한다. 때문에 아임포트를\n통한 간편 결제 카드 등록의 건만 예외적으로, `IPaymentVendor.uid` 에\n{@link IPaymentSource.id } 를 동일하게 할당해주어야 한다."}},"nullable":false,"required":["code","store_id","uid"],"description":"벤더사 정보.\n\n`IPaymentVendor` 결제 PG 벤더사에 관련된 정보를 형상화한 자료구조 인터페이스이다."},"ITossPayment":{"oneOf":[{"$ref":"#/components/schemas/ITossCardPayment"},{"$ref":"#/components/schemas/ITossGiftCertificatePayment"},{"$ref":"#/components/schemas/ITossMobilePhonePayment"},{"$ref":"#/components/schemas/ITossTransferPayment"},{"$ref":"#/components/schemas/ITossVirtualAccountPayment"}],"description":"결제 정보.\n\n`ITossPayment` 는 토스 페이먼츠의 결제 정보를 형상화한 자료구조이자 유니언 타입의\n인터페이스로써, if condition 을 통하여 method 값을 특정하면, 파생 타입이 자동으로\n지정된다.\n\n```typescript\nif (payment.method === \"카드\")\n payment.card; // payment be ITossCardPayment\n```"},"ITossCardPayment":{"type":"object","properties":{"card":{"$ref":"#/components/schemas/ITossCardPayment.ICard","description":"카드 정보."},"discount":{"$ref":"#/components/schemas/ITossCardPayment.IDiscount.Nullable","description":"카드사의 즉시 할인 프로모션 정보."},"easyPay":{"type":"string","enum":["토스결제","페이코","삼성페이"],"nullable":true,"description":"간편결제로 결제한 경우 간편결제 타입 정보."},"method":{"type":"string","enum":["카드"],"description":"결제 수단."},"type":{"type":"string","enum":["NORMAL","BILLING"],"description":"결제 타입.\n\n - NORMAL: 일반 결제\n - BILLING: 미리 등록한 카드에 의한 간편 결제."},"status":{"type":"string","enum":["READY","IN_PROGRESS","WAITING_FOR_DEPOSIT","DONE","CANCELED","PARTIAL_CANCELED","ABORTED","EXPIRED"],"description":"결제 상태.\n\n - READY\n - IN_PROGRESS\n - WAITING_FOR_DEPOSIT\n - DONE\n - CANCELED\n - PARTIAL_CANCELED\n - ABORTED\n - EXPIRED"},"mId":{"type":"string","description":"가맹점 ID.\n\n현재 tosspayments 가 쓰임."},"version":{"type":"string","description":"사용 중인 토스 페이먼츠 API 의 버전."},"paymentKey":{"type":"string","description":"결제 내역의 식별자 번호."},"orderId":{"type":"string","description":"주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키."},"transactionKey":{"type":"string","description":"거래 건에 대한 고유한 키 값.\n\n{@link paymentKey } 와 달리, 이를 사용할 일은 없더라."},"orderName":{"type":"string","description":"주문 이름.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 발급한 주문명."},"currency":{"type":"string","description":"화폐 단위.\n\n현재 토스 페이먼츠는 KRW 만 사용 가능."},"totalAmount":{"type":"number","description":"총 결제 금액."},"balanceAmount":{"type":"number","description":"취소할 수 있는 금액."},"suppliedAmount":{"type":"number","description":"공급가액."},"taxFreeAmount":{"type":"number","description":"면세액."},"vat":{"type":"number","description":"부가세."},"useEscrow":{"type":"boolean","description":"에스크로 사용 여부."},"cultureExpense":{"type":"boolean","description":"문화비 지출 여부.\n\n도석입, 공연 티켓, 박물관/미술관 입장권 등."},"requestedAt":{"type":"string","format":"date-time","description":"결제 요청 일시."},"approvedAt":{"type":"string","format":"date-time","nullable":true,"description":"결제 승인 일시."},"cancels":{"type":"array","items":{"$ref":"#/components/schemas/ITossPaymentCancel"},"nullable":true,"description":"결제 취소 내역."},"cashReceipt":{"$ref":"#/components/schemas/ITossCashReceipt.ISummary.Nullable","description":"현금 영수증 정보."}},"nullable":false,"required":["card","discount","easyPay","method","type","status","mId","version","paymentKey","orderId","transactionKey","orderName","currency","totalAmount","balanceAmount","suppliedAmount","taxFreeAmount","vat","useEscrow","cultureExpense","requestedAt","approvedAt","cancels","cashReceipt"],"description":"카드 결제 정보."},"ITossCardPayment.ICard":{"type":"object","properties":{"company":{"type":"string","description":"카드사 이름."},"number":{"type":"string","pattern":"[0-9]{16}","description":"카드 번호."},"installmentPlanMonths":{"type":"number","description":"할부 개월 수."},"isInterestFree":{"type":"boolean","description":"무이자 할부 적용 여부."},"approveNo":{"type":"string","description":"승인 번호."},"useCardPoint":{"type":"boolean","enum":[false],"description":"카드 포인트 사용 여부."},"cardType":{"type":"string","enum":["신용","체크","기프트"],"description":"카드 타입."},"ownerType":{"type":"string","enum":["개인","법인"],"description":"카드의 소유자 타입."},"acquireStatus":{"type":"string","enum":["READY","CANCELED","REQUESTED","COMPLETED","CANCEL_REQUESTED"],"description":"카드 결제의 매입 상태.\n\n - READY: 매입 대기\n - REQUESTED: 매입 요청됨\n - COMPLETED: 매입 완료\n - CANCEL_REQUESTED: 매입 취소 요청됨\n - CANCELD: 매입 취소됨"},"receiptUrl":{"type":"string","format":"uri","description":"영수증 URL."}},"nullable":false,"required":["company","number","installmentPlanMonths","isInterestFree","approveNo","useCardPoint","cardType","ownerType","acquireStatus","receiptUrl"],"description":"카드 정보."},"ITossCardPayment.IDiscount.Nullable":{"type":"object","properties":{"amount":{"type":"number","description":"카드사의 즉시 할인 프로모션을 적용한 금액."}},"nullable":true,"required":["amount"],"description":"카드사의 즉시 할인 프로모션 정보."},"ITossPaymentCancel":{"type":"object","properties":{"cancelAmount":{"type":"number","description":"취소 총액."},"cancelReason":{"type":"string","description":"취소 사유."},"taxFreeAmount":{"type":"number","description":"면세 처리된 금액."},"taxAmount":{"type":"number","description":"과세 처리된 금액."},"refundableAmount":{"type":"number","description":"결제 취소 후 환불 가능 잔액."},"canceledAt":{"type":"string","format":"date-time","description":"취소 일시."}},"nullable":false,"required":["cancelAmount","cancelReason","taxFreeAmount","taxAmount","refundableAmount","canceledAt"],"description":"결제 취소 정보."},"ITossCashReceipt.ISummary.Nullable":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ITossCashReceipt.Type","description":"현금 영수증의 종류."},"amount":{"type":"number","description":"현금 영수증 처리된 금액."},"taxFreeAmount":{"type":"number","description":"면세 처리된 금액."},"issueNumber":{"type":"string","description":"현금영수증 발급번호."},"receiptUrl":{"type":"string","description":"현금영수증 조회 페이지 주소."}},"nullable":true,"required":["type","amount","taxFreeAmount","issueNumber","receiptUrl"],"description":"현금 영수증 요약 정보."},"ITossCashReceipt.Type":{"type":"string","enum":["소득공제","지출증빙"],"description":"현금 영수증의 종류."},"ITossGiftCertificatePayment":{"type":"object","properties":{"giftCertificate":{"$ref":"#/components/schemas/ITossGiftCertificatePayment.IGiftCertificate","description":"상품권 정보."},"method":{"type":"string","enum":["상품권"],"description":"결제 수단."},"type":{"type":"string","enum":["NORMAL"],"description":"결제 타입.\n\n - NORMAL: 일반 결제\n - BILLING: 미리 등록한 카드에 의한 간편 결제."},"status":{"type":"string","enum":["READY","IN_PROGRESS","WAITING_FOR_DEPOSIT","DONE","CANCELED","PARTIAL_CANCELED","ABORTED","EXPIRED"],"description":"결제 상태.\n\n - READY\n - IN_PROGRESS\n - WAITING_FOR_DEPOSIT\n - DONE\n - CANCELED\n - PARTIAL_CANCELED\n - ABORTED\n - EXPIRED"},"mId":{"type":"string","description":"가맹점 ID.\n\n현재 tosspayments 가 쓰임."},"version":{"type":"string","description":"사용 중인 토스 페이먼츠 API 의 버전."},"paymentKey":{"type":"string","description":"결제 내역의 식별자 번호."},"orderId":{"type":"string","description":"주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키."},"transactionKey":{"type":"string","description":"거래 건에 대한 고유한 키 값.\n\n{@link paymentKey } 와 달리, 이를 사용할 일은 없더라."},"orderName":{"type":"string","description":"주문 이름.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 발급한 주문명."},"currency":{"type":"string","description":"화폐 단위.\n\n현재 토스 페이먼츠는 KRW 만 사용 가능."},"totalAmount":{"type":"number","description":"총 결제 금액."},"balanceAmount":{"type":"number","description":"취소할 수 있는 금액."},"suppliedAmount":{"type":"number","description":"공급가액."},"taxFreeAmount":{"type":"number","description":"면세액."},"vat":{"type":"number","description":"부가세."},"useEscrow":{"type":"boolean","description":"에스크로 사용 여부."},"cultureExpense":{"type":"boolean","description":"문화비 지출 여부.\n\n도석입, 공연 티켓, 박물관/미술관 입장권 등."},"requestedAt":{"type":"string","format":"date-time","description":"결제 요청 일시."},"approvedAt":{"type":"string","format":"date-time","nullable":true,"description":"결제 승인 일시."},"cancels":{"type":"array","items":{"$ref":"#/components/schemas/ITossPaymentCancel"},"nullable":true,"description":"결제 취소 내역."},"cashReceipt":{"$ref":"#/components/schemas/ITossCashReceipt.ISummary.Nullable","description":"현금 영수증 정보."}},"nullable":false,"required":["giftCertificate","method","type","status","mId","version","paymentKey","orderId","transactionKey","orderName","currency","totalAmount","balanceAmount","suppliedAmount","taxFreeAmount","vat","useEscrow","cultureExpense","requestedAt","approvedAt","cancels","cashReceipt"],"description":"상품권 결제 정보."},"ITossGiftCertificatePayment.IGiftCertificate":{"type":"object","properties":{"approveNo":{"type":"string","description":"승인 번호."},"settlementStatus":{"type":"string","enum":["COMPLETE","INCOMPLETE"],"description":"정산 상태."}},"nullable":false,"required":["approveNo","settlementStatus"],"description":"상품권 정보."},"ITossMobilePhonePayment":{"type":"object","properties":{"mobilePhone":{"$ref":"#/components/schemas/ITossMobilePhonePayment.IMobilePhone","description":"휴대폰 정보."},"method":{"type":"string","enum":["휴대폰"],"description":"결제 수단."},"type":{"type":"string","enum":["NORMAL"],"description":"결제 타입.\n\n - NORMAL: 일반 결제\n - BILLING: 미리 등록한 카드에 의한 간편 결제."},"status":{"type":"string","enum":["READY","IN_PROGRESS","WAITING_FOR_DEPOSIT","DONE","CANCELED","PARTIAL_CANCELED","ABORTED","EXPIRED"],"description":"결제 상태.\n\n - READY\n - IN_PROGRESS\n - WAITING_FOR_DEPOSIT\n - DONE\n - CANCELED\n - PARTIAL_CANCELED\n - ABORTED\n - EXPIRED"},"mId":{"type":"string","description":"가맹점 ID.\n\n현재 tosspayments 가 쓰임."},"version":{"type":"string","description":"사용 중인 토스 페이먼츠 API 의 버전."},"paymentKey":{"type":"string","description":"결제 내역의 식별자 번호."},"orderId":{"type":"string","description":"주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키."},"transactionKey":{"type":"string","description":"거래 건에 대한 고유한 키 값.\n\n{@link paymentKey } 와 달리, 이를 사용할 일은 없더라."},"orderName":{"type":"string","description":"주문 이름.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 발급한 주문명."},"currency":{"type":"string","description":"화폐 단위.\n\n현재 토스 페이먼츠는 KRW 만 사용 가능."},"totalAmount":{"type":"number","description":"총 결제 금액."},"balanceAmount":{"type":"number","description":"취소할 수 있는 금액."},"suppliedAmount":{"type":"number","description":"공급가액."},"taxFreeAmount":{"type":"number","description":"면세액."},"vat":{"type":"number","description":"부가세."},"useEscrow":{"type":"boolean","description":"에스크로 사용 여부."},"cultureExpense":{"type":"boolean","description":"문화비 지출 여부.\n\n도석입, 공연 티켓, 박물관/미술관 입장권 등."},"requestedAt":{"type":"string","format":"date-time","description":"결제 요청 일시."},"approvedAt":{"type":"string","format":"date-time","nullable":true,"description":"결제 승인 일시."},"cancels":{"type":"array","items":{"$ref":"#/components/schemas/ITossPaymentCancel"},"nullable":true,"description":"결제 취소 내역."},"cashReceipt":{"$ref":"#/components/schemas/ITossCashReceipt.ISummary.Nullable","description":"현금 영수증 정보."}},"nullable":false,"required":["mobilePhone","method","type","status","mId","version","paymentKey","orderId","transactionKey","orderName","currency","totalAmount","balanceAmount","suppliedAmount","taxFreeAmount","vat","useEscrow","cultureExpense","requestedAt","approvedAt","cancels","cashReceipt"],"description":"휴대폰 결제 정보."},"ITossMobilePhonePayment.IMobilePhone":{"type":"object","properties":{"carrier":{"type":"string","description":"통신사."},"customerMobilePhone":{"type":"string","description":"고객 휴대폰 번호."},"settlementStatus":{"type":"string","enum":["COMPLETED","INCOMPLETED"],"description":"정산 상태."}},"nullable":false,"required":["carrier","customerMobilePhone","settlementStatus"],"description":"휴대폰 정보."},"ITossTransferPayment":{"type":"object","properties":{"transfer":{"$ref":"#/components/schemas/ITossTransferPayment.ITransfer","description":"계좌 이체 정보."},"method":{"type":"string","enum":["계좌이체"],"description":"결제 수단."},"type":{"type":"string","enum":["NORMAL"],"description":"결제 타입.\n\n - NORMAL: 일반 결제\n - BILLING: 미리 등록한 카드에 의한 간편 결제."},"status":{"type":"string","enum":["READY","IN_PROGRESS","WAITING_FOR_DEPOSIT","DONE","CANCELED","PARTIAL_CANCELED","ABORTED","EXPIRED"],"description":"결제 상태.\n\n - READY\n - IN_PROGRESS\n - WAITING_FOR_DEPOSIT\n - DONE\n - CANCELED\n - PARTIAL_CANCELED\n - ABORTED\n - EXPIRED"},"mId":{"type":"string","description":"가맹점 ID.\n\n현재 tosspayments 가 쓰임."},"version":{"type":"string","description":"사용 중인 토스 페이먼츠 API 의 버전."},"paymentKey":{"type":"string","description":"결제 내역의 식별자 번호."},"orderId":{"type":"string","description":"주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키."},"transactionKey":{"type":"string","description":"거래 건에 대한 고유한 키 값.\n\n{@link paymentKey } 와 달리, 이를 사용할 일은 없더라."},"orderName":{"type":"string","description":"주문 이름.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 발급한 주문명."},"currency":{"type":"string","description":"화폐 단위.\n\n현재 토스 페이먼츠는 KRW 만 사용 가능."},"totalAmount":{"type":"number","description":"총 결제 금액."},"balanceAmount":{"type":"number","description":"취소할 수 있는 금액."},"suppliedAmount":{"type":"number","description":"공급가액."},"taxFreeAmount":{"type":"number","description":"면세액."},"vat":{"type":"number","description":"부가세."},"useEscrow":{"type":"boolean","description":"에스크로 사용 여부."},"cultureExpense":{"type":"boolean","description":"문화비 지출 여부.\n\n도석입, 공연 티켓, 박물관/미술관 입장권 등."},"requestedAt":{"type":"string","format":"date-time","description":"결제 요청 일시."},"approvedAt":{"type":"string","format":"date-time","nullable":true,"description":"결제 승인 일시."},"cancels":{"type":"array","items":{"$ref":"#/components/schemas/ITossPaymentCancel"},"nullable":true,"description":"결제 취소 내역."},"cashReceipt":{"$ref":"#/components/schemas/ITossCashReceipt.ISummary.Nullable","description":"현금 영수증 정보."}},"nullable":false,"required":["transfer","method","type","status","mId","version","paymentKey","orderId","transactionKey","orderName","currency","totalAmount","balanceAmount","suppliedAmount","taxFreeAmount","vat","useEscrow","cultureExpense","requestedAt","approvedAt","cancels","cashReceipt"],"description":"계좌 이체 결제 정보."},"ITossTransferPayment.ITransfer":{"type":"object","properties":{"bank":{"type":"string","description":"은행명."},"settlementStatus":{"type":"string","enum":["COMPLETED","INCOMPLETED"],"description":"이체 상태."}},"nullable":false,"required":["bank","settlementStatus"],"description":"계좌 이체 정보."},"ITossVirtualAccountPayment":{"type":"object","properties":{"secret":{"type":"string","description":"가상 계좌로 결제할 때 전달되는 입금 콜백을 검증하기 위한 값."},"virtualAccount":{"$ref":"#/components/schemas/ITossVirtualAccountPayment.IVirtualAccount","description":"가상 계좌 정보."},"method":{"type":"string","enum":["가상계좌"],"description":"결제 수단."},"type":{"type":"string","enum":["NORMAL"],"description":"결제 타입.\n\n - NORMAL: 일반 결제\n - BILLING: 미리 등록한 카드에 의한 간편 결제."},"status":{"type":"string","enum":["READY","IN_PROGRESS","WAITING_FOR_DEPOSIT","DONE","CANCELED","PARTIAL_CANCELED","ABORTED","EXPIRED"],"description":"결제 상태.\n\n - READY\n - IN_PROGRESS\n - WAITING_FOR_DEPOSIT\n - DONE\n - CANCELED\n - PARTIAL_CANCELED\n - ABORTED\n - EXPIRED"},"mId":{"type":"string","description":"가맹점 ID.\n\n현재 tosspayments 가 쓰임."},"version":{"type":"string","description":"사용 중인 토스 페이먼츠 API 의 버전."},"paymentKey":{"type":"string","description":"결제 내역의 식별자 번호."},"orderId":{"type":"string","description":"주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키."},"transactionKey":{"type":"string","description":"거래 건에 대한 고유한 키 값.\n\n{@link paymentKey } 와 달리, 이를 사용할 일은 없더라."},"orderName":{"type":"string","description":"주문 이름.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 발급한 주문명."},"currency":{"type":"string","description":"화폐 단위.\n\n현재 토스 페이먼츠는 KRW 만 사용 가능."},"totalAmount":{"type":"number","description":"총 결제 금액."},"balanceAmount":{"type":"number","description":"취소할 수 있는 금액."},"suppliedAmount":{"type":"number","description":"공급가액."},"taxFreeAmount":{"type":"number","description":"면세액."},"vat":{"type":"number","description":"부가세."},"useEscrow":{"type":"boolean","description":"에스크로 사용 여부."},"cultureExpense":{"type":"boolean","description":"문화비 지출 여부.\n\n도석입, 공연 티켓, 박물관/미술관 입장권 등."},"requestedAt":{"type":"string","format":"date-time","description":"결제 요청 일시."},"approvedAt":{"type":"string","format":"date-time","nullable":true,"description":"결제 승인 일시."},"cancels":{"type":"array","items":{"$ref":"#/components/schemas/ITossPaymentCancel"},"nullable":true,"description":"결제 취소 내역."},"cashReceipt":{"$ref":"#/components/schemas/ITossCashReceipt.ISummary.Nullable","description":"현금 영수증 정보."}},"nullable":false,"required":["secret","virtualAccount","method","type","status","mId","version","paymentKey","orderId","transactionKey","orderName","currency","totalAmount","balanceAmount","suppliedAmount","taxFreeAmount","vat","useEscrow","cultureExpense","requestedAt","approvedAt","cancels","cashReceipt"],"description":"가상 계좌 결제 정보."},"ITossVirtualAccountPayment.IVirtualAccount":{"type":"object","properties":{"accountNumber":{"type":"string","description":"계좌 번호."},"accountType":{"type":"string","enum":["일반","고정"],"description":"가상 계좌 타입."},"bank":{"type":"string","description":"은행명."},"customerName":{"type":"string","description":"고객 이름."},"dueDate":{"type":"string","format":"date","description":"입금 기한."},"expired":{"type":"boolean","description":"가상 계좌 만료 여부."},"settlementStatus":{"type":"string","enum":["COMPLETED","INCOMPLETED"],"description":"정산 상태."},"refundStatus":{"type":"string","enum":["COMPLETED","NONE","FAILED","PENDING","PARTIAL_FAILED"],"description":"환불 처리 상태.\n\n - NONE: 해당 없음\n - FAILED: 환불 실패\n - PENDING: 환불 처리중\n - PARTIAL_FAILED: 부분 환불 실패\n - COMPLETED: 환불 완료"}},"nullable":false,"required":["accountNumber","accountType","bank","customerName","dueDate","expired","settlementStatus","refundStatus"],"description":"가상 계좌 정보."},"IPaymentSource.IPassword":{"type":"object","properties":{"password":{"type":"string","description":"레코드 조회를 위한 비밀번호 입력."}},"nullable":false,"required":["password"],"description":"비밀번호 입력 정보."},"IPaymentHistory.ICreate":{"type":"object","properties":{"vendor":{"$ref":"#/components/schemas/IPaymentVendoriamporttoss.payments","description":"벤더사 정보"},"source":{"$ref":"#/components/schemas/IPaymentSource","description":"결제의 근간이 된 원천 레코드 정보."},"price":{"type":"number","minimum":0,"description":"결제되어야 할 총액.\n\n실 결제금액과 비교하여 이와 다를 시, 422 에러가 리턴됨."},"password":{"type":"string","description":"레코드 열람에 사용할 비밀번호 설정."},"webhook_url":{"type":"string","format":"uri","description":"결제 정보가 갱신되었을 때, 이를 수신할 URL"}},"nullable":false,"required":["vendor","source","price","password","webhook_url"],"description":"결제 입력 정보.\n\nSDK 에서 받은 데이터를 취합하여 결제 진행 상황을 서버에 알려준다."},"IPaymentVendoriamporttoss.payments":{"type":"object","properties":{"code":{"type":"string","enum":["iamport","toss.payments"],"description":"벤더사 식별자 코드.\n\n아임포트의 경우에는 `iamport` 를, 토스의 경우에는 `toss.payments` 를 적어주면 된다."},"store_id":{"type":"string","description":"벤더사에 등록한 스토어 ID.\n\n결제 PG 사들은 서비스 주소가 다르거나, 또는 동일한 서비스이되 연결되는 백엔드 서버\n주소가 다르거든, 각기 다른 스토어 계정을 신청해 사용하라고 한다. 이는 요즘같이 MSA\n(Micro Service Architecture) 가 대세인 시대에 매우 불합리한 방식이기는 하지만, 어쨋든\n이러한 이유로 인하여, 한 회사 내지 단체가 복수의 스토어 ID 를 가지는 경우가 왕왕\n있다.\n\n때문에 `payments-server` 는, {@link IPaymentHistory 결제 내역}을 발행하거나\n{@link IPaymentReservation 간편 결제 수단}을 등록할 때 모두, 사용된 스토어의 ID\n를 반드시 기재하도록 하고 있다."},"uid":{"type":"string","description":"벤더사로부터 발급받은 식별자 번호.\n\n결제 PG 사들이 제공하는 팝업창을 이용하여 결제를 진행하거나 혹은 간편 결제 수단을\n등록하거든, 결제 PG 사들은 해당 건에 대하여 별도의 식별자 번호를 발급한다.\n`IPaymentVendor.uid` 는 이처럼 결제 PG 사들이 발급해 준 식별자 번호를 기재하는\n속성이다.\n\n단 예외가 하나 있어, 아임포트는 간편 결제 카드 등록 건에 대하여 별도의 식별자 번호를\n부여하지 않고, 귀하의 서비스에서 발급해 준 ID 를 그대로 사용한다. 때문에 아임포트를\n통한 간편 결제 카드 등록의 건만 예외적으로, `IPaymentVendor.uid` 에\n{@link IPaymentSource.id } 를 동일하게 할당해주어야 한다."}},"nullable":false,"required":["code","store_id","uid"],"description":"벤더사 정보.\n\n`IPaymentVendor` 결제 PG 벤더사에 관련된 정보를 형상화한 자료구조 인터페이스이다."},"IPaymentCancelHistory.ICreate":{"type":"object","properties":{"source":{"$ref":"#/components/schemas/IPaymentSource","description":"결제의 근간이 된 원천 레코드 정보."},"password":{"type":"string","description":"결제 이력에 대한 비밀번호 입력."},"price":{"type":"number","minimum":0,"description":"환불 금액."},"reason":{"type":"string","description":"결제 취소 사유."},"account":{"$ref":"#/components/schemas/IPaymentCancelHistory.IBankAccount.Nullable","description":"환불 계좌 정보.\n\n가상 계좌로 입금한 경우, 결제 취소시, 이를 환불받을 계좌가 필요함.\n\n단, 이 정보는 본 결제 시스템에 저장하지 아니함."}},"nullable":false,"required":["source","password","price","reason","account"],"description":"결제 취소 입력 정보."},"IPaymentCancelHistory.IBankAccount.Nullable":{"type":"object","properties":{"bank":{"type":"string","description":"은행 이름."},"account":{"type":"string","description":"계좌번호."},"holder":{"type":"string","description":"예금주."},"mobile":{"type":"string","description":"연락처, 핸드폰 번호."}},"nullable":true,"required":["bank","account","holder","mobile"],"description":"은행 계좌 정보.\n\n가상 계좌로 입금한 경우, 결제 취소시, 이를 환불받을 계좌가 필요함.\n\n단, 이 정보는 본 결제 시스템에 저장하지 아니함."},"IPaymentReservation":{"oneOf":[{"$ref":"#/components/schemas/IPaymentReservation.IamportType"},{"$ref":"#/components/schemas/IPaymentReservation.TossType"}],"description":"간편 결제 수단 정보.\n\n`IPaymentReservation` 은 간편 결제 수단을 형상화한 자료구조이자 유니언 타입의\n인터페이스로써, if condition 을 통하여 {@link IPaymentReservation.vendor_code } 값을\n특정하면, 파생 타입이 자동으로 다운 캐스팅 된다.\n\n```typescript\nif (history.vendor_code === \"toss.payments\")\n history.data.billingKey; // history.data be ITossBilling\n```"},"IPaymentReservation.IamportType":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Primary Key."},"vendor_code":{"type":"string","enum":["iamport"],"description":"벤더사 코드.\n\n{@link IPaymentVendor.code }와 완전히 동일한 값이되, 단지 union type\nspecialization 을 위해 중복 표기하였을 뿐이다. If else condition 을 통하여\n{@link IPaymentReservation.data }의 타입을 특정할 수 있다."},"vendor":{"$ref":"#/components/schemas/IPaymentVendoriamport","description":"벤더사."},"source":{"$ref":"#/components/schemas/IPaymentSource","description":"대상 액터의 참조 정보."},"title":{"type":"string","description":"제목."},"data":{"$ref":"#/components/schemas/IIamportSubscription","description":"벤더사 데이터."},"created_at":{"type":"string","format":"date-time","description":"레코드 생성 일시."}},"nullable":false,"required":["id","vendor_code","vendor","source","title","data","created_at"],"description":"아임 포트의 간편 결제 카드 정보."},"IIamportSubscription":{"type":"object","properties":{"pg_provider":{"type":"string"},"pg_id":{"type":"string"},"card_name":{"type":"string"},"card_code":{"type":"string"},"card_number":{"type":"string"},"card_type":{"type":"string"},"customer_name":{"type":"string","nullable":true},"customer_tel":{"type":"string","nullable":true},"customer_email":{"type":"string","nullable":true},"customer_addr":{"type":"string","nullable":true},"customer_postcode":{"type":"string","nullable":true},"inserted":{"type":"number"},"updated":{"type":"number"},"customer_uid":{"type":"string","description":"고객 식별자 키.\n\n아임포트가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키.\n\n다만 고객이라기보다 실제로는 카드의 식별자 키로 써야함."}},"nullable":false,"required":["pg_provider","pg_id","card_name","card_code","card_number","card_type","customer_name","customer_tel","customer_email","customer_addr","customer_postcode","inserted","updated","customer_uid"],"description":"간편 결제 카드 정보."},"IPaymentReservation.TossType":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Primary Key."},"vendor_code":{"type":"string","enum":["toss.payments"],"description":"벤더사 코드.\n\n{@link IPaymentVendor.code }와 완전히 동일한 값이되, 단지 union type\nspecialization 을 위해 중복 표기하였을 뿐이다. If else condition 을 통하여\n{@link IPaymentReservation.data }의 타입을 특정할 수 있다."},"vendor":{"$ref":"#/components/schemas/IPaymentVendortoss.payments","description":"벤더사."},"source":{"$ref":"#/components/schemas/IPaymentSource","description":"대상 액터의 참조 정보."},"title":{"type":"string","description":"제목."},"data":{"$ref":"#/components/schemas/ITossBilling","description":"벤더사 데이터."},"created_at":{"type":"string","format":"date-time","description":"레코드 생성 일시."}},"nullable":false,"required":["id","vendor_code","vendor","source","title","data","created_at"],"description":"토스의 간편 결제 수단 정보."},"ITossBilling":{"type":"object","properties":{"mId":{"type":"string","description":"가맹점 ID.\n\n현재 tosspayments 가 쓰임."},"billingKey":{"type":"string","description":"{@link ITossBilling } 의 식별자 키."},"method":{"type":"string","enum":["카드"],"description":"결제 수단."},"cardCompany":{"type":"string","description":"카드사 이름."},"cardNumber":{"type":"string","pattern":"[0-9]{16}","description":"카드 번호."},"authenticatedAt":{"type":"string","format":"date-time","description":"인증 일시."},"customerKey":{"type":"string","description":"고객 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키."}},"nullable":false,"required":["mId","billingKey","method","cardCompany","cardNumber","authenticatedAt","customerKey"],"description":"간편 결제 등록 수단 정보.\n\n`ITossBilling` 은 간편 결제 등록 수단을 형상화한 자료구조 인터페이스로써, 고객이 자신의\n신용 카드를 서버에 등록해두고, 매번 결제가 필요할 때마다 카드 정보를 반복 입려하는 일\n없이 간편하게 결제를 진행하고자 할 때 사용한다."},"IPaymentReservation.ICreate":{"type":"object","properties":{"vendor":{"$ref":"#/components/schemas/IPaymentVendorIPaymentVendor.Code","description":"벤더사 정보."},"source":{"$ref":"#/components/schemas/IPaymentSource","description":"원천 레코드 정보."},"title":{"type":"string","description":"제목"},"password":{"type":"string","description":"간편결제 비밀번호.\n\n주의할 점은 카드 비밀번호가 아니라는 것."}},"nullable":false,"required":["vendor","source","title","password"],"description":"간편 결제 수단 등록 정보.\n\n결제사의 팝업 창로부터 전달받은 식별자 정보를 취합하여 전달한다.\n\n참고로 아임포트의 경우 간편 결제로 등록한 카드에 자체 식별자 번호를 부여하지 않는다.\n따라서 귀하의 서비스가 발행한 식별자 ID 가 곧, 해당 간편 결제 수단의 유일무이한\n식별자ㅏ 되니, 이를 {@link IPaymentVendor.uid } 와 {@link IPaymentSource.id } 에\n모두 동일하게 할당해주면 된다."},"IPaymentVendorIPaymentVendor.Code":{"type":"object","properties":{"code":{"type":"string","enum":["iamport","toss.payments"],"description":"벤더사 식별자 코드.\n\n아임포트의 경우에는 `iamport` 를, 토스의 경우에는 `toss.payments` 를 적어주면 된다."},"store_id":{"type":"string","description":"벤더사에 등록한 스토어 ID.\n\n결제 PG 사들은 서비스 주소가 다르거나, 또는 동일한 서비스이되 연결되는 백엔드 서버\n주소가 다르거든, 각기 다른 스토어 계정을 신청해 사용하라고 한다. 이는 요즘같이 MSA\n(Micro Service Architecture) 가 대세인 시대에 매우 불합리한 방식이기는 하지만, 어쨋든\n이러한 이유로 인하여, 한 회사 내지 단체가 복수의 스토어 ID 를 가지는 경우가 왕왕\n있다.\n\n때문에 `payments-server` 는, {@link IPaymentHistory 결제 내역}을 발행하거나\n{@link IPaymentReservation 간편 결제 수단}을 등록할 때 모두, 사용된 스토어의 ID\n를 반드시 기재하도록 하고 있다."},"uid":{"type":"string","description":"벤더사로부터 발급받은 식별자 번호.\n\n결제 PG 사들이 제공하는 팝업창을 이용하여 결제를 진행하거나 혹은 간편 결제 수단을\n등록하거든, 결제 PG 사들은 해당 건에 대하여 별도의 식별자 번호를 발급한다.\n`IPaymentVendor.uid` 는 이처럼 결제 PG 사들이 발급해 준 식별자 번호를 기재하는\n속성이다.\n\n단 예외가 하나 있어, 아임포트는 간편 결제 카드 등록 건에 대하여 별도의 식별자 번호를\n부여하지 않고, 귀하의 서비스에서 발급해 준 ID 를 그대로 사용한다. 때문에 아임포트를\n통한 간편 결제 카드 등록의 건만 예외적으로, `IPaymentVendor.uid` 에\n{@link IPaymentSource.id } 를 동일하게 할당해주어야 한다."}},"nullable":false,"required":["code","store_id","uid"],"description":"벤더사 정보.\n\n`IPaymentVendor` 결제 PG 벤더사에 관련된 정보를 형상화한 자료구조 인터페이스이다."},"IIamportPayment.IWebhook":{"type":"object","properties":{"imp_uid":{"type":"string","description":"결제 정보 {@link IIamportPayment } 의 식별자 키."},"merchant_uid":{"type":"string","description":"주문 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다."},"status":{"type":"string","enum":["paid","ready","failed","cancelled"],"description":"현재 상태."}},"nullable":false,"required":["imp_uid","merchant_uid","status"],"description":"웹훅 데이터."}}}} \ No newline at end of file +{ + "openapi": "3.0.1", + "servers": [ + { + "url": "https://github.com/samchon/nestia", + "description": "insert your server url" + } + ], + "info": { + "version": "6.0.6", + "title": "@samchon/payment-backend", + "description": "Payment Backend Server", + "license": { + "name": "MIT" + } + }, + "paths": { + "/monitors/health": { + "get": { + "tags": [], + "parameters": [], + "responses": { + "200": { + "description": "" + } + } + } + }, + "/monitors/performance": { + "get": { + "tags": [], + "parameters": [], + "responses": { + "200": { + "description": "## Warning\n\nResponse data have been encrypted.\n\nThe response body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedRoute.G.et](https://github.com/samchon/@nestia/core#encryptedroute) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/IPerformance" + } + } + }, + "x-nestia-encrypted": true + } + } + } + }, + "/monitors/system": { + "get": { + "tags": [], + "parameters": [], + "responses": { + "200": { + "description": "## Warning\n\nResponse data have been encrypted.\n\nThe response body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedRoute.G.et](https://github.com/samchon/@nestia/core#encryptedroute) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/ISystem" + } + } + }, + "x-nestia-encrypted": true + } + } + } + }, + "/payments/histories/get": { + "patch": { + "tags": [], + "parameters": [], + "requestBody": { + "description": "## Warning\n\nRequest body must be encrypted.\n\nThe request body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedBody](https://github.com/samchon/@nestia/core#encryptedbody) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n결제 내역의 원천 정보 + 비밀번호", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/IPaymentSource.IAccessor" + } + } + }, + "required": true, + "x-nestia-encrypted": true + }, + "responses": { + "200": { + "description": "## Warning\n\nResponse data have been encrypted.\n\nThe response body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedRoute.P.atch](https://github.com/samchon/@nestia/core#encryptedroute) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n결제 내역", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/IPaymentHistory" + } + } + }, + "x-nestia-encrypted": true + } + }, + "summary": "결제 내역 상세 조회하기", + "description": "결제 내역 상세 조회하기." + } + }, + "/payments/histories/{id}": { + "patch": { + "tags": [], + "parameters": [ + { + "name": "id", + "in": "path", + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Primary Key", + "required": true + } + ], + "requestBody": { + "description": "## Warning\n\nRequest body must be encrypted.\n\nThe request body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedBody](https://github.com/samchon/@nestia/core#encryptedbody) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n결제 내역의 비밀번호", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/IPaymentSource.IPassword" + } + } + }, + "required": true, + "x-nestia-encrypted": true + }, + "responses": { + "200": { + "description": "## Warning\n\nResponse data have been encrypted.\n\nThe response body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedRoute.P.atch](https://github.com/samchon/@nestia/core#encryptedroute) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n결제 내역", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/IPaymentHistory" + } + } + }, + "x-nestia-encrypted": true + } + }, + "summary": "결제 내역 상세 조회하기", + "description": "결제 내역 상세 조회하기." + } + }, + "/payments/histories": { + "post": { + "tags": [], + "parameters": [], + "requestBody": { + "description": "## Warning\n\nRequest body must be encrypted.\n\nThe request body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedBody](https://github.com/samchon/@nestia/core#encryptedbody) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n결제 내역 입력 정보", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/IPaymentHistory.ICreate" + } + } + }, + "required": true, + "x-nestia-encrypted": true + }, + "responses": { + "201": { + "description": "## Warning\n\nResponse data have been encrypted.\n\nThe response body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedRoute.P.ost](https://github.com/samchon/@nestia/core#encryptedroute) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n결제 내역", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/IPaymentHistory" + } + } + }, + "x-nestia-encrypted": true + } + }, + "summary": "결제 내역 발행하기", + "description": "결제 내역 발행하기." + } + }, + "/payments/histories/cancel": { + "put": { + "tags": [], + "parameters": [], + "requestBody": { + "description": "## Warning\n\nRequest body must be encrypted.\n\nThe request body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedBody](https://github.com/samchon/@nestia/core#encryptedbody) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n결제 취소 내역 입력 정보", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/IPaymentCancelHistory.ICreate" + } + } + }, + "required": true, + "x-nestia-encrypted": true + }, + "responses": { + "200": { + "description": "## Warning\n\nResponse data have been encrypted.\n\nThe response body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedRoute.P.ut](https://github.com/samchon/@nestia/core#encryptedroute) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/IPaymentHistory" + } + } + }, + "x-nestia-encrypted": true + } + }, + "summary": "결제 취소하기", + "description": "결제 취소하기." + } + }, + "/payments/reservations/get": { + "patch": { + "tags": [], + "parameters": [], + "requestBody": { + "description": "## Warning\n\nRequest body must be encrypted.\n\nThe request body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedBody](https://github.com/samchon/@nestia/core#encryptedbody) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n간편 결제 수단의 원천 정보 + 비밀번호", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/IPaymentSource.IAccessor" + } + } + }, + "required": true, + "x-nestia-encrypted": true + }, + "responses": { + "200": { + "description": "## Warning\n\nResponse data have been encrypted.\n\nThe response body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedRoute.P.atch](https://github.com/samchon/@nestia/core#encryptedroute) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n결제 내역", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/IPaymentReservation" + } + } + }, + "x-nestia-encrypted": true + } + }, + "summary": "간편 결제 수단 조회하기", + "description": "간편 결제 수단 조회하기." + } + }, + "/payments/reservations/{id}": { + "patch": { + "tags": [], + "parameters": [ + { + "name": "id", + "in": "path", + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Primary Key", + "required": true + } + ], + "requestBody": { + "description": "## Warning\n\nRequest body must be encrypted.\n\nThe request body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedBody](https://github.com/samchon/@nestia/core#encryptedbody) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n비밀번호", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/IPaymentSource.IPassword" + } + } + }, + "required": true, + "x-nestia-encrypted": true + }, + "responses": { + "200": { + "description": "## Warning\n\nResponse data have been encrypted.\n\nThe response body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedRoute.P.atch](https://github.com/samchon/@nestia/core#encryptedroute) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n간편 결제 수단 정보", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/IPaymentReservation" + } + } + }, + "x-nestia-encrypted": true + } + }, + "summary": "간편 결제 수단 조회하기", + "description": "간편 결제 수단 조회하기." + } + }, + "/payments/reservations": { + "post": { + "tags": [], + "parameters": [], + "requestBody": { + "description": "## Warning\n\nRequest body must be encrypted.\n\nThe request body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedBody](https://github.com/samchon/@nestia/core#encryptedbody) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n간편 결제 수단 입력 정보", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/IPaymentReservation.ICreate" + } + } + }, + "required": true, + "x-nestia-encrypted": true + }, + "responses": { + "201": { + "description": "## Warning\n\nResponse data have been encrypted.\n\nThe response body data would be encrypted as \"AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding\", through the [EncryptedRoute.P.ost](https://github.com/samchon/@nestia/core#encryptedroute) component.\n\nTherefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.\n\n----------------\n\n간편 결제 수단 정보", + "content": { + "text/plain": { + "schema": { + "$ref": "#/components/schemas/IPaymentReservation" + } + } + }, + "x-nestia-encrypted": true + } + }, + "summary": "간편 결제 수단 등록하기", + "description": "간편 결제 수단 등록하기." + } + }, + "/payments/webhooks/iamport": { + "post": { + "tags": [], + "parameters": [], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IIamportPayment.IWebhook" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "" + } + } + } + } + }, + "components": { + "schemas": { + "IPerformance": { + "type": "object", + "properties": { + "cpu": { + "$ref": "#/components/schemas/process.global.NodeJS.CpuUsage" + }, + "memory": { + "$ref": "#/components/schemas/process.global.NodeJS.MemoryUsage" + }, + "resource": { + "$ref": "#/components/schemas/process.global.NodeJS.ResourceUsage" + } + }, + "nullable": false, + "required": [ + "cpu", + "memory", + "resource" + ] + }, + "process.global.NodeJS.CpuUsage": { + "type": "object", + "properties": { + "user": { + "type": "number" + }, + "system": { + "type": "number" + } + }, + "nullable": false, + "required": [ + "user", + "system" + ] + }, + "process.global.NodeJS.MemoryUsage": { + "type": "object", + "properties": { + "rss": { + "type": "number" + }, + "heapTotal": { + "type": "number" + }, + "heapUsed": { + "type": "number" + }, + "external": { + "type": "number" + }, + "arrayBuffers": { + "type": "number" + } + }, + "nullable": false, + "required": [ + "rss", + "heapTotal", + "heapUsed", + "external", + "arrayBuffers" + ] + }, + "process.global.NodeJS.ResourceUsage": { + "type": "object", + "properties": { + "fsRead": { + "type": "number" + }, + "fsWrite": { + "type": "number" + }, + "involuntaryContextSwitches": { + "type": "number" + }, + "ipcReceived": { + "type": "number" + }, + "ipcSent": { + "type": "number" + }, + "majorPageFault": { + "type": "number" + }, + "maxRSS": { + "type": "number" + }, + "minorPageFault": { + "type": "number" + }, + "sharedMemorySize": { + "type": "number" + }, + "signalsCount": { + "type": "number" + }, + "swappedOut": { + "type": "number" + }, + "systemCPUTime": { + "type": "number" + }, + "unsharedDataSize": { + "type": "number" + }, + "unsharedStackSize": { + "type": "number" + }, + "userCPUTime": { + "type": "number" + }, + "voluntaryContextSwitches": { + "type": "number" + } + }, + "nullable": false, + "required": [ + "fsRead", + "fsWrite", + "involuntaryContextSwitches", + "ipcReceived", + "ipcSent", + "majorPageFault", + "maxRSS", + "minorPageFault", + "sharedMemorySize", + "signalsCount", + "swappedOut", + "systemCPUTime", + "unsharedDataSize", + "unsharedStackSize", + "userCPUTime", + "voluntaryContextSwitches" + ] + }, + "ISystem": { + "type": "object", + "properties": { + "uid": { + "type": "string", + "title": "Random Unique ID", + "description": "Random Unique ID." + }, + "arguments": { + "type": "array", + "items": { + "type": "string" + }, + "title": "`process", + "description": "`process.argv`" + }, + "commit": { + "$ref": "#/components/schemas/ISystem.ICommit", + "title": "Git commit information", + "description": "Git commit information." + }, + "package": { + "$ref": "#/components/schemas/ISystem.IPackage", + "title": "`package", + "description": "`package.json`" + }, + "created_at": { + "type": "string", + "title": "Creation time of this system", + "description": "Creation time of this system." + } + }, + "nullable": false, + "required": [ + "uid", + "arguments", + "commit", + "package", + "created_at" + ] + }, + "ISystem.ICommit": { + "type": "object", + "properties": { + "shortHash": { + "type": "string" + }, + "branch": { + "type": "string" + }, + "hash": { + "type": "string" + }, + "subject": { + "type": "string" + }, + "sanitizedSubject": { + "type": "string" + }, + "body": { + "type": "string" + }, + "author": { + "$ref": "#/components/schemas/ISystem.ICommit.IUser" + }, + "committer": { + "$ref": "#/components/schemas/ISystem.ICommit.IUser" + }, + "authored_at": { + "type": "string" + }, + "commited_at": { + "type": "string" + }, + "notes": { + "type": "string" + }, + "tags": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "nullable": false, + "required": [ + "shortHash", + "branch", + "hash", + "subject", + "sanitizedSubject", + "body", + "author", + "committer", + "authored_at", + "commited_at", + "tags" + ], + "description": "Git commit information." + }, + "ISystem.ICommit.IUser": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "email": { + "type": "string" + } + }, + "nullable": false, + "required": [ + "name", + "email" + ], + "description": "Git user information." + }, + "ISystem.IPackage": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "version": { + "type": "string" + }, + "description": { + "type": "string" + }, + "scripts": { + "$ref": "#/components/schemas/Recordstringstring" + }, + "repository": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "git" + ] + }, + "url": { + "type": "string" + } + }, + "nullable": false, + "required": [ + "type", + "url" + ] + }, + "author": { + "type": "string" + }, + "license": { + "type": "string" + }, + "bugs": { + "type": "object", + "properties": { + "url": { + "type": "string" + } + }, + "nullable": false, + "required": [ + "url" + ] + }, + "homepage": { + "type": "string" + }, + "devDependencies": { + "$ref": "#/components/schemas/Recordstringstring" + }, + "dependencies": { + "$ref": "#/components/schemas/Recordstringstring" + }, + "publishConfig": { + "type": "object", + "properties": { + "registry": { + "type": "string" + } + }, + "nullable": false, + "required": [ + "registry" + ] + }, + "main": { + "type": "string" + }, + "typings": { + "type": "string" + }, + "files": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "nullable": false, + "required": [ + "name", + "version", + "description", + "scripts", + "repository", + "author", + "license", + "bugs", + "homepage", + "devDependencies", + "dependencies" + ], + "description": "NPM package information." + }, + "Recordstringstring": { + "type": "object", + "properties": {}, + "nullable": false, + "description": "Construct a type with a set of properties K of type T" + }, + "IPaymentSource.IAccessor": { + "type": "object", + "properties": { + "schema": { + "type": "string", + "description": "DB 스키마 이름" + }, + "table": { + "type": "string", + "description": "DB 테이블 명" + }, + "id": { + "type": "string", + "format": "uuid", + "description": "참조 레코드의 PK" + }, + "password": { + "type": "string", + "title": "레코드 조회를 위한 비밀번호 입력", + "description": "레코드 조회를 위한 비밀번호 입력." + } + }, + "nullable": false, + "required": [ + "schema", + "table", + "id", + "password" + ], + "description": "접근자 정보.\n\n`IPaymentSource.IAccessor` 는 {@link IPaymentHistory 결제 내역} 내지\n{@link IPaymentReservation 간편 결제 수단 정보}를 조회할 때, 그것의 고유 식별자\nID 가 아닌 원천 레코드 식별자 정보 {@link IPaymentSource } 를 통하여 조회할 때\n사용하는 접근자 정보이다.\n\n다만 `payments-server` 의 모든 개별 레코드는 이를 조회할 시 비밀번호가 필요하기에,\n{@link IPaymentSource } 의 속성들에 비밀번호가 하나 더 추가되었을 뿐이다." + }, + "IPaymentHistory": { + "oneOf": [ + { + "$ref": "#/components/schemas/IPaymentHistory.IamportType" + }, + { + "$ref": "#/components/schemas/IPaymentHistory.TossType" + } + ], + "description": "결제 내역.\n\n`IPaymentHistory` 는 결제 내역을 형상화한 자료구조이자 유니언 타입의 인터페이이다.\n서비스 시스템으로부 결제 사건의 귀속 정보 ({@link IPaymentHistory.ICreate.vendor } +\n{@link IPaymentHistory.ICreate.source }) 를 전달받아, 본 Payment 시스템이 PG 사에\n추가 정보를 취득하여 레코드가 완성된다.\n\n그리고 만일 현 결제 건이 가상계좌와 같이 레코드 생성 시점에 지불이 이루어지지 않은\n경우라면, 사후 {@link IPaymentWebhook 웹훅 이벤트}를 통하여 지불 완료 시각을 뜻하는\n{@link paid_at } 가 설정될 수 있다. 그리고 반대로 이미 결제가 완료된 경우라도,\n환불 등의 이유로 인하여 {@link cancelled_at } 이 사후 기재될 수 있다.\n\n참고로 `if condition` 을 통하여 {@link IPaymentHistory.vendor_code } 값을 특정하면,\n파생 타입이 자동으로 다운 캐스팅 된다.\n\n```typescript\nif (history.vendor_code === \"toss.payments\")\n history.data.paymentKey; // history.data be ITossPayment\n```" + }, + "IPaymentHistory.IamportType": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "title": "Primary Key", + "description": "Primary Key." + }, + "vendor_code": { + "type": "string", + "enum": [ + "iamport" + ], + "title": "벤더사 식별자 코드", + "description": "벤더사 식별자 코드.\n\n{@link IPaymentVendor.code }와 완전히 동일한 값이되, 단지 union type\nspecialization 을 위해 중복 표기하였을 뿐이다. `if condition` 을 통하여\n{@link IPaymentHistory.data }의 타입을 특정할 수 있다." + }, + "vendor": { + "$ref": "#/components/schemas/IPaymentVendoriamport", + "title": "벤더 정보", + "description": "벤더 정보." + }, + "source": { + "$ref": "#/components/schemas/IPaymentSource", + "title": "원천 래코드 정보", + "description": "원천 래코드 정보." + }, + "data": { + "$ref": "#/components/schemas/IIamportPayment", + "title": "결제 상세 데이터, 벤더별로 데이터 양식이 다르니 주의할 것", + "description": "결제 상세 데이터, 벤더별로 데이터 양식이 다르니 주의할 것." + }, + "currency": { + "type": "string", + "description": "통화 단위\n\nKRW, USB, JPY 등." + }, + "price": { + "type": "number", + "minimum": 0, + "title": "결제 가격", + "description": "결제 가격." + }, + "refund": { + "type": "number", + "minimum": 0, + "nullable": true, + "title": "결제 취소시의 환불 금액", + "description": "결제 취소시의 환불 금액." + }, + "webhook_url": { + "type": "string", + "format": "uri", + "nullable": true, + "description": "결제 정보가 갱신되었을 때, 이를 수신할 URL" + }, + "created_at": { + "type": "string", + "format": "date-time", + "title": "결제 레코드 생성 일시", + "description": "결제 레코드 생성 일시." + }, + "paid_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "title": "결제 완료 일시", + "description": "결제 완료 일시." + }, + "cancelled_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "title": "결제 취소 일시", + "description": "결제 취소 일시." + }, + "cancels": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IPaymentCancelHistory" + }, + "title": "결제 취소 내역 리스트", + "description": "결제 취소 내역 리스트." + } + }, + "nullable": false, + "required": [ + "id", + "vendor_code", + "vendor", + "source", + "data", + "currency", + "price", + "refund", + "webhook_url", + "created_at", + "paid_at", + "cancelled_at", + "cancels" + ], + "description": "아임포트로부터의 결제 내역." + }, + "IPaymentVendoriamport": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "iamport" + ], + "title": "벤더사 식별자 코드", + "description": "벤더사 식별자 코드.\n\n아임포트의 경우에는 `iamport` 를, 토스의 경우에는 `toss.payments` 를 적어주면 된다." + }, + "store_id": { + "type": "string", + "title": "벤더사에 등록한 스토어 ID", + "description": "벤더사에 등록한 스토어 ID.\n\n결제 PG 사들은 서비스 주소가 다르거나, 또는 동일한 서비스이되 연결되는 백엔드 서버\n주소가 다르거든, 각기 다른 스토어 계정을 신청해 사용하라고 한다. 이는 요즘같이 MSA\n(Micro Service Architecture) 가 대세인 시대에 매우 불합리한 방식이기는 하지만, 어쨋든\n이러한 이유로 인하여, 한 회사 내지 단체가 복수의 스토어 ID 를 가지는 경우가 왕왕\n있다.\n\n때문에 `payments-server` 는, {@link IPaymentHistory 결제 내역}을 발행하거나\n{@link IPaymentReservation 간편 결제 수단}을 등록할 때 모두, 사용된 스토어의 ID\n를 반드시 기재하도록 하고 있다." + }, + "uid": { + "type": "string", + "title": "벤더사로부터 발급받은 식별자 번호", + "description": "벤더사로부터 발급받은 식별자 번호.\n\n결제 PG 사들이 제공하는 팝업창을 이용하여 결제를 진행하거나 혹은 간편 결제 수단을\n등록하거든, 결제 PG 사들은 해당 건에 대하여 별도의 식별자 번호를 발급한다.\n`IPaymentVendor.uid` 는 이처럼 결제 PG 사들이 발급해 준 식별자 번호를 기재하는\n속성이다.\n\n단 예외가 하나 있어, 아임포트는 간편 결제 카드 등록 건에 대하여 별도의 식별자 번호를\n부여하지 않고, 귀하의 서비스에서 발급해 준 ID 를 그대로 사용한다. 때문에 아임포트를\n통한 간편 결제 카드 등록의 건만 예외적으로, `IPaymentVendor.uid` 에\n{@link IPaymentSource.id } 를 동일하게 할당해주어야 한다." + } + }, + "nullable": false, + "required": [ + "code", + "store_id", + "uid" + ], + "description": "벤더사 정보.\n\n`IPaymentVendor` 결제 PG 벤더사에 관련된 정보를 형상화한 자료구조 인터페이스이다." + }, + "IPaymentSource": { + "type": "object", + "properties": { + "schema": { + "type": "string", + "description": "DB 스키마 이름" + }, + "table": { + "type": "string", + "description": "DB 테이블 명" + }, + "id": { + "type": "string", + "format": "uuid", + "description": "참조 레코드의 PK" + } + }, + "nullable": false, + "required": [ + "schema", + "table", + "id" + ], + "description": "원천 레코드 참조 정보.\n\n`IPaymentSource` 는 {@link IPaymentHistory 결제 내역} 및\n{@link IPaymentResrvation 간편 결제 수단}의 원천이 되는 레코드의 참조 정보를 형상화한\n자료구조 인터페이이다. 만일 대상이 {@link IPaymentHistory 결제 내역}이라면 결제의\n근원이 되는 주문에 대한 참조 정보를, 대상이 {@link IPaymentResrvation 간편 결제 수단}\n이라면 이를 기록한 귀사 서비스의 참조 정보를 기입하면 된다." + }, + "IIamportPayment": { + "oneOf": [ + { + "$ref": "#/components/schemas/IIamportCardPayment" + }, + { + "$ref": "#/components/schemas/IIamportTransferPayment" + }, + { + "$ref": "#/components/schemas/IIamportVBankPayment" + }, + { + "$ref": "#/components/schemas/IIamportPayment.IBasephonekpaykakaopaypaycolpayssgpaytosspayculturelandsmartculturehappymoneybooknlifepoint" + } + ], + "description": "결제 정보.\n\n`IIamportPayment` 는 아임포트의 결제 정보를 형상화한 자료구조이자 유니언 타입의\n인터페이스로써, if condition 을 통하여 method 값을 특정하면, 파생 타입이 자동으로\n지정된다.\n\n```typescript\nif (payment.pay_method === \"card\")\n payment.card_number; // payment be IIamportCardPayment\n```" + }, + "IIamportCardPayment": { + "type": "object", + "properties": { + "card_code": { + "type": "string", + "title": "카드 식별자 코드", + "description": "카드 식별자 코드." + }, + "card_name": { + "type": "string", + "title": "카드 이름", + "description": "카드 이름." + }, + "card_number": { + "type": "string", + "pattern": "\\d{4}-\\d{4}-\\d{4}-\\d{4}", + "title": "카드 번호", + "description": "카드 번호." + }, + "card_quota": { + "type": "integer", + "title": "할부 개월 수", + "description": "할부 개월 수." + }, + "apply_num": { + "type": "string", + "title": "카드사 승인번호", + "description": "카드사 승인번호." + }, + "pay_method": { + "type": "string", + "enum": [ + "card", + "samsung" + ] + }, + "imp_uid": { + "type": "string", + "title": "결제 정보 {@link IIamportPayment } 의 식별자 키", + "description": "결제 정보 {@link IIamportPayment } 의 식별자 키." + }, + "merchant_uid": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다." + }, + "name": { + "type": "string", + "nullable": true, + "title": "주문명, 누락 가능", + "description": "주문명, 누락 가능." + }, + "amount": { + "type": "number", + "title": "결제 총액", + "description": "결제 총액." + }, + "cancel_amount": { + "type": "number", + "title": "결제 취소, 환불 총액", + "description": "결제 취소, 환불 총액." + }, + "currency": { + "$ref": "#/components/schemas/IIamportPayment.Currency", + "title": "통화 단위", + "description": "통화 단위." + }, + "receipt_url": { + "type": "string", + "format": "uri", + "title": "영수증 URL", + "description": "영수증 URL." + }, + "cash_receipt_issue": { + "type": "boolean", + "title": "현금 영수증 발행 여부", + "description": "현금 영수증 발행 여부." + }, + "channel": { + "type": "string" + }, + "pg_provider": { + "type": "string" + }, + "emb_pg_provider": { + "type": "string", + "nullable": true + }, + "pg_id": { + "type": "string" + }, + "pg_tid": { + "type": "string" + }, + "escrow": { + "type": "boolean" + }, + "buyer_name": { + "type": "string", + "nullable": true + }, + "buyer_email": { + "type": "string", + "format": "email", + "nullable": true + }, + "buyer_tel": { + "type": "string", + "nullable": true + }, + "buyer_addr": { + "type": "string", + "nullable": true + }, + "buyer_postcode": { + "type": "string", + "nullable": true + }, + "customer_uid": { + "type": "string", + "nullable": true + }, + "customer_uid_usage": { + "type": "string", + "nullable": true + }, + "custom_data": { + "type": "string", + "nullable": true + }, + "user_agent": { + "type": "string", + "nullable": true + }, + "status": { + "$ref": "#/components/schemas/IIamportPayment.Status", + "title": "결제의 현재 (진행) 상태", + "description": "결제의 현재 (진행) 상태." + }, + "started_at": { + "type": "number", + "title": "결제 신청 일시", + "description": "결제 신청 일시.\n\n리눅스 타임이 쓰임." + }, + "paid_at": { + "type": "number", + "title": "결제 (지불) 완료 일시", + "description": "결제 (지불) 완료 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "failed_at": { + "type": "number", + "title": "결제 실패 일시", + "description": "결제 실패 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "cancelled_at": { + "type": "number", + "title": "결제 취소 일시", + "description": "결제 취소 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "fail_reason": { + "type": "string", + "nullable": true + }, + "cancel_reason": { + "type": "string", + "nullable": true + }, + "cancel_history": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IIamportPaymentCancel" + } + } + }, + "nullable": false, + "required": [ + "card_code", + "card_name", + "card_number", + "card_quota", + "apply_num", + "pay_method", + "imp_uid", + "merchant_uid", + "name", + "amount", + "cancel_amount", + "currency", + "receipt_url", + "cash_receipt_issue", + "channel", + "pg_provider", + "emb_pg_provider", + "pg_id", + "pg_tid", + "escrow", + "buyer_name", + "buyer_email", + "buyer_tel", + "buyer_addr", + "buyer_postcode", + "customer_uid", + "customer_uid_usage", + "custom_data", + "user_agent", + "status", + "started_at", + "paid_at", + "failed_at", + "cancelled_at", + "fail_reason", + "cancel_reason", + "cancel_history" + ], + "description": "카드 결제 정보." + }, + "IIamportPayment.Currency": { + "type": "string", + "enum": [ + "KRW", + "USD", + "EUR", + "JPY" + ] + }, + "IIamportPayment.Status": { + "type": "string", + "enum": [ + "paid", + "ready", + "failed", + "cancelled" + ] + }, + "IIamportPaymentCancel": { + "type": "object", + "properties": { + "pg_id": { + "type": "string" + }, + "pg_tid": { + "type": "string" + }, + "amount": { + "type": "number" + }, + "cancelled_at": { + "type": "number" + }, + "reason": { + "type": "string" + }, + "receipt_url": { + "type": "string", + "format": "uri" + } + }, + "nullable": false, + "required": [ + "pg_id", + "pg_tid", + "amount", + "cancelled_at", + "reason", + "receipt_url" + ], + "description": "결제 취소 정보." + }, + "IIamportTransferPayment": { + "type": "object", + "properties": { + "bank_code": { + "type": "string", + "title": "은행 식별자 코드", + "description": "은행 식별자 코드." + }, + "bank_name": { + "type": "string", + "title": "은행 이름", + "description": "은행 이름." + }, + "pay_method": { + "type": "string", + "enum": [ + "trans" + ] + }, + "imp_uid": { + "type": "string", + "title": "결제 정보 {@link IIamportPayment } 의 식별자 키", + "description": "결제 정보 {@link IIamportPayment } 의 식별자 키." + }, + "merchant_uid": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다." + }, + "name": { + "type": "string", + "nullable": true, + "title": "주문명, 누락 가능", + "description": "주문명, 누락 가능." + }, + "amount": { + "type": "number", + "title": "결제 총액", + "description": "결제 총액." + }, + "cancel_amount": { + "type": "number", + "title": "결제 취소, 환불 총액", + "description": "결제 취소, 환불 총액." + }, + "currency": { + "$ref": "#/components/schemas/IIamportPayment.Currency", + "title": "통화 단위", + "description": "통화 단위." + }, + "receipt_url": { + "type": "string", + "format": "uri", + "title": "영수증 URL", + "description": "영수증 URL." + }, + "cash_receipt_issue": { + "type": "boolean", + "title": "현금 영수증 발행 여부", + "description": "현금 영수증 발행 여부." + }, + "channel": { + "type": "string" + }, + "pg_provider": { + "type": "string" + }, + "emb_pg_provider": { + "type": "string", + "nullable": true + }, + "pg_id": { + "type": "string" + }, + "pg_tid": { + "type": "string" + }, + "escrow": { + "type": "boolean" + }, + "buyer_name": { + "type": "string", + "nullable": true + }, + "buyer_email": { + "type": "string", + "format": "email", + "nullable": true + }, + "buyer_tel": { + "type": "string", + "nullable": true + }, + "buyer_addr": { + "type": "string", + "nullable": true + }, + "buyer_postcode": { + "type": "string", + "nullable": true + }, + "customer_uid": { + "type": "string", + "nullable": true + }, + "customer_uid_usage": { + "type": "string", + "nullable": true + }, + "custom_data": { + "type": "string", + "nullable": true + }, + "user_agent": { + "type": "string", + "nullable": true + }, + "status": { + "$ref": "#/components/schemas/IIamportPayment.Status", + "title": "결제의 현재 (진행) 상태", + "description": "결제의 현재 (진행) 상태." + }, + "started_at": { + "type": "number", + "title": "결제 신청 일시", + "description": "결제 신청 일시.\n\n리눅스 타임이 쓰임." + }, + "paid_at": { + "type": "number", + "title": "결제 (지불) 완료 일시", + "description": "결제 (지불) 완료 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "failed_at": { + "type": "number", + "title": "결제 실패 일시", + "description": "결제 실패 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "cancelled_at": { + "type": "number", + "title": "결제 취소 일시", + "description": "결제 취소 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "fail_reason": { + "type": "string", + "nullable": true + }, + "cancel_reason": { + "type": "string", + "nullable": true + }, + "cancel_history": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IIamportPaymentCancel" + } + } + }, + "nullable": false, + "required": [ + "bank_code", + "bank_name", + "pay_method", + "imp_uid", + "merchant_uid", + "name", + "amount", + "cancel_amount", + "currency", + "receipt_url", + "cash_receipt_issue", + "channel", + "pg_provider", + "emb_pg_provider", + "pg_id", + "pg_tid", + "escrow", + "buyer_name", + "buyer_email", + "buyer_tel", + "buyer_addr", + "buyer_postcode", + "customer_uid", + "customer_uid_usage", + "custom_data", + "user_agent", + "status", + "started_at", + "paid_at", + "failed_at", + "cancelled_at", + "fail_reason", + "cancel_reason", + "cancel_history" + ], + "description": "계좌 이체 결제 정보." + }, + "IIamportVBankPayment": { + "type": "object", + "properties": { + "vbank_code": { + "type": "string", + "title": "가상 계좌 식별자 코드", + "description": "가상 계좌 식별자 코드." + }, + "vbank_name": { + "type": "string", + "description": "가상 게좌 이름" + }, + "vbank_num": { + "type": "string", + "description": "가상 계좌 번호" + }, + "vbank_holder": { + "type": "string", + "title": "가상 계좌 예금주", + "description": "가상 계좌 예금주." + }, + "vbank_date": { + "type": "number", + "title": "가상 계좌 입금 만료 기한", + "description": "가상 계좌 입금 만료 기한." + }, + "vbank_issued_at": { + "type": "number", + "title": "가상 계좌 개설 일시", + "description": "가상 계좌 개설 일시." + }, + "pay_method": { + "type": "string", + "enum": [ + "vbank" + ] + }, + "imp_uid": { + "type": "string", + "title": "결제 정보 {@link IIamportPayment } 의 식별자 키", + "description": "결제 정보 {@link IIamportPayment } 의 식별자 키." + }, + "merchant_uid": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다." + }, + "name": { + "type": "string", + "nullable": true, + "title": "주문명, 누락 가능", + "description": "주문명, 누락 가능." + }, + "amount": { + "type": "number", + "title": "결제 총액", + "description": "결제 총액." + }, + "cancel_amount": { + "type": "number", + "title": "결제 취소, 환불 총액", + "description": "결제 취소, 환불 총액." + }, + "currency": { + "$ref": "#/components/schemas/IIamportPayment.Currency", + "title": "통화 단위", + "description": "통화 단위." + }, + "receipt_url": { + "type": "string", + "format": "uri", + "title": "영수증 URL", + "description": "영수증 URL." + }, + "cash_receipt_issue": { + "type": "boolean", + "title": "현금 영수증 발행 여부", + "description": "현금 영수증 발행 여부." + }, + "channel": { + "type": "string" + }, + "pg_provider": { + "type": "string" + }, + "emb_pg_provider": { + "type": "string", + "nullable": true + }, + "pg_id": { + "type": "string" + }, + "pg_tid": { + "type": "string" + }, + "escrow": { + "type": "boolean" + }, + "buyer_name": { + "type": "string", + "nullable": true + }, + "buyer_email": { + "type": "string", + "format": "email", + "nullable": true + }, + "buyer_tel": { + "type": "string", + "nullable": true + }, + "buyer_addr": { + "type": "string", + "nullable": true + }, + "buyer_postcode": { + "type": "string", + "nullable": true + }, + "customer_uid": { + "type": "string", + "nullable": true + }, + "customer_uid_usage": { + "type": "string", + "nullable": true + }, + "custom_data": { + "type": "string", + "nullable": true + }, + "user_agent": { + "type": "string", + "nullable": true + }, + "status": { + "$ref": "#/components/schemas/IIamportPayment.Status", + "title": "결제의 현재 (진행) 상태", + "description": "결제의 현재 (진행) 상태." + }, + "started_at": { + "type": "number", + "title": "결제 신청 일시", + "description": "결제 신청 일시.\n\n리눅스 타임이 쓰임." + }, + "paid_at": { + "type": "number", + "title": "결제 (지불) 완료 일시", + "description": "결제 (지불) 완료 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "failed_at": { + "type": "number", + "title": "결제 실패 일시", + "description": "결제 실패 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "cancelled_at": { + "type": "number", + "title": "결제 취소 일시", + "description": "결제 취소 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "fail_reason": { + "type": "string", + "nullable": true + }, + "cancel_reason": { + "type": "string", + "nullable": true + }, + "cancel_history": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IIamportPaymentCancel" + } + } + }, + "nullable": false, + "required": [ + "vbank_code", + "vbank_name", + "vbank_num", + "vbank_holder", + "vbank_date", + "vbank_issued_at", + "pay_method", + "imp_uid", + "merchant_uid", + "name", + "amount", + "cancel_amount", + "currency", + "receipt_url", + "cash_receipt_issue", + "channel", + "pg_provider", + "emb_pg_provider", + "pg_id", + "pg_tid", + "escrow", + "buyer_name", + "buyer_email", + "buyer_tel", + "buyer_addr", + "buyer_postcode", + "customer_uid", + "customer_uid_usage", + "custom_data", + "user_agent", + "status", + "started_at", + "paid_at", + "failed_at", + "cancelled_at", + "fail_reason", + "cancel_reason", + "cancel_history" + ], + "description": "가상 계좌 결제 정보." + }, + "IIamportPayment.IBasephonekpaykakaopaypaycolpayssgpaytosspayculturelandsmartculturehappymoneybooknlifepoint": { + "type": "object", + "properties": { + "pay_method": { + "type": "string", + "enum": [ + "phone", + "kpay", + "kakaopay", + "payco", + "lpay", + "ssgpay", + "tosspay", + "cultureland", + "smartculture", + "happymoney", + "booknlife", + "point" + ] + }, + "imp_uid": { + "type": "string", + "title": "결제 정보 {@link IIamportPayment } 의 식별자 키", + "description": "결제 정보 {@link IIamportPayment } 의 식별자 키." + }, + "merchant_uid": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다." + }, + "name": { + "type": "string", + "nullable": true, + "title": "주문명, 누락 가능", + "description": "주문명, 누락 가능." + }, + "amount": { + "type": "number", + "title": "결제 총액", + "description": "결제 총액." + }, + "cancel_amount": { + "type": "number", + "title": "결제 취소, 환불 총액", + "description": "결제 취소, 환불 총액." + }, + "currency": { + "$ref": "#/components/schemas/IIamportPayment.Currency", + "title": "통화 단위", + "description": "통화 단위." + }, + "receipt_url": { + "type": "string", + "format": "uri", + "title": "영수증 URL", + "description": "영수증 URL." + }, + "cash_receipt_issue": { + "type": "boolean", + "title": "현금 영수증 발행 여부", + "description": "현금 영수증 발행 여부." + }, + "channel": { + "type": "string" + }, + "pg_provider": { + "type": "string" + }, + "emb_pg_provider": { + "type": "string", + "nullable": true + }, + "pg_id": { + "type": "string" + }, + "pg_tid": { + "type": "string" + }, + "escrow": { + "type": "boolean" + }, + "buyer_name": { + "type": "string", + "nullable": true + }, + "buyer_email": { + "type": "string", + "format": "email", + "nullable": true + }, + "buyer_tel": { + "type": "string", + "nullable": true + }, + "buyer_addr": { + "type": "string", + "nullable": true + }, + "buyer_postcode": { + "type": "string", + "nullable": true + }, + "customer_uid": { + "type": "string", + "nullable": true + }, + "customer_uid_usage": { + "type": "string", + "nullable": true + }, + "custom_data": { + "type": "string", + "nullable": true + }, + "user_agent": { + "type": "string", + "nullable": true + }, + "status": { + "$ref": "#/components/schemas/IIamportPayment.Status", + "title": "결제의 현재 (진행) 상태", + "description": "결제의 현재 (진행) 상태." + }, + "started_at": { + "type": "number", + "title": "결제 신청 일시", + "description": "결제 신청 일시.\n\n리눅스 타임이 쓰임." + }, + "paid_at": { + "type": "number", + "title": "결제 (지불) 완료 일시", + "description": "결제 (지불) 완료 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "failed_at": { + "type": "number", + "title": "결제 실패 일시", + "description": "결제 실패 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "cancelled_at": { + "type": "number", + "title": "결제 취소 일시", + "description": "결제 취소 일시.\n\n리눅스 타임이 쓰이며, `null` 대신 0 을 씀." + }, + "fail_reason": { + "type": "string", + "nullable": true + }, + "cancel_reason": { + "type": "string", + "nullable": true + }, + "cancel_history": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IIamportPaymentCancel" + } + } + }, + "nullable": false, + "required": [ + "pay_method", + "imp_uid", + "merchant_uid", + "name", + "amount", + "cancel_amount", + "currency", + "receipt_url", + "cash_receipt_issue", + "channel", + "pg_provider", + "emb_pg_provider", + "pg_id", + "pg_tid", + "escrow", + "buyer_name", + "buyer_email", + "buyer_tel", + "buyer_addr", + "buyer_postcode", + "customer_uid", + "customer_uid_usage", + "custom_data", + "user_agent", + "status", + "started_at", + "paid_at", + "failed_at", + "cancelled_at", + "fail_reason", + "cancel_reason", + "cancel_history" + ], + "description": "결제 기본 (공통) 정보." + }, + "IPaymentCancelHistory": { + "type": "object", + "properties": { + "reason": { + "type": "string", + "title": "결제 취소 사유", + "description": "결제 취소 사유." + }, + "price": { + "type": "number", + "minimum": 0, + "title": "환불 금액", + "description": "환불 금액." + }, + "created_at": { + "type": "string", + "format": "date-time", + "title": "레코드 생성 일시", + "description": "레코드 생성 일시.\n\n즉, 결제 취소가 발생한 시각." + } + }, + "nullable": false, + "required": [ + "reason", + "price", + "created_at" + ], + "description": "결제 취소 내역." + }, + "IPaymentHistory.TossType": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "title": "Primary Key", + "description": "Primary Key." + }, + "vendor_code": { + "type": "string", + "enum": [ + "toss.payments" + ], + "title": "벤더사 식별자 코드", + "description": "벤더사 식별자 코드.\n\n{@link IPaymentVendor.code }와 완전히 동일한 값이되, 단지 union type\nspecialization 을 위해 중복 표기하였을 뿐이다. `if condition` 을 통하여\n{@link IPaymentHistory.data }의 타입을 특정할 수 있다." + }, + "vendor": { + "$ref": "#/components/schemas/IPaymentVendortoss.payments", + "title": "벤더 정보", + "description": "벤더 정보." + }, + "source": { + "$ref": "#/components/schemas/IPaymentSource", + "title": "원천 래코드 정보", + "description": "원천 래코드 정보." + }, + "data": { + "$ref": "#/components/schemas/ITossPayment", + "title": "결제 상세 데이터, 벤더별로 데이터 양식이 다르니 주의할 것", + "description": "결제 상세 데이터, 벤더별로 데이터 양식이 다르니 주의할 것." + }, + "currency": { + "type": "string", + "description": "통화 단위\n\nKRW, USB, JPY 등." + }, + "price": { + "type": "number", + "minimum": 0, + "title": "결제 가격", + "description": "결제 가격." + }, + "refund": { + "type": "number", + "minimum": 0, + "nullable": true, + "title": "결제 취소시의 환불 금액", + "description": "결제 취소시의 환불 금액." + }, + "webhook_url": { + "type": "string", + "format": "uri", + "nullable": true, + "description": "결제 정보가 갱신되었을 때, 이를 수신할 URL" + }, + "created_at": { + "type": "string", + "format": "date-time", + "title": "결제 레코드 생성 일시", + "description": "결제 레코드 생성 일시." + }, + "paid_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "title": "결제 완료 일시", + "description": "결제 완료 일시." + }, + "cancelled_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "title": "결제 취소 일시", + "description": "결제 취소 일시." + }, + "cancels": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IPaymentCancelHistory" + }, + "title": "결제 취소 내역 리스트", + "description": "결제 취소 내역 리스트." + } + }, + "nullable": false, + "required": [ + "id", + "vendor_code", + "vendor", + "source", + "data", + "currency", + "price", + "refund", + "webhook_url", + "created_at", + "paid_at", + "cancelled_at", + "cancels" + ], + "description": "토스 페이먼츠로부터의 결제 내역." + }, + "IPaymentVendortoss.payments": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "toss.payments" + ], + "title": "벤더사 식별자 코드", + "description": "벤더사 식별자 코드.\n\n아임포트의 경우에는 `iamport` 를, 토스의 경우에는 `toss.payments` 를 적어주면 된다." + }, + "store_id": { + "type": "string", + "title": "벤더사에 등록한 스토어 ID", + "description": "벤더사에 등록한 스토어 ID.\n\n결제 PG 사들은 서비스 주소가 다르거나, 또는 동일한 서비스이되 연결되는 백엔드 서버\n주소가 다르거든, 각기 다른 스토어 계정을 신청해 사용하라고 한다. 이는 요즘같이 MSA\n(Micro Service Architecture) 가 대세인 시대에 매우 불합리한 방식이기는 하지만, 어쨋든\n이러한 이유로 인하여, 한 회사 내지 단체가 복수의 스토어 ID 를 가지는 경우가 왕왕\n있다.\n\n때문에 `payments-server` 는, {@link IPaymentHistory 결제 내역}을 발행하거나\n{@link IPaymentReservation 간편 결제 수단}을 등록할 때 모두, 사용된 스토어의 ID\n를 반드시 기재하도록 하고 있다." + }, + "uid": { + "type": "string", + "title": "벤더사로부터 발급받은 식별자 번호", + "description": "벤더사로부터 발급받은 식별자 번호.\n\n결제 PG 사들이 제공하는 팝업창을 이용하여 결제를 진행하거나 혹은 간편 결제 수단을\n등록하거든, 결제 PG 사들은 해당 건에 대하여 별도의 식별자 번호를 발급한다.\n`IPaymentVendor.uid` 는 이처럼 결제 PG 사들이 발급해 준 식별자 번호를 기재하는\n속성이다.\n\n단 예외가 하나 있어, 아임포트는 간편 결제 카드 등록 건에 대하여 별도의 식별자 번호를\n부여하지 않고, 귀하의 서비스에서 발급해 준 ID 를 그대로 사용한다. 때문에 아임포트를\n통한 간편 결제 카드 등록의 건만 예외적으로, `IPaymentVendor.uid` 에\n{@link IPaymentSource.id } 를 동일하게 할당해주어야 한다." + } + }, + "nullable": false, + "required": [ + "code", + "store_id", + "uid" + ], + "description": "벤더사 정보.\n\n`IPaymentVendor` 결제 PG 벤더사에 관련된 정보를 형상화한 자료구조 인터페이스이다." + }, + "ITossPayment": { + "oneOf": [ + { + "$ref": "#/components/schemas/ITossCardPayment" + }, + { + "$ref": "#/components/schemas/ITossGiftCertificatePayment" + }, + { + "$ref": "#/components/schemas/ITossMobilePhonePayment" + }, + { + "$ref": "#/components/schemas/ITossTransferPayment" + }, + { + "$ref": "#/components/schemas/ITossVirtualAccountPayment" + } + ], + "description": "결제 정보.\n\n`ITossPayment` 는 토스 페이먼츠의 결제 정보를 형상화한 자료구조이자 유니언 타입의\n인터페이스로써, if condition 을 통하여 method 값을 특정하면, 파생 타입이 자동으로\n지정된다.\n\n```typescript\nif (payment.method === \"카드\")\n payment.card; // payment be ITossCardPayment\n```" + }, + "ITossCardPayment": { + "type": "object", + "properties": { + "card": { + "$ref": "#/components/schemas/ITossCardPayment.ICard", + "title": "카드 정보", + "description": "카드 정보." + }, + "discount": { + "$ref": "#/components/schemas/ITossCardPayment.IDiscount.Nullable", + "title": "카드사의 즉시 할인 프로모션 정보", + "description": "카드사의 즉시 할인 프로모션 정보." + }, + "easyPay": { + "type": "string", + "enum": [ + "토스결제", + "페이코", + "삼성페이" + ], + "nullable": true, + "title": "간편결제로 결제한 경우 간편결제 타입 정보", + "description": "간편결제로 결제한 경우 간편결제 타입 정보." + }, + "method": { + "type": "string", + "enum": [ + "카드" + ], + "title": "결제 수단", + "description": "결제 수단." + }, + "type": { + "type": "string", + "enum": [ + "NORMAL", + "BILLING" + ], + "title": "결제 타입", + "description": "결제 타입.\n\n - NORMAL: 일반 결제\n - BILLING: 미리 등록한 카드에 의한 간편 결제." + }, + "status": { + "type": "string", + "enum": [ + "READY", + "IN_PROGRESS", + "WAITING_FOR_DEPOSIT", + "DONE", + "CANCELED", + "PARTIAL_CANCELED", + "ABORTED", + "EXPIRED" + ], + "title": "결제 상태", + "description": "결제 상태.\n\n - READY\n - IN_PROGRESS\n - WAITING_FOR_DEPOSIT\n - DONE\n - CANCELED\n - PARTIAL_CANCELED\n - ABORTED\n - EXPIRED" + }, + "mId": { + "type": "string", + "title": "가맹점 ID", + "description": "가맹점 ID.\n\n현재 tosspayments 가 쓰임." + }, + "version": { + "type": "string", + "title": "사용 중인 토스 페이먼츠 API 의 버전", + "description": "사용 중인 토스 페이먼츠 API 의 버전." + }, + "paymentKey": { + "type": "string", + "title": "결제 내역의 식별자 번호", + "description": "결제 내역의 식별자 번호." + }, + "orderId": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키." + }, + "transactionKey": { + "type": "string", + "title": "거래 건에 대한 고유한 키 값", + "description": "거래 건에 대한 고유한 키 값.\n\n{@link paymentKey } 와 달리, 이를 사용할 일은 없더라." + }, + "orderName": { + "type": "string", + "title": "주문 이름", + "description": "주문 이름.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 발급한 주문명." + }, + "currency": { + "type": "string", + "title": "화폐 단위", + "description": "화폐 단위.\n\n현재 토스 페이먼츠는 KRW 만 사용 가능." + }, + "totalAmount": { + "type": "number", + "title": "총 결제 금액", + "description": "총 결제 금액." + }, + "balanceAmount": { + "type": "number", + "title": "취소할 수 있는 금액", + "description": "취소할 수 있는 금액." + }, + "suppliedAmount": { + "type": "number", + "title": "공급가액", + "description": "공급가액." + }, + "taxFreeAmount": { + "type": "number", + "title": "면세액", + "description": "면세액." + }, + "vat": { + "type": "number", + "title": "부가세", + "description": "부가세." + }, + "useEscrow": { + "type": "boolean", + "title": "에스크로 사용 여부", + "description": "에스크로 사용 여부." + }, + "cultureExpense": { + "type": "boolean", + "title": "문화비 지출 여부", + "description": "문화비 지출 여부.\n\n도석입, 공연 티켓, 박물관/미술관 입장권 등." + }, + "requestedAt": { + "type": "string", + "format": "date-time", + "title": "결제 요청 일시", + "description": "결제 요청 일시." + }, + "approvedAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "title": "결제 승인 일시", + "description": "결제 승인 일시." + }, + "cancels": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ITossPaymentCancel" + }, + "nullable": true, + "title": "결제 취소 내역", + "description": "결제 취소 내역." + }, + "cashReceipt": { + "$ref": "#/components/schemas/ITossCashReceipt.ISummary.Nullable", + "title": "현금 영수증 정보", + "description": "현금 영수증 정보." + } + }, + "nullable": false, + "required": [ + "card", + "discount", + "easyPay", + "method", + "type", + "status", + "mId", + "version", + "paymentKey", + "orderId", + "transactionKey", + "orderName", + "currency", + "totalAmount", + "balanceAmount", + "suppliedAmount", + "taxFreeAmount", + "vat", + "useEscrow", + "cultureExpense", + "requestedAt", + "approvedAt", + "cancels", + "cashReceipt" + ], + "description": "카드 결제 정보." + }, + "ITossCardPayment.ICard": { + "type": "object", + "properties": { + "company": { + "type": "string", + "title": "카드사 이름", + "description": "카드사 이름." + }, + "number": { + "type": "string", + "pattern": "[0-9]{16}", + "title": "카드 번호", + "description": "카드 번호." + }, + "installmentPlanMonths": { + "type": "number", + "title": "할부 개월 수", + "description": "할부 개월 수." + }, + "isInterestFree": { + "type": "boolean", + "title": "무이자 할부 적용 여부", + "description": "무이자 할부 적용 여부." + }, + "approveNo": { + "type": "string", + "title": "승인 번호", + "description": "승인 번호." + }, + "useCardPoint": { + "type": "boolean", + "enum": [ + false + ], + "title": "카드 포인트 사용 여부", + "description": "카드 포인트 사용 여부." + }, + "cardType": { + "type": "string", + "enum": [ + "신용", + "체크", + "기프트" + ], + "title": "카드 타입", + "description": "카드 타입." + }, + "ownerType": { + "type": "string", + "enum": [ + "개인", + "법인" + ], + "title": "카드의 소유자 타입", + "description": "카드의 소유자 타입." + }, + "acquireStatus": { + "type": "string", + "enum": [ + "READY", + "CANCELED", + "REQUESTED", + "COMPLETED", + "CANCEL_REQUESTED" + ], + "title": "카드 결제의 매입 상태", + "description": "카드 결제의 매입 상태.\n\n - READY: 매입 대기\n - REQUESTED: 매입 요청됨\n - COMPLETED: 매입 완료\n - CANCEL_REQUESTED: 매입 취소 요청됨\n - CANCELD: 매입 취소됨" + }, + "receiptUrl": { + "type": "string", + "format": "uri", + "title": "영수증 URL", + "description": "영수증 URL." + } + }, + "nullable": false, + "required": [ + "company", + "number", + "installmentPlanMonths", + "isInterestFree", + "approveNo", + "useCardPoint", + "cardType", + "ownerType", + "acquireStatus", + "receiptUrl" + ], + "description": "카드 정보." + }, + "ITossCardPayment.IDiscount.Nullable": { + "type": "object", + "properties": { + "amount": { + "type": "number", + "title": "카드사의 즉시 할인 프로모션을 적용한 금액", + "description": "카드사의 즉시 할인 프로모션을 적용한 금액." + } + }, + "nullable": true, + "required": [ + "amount" + ], + "description": "카드사의 즉시 할인 프로모션 정보." + }, + "ITossPaymentCancel": { + "type": "object", + "properties": { + "cancelAmount": { + "type": "number", + "title": "취소 총액", + "description": "취소 총액." + }, + "cancelReason": { + "type": "string", + "title": "취소 사유", + "description": "취소 사유." + }, + "taxFreeAmount": { + "type": "number", + "title": "면세 처리된 금액", + "description": "면세 처리된 금액." + }, + "taxAmount": { + "type": "number", + "title": "과세 처리된 금액", + "description": "과세 처리된 금액." + }, + "refundableAmount": { + "type": "number", + "title": "결제 취소 후 환불 가능 잔액", + "description": "결제 취소 후 환불 가능 잔액." + }, + "canceledAt": { + "type": "string", + "format": "date-time", + "title": "취소 일시", + "description": "취소 일시." + } + }, + "nullable": false, + "required": [ + "cancelAmount", + "cancelReason", + "taxFreeAmount", + "taxAmount", + "refundableAmount", + "canceledAt" + ], + "description": "결제 취소 정보." + }, + "ITossCashReceipt.ISummary.Nullable": { + "type": "object", + "properties": { + "type": { + "$ref": "#/components/schemas/ITossCashReceipt.Type", + "title": "현금 영수증의 종류", + "description": "현금 영수증의 종류." + }, + "amount": { + "type": "number", + "title": "현금 영수증 처리된 금액", + "description": "현금 영수증 처리된 금액." + }, + "taxFreeAmount": { + "type": "number", + "title": "면세 처리된 금액", + "description": "면세 처리된 금액." + }, + "issueNumber": { + "type": "string", + "title": "현금영수증 발급번호", + "description": "현금영수증 발급번호." + }, + "receiptUrl": { + "type": "string", + "title": "현금영수증 조회 페이지 주소", + "description": "현금영수증 조회 페이지 주소." + } + }, + "nullable": true, + "required": [ + "type", + "amount", + "taxFreeAmount", + "issueNumber", + "receiptUrl" + ], + "description": "현금 영수증 요약 정보." + }, + "ITossCashReceipt.Type": { + "type": "string", + "enum": [ + "소득공제", + "지출증빙" + ], + "description": "현금 영수증의 종류." + }, + "ITossGiftCertificatePayment": { + "type": "object", + "properties": { + "giftCertificate": { + "$ref": "#/components/schemas/ITossGiftCertificatePayment.IGiftCertificate", + "title": "상품권 정보", + "description": "상품권 정보." + }, + "method": { + "type": "string", + "enum": [ + "상품권" + ], + "title": "결제 수단", + "description": "결제 수단." + }, + "type": { + "type": "string", + "enum": [ + "NORMAL" + ], + "title": "결제 타입", + "description": "결제 타입.\n\n - NORMAL: 일반 결제\n - BILLING: 미리 등록한 카드에 의한 간편 결제." + }, + "status": { + "type": "string", + "enum": [ + "READY", + "IN_PROGRESS", + "WAITING_FOR_DEPOSIT", + "DONE", + "CANCELED", + "PARTIAL_CANCELED", + "ABORTED", + "EXPIRED" + ], + "title": "결제 상태", + "description": "결제 상태.\n\n - READY\n - IN_PROGRESS\n - WAITING_FOR_DEPOSIT\n - DONE\n - CANCELED\n - PARTIAL_CANCELED\n - ABORTED\n - EXPIRED" + }, + "mId": { + "type": "string", + "title": "가맹점 ID", + "description": "가맹점 ID.\n\n현재 tosspayments 가 쓰임." + }, + "version": { + "type": "string", + "title": "사용 중인 토스 페이먼츠 API 의 버전", + "description": "사용 중인 토스 페이먼츠 API 의 버전." + }, + "paymentKey": { + "type": "string", + "title": "결제 내역의 식별자 번호", + "description": "결제 내역의 식별자 번호." + }, + "orderId": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키." + }, + "transactionKey": { + "type": "string", + "title": "거래 건에 대한 고유한 키 값", + "description": "거래 건에 대한 고유한 키 값.\n\n{@link paymentKey } 와 달리, 이를 사용할 일은 없더라." + }, + "orderName": { + "type": "string", + "title": "주문 이름", + "description": "주문 이름.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 발급한 주문명." + }, + "currency": { + "type": "string", + "title": "화폐 단위", + "description": "화폐 단위.\n\n현재 토스 페이먼츠는 KRW 만 사용 가능." + }, + "totalAmount": { + "type": "number", + "title": "총 결제 금액", + "description": "총 결제 금액." + }, + "balanceAmount": { + "type": "number", + "title": "취소할 수 있는 금액", + "description": "취소할 수 있는 금액." + }, + "suppliedAmount": { + "type": "number", + "title": "공급가액", + "description": "공급가액." + }, + "taxFreeAmount": { + "type": "number", + "title": "면세액", + "description": "면세액." + }, + "vat": { + "type": "number", + "title": "부가세", + "description": "부가세." + }, + "useEscrow": { + "type": "boolean", + "title": "에스크로 사용 여부", + "description": "에스크로 사용 여부." + }, + "cultureExpense": { + "type": "boolean", + "title": "문화비 지출 여부", + "description": "문화비 지출 여부.\n\n도석입, 공연 티켓, 박물관/미술관 입장권 등." + }, + "requestedAt": { + "type": "string", + "format": "date-time", + "title": "결제 요청 일시", + "description": "결제 요청 일시." + }, + "approvedAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "title": "결제 승인 일시", + "description": "결제 승인 일시." + }, + "cancels": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ITossPaymentCancel" + }, + "nullable": true, + "title": "결제 취소 내역", + "description": "결제 취소 내역." + }, + "cashReceipt": { + "$ref": "#/components/schemas/ITossCashReceipt.ISummary.Nullable", + "title": "현금 영수증 정보", + "description": "현금 영수증 정보." + } + }, + "nullable": false, + "required": [ + "giftCertificate", + "method", + "type", + "status", + "mId", + "version", + "paymentKey", + "orderId", + "transactionKey", + "orderName", + "currency", + "totalAmount", + "balanceAmount", + "suppliedAmount", + "taxFreeAmount", + "vat", + "useEscrow", + "cultureExpense", + "requestedAt", + "approvedAt", + "cancels", + "cashReceipt" + ], + "description": "상품권 결제 정보." + }, + "ITossGiftCertificatePayment.IGiftCertificate": { + "type": "object", + "properties": { + "approveNo": { + "type": "string", + "title": "승인 번호", + "description": "승인 번호." + }, + "settlementStatus": { + "type": "string", + "enum": [ + "COMPLETE", + "INCOMPLETE" + ], + "title": "정산 상태", + "description": "정산 상태." + } + }, + "nullable": false, + "required": [ + "approveNo", + "settlementStatus" + ], + "description": "상품권 정보." + }, + "ITossMobilePhonePayment": { + "type": "object", + "properties": { + "mobilePhone": { + "$ref": "#/components/schemas/ITossMobilePhonePayment.IMobilePhone", + "title": "휴대폰 정보", + "description": "휴대폰 정보." + }, + "method": { + "type": "string", + "enum": [ + "휴대폰" + ], + "title": "결제 수단", + "description": "결제 수단." + }, + "type": { + "type": "string", + "enum": [ + "NORMAL" + ], + "title": "결제 타입", + "description": "결제 타입.\n\n - NORMAL: 일반 결제\n - BILLING: 미리 등록한 카드에 의한 간편 결제." + }, + "status": { + "type": "string", + "enum": [ + "READY", + "IN_PROGRESS", + "WAITING_FOR_DEPOSIT", + "DONE", + "CANCELED", + "PARTIAL_CANCELED", + "ABORTED", + "EXPIRED" + ], + "title": "결제 상태", + "description": "결제 상태.\n\n - READY\n - IN_PROGRESS\n - WAITING_FOR_DEPOSIT\n - DONE\n - CANCELED\n - PARTIAL_CANCELED\n - ABORTED\n - EXPIRED" + }, + "mId": { + "type": "string", + "title": "가맹점 ID", + "description": "가맹점 ID.\n\n현재 tosspayments 가 쓰임." + }, + "version": { + "type": "string", + "title": "사용 중인 토스 페이먼츠 API 의 버전", + "description": "사용 중인 토스 페이먼츠 API 의 버전." + }, + "paymentKey": { + "type": "string", + "title": "결제 내역의 식별자 번호", + "description": "결제 내역의 식별자 번호." + }, + "orderId": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키." + }, + "transactionKey": { + "type": "string", + "title": "거래 건에 대한 고유한 키 값", + "description": "거래 건에 대한 고유한 키 값.\n\n{@link paymentKey } 와 달리, 이를 사용할 일은 없더라." + }, + "orderName": { + "type": "string", + "title": "주문 이름", + "description": "주문 이름.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 발급한 주문명." + }, + "currency": { + "type": "string", + "title": "화폐 단위", + "description": "화폐 단위.\n\n현재 토스 페이먼츠는 KRW 만 사용 가능." + }, + "totalAmount": { + "type": "number", + "title": "총 결제 금액", + "description": "총 결제 금액." + }, + "balanceAmount": { + "type": "number", + "title": "취소할 수 있는 금액", + "description": "취소할 수 있는 금액." + }, + "suppliedAmount": { + "type": "number", + "title": "공급가액", + "description": "공급가액." + }, + "taxFreeAmount": { + "type": "number", + "title": "면세액", + "description": "면세액." + }, + "vat": { + "type": "number", + "title": "부가세", + "description": "부가세." + }, + "useEscrow": { + "type": "boolean", + "title": "에스크로 사용 여부", + "description": "에스크로 사용 여부." + }, + "cultureExpense": { + "type": "boolean", + "title": "문화비 지출 여부", + "description": "문화비 지출 여부.\n\n도석입, 공연 티켓, 박물관/미술관 입장권 등." + }, + "requestedAt": { + "type": "string", + "format": "date-time", + "title": "결제 요청 일시", + "description": "결제 요청 일시." + }, + "approvedAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "title": "결제 승인 일시", + "description": "결제 승인 일시." + }, + "cancels": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ITossPaymentCancel" + }, + "nullable": true, + "title": "결제 취소 내역", + "description": "결제 취소 내역." + }, + "cashReceipt": { + "$ref": "#/components/schemas/ITossCashReceipt.ISummary.Nullable", + "title": "현금 영수증 정보", + "description": "현금 영수증 정보." + } + }, + "nullable": false, + "required": [ + "mobilePhone", + "method", + "type", + "status", + "mId", + "version", + "paymentKey", + "orderId", + "transactionKey", + "orderName", + "currency", + "totalAmount", + "balanceAmount", + "suppliedAmount", + "taxFreeAmount", + "vat", + "useEscrow", + "cultureExpense", + "requestedAt", + "approvedAt", + "cancels", + "cashReceipt" + ], + "description": "휴대폰 결제 정보." + }, + "ITossMobilePhonePayment.IMobilePhone": { + "type": "object", + "properties": { + "carrier": { + "type": "string", + "title": "통신사", + "description": "통신사." + }, + "customerMobilePhone": { + "type": "string", + "title": "고객 휴대폰 번호", + "description": "고객 휴대폰 번호." + }, + "settlementStatus": { + "type": "string", + "enum": [ + "COMPLETED", + "INCOMPLETED" + ], + "title": "정산 상태", + "description": "정산 상태." + } + }, + "nullable": false, + "required": [ + "carrier", + "customerMobilePhone", + "settlementStatus" + ], + "description": "휴대폰 정보." + }, + "ITossTransferPayment": { + "type": "object", + "properties": { + "transfer": { + "$ref": "#/components/schemas/ITossTransferPayment.ITransfer", + "title": "계좌 이체 정보", + "description": "계좌 이체 정보." + }, + "method": { + "type": "string", + "enum": [ + "계좌이체" + ], + "title": "결제 수단", + "description": "결제 수단." + }, + "type": { + "type": "string", + "enum": [ + "NORMAL" + ], + "title": "결제 타입", + "description": "결제 타입.\n\n - NORMAL: 일반 결제\n - BILLING: 미리 등록한 카드에 의한 간편 결제." + }, + "status": { + "type": "string", + "enum": [ + "READY", + "IN_PROGRESS", + "WAITING_FOR_DEPOSIT", + "DONE", + "CANCELED", + "PARTIAL_CANCELED", + "ABORTED", + "EXPIRED" + ], + "title": "결제 상태", + "description": "결제 상태.\n\n - READY\n - IN_PROGRESS\n - WAITING_FOR_DEPOSIT\n - DONE\n - CANCELED\n - PARTIAL_CANCELED\n - ABORTED\n - EXPIRED" + }, + "mId": { + "type": "string", + "title": "가맹점 ID", + "description": "가맹점 ID.\n\n현재 tosspayments 가 쓰임." + }, + "version": { + "type": "string", + "title": "사용 중인 토스 페이먼츠 API 의 버전", + "description": "사용 중인 토스 페이먼츠 API 의 버전." + }, + "paymentKey": { + "type": "string", + "title": "결제 내역의 식별자 번호", + "description": "결제 내역의 식별자 번호." + }, + "orderId": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키." + }, + "transactionKey": { + "type": "string", + "title": "거래 건에 대한 고유한 키 값", + "description": "거래 건에 대한 고유한 키 값.\n\n{@link paymentKey } 와 달리, 이를 사용할 일은 없더라." + }, + "orderName": { + "type": "string", + "title": "주문 이름", + "description": "주문 이름.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 발급한 주문명." + }, + "currency": { + "type": "string", + "title": "화폐 단위", + "description": "화폐 단위.\n\n현재 토스 페이먼츠는 KRW 만 사용 가능." + }, + "totalAmount": { + "type": "number", + "title": "총 결제 금액", + "description": "총 결제 금액." + }, + "balanceAmount": { + "type": "number", + "title": "취소할 수 있는 금액", + "description": "취소할 수 있는 금액." + }, + "suppliedAmount": { + "type": "number", + "title": "공급가액", + "description": "공급가액." + }, + "taxFreeAmount": { + "type": "number", + "title": "면세액", + "description": "면세액." + }, + "vat": { + "type": "number", + "title": "부가세", + "description": "부가세." + }, + "useEscrow": { + "type": "boolean", + "title": "에스크로 사용 여부", + "description": "에스크로 사용 여부." + }, + "cultureExpense": { + "type": "boolean", + "title": "문화비 지출 여부", + "description": "문화비 지출 여부.\n\n도석입, 공연 티켓, 박물관/미술관 입장권 등." + }, + "requestedAt": { + "type": "string", + "format": "date-time", + "title": "결제 요청 일시", + "description": "결제 요청 일시." + }, + "approvedAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "title": "결제 승인 일시", + "description": "결제 승인 일시." + }, + "cancels": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ITossPaymentCancel" + }, + "nullable": true, + "title": "결제 취소 내역", + "description": "결제 취소 내역." + }, + "cashReceipt": { + "$ref": "#/components/schemas/ITossCashReceipt.ISummary.Nullable", + "title": "현금 영수증 정보", + "description": "현금 영수증 정보." + } + }, + "nullable": false, + "required": [ + "transfer", + "method", + "type", + "status", + "mId", + "version", + "paymentKey", + "orderId", + "transactionKey", + "orderName", + "currency", + "totalAmount", + "balanceAmount", + "suppliedAmount", + "taxFreeAmount", + "vat", + "useEscrow", + "cultureExpense", + "requestedAt", + "approvedAt", + "cancels", + "cashReceipt" + ], + "description": "계좌 이체 결제 정보." + }, + "ITossTransferPayment.ITransfer": { + "type": "object", + "properties": { + "bank": { + "type": "string", + "title": "은행명", + "description": "은행명." + }, + "settlementStatus": { + "type": "string", + "enum": [ + "COMPLETED", + "INCOMPLETED" + ], + "title": "이체 상태", + "description": "이체 상태." + } + }, + "nullable": false, + "required": [ + "bank", + "settlementStatus" + ], + "description": "계좌 이체 정보." + }, + "ITossVirtualAccountPayment": { + "type": "object", + "properties": { + "secret": { + "type": "string", + "title": "가상 계좌로 결제할 때 전달되는 입금 콜백을 검증하기 위한 값", + "description": "가상 계좌로 결제할 때 전달되는 입금 콜백을 검증하기 위한 값." + }, + "virtualAccount": { + "$ref": "#/components/schemas/ITossVirtualAccountPayment.IVirtualAccount", + "title": "가상 계좌 정보", + "description": "가상 계좌 정보." + }, + "method": { + "type": "string", + "enum": [ + "가상계좌" + ], + "title": "결제 수단", + "description": "결제 수단." + }, + "type": { + "type": "string", + "enum": [ + "NORMAL" + ], + "title": "결제 타입", + "description": "결제 타입.\n\n - NORMAL: 일반 결제\n - BILLING: 미리 등록한 카드에 의한 간편 결제." + }, + "status": { + "type": "string", + "enum": [ + "READY", + "IN_PROGRESS", + "WAITING_FOR_DEPOSIT", + "DONE", + "CANCELED", + "PARTIAL_CANCELED", + "ABORTED", + "EXPIRED" + ], + "title": "결제 상태", + "description": "결제 상태.\n\n - READY\n - IN_PROGRESS\n - WAITING_FOR_DEPOSIT\n - DONE\n - CANCELED\n - PARTIAL_CANCELED\n - ABORTED\n - EXPIRED" + }, + "mId": { + "type": "string", + "title": "가맹점 ID", + "description": "가맹점 ID.\n\n현재 tosspayments 가 쓰임." + }, + "version": { + "type": "string", + "title": "사용 중인 토스 페이먼츠 API 의 버전", + "description": "사용 중인 토스 페이먼츠 API 의 버전." + }, + "paymentKey": { + "type": "string", + "title": "결제 내역의 식별자 번호", + "description": "결제 내역의 식별자 번호." + }, + "orderId": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키." + }, + "transactionKey": { + "type": "string", + "title": "거래 건에 대한 고유한 키 값", + "description": "거래 건에 대한 고유한 키 값.\n\n{@link paymentKey } 와 달리, 이를 사용할 일은 없더라." + }, + "orderName": { + "type": "string", + "title": "주문 이름", + "description": "주문 이름.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 발급한 주문명." + }, + "currency": { + "type": "string", + "title": "화폐 단위", + "description": "화폐 단위.\n\n현재 토스 페이먼츠는 KRW 만 사용 가능." + }, + "totalAmount": { + "type": "number", + "title": "총 결제 금액", + "description": "총 결제 금액." + }, + "balanceAmount": { + "type": "number", + "title": "취소할 수 있는 금액", + "description": "취소할 수 있는 금액." + }, + "suppliedAmount": { + "type": "number", + "title": "공급가액", + "description": "공급가액." + }, + "taxFreeAmount": { + "type": "number", + "title": "면세액", + "description": "면세액." + }, + "vat": { + "type": "number", + "title": "부가세", + "description": "부가세." + }, + "useEscrow": { + "type": "boolean", + "title": "에스크로 사용 여부", + "description": "에스크로 사용 여부." + }, + "cultureExpense": { + "type": "boolean", + "title": "문화비 지출 여부", + "description": "문화비 지출 여부.\n\n도석입, 공연 티켓, 박물관/미술관 입장권 등." + }, + "requestedAt": { + "type": "string", + "format": "date-time", + "title": "결제 요청 일시", + "description": "결제 요청 일시." + }, + "approvedAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "title": "결제 승인 일시", + "description": "결제 승인 일시." + }, + "cancels": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ITossPaymentCancel" + }, + "nullable": true, + "title": "결제 취소 내역", + "description": "결제 취소 내역." + }, + "cashReceipt": { + "$ref": "#/components/schemas/ITossCashReceipt.ISummary.Nullable", + "title": "현금 영수증 정보", + "description": "현금 영수증 정보." + } + }, + "nullable": false, + "required": [ + "secret", + "virtualAccount", + "method", + "type", + "status", + "mId", + "version", + "paymentKey", + "orderId", + "transactionKey", + "orderName", + "currency", + "totalAmount", + "balanceAmount", + "suppliedAmount", + "taxFreeAmount", + "vat", + "useEscrow", + "cultureExpense", + "requestedAt", + "approvedAt", + "cancels", + "cashReceipt" + ], + "description": "가상 계좌 결제 정보." + }, + "ITossVirtualAccountPayment.IVirtualAccount": { + "type": "object", + "properties": { + "accountNumber": { + "type": "string", + "title": "계좌 번호", + "description": "계좌 번호." + }, + "accountType": { + "type": "string", + "enum": [ + "일반", + "고정" + ], + "title": "가상 계좌 타입", + "description": "가상 계좌 타입." + }, + "bank": { + "type": "string", + "title": "은행명", + "description": "은행명." + }, + "customerName": { + "type": "string", + "title": "고객 이름", + "description": "고객 이름." + }, + "dueDate": { + "type": "string", + "format": "date", + "title": "입금 기한", + "description": "입금 기한." + }, + "expired": { + "type": "boolean", + "title": "가상 계좌 만료 여부", + "description": "가상 계좌 만료 여부." + }, + "settlementStatus": { + "type": "string", + "enum": [ + "COMPLETED", + "INCOMPLETED" + ], + "title": "정산 상태", + "description": "정산 상태." + }, + "refundStatus": { + "type": "string", + "enum": [ + "COMPLETED", + "NONE", + "FAILED", + "PENDING", + "PARTIAL_FAILED" + ], + "title": "환불 처리 상태", + "description": "환불 처리 상태.\n\n - NONE: 해당 없음\n - FAILED: 환불 실패\n - PENDING: 환불 처리중\n - PARTIAL_FAILED: 부분 환불 실패\n - COMPLETED: 환불 완료" + } + }, + "nullable": false, + "required": [ + "accountNumber", + "accountType", + "bank", + "customerName", + "dueDate", + "expired", + "settlementStatus", + "refundStatus" + ], + "description": "가상 계좌 정보." + }, + "IPaymentSource.IPassword": { + "type": "object", + "properties": { + "password": { + "type": "string", + "title": "레코드 조회를 위한 비밀번호 입력", + "description": "레코드 조회를 위한 비밀번호 입력." + } + }, + "nullable": false, + "required": [ + "password" + ], + "description": "비밀번호 입력 정보." + }, + "IPaymentHistory.ICreate": { + "type": "object", + "properties": { + "vendor": { + "$ref": "#/components/schemas/IPaymentVendoriamporttoss.payments", + "description": "벤더사 정보" + }, + "source": { + "$ref": "#/components/schemas/IPaymentSource", + "title": "결제의 근간이 된 원천 레코드 정보", + "description": "결제의 근간이 된 원천 레코드 정보." + }, + "price": { + "type": "number", + "minimum": 0, + "title": "결제되어야 할 총액", + "description": "결제되어야 할 총액.\n\n실 결제금액과 비교하여 이와 다를 시, 422 에러가 리턴됨." + }, + "password": { + "type": "string", + "title": "레코드 열람에 사용할 비밀번호 설정", + "description": "레코드 열람에 사용할 비밀번호 설정." + }, + "webhook_url": { + "type": "string", + "format": "uri", + "description": "결제 정보가 갱신되었을 때, 이를 수신할 URL" + } + }, + "nullable": false, + "required": [ + "vendor", + "source", + "price", + "password", + "webhook_url" + ], + "description": "결제 입력 정보.\n\nSDK 에서 받은 데이터를 취합하여 결제 진행 상황을 서버에 알려준다." + }, + "IPaymentVendoriamporttoss.payments": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "iamport", + "toss.payments" + ], + "title": "벤더사 식별자 코드", + "description": "벤더사 식별자 코드.\n\n아임포트의 경우에는 `iamport` 를, 토스의 경우에는 `toss.payments` 를 적어주면 된다." + }, + "store_id": { + "type": "string", + "title": "벤더사에 등록한 스토어 ID", + "description": "벤더사에 등록한 스토어 ID.\n\n결제 PG 사들은 서비스 주소가 다르거나, 또는 동일한 서비스이되 연결되는 백엔드 서버\n주소가 다르거든, 각기 다른 스토어 계정을 신청해 사용하라고 한다. 이는 요즘같이 MSA\n(Micro Service Architecture) 가 대세인 시대에 매우 불합리한 방식이기는 하지만, 어쨋든\n이러한 이유로 인하여, 한 회사 내지 단체가 복수의 스토어 ID 를 가지는 경우가 왕왕\n있다.\n\n때문에 `payments-server` 는, {@link IPaymentHistory 결제 내역}을 발행하거나\n{@link IPaymentReservation 간편 결제 수단}을 등록할 때 모두, 사용된 스토어의 ID\n를 반드시 기재하도록 하고 있다." + }, + "uid": { + "type": "string", + "title": "벤더사로부터 발급받은 식별자 번호", + "description": "벤더사로부터 발급받은 식별자 번호.\n\n결제 PG 사들이 제공하는 팝업창을 이용하여 결제를 진행하거나 혹은 간편 결제 수단을\n등록하거든, 결제 PG 사들은 해당 건에 대하여 별도의 식별자 번호를 발급한다.\n`IPaymentVendor.uid` 는 이처럼 결제 PG 사들이 발급해 준 식별자 번호를 기재하는\n속성이다.\n\n단 예외가 하나 있어, 아임포트는 간편 결제 카드 등록 건에 대하여 별도의 식별자 번호를\n부여하지 않고, 귀하의 서비스에서 발급해 준 ID 를 그대로 사용한다. 때문에 아임포트를\n통한 간편 결제 카드 등록의 건만 예외적으로, `IPaymentVendor.uid` 에\n{@link IPaymentSource.id } 를 동일하게 할당해주어야 한다." + } + }, + "nullable": false, + "required": [ + "code", + "store_id", + "uid" + ], + "description": "벤더사 정보.\n\n`IPaymentVendor` 결제 PG 벤더사에 관련된 정보를 형상화한 자료구조 인터페이스이다." + }, + "IPaymentCancelHistory.ICreate": { + "type": "object", + "properties": { + "source": { + "$ref": "#/components/schemas/IPaymentSource", + "title": "결제의 근간이 된 원천 레코드 정보", + "description": "결제의 근간이 된 원천 레코드 정보." + }, + "password": { + "type": "string", + "title": "결제 이력에 대한 비밀번호 입력", + "description": "결제 이력에 대한 비밀번호 입력." + }, + "price": { + "type": "number", + "minimum": 0, + "title": "환불 금액", + "description": "환불 금액." + }, + "reason": { + "type": "string", + "title": "결제 취소 사유", + "description": "결제 취소 사유." + }, + "account": { + "$ref": "#/components/schemas/IPaymentCancelHistory.IBankAccount.Nullable", + "title": "환불 계좌 정보", + "description": "환불 계좌 정보.\n\n가상 계좌로 입금한 경우, 결제 취소시, 이를 환불받을 계좌가 필요함.\n\n단, 이 정보는 본 결제 시스템에 저장하지 아니함." + } + }, + "nullable": false, + "required": [ + "source", + "password", + "price", + "reason", + "account" + ], + "description": "결제 취소 입력 정보." + }, + "IPaymentCancelHistory.IBankAccount.Nullable": { + "type": "object", + "properties": { + "bank": { + "type": "string", + "title": "은행 이름", + "description": "은행 이름." + }, + "account": { + "type": "string", + "title": "계좌번호", + "description": "계좌번호." + }, + "holder": { + "type": "string", + "title": "예금주", + "description": "예금주." + }, + "mobile": { + "type": "string", + "title": "연락처, 핸드폰 번호", + "description": "연락처, 핸드폰 번호." + } + }, + "nullable": true, + "required": [ + "bank", + "account", + "holder", + "mobile" + ], + "description": "은행 계좌 정보.\n\n가상 계좌로 입금한 경우, 결제 취소시, 이를 환불받을 계좌가 필요함.\n\n단, 이 정보는 본 결제 시스템에 저장하지 아니함." + }, + "IPaymentReservation": { + "oneOf": [ + { + "$ref": "#/components/schemas/IPaymentReservation.IamportType" + }, + { + "$ref": "#/components/schemas/IPaymentReservation.TossType" + } + ], + "description": "간편 결제 수단 정보.\n\n`IPaymentReservation` 은 간편 결제 수단을 형상화한 자료구조이자 유니언 타입의\n인터페이스로써, if condition 을 통하여 {@link IPaymentReservation.vendor_code } 값을\n특정하면, 파생 타입이 자동으로 다운 캐스팅 된다.\n\n```typescript\nif (history.vendor_code === \"toss.payments\")\n history.data.billingKey; // history.data be ITossBilling\n```" + }, + "IPaymentReservation.IamportType": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "title": "Primary Key", + "description": "Primary Key." + }, + "vendor_code": { + "type": "string", + "enum": [ + "iamport" + ], + "title": "벤더사 코드", + "description": "벤더사 코드.\n\n{@link IPaymentVendor.code }와 완전히 동일한 값이되, 단지 union type\nspecialization 을 위해 중복 표기하였을 뿐이다. If else condition 을 통하여\n{@link IPaymentReservation.data }의 타입을 특정할 수 있다." + }, + "vendor": { + "$ref": "#/components/schemas/IPaymentVendoriamport", + "title": "벤더사", + "description": "벤더사." + }, + "source": { + "$ref": "#/components/schemas/IPaymentSource", + "title": "대상 액터의 참조 정보", + "description": "대상 액터의 참조 정보." + }, + "title": { + "type": "string", + "title": "제목", + "description": "제목." + }, + "data": { + "$ref": "#/components/schemas/IIamportSubscription", + "title": "벤더사 데이터", + "description": "벤더사 데이터." + }, + "created_at": { + "type": "string", + "format": "date-time", + "title": "레코드 생성 일시", + "description": "레코드 생성 일시." + } + }, + "nullable": false, + "required": [ + "id", + "vendor_code", + "vendor", + "source", + "title", + "data", + "created_at" + ], + "description": "아임 포트의 간편 결제 카드 정보." + }, + "IIamportSubscription": { + "type": "object", + "properties": { + "pg_provider": { + "type": "string" + }, + "pg_id": { + "type": "string" + }, + "card_name": { + "type": "string" + }, + "card_code": { + "type": "string" + }, + "card_number": { + "type": "string" + }, + "card_type": { + "type": "string" + }, + "customer_name": { + "type": "string", + "nullable": true + }, + "customer_tel": { + "type": "string", + "nullable": true + }, + "customer_email": { + "type": "string", + "nullable": true + }, + "customer_addr": { + "type": "string", + "nullable": true + }, + "customer_postcode": { + "type": "string", + "nullable": true + }, + "inserted": { + "type": "number" + }, + "updated": { + "type": "number" + }, + "customer_uid": { + "type": "string", + "title": "고객 식별자 키", + "description": "고객 식별자 키.\n\n아임포트가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키.\n\n다만 고객이라기보다 실제로는 카드의 식별자 키로 써야함." + } + }, + "nullable": false, + "required": [ + "pg_provider", + "pg_id", + "card_name", + "card_code", + "card_number", + "card_type", + "customer_name", + "customer_tel", + "customer_email", + "customer_addr", + "customer_postcode", + "inserted", + "updated", + "customer_uid" + ], + "description": "간편 결제 카드 정보." + }, + "IPaymentReservation.TossType": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "title": "Primary Key", + "description": "Primary Key." + }, + "vendor_code": { + "type": "string", + "enum": [ + "toss.payments" + ], + "title": "벤더사 코드", + "description": "벤더사 코드.\n\n{@link IPaymentVendor.code }와 완전히 동일한 값이되, 단지 union type\nspecialization 을 위해 중복 표기하였을 뿐이다. If else condition 을 통하여\n{@link IPaymentReservation.data }의 타입을 특정할 수 있다." + }, + "vendor": { + "$ref": "#/components/schemas/IPaymentVendortoss.payments", + "title": "벤더사", + "description": "벤더사." + }, + "source": { + "$ref": "#/components/schemas/IPaymentSource", + "title": "대상 액터의 참조 정보", + "description": "대상 액터의 참조 정보." + }, + "title": { + "type": "string", + "title": "제목", + "description": "제목." + }, + "data": { + "$ref": "#/components/schemas/ITossBilling", + "title": "벤더사 데이터", + "description": "벤더사 데이터." + }, + "created_at": { + "type": "string", + "format": "date-time", + "title": "레코드 생성 일시", + "description": "레코드 생성 일시." + } + }, + "nullable": false, + "required": [ + "id", + "vendor_code", + "vendor", + "source", + "title", + "data", + "created_at" + ], + "description": "토스의 간편 결제 수단 정보." + }, + "ITossBilling": { + "type": "object", + "properties": { + "mId": { + "type": "string", + "title": "가맹점 ID", + "description": "가맹점 ID.\n\n현재 tosspayments 가 쓰임." + }, + "billingKey": { + "type": "string", + "title": "{@link ITossBilling } 의 식별자 키", + "description": "{@link ITossBilling } 의 식별자 키." + }, + "method": { + "type": "string", + "enum": [ + "카드" + ], + "title": "결제 수단", + "description": "결제 수단." + }, + "cardCompany": { + "type": "string", + "title": "카드사 이름", + "description": "카드사 이름." + }, + "cardNumber": { + "type": "string", + "pattern": "[0-9]{16}", + "title": "카드 번호", + "description": "카드 번호." + }, + "authenticatedAt": { + "type": "string", + "format": "date-time", + "title": "인증 일시", + "description": "인증 일시." + }, + "customerKey": { + "type": "string", + "title": "고객 식별자 키", + "description": "고객 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키." + } + }, + "nullable": false, + "required": [ + "mId", + "billingKey", + "method", + "cardCompany", + "cardNumber", + "authenticatedAt", + "customerKey" + ], + "description": "간편 결제 등록 수단 정보.\n\n`ITossBilling` 은 간편 결제 등록 수단을 형상화한 자료구조 인터페이스로써, 고객이 자신의\n신용 카드를 서버에 등록해두고, 매번 결제가 필요할 때마다 카드 정보를 반복 입려하는 일\n없이 간편하게 결제를 진행하고자 할 때 사용한다." + }, + "IPaymentReservation.ICreate": { + "type": "object", + "properties": { + "vendor": { + "$ref": "#/components/schemas/IPaymentVendorIPaymentVendor.Code", + "title": "벤더사 정보", + "description": "벤더사 정보." + }, + "source": { + "$ref": "#/components/schemas/IPaymentSource", + "title": "원천 레코드 정보", + "description": "원천 레코드 정보." + }, + "title": { + "type": "string", + "description": "제목" + }, + "password": { + "type": "string", + "title": "간편결제 비밀번호", + "description": "간편결제 비밀번호.\n\n주의할 점은 카드 비밀번호가 아니라는 것." + } + }, + "nullable": false, + "required": [ + "vendor", + "source", + "title", + "password" + ], + "description": "간편 결제 수단 등록 정보.\n\n결제사의 팝업 창로부터 전달받은 식별자 정보를 취합하여 전달한다.\n\n참고로 아임포트의 경우 간편 결제로 등록한 카드에 자체 식별자 번호를 부여하지 않는다.\n따라서 귀하의 서비스가 발행한 식별자 ID 가 곧, 해당 간편 결제 수단의 유일무이한\n식별자ㅏ 되니, 이를 {@link IPaymentVendor.uid } 와 {@link IPaymentSource.id } 에\n모두 동일하게 할당해주면 된다." + }, + "IPaymentVendorIPaymentVendor.Code": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "iamport", + "toss.payments" + ], + "title": "벤더사 식별자 코드", + "description": "벤더사 식별자 코드.\n\n아임포트의 경우에는 `iamport` 를, 토스의 경우에는 `toss.payments` 를 적어주면 된다." + }, + "store_id": { + "type": "string", + "title": "벤더사에 등록한 스토어 ID", + "description": "벤더사에 등록한 스토어 ID.\n\n결제 PG 사들은 서비스 주소가 다르거나, 또는 동일한 서비스이되 연결되는 백엔드 서버\n주소가 다르거든, 각기 다른 스토어 계정을 신청해 사용하라고 한다. 이는 요즘같이 MSA\n(Micro Service Architecture) 가 대세인 시대에 매우 불합리한 방식이기는 하지만, 어쨋든\n이러한 이유로 인하여, 한 회사 내지 단체가 복수의 스토어 ID 를 가지는 경우가 왕왕\n있다.\n\n때문에 `payments-server` 는, {@link IPaymentHistory 결제 내역}을 발행하거나\n{@link IPaymentReservation 간편 결제 수단}을 등록할 때 모두, 사용된 스토어의 ID\n를 반드시 기재하도록 하고 있다." + }, + "uid": { + "type": "string", + "title": "벤더사로부터 발급받은 식별자 번호", + "description": "벤더사로부터 발급받은 식별자 번호.\n\n결제 PG 사들이 제공하는 팝업창을 이용하여 결제를 진행하거나 혹은 간편 결제 수단을\n등록하거든, 결제 PG 사들은 해당 건에 대하여 별도의 식별자 번호를 발급한다.\n`IPaymentVendor.uid` 는 이처럼 결제 PG 사들이 발급해 준 식별자 번호를 기재하는\n속성이다.\n\n단 예외가 하나 있어, 아임포트는 간편 결제 카드 등록 건에 대하여 별도의 식별자 번호를\n부여하지 않고, 귀하의 서비스에서 발급해 준 ID 를 그대로 사용한다. 때문에 아임포트를\n통한 간편 결제 카드 등록의 건만 예외적으로, `IPaymentVendor.uid` 에\n{@link IPaymentSource.id } 를 동일하게 할당해주어야 한다." + } + }, + "nullable": false, + "required": [ + "code", + "store_id", + "uid" + ], + "description": "벤더사 정보.\n\n`IPaymentVendor` 결제 PG 벤더사에 관련된 정보를 형상화한 자료구조 인터페이스이다." + }, + "IIamportPayment.IWebhook": { + "type": "object", + "properties": { + "imp_uid": { + "type": "string", + "title": "결제 정보 {@link IIamportPayment } 의 식별자 키", + "description": "결제 정보 {@link IIamportPayment } 의 식별자 키." + }, + "merchant_uid": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n아임포트 서버가 아닌, 이를 사용하는 서비스가 자체적으로 발급하고 관리한다." + }, + "status": { + "type": "string", + "enum": [ + "paid", + "ready", + "failed", + "cancelled" + ], + "title": "현재 상태", + "description": "현재 상태." + } + }, + "nullable": false, + "required": [ + "imp_uid", + "merchant_uid", + "status" + ], + "description": "웹훅 데이터." + } + } + } +} \ No newline at end of file diff --git a/packages/payment-backend/nestia.config.ts b/packages/payment-backend/nestia.config.ts index 22b852d..49ecc13 100644 --- a/packages/payment-backend/nestia.config.ts +++ b/packages/payment-backend/nestia.config.ts @@ -1,14 +1,17 @@ import type { INestiaConfig } from "@nestia/sdk"; import { NestFactory } from "@nestjs/core"; +import { FastifyAdapter } from "@nestjs/platform-fastify"; import { PaymentModule } from "./src/PaymentModule"; const NESTIA_CONFIG: INestiaConfig = { - input: () => NestFactory.create(PaymentModule), + input: () => NestFactory.create(PaymentModule, new FastifyAdapter()), output: "src/api", distribute: "../payment-api", swagger: { output: "../payment-api/swagger.json", + beautify: true, }, + primitive: false, }; export default NESTIA_CONFIG; diff --git a/packages/payment-backend/package.json b/packages/payment-backend/package.json index ef279dc..8ecf8fd 100644 --- a/packages/payment-backend/package.json +++ b/packages/payment-backend/package.json @@ -1,6 +1,6 @@ { "name": "@samchon/payment-backend", - "version": "6.0.5", + "version": "6.0.6", "description": "Payment Backend Server", "main": "lib/index.js", "typings": "lib/index.d.ts", @@ -37,8 +37,8 @@ }, "homepage": "https://github.com/samchon/payments", "devDependencies": { - "@nestia/fetcher": "^2.5.1", - "@nestia/sdk": "^2.5.1", + "@nestia/fetcher": "^2.5.8", + "@nestia/sdk": "^2.5.8", "@types/atob": "^2.1.2", "@types/bcryptjs": "^2.4.4", "@types/btoa": "^1.2.3", @@ -53,12 +53,12 @@ "cli": "^1.0.1", "copy-webpack-plugin": "^11.0.0", "copyfiles": "^2.4.1", - "iamport-server-api": "^6.0.5", + "iamport-server-api": "^6.0.6", "nestia": "^5.0.3", "pm2": "^4.5.6", "rimraf": "^3.0.2", "sloc": "^0.2.1", - "toss-payments-server-api": "^6.0.5", + "toss-payments-server-api": "^6.0.6", "ts-loader": "^9.5.0", "ts-node": "^10.9.1", "ts-patch": "^3.1.1", @@ -69,7 +69,7 @@ "write-file-webpack-plugin": "^4.5.1" }, "dependencies": { - "@nestia/core": "^2.5.1", + "@nestia/core": "^2.5.8", "@nestia/e2e": "^0.4.1", "@nestjs/common": "^10.2.8", "@nestjs/core": "^10.2.8", @@ -81,8 +81,8 @@ "commander": "10.0.0", "dotenv": "^16.3.1", "dotenv-expand": "^10.0.0", - "fake-iamport-server": "^6.0.5", - "fake-toss-payments-server": "^6.0.5", + "fake-iamport-server": "^6.0.6", + "fake-toss-payments-server": "^6.0.6", "fastify": "^4.24.3", "git-last-commit": "^1.0.0", "inquirer": "^8.2.5", @@ -92,7 +92,7 @@ "serialize-error": "^4.1.0", "source-map-support": "^0.5.19", "tstl": "^2.5.13", - "typia": "^5.4.1", + "typia": "^5.4.9", "uuid": "^9.0.1" }, "files": [ diff --git a/packages/payment-backend/src/api/functional/monitors/performance/index.ts b/packages/payment-backend/src/api/functional/monitors/performance/index.ts index 012e349..cd51e9e 100644 --- a/packages/payment-backend/src/api/functional/monitors/performance/index.ts +++ b/packages/payment-backend/src/api/functional/monitors/performance/index.ts @@ -4,7 +4,7 @@ * @nestia Generated by Nestia - https://github.com/samchon/nestia */ //================================================================ -import type { IConnection, Primitive } from "@nestia/fetcher"; +import type { IConnection } from "@nestia/fetcher"; import { EncryptedFetcher } from "@nestia/fetcher/lib/EncryptedFetcher"; import type { IPerformance } from "../../../structures/monitors/IPerformance"; @@ -21,7 +21,7 @@ export async function get(connection: IConnection): Promise { }); } export namespace get { - export type Output = Primitive; + export type Output = IPerformance; export const METADATA = { method: "GET", diff --git a/packages/payment-backend/src/api/functional/monitors/system/index.ts b/packages/payment-backend/src/api/functional/monitors/system/index.ts index 99122c4..0de3faa 100644 --- a/packages/payment-backend/src/api/functional/monitors/system/index.ts +++ b/packages/payment-backend/src/api/functional/monitors/system/index.ts @@ -4,7 +4,7 @@ * @nestia Generated by Nestia - https://github.com/samchon/nestia */ //================================================================ -import type { IConnection, Primitive } from "@nestia/fetcher"; +import type { IConnection } from "@nestia/fetcher"; import { EncryptedFetcher } from "@nestia/fetcher/lib/EncryptedFetcher"; import type { ISystem } from "../../../structures/monitors/ISystem"; @@ -21,7 +21,7 @@ export async function get(connection: IConnection): Promise { }); } export namespace get { - export type Output = Primitive; + export type Output = ISystem; export const METADATA = { method: "GET", diff --git a/packages/payment-backend/src/api/functional/payments/histories/index.ts b/packages/payment-backend/src/api/functional/payments/histories/index.ts index a1ccfe2..6a8f058 100644 --- a/packages/payment-backend/src/api/functional/payments/histories/index.ts +++ b/packages/payment-backend/src/api/functional/payments/histories/index.ts @@ -4,7 +4,7 @@ * @nestia Generated by Nestia - https://github.com/samchon/nestia */ //================================================================ -import type { IConnection, Primitive } from "@nestia/fetcher"; +import type { IConnection } from "@nestia/fetcher"; import { EncryptedFetcher } from "@nestia/fetcher/lib/EncryptedFetcher"; import type { Format } from "typia/lib/tags/Format"; @@ -25,7 +25,7 @@ import type { IPaymentSource } from "../../../structures/payments/IPaymentSource */ export async function get( connection: IConnection, - input: get.Input, + input: IPaymentSource.IAccessor, ): Promise { return EncryptedFetcher.fetch( { @@ -43,8 +43,8 @@ export async function get( ); } export namespace get { - export type Input = Primitive; - export type Output = Primitive; + export type Input = IPaymentSource.IAccessor; + export type Output = IPaymentHistory; export const METADATA = { method: "PATCH", @@ -78,7 +78,7 @@ export namespace get { export async function at( connection: IConnection, id: string & Format<"uuid">, - input: at.Input, + input: IPaymentSource.IPassword, ): Promise { return EncryptedFetcher.fetch( { @@ -96,8 +96,8 @@ export async function at( ); } export namespace at { - export type Input = Primitive; - export type Output = Primitive; + export type Input = IPaymentSource.IPassword; + export type Output = IPaymentHistory; export const METADATA = { method: "PATCH", @@ -130,7 +130,7 @@ export namespace at { */ export async function create( connection: IConnection, - input: create.Input, + input: IPaymentHistory.ICreate, ): Promise { return EncryptedFetcher.fetch( { @@ -148,8 +148,8 @@ export async function create( ); } export namespace create { - export type Input = Primitive; - export type Output = Primitive; + export type Input = IPaymentHistory.ICreate; + export type Output = IPaymentHistory; export const METADATA = { method: "POST", @@ -180,7 +180,7 @@ export namespace create { */ export async function cancel( connection: IConnection, - input: cancel.Input, + input: IPaymentCancelHistory.ICreate, ): Promise { return EncryptedFetcher.fetch( { @@ -198,8 +198,8 @@ export async function cancel( ); } export namespace cancel { - export type Input = Primitive; - export type Output = Primitive; + export type Input = IPaymentCancelHistory.ICreate; + export type Output = IPaymentHistory; export const METADATA = { method: "PUT", diff --git a/packages/payment-backend/src/api/functional/payments/internal/index.ts b/packages/payment-backend/src/api/functional/payments/internal/index.ts index 098c231..81b0c24 100644 --- a/packages/payment-backend/src/api/functional/payments/internal/index.ts +++ b/packages/payment-backend/src/api/functional/payments/internal/index.ts @@ -4,7 +4,7 @@ * @nestia Generated by Nestia - https://github.com/samchon/nestia */ //================================================================ -import type { IConnection, Primitive } from "@nestia/fetcher"; +import type { IConnection } from "@nestia/fetcher"; import { EncryptedFetcher } from "@nestia/fetcher/lib/EncryptedFetcher"; import type { IPaymentWebhookHistory } from "../../../structures/payments/IPaymentWebhookHistory"; @@ -19,7 +19,7 @@ import type { IPaymentWebhookHistory } from "../../../structures/payments/IPayme */ export async function webhook( connection: IConnection, - input: webhook.Input, + input: IPaymentWebhookHistory, ): Promise { return EncryptedFetcher.fetch( { @@ -37,7 +37,7 @@ export async function webhook( ); } export namespace webhook { - export type Input = Primitive; + export type Input = IPaymentWebhookHistory; export const METADATA = { method: "POST", diff --git a/packages/payment-backend/src/api/functional/payments/reservations/index.ts b/packages/payment-backend/src/api/functional/payments/reservations/index.ts index 654947e..58b864e 100644 --- a/packages/payment-backend/src/api/functional/payments/reservations/index.ts +++ b/packages/payment-backend/src/api/functional/payments/reservations/index.ts @@ -4,7 +4,7 @@ * @nestia Generated by Nestia - https://github.com/samchon/nestia */ //================================================================ -import type { IConnection, Primitive } from "@nestia/fetcher"; +import type { IConnection } from "@nestia/fetcher"; import { EncryptedFetcher } from "@nestia/fetcher/lib/EncryptedFetcher"; import type { Format } from "typia/lib/tags/Format"; @@ -23,7 +23,7 @@ import type { IPaymentSource } from "../../../structures/payments/IPaymentSource */ export async function get( connection: IConnection, - input: get.Input, + input: IPaymentSource.IAccessor, ): Promise { return EncryptedFetcher.fetch( { @@ -41,8 +41,8 @@ export async function get( ); } export namespace get { - export type Input = Primitive; - export type Output = Primitive; + export type Input = IPaymentSource.IAccessor; + export type Output = IPaymentReservation; export const METADATA = { method: "PATCH", @@ -75,7 +75,7 @@ export namespace get { export async function at( connection: IConnection, id: string & Format<"uuid">, - input: at.Input, + input: IPaymentSource.IPassword, ): Promise { return EncryptedFetcher.fetch( { @@ -93,8 +93,8 @@ export async function at( ); } export namespace at { - export type Input = Primitive; - export type Output = Primitive; + export type Input = IPaymentSource.IPassword; + export type Output = IPaymentReservation; export const METADATA = { method: "PATCH", @@ -126,7 +126,7 @@ export namespace at { */ export async function create( connection: IConnection, - input: create.Input, + input: IPaymentReservation.ICreate, ): Promise { return EncryptedFetcher.fetch( { @@ -144,8 +144,8 @@ export async function create( ); } export namespace create { - export type Input = Primitive; - export type Output = Primitive; + export type Input = IPaymentReservation.ICreate; + export type Output = IPaymentReservation; export const METADATA = { method: "POST", diff --git a/packages/payment-backend/src/api/functional/payments/webhooks/index.ts b/packages/payment-backend/src/api/functional/payments/webhooks/index.ts index 3a70e2f..cc8bd65 100644 --- a/packages/payment-backend/src/api/functional/payments/webhooks/index.ts +++ b/packages/payment-backend/src/api/functional/payments/webhooks/index.ts @@ -4,7 +4,7 @@ * @nestia Generated by Nestia - https://github.com/samchon/nestia */ //================================================================ -import type { IConnection, Primitive } from "@nestia/fetcher"; +import type { IConnection } from "@nestia/fetcher"; import { PlainFetcher } from "@nestia/fetcher/lib/PlainFetcher"; import type { IIamportPayment } from "iamport-server-api/lib/structures/IIamportPayment"; import type { ITossPaymentWebhook } from "toss-payments-server-api/lib/structures/ITossPaymentWebhook"; @@ -19,7 +19,7 @@ import type { ITossPaymentWebhook } from "toss-payments-server-api/lib/structure */ export async function iamport( connection: IConnection, - input: iamport.Input, + input: IIamportPayment.IWebhook, ): Promise { return PlainFetcher.fetch( { @@ -37,7 +37,7 @@ export async function iamport( ); } export namespace iamport { - export type Input = Primitive; + export type Input = IIamportPayment.IWebhook; export const METADATA = { method: "POST", @@ -66,7 +66,7 @@ export namespace iamport { */ export async function toss( connection: IConnection, - input: toss.Input, + input: ITossPaymentWebhook, ): Promise { return PlainFetcher.fetch( { @@ -84,7 +84,7 @@ export async function toss( ); } export namespace toss { - export type Input = Primitive; + export type Input = ITossPaymentWebhook; export const METADATA = { method: "POST", diff --git a/packages/toss-payments-server-api/package.json b/packages/toss-payments-server-api/package.json index 09db040..fe2e989 100644 --- a/packages/toss-payments-server-api/package.json +++ b/packages/toss-payments-server-api/package.json @@ -1,6 +1,6 @@ { "name": "toss-payments-server-api", - "version": "6.0.5", + "version": "6.0.6", "description": "API for Toss Payments Server", "main": "lib/index.js", "typings": "lib/index.d.ts", @@ -34,7 +34,7 @@ "typescript": "^5.3.2" }, "dependencies": { - "@nestia/fetcher": "^2.5.1", - "typia": "^5.4.1" + "@nestia/fetcher": "^2.5.8", + "typia": "^5.4.9" } } \ No newline at end of file diff --git a/packages/toss-payments-server-api/swagger.json b/packages/toss-payments-server-api/swagger.json index f8d0345..c71c085 100644 --- a/packages/toss-payments-server-api/swagger.json +++ b/packages/toss-payments-server-api/swagger.json @@ -1 +1,2361 @@ -{"openapi":"3.0.1","servers":[{"url":"http://localhost:30771","description":"fake"},{"url":"https://api.tosspayments.com","description":"real"}],"info":{"title":"Toss Payments API","description":"Built by [fake-toss-payments-server](https://github.com/samchon/payments/tree/master/packages/toss-payments-server-api) with [nestia](https://github.com/samchon/nestia)","version":"6.0.5","license":{"name":"MIT"}},"paths":{"/v1/billing/authorizations/card":{"post":{"tags":[],"parameters":[],"requestBody":{"description":"간편 결제 카드 등록 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITossBilling.ICreate"}}},"required":true},"responses":{"201":{"description":"간편 결제 카드 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITossBilling"}}}}},"summary":"간편 결제 카드 등록하기","description":"간편 결제 카드 등록하기.\n\n`billing.authorizations.card.create` 는 고객이 자신의 신록 카드를 서버에 등록해두고,\n매번 결제가 필요할 때마다 카드 정보를 반복 입력하는 일 없이 간편하게 결제를\n진행하고자 할 때, 호출되는 API 함수이다.\n\n참고로 `billing.authorizations.card.create` 는 클라이언트 어플리케이션이 토스\n페이먼츠가 제공하는 간편 결제 카드 등록 창을 사용하는 경우, 귀하의 백엔드 서버가 이를\n실 서비스에서 호출하는 일은 없을 것이다. 다만, 고객이 간편 결제 카드를 등록하는\n상황을 시뮬레이션하기 위하여, 테스트 자동화 프로그램 수준에서 사용될 수는 있다.","security":[{"basic":[]}]}},"/v1/billing/authorizations/{billingKey}":{"post":{"tags":[],"parameters":[{"name":"billingKey","in":"path","schema":{"type":"string"},"description":"대상 정보의 ","required":true}],"requestBody":{"description":"고객 식별자 키","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITossBilling.ICustomerKey"}}},"required":true},"responses":{"201":{"description":"간편 결제 수단 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITossBilling"}}}}},"summary":"간편 결제로 등록한 수단 조회하기","description":"간편 결제로 등록한 수단 조회하기.\n\n`billing.authorizations.at` 은 고객이 간편 결제를 위하여 토스 페이먼츠 서버에\n등록한 결제 수단을 조회하는 함수이다.\n\n주로 클라이언트 어플리케이션이 토스 페이먼츠가 자체적으로 제공하는 결제 창을 사용하는\n경우, 그래서 프론트 어플리케이션이 귀하의 백엔드 서버에 `billingKey` 와` customerKey`\n만을 전달해주어, 상세 간편 결제 수단 정보가 필요할 때 사용한다.","security":[{"basic":[]}]}},"/v1/billing/{billingKey}":{"post":{"tags":[],"parameters":[{"name":"billingKey","in":"path","schema":{"type":"string"},"description":"간편 결제에 등록한 수단의 ","required":true}],"requestBody":{"description":"주문 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITossBilling.IPaymentStore"}}},"required":true},"responses":{"201":{"description":"결제 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITossPayment"}}}}},"summary":"간편 결제에 등록한 수단으로 결제하기","description":"간편 결제에 등록한 수단으로 결제하기.\n\n`billing.pay` 는 간편 결제에 등록한 수단으로 결제를 진행하고자 할 때 호출하는 API\n함수이다.\n\n그리고 `billing.pay` 는 결제 수단 중 유일하게, 클라이언트 어플리케이션이 토스\n페이먼츠가 제공하는 결제 창을 사용할 수 없어, 귀하의 백엔드 서버가 토스 페이먼츠의\nAPI 함수를 직접 호출해야 하는 경우에 해당한다. 따라서 간편 결제에 관련하여 토스\n페이먼츠와 연동하는 백엔드 서버 및 프론트 어플리케이션을 개발할 때, 반드시 이 상황에\n대한 별도의 설계 및 개발이 필요하니, 이 점을 염두에 두기 바란다.\n\n더하여 `billing.pay` 는 철저히 귀사 백엔드 서버의 판단 아래 호출되는 API 함수인지라,\n이를 통하여 이루어지는 결제는 일절 {@link payments.approve } 가 필요 없다. 다만\n`billing.pay` 는 이처럼 부차적인 승인 과정 필요없이 그 즉시로 결제가 완성되니, 이를\n호출하는 상황에 대하여 세심히 주의를 기울일 필요가 있다","security":[{"basic":[]}]}},"/v1/cash-receipts":{"post":{"tags":[],"parameters":[],"requestBody":{"description":"입력 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITossCashReceipt.ICreate"}}},"required":true},"responses":{"201":{"description":"현금 영수증 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITossCashReceipt"}}}}},"summary":"현금 영수증 발행하기","description":"현금 영수증 발행하기.","security":[{"basic":[]}]}},"/v1/cash-receipts/{receiptKey}/cancel":{"post":{"tags":[],"parameters":[{"name":"receiptKey","in":"path","schema":{"type":"string"},"description":"현금 영수증의 ","required":true}],"requestBody":{"description":"취소 입력 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITossCashReceipt.ICancel"}}},"required":true},"responses":{"201":{"description":"취소된 현금 영수증 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITossCashReceipt"}}}}},"summary":"현금 영수증 취소하기","description":"현금 영수증 취소하기.","security":[{"basic":[]}]}},"/internal/webhook":{"post":{"tags":[],"parameters":[],"requestBody":{"description":"웹훅 이벤트 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITossPaymentWebhook"}}},"required":true},"responses":{"201":{"description":""}},"summary":"웹훅 이벤트 더미 리스너","description":"웹훅 이벤트 더미 리스너.\n\n`internal.webhook` 은 실제 토스 페이먼츠의 결제 서버에는 존재하지 않는 API 로써,\n`fake-toss-payments-server` 의 {@link Configuration.WEBHOOK_URL } 에 아무런 URL 을\n설정하지 않으면, `fake-toss-payments-server` 로부터 발생하는 모든 종류의 웹훅\n이벤트는 이 곳으로 전달되어 무의미하게 사라진다.\n\n따라서 `fake-toss-payments-server` 를 사용하여 토스 페이먼츠 서버와의 연동을 미리\n검증코자 할 때는, 반드시 {@link Configuration.WEBHOOK_URL } 를 설정하여 웹훅\n이벤트가 귀하의 백엔드 서버로 제대로 전달되도록 하자."}},"/internal/{paymentKey}/deposit":{"put":{"tags":[],"parameters":[{"name":"paymentKey","in":"path","schema":{"type":"string"},"description":"대상 가상 계좌 결제 정보의 ","required":true}],"responses":{"201":{"description":"입금 완료된 가상 꼐좌 결제 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITossPayment"}}}}},"summary":"가상 계좌에 입금하기","description":"가상 계좌에 입금하기.\n\n`internal.virtual_accounts.deposit` 은 실제 토스 페이먼츠의 결제 서버에는 존재하지\n않는 API 로써, 가상 계좌 결제를 신청한 고객이, 이후 가상 계좌에 목표 금액을 입금하는\n상황을 시뮬레이션할 수 있는 함수이다.\n\n즉 `internal.virtual_accounts.deposit` 는 고객이 스스로에게 가상으로 발급된 계좌에\n입금을 하고, 그에 따라 토스 페이먼츠 서버에서 webhook 이벤트가 발생하여 이를 귀하의\n백엔드 서버로 전송하는 일련의 상황을 테스트하기 위한 함수인 셈이다.","security":[{"basic":[]}]}},"/v1/payments/{paymentKey}":{"get":{"tags":[],"parameters":[{"name":"paymentKey","in":"path","schema":{"type":"string"},"description":"결제 정보의 ","required":true}],"responses":{"200":{"description":"결제 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITossPayment"}}}}},"summary":"결제 정보 조회하기","description":"결제 정보 조회하기.\n\n`payments.at` 은 결제 정보를 조회하는 함수이다.\n\n주로 클라이언트 어플리케이션이 토스 페이먼츠가 자체적으로 제공하는 결제 창을 사용하는\n경우, 그래서 프론트 어플리케이션이 귀하의 백엔드 서버에 `paymentKey` 등 극히 일부의\n식별자 정보만을 전달해주어, 상세 결제 정보가 필요할 때 사용한다.\n\n참고로 토스 페이먼츠는 다른 결제 PG 사들과 다르게, 클라이언트 어플리케이션에서 토스\n페이먼츠의 결제 창을 이용하여 진행한 결제가 바로 확정되는 것은 아니다. 귀사의 백엔드\n서버가 현재의 `payments.at` 을 통하여 해당 결제 정보를 확인하고, {@link approve } 를\n호출하여 직접 승인하기 전까지, 해당 결제는 확정되지 않으니, 이 점에 유의하기 바란다."},"post":{"tags":[],"parameters":[{"name":"paymentKey","in":"path","schema":{"type":"string"},"description":"대상 결제의 ","required":true}],"requestBody":{"description":"주문 정보 확인","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITossPayment.IApproval"}}},"required":true},"responses":{"201":{"description":"승인된 결제 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITossPayment"}}}}},"summary":"결제 승인하기","description":"결제 승인하기.\n\n토스 페이먼츠는 귀사의 백엔드에서 일어난 결제가 아닌 프론트 어플리케이션의 결제 창에서\n이루어진 결제의 경우, 해당 서비스으 백엔드 서버로부터 결제를 승인받기 전까지, 이를\n확정하지 않는다. `payments.approve` 는 바로 이러한 상황에서, 해당 결제를 승인해주는\n함수이다.\n\n만일 귀하가 `fake-toss-payments-server` 를 이용하여 결제를 시뮬레이션하는 경우라면,\n결제 관련 API 를 호출함에 있어 {@link ITossCardPayment.ICreate.__approved } 내지\n{@link ITossVirtualAccountPayment.ICreate.__approved } 를 `false` 로 함으로써, 별도\n승인이 필요한 이러한 상황을 시뮬레이션 할 수 있다.","security":[{"basic":[]}]}},"/v1/payments/key-in":{"post":{"tags":[],"parameters":[],"requestBody":{"description":"카드 결제 입력 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITossCardPayment.ICreate"}}},"required":true},"responses":{"201":{"description":"카드 결제 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITossCardPayment"}}}}},"summary":"카드로 결제하기","description":"카드로 결제하기.\n\n`payments.key_in` 은 카드를 이용한 결제를 할 때 호출되는 API 함수이다.\n\n참고로 `payments.key_in` 는 클라이언트 어플리케이션이 토스 페이먼츠가 자체적으로\n제공하는 결제 창을 사용하는 경우, 귀하의 백엔드 서버가 이를 실 서비스에서 호출하는\n일은 없을 것이다. 다만, 고객이 카드를 통하여 결제하는 상황을 시뮬레이션하기 위하여,\n테스트 자동화 프로그램 수준에서 사용될 수는 있다.\n\n그리고 귀하의 백엔드 서버가 `payments.key-in` 을 직접 호출하는 경우, 토스 페이먼츠\n서버는 이를 완전히 승인된 결제로 보고 바로 확정한다. 때문에 `payments.key-in` 을\n직접 호출하는 경우, 토스 페이먼츠의 결제 창을 이용하여 별도의 {@link approve } 가\n필요한 때 대비, 훨씬 더 세심한 주의가 요구된다.\n\n더하여 만약 귀하의 백엔드 서버가 `fake-toss-payments-server` 를 이용하여 고객의\n카드 결제를 시뮬레이션하는 경우, {@link ITossCardPayment.ICreate.__approved } 값을\n`false` 로 하여 카드 결제의 확정을 고의로 회피할 수 있다. 이를 통하여 토스\n페이먼츠의 결제 창을 이용한 카드 결제의 경우, 별도의 {@link approve } 가 필요한\n상황을 시뮬레이션 할 수 있다.","security":[{"basic":[]}]}},"/v1/payments/{paymentKey}/cancel":{"post":{"tags":[],"parameters":[{"name":"paymentKey","in":"path","schema":{"type":"string"},"description":"결제 정보의 ","required":true}],"requestBody":{"description":"취소 입력 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITossPaymentCancel.ICreate"}}},"required":true},"responses":{"201":{"description":"취소된 결제 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITossPayment"}}}}},"summary":"결제 취소하기","description":"결제 취소하기.\n\n`payments.cancel` 은 결제를 취소하는 API 이다.\n\n결제 취소 입력 정보 {@link ITossPaymentCancel.ICreate } 에는 취소 사유를 비롯하여,\n고객에게 환불해 줄 금액과 부가세 및 필요시 환불 계좌 정보 등을 입력하게 되어있다.","security":[{"basic":[]}]}},"/v1/virtual-accounts":{"post":{"tags":[],"parameters":[],"requestBody":{"description":"가상 결제 신청 정보.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITossVirtualAccountPayment.ICreate"}}},"required":true},"responses":{"201":{"description":"가상 계좌 결제 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITossVirtualAccountPayment"}}}}},"summary":"가상 계좌로 결제 신청하기","description":"가상 계좌로 결제 신청하기.\n\n`virtual_accounts.create` 는 고객이 결제 수단을 가상 계좌로 선택하는 경우에 호출되는\nAPI 함수이다. 물론 고객이 이처럼 가상 계좌를 선택한 경우, 고객이 지정된 계좌에 돈을\n입금하기 전까지는 결제가 마무리된 것이 아니기에, {@link ITossPayment.status } 값은\n`WAITING_FOR_DEPOSIT` 이 된다.\n\n참고로 `virtual_accounts.create` 는 클라이언트 어플리케이션이 토스 페이먼츠가\n자체적으로 제공하는 결제 창을 사용하는 경우, 귀하의 백엔드 서버가 이를 실 서비스에서\n호출하는 일은 없을 것이다. 다만, 고객이 가상 계좌로 결제를 진행하는 상황을\n시뮬레이션하기 위하여, 테스트 자동화 프로그램 수준에서 사용될 수는 있다.\n\n그리고 `virtual_accounts.create` 이후에 고객이 지정된 계좌에 금액을 입금하거든, 토스\n페이먼츠 서버로부터 웹훅 이벤트가 발생되어 귀하의 백엔드 서버로 전송된다. 만약 연동\n대상 토스 페이먼츠 서버가 실제가 아닌 `fake-toss-payments-server` 라면,\n{@link internal.virtual_accounts.deposit } 를 호출하여, 고객이 가상 계좌에 입금하는\n상황을 시뮬레이션 할 수 있다.","security":[{"basic":[]}]}}},"components":{"schemas":{"ITossBilling.ICreate":{"type":"object","properties":{"cardNumber":{"type":"string","pattern":"[0-9]{16}","description":"카드 번호."},"cardExpirationYear":{"type":"string","pattern":"\\d{2}","description":"카드 만료 년도 (2 자리)."},"cardExpirationMonth":{"type":"string","pattern":"^(0[1-9]|1[012])$","description":"카드 만료 월 (2 자리)."},"cardPassword":{"type":"string","description":"카드 비밀번호."},"customerBirthday":{"type":"string","pattern":"^([0-9]{2})(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$","description":"고객의 생년월일.\n\n표기 형식 YYMMDD."},"consumerName":{"type":"string","description":"고객의 이름."},"customerEmail":{"type":"string","format":"email","description":"고객의 이메일."},"vbv":{"type":"object","properties":{"cavv":{"type":"string","description":"3D Secure 인증 세션에 대한 인증 값."},"xid":{"type":"string","description":"트랜잭션 ID."},"eci":{"type":"string","description":"3DS 인증 결과에 대한 코드 값."}},"nullable":false,"required":["cavv","xid","eci"],"description":"해외카드로 결제하는 경우 3DS 인증 적용을 위해 사용.\n\n3DS 인증 결과를 전송해야 하는 경우에만 필수."},"customerKey":{"type":"string","description":"고객 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키."}},"nullable":false,"required":["cardNumber","cardExpirationYear","cardExpirationMonth","cardPassword","customerBirthday","customerKey"],"description":"간편 결제 카드 등록 정보."},"ITossBilling":{"type":"object","properties":{"mId":{"type":"string","description":"가맹점 ID.\n\n현재 tosspayments 가 쓰임."},"billingKey":{"type":"string","description":"{@link ITossBilling } 의 식별자 키."},"method":{"type":"string","enum":["카드"],"description":"결제 수단."},"cardCompany":{"type":"string","description":"카드사 이름."},"cardNumber":{"type":"string","pattern":"[0-9]{16}","description":"카드 번호."},"authenticatedAt":{"type":"string","format":"date-time","description":"인증 일시."},"customerKey":{"type":"string","description":"고객 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키."}},"nullable":false,"required":["mId","billingKey","method","cardCompany","cardNumber","authenticatedAt","customerKey"],"description":"간편 결제 등록 수단 정보.\n\n`ITossBilling` 은 간편 결제 등록 수단을 형상화한 자료구조 인터페이스로써, 고객이 자신의\n신용 카드를 서버에 등록해두고, 매번 결제가 필요할 때마다 카드 정보를 반복 입려하는 일\n없이 간편하게 결제를 진행하고자 할 때 사용한다."},"ITossBilling.ICustomerKey":{"type":"object","properties":{"customerKey":{"type":"string","description":"고객 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키."}},"nullable":false,"required":["customerKey"],"description":"고객 식별자 정보."},"ITossBilling.IPaymentStore":{"type":"object","properties":{"method":{"type":"string","enum":["billing"],"description":"결제 수단이 간편 결제임을 의미함."},"billingKey":{"type":"string","description":"{@link IPaymentStore } 의 식별자 키."},"orderId":{"type":"string","description":"주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키."},"amount":{"type":"number","description":"결제 총액."},"customerKey":{"type":"string","description":"고객 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키."}},"nullable":false,"required":["method","billingKey","orderId","amount","customerKey"],"description":"간편 결제를 이용한 결제 신청 정보."},"ITossPayment":{"oneOf":[{"$ref":"#/components/schemas/ITossCardPayment"},{"$ref":"#/components/schemas/ITossGiftCertificatePayment"},{"$ref":"#/components/schemas/ITossMobilePhonePayment"},{"$ref":"#/components/schemas/ITossTransferPayment"},{"$ref":"#/components/schemas/ITossVirtualAccountPayment"}],"description":"결제 정보.\n\n`ITossPayment` 는 토스 페이먼츠의 결제 정보를 형상화한 자료구조이자 유니언 타입의\n인터페이스로써, if condition 을 통하여 method 값을 특정하면, 파생 타입이 자동으로\n지정된다.\n\n```typescript\nif (payment.method === \"카드\")\n payment.card; // payment be ITossCardPayment\n```"},"ITossCardPayment":{"type":"object","properties":{"card":{"$ref":"#/components/schemas/ITossCardPayment.ICard","description":"카드 정보."},"discount":{"$ref":"#/components/schemas/ITossCardPayment.IDiscount.Nullable","description":"카드사의 즉시 할인 프로모션 정보."},"easyPay":{"type":"string","enum":["토스결제","페이코","삼성페이"],"nullable":true,"description":"간편결제로 결제한 경우 간편결제 타입 정보."},"method":{"type":"string","enum":["카드"],"description":"결제 수단."},"type":{"type":"string","enum":["NORMAL","BILLING"],"description":"결제 타입.\n\n - NORMAL: 일반 결제\n - BILLING: 미리 등록한 카드에 의한 간편 결제."},"status":{"type":"string","enum":["READY","IN_PROGRESS","WAITING_FOR_DEPOSIT","DONE","CANCELED","PARTIAL_CANCELED","ABORTED","EXPIRED"],"description":"결제 상태.\n\n - READY\n - IN_PROGRESS\n - WAITING_FOR_DEPOSIT\n - DONE\n - CANCELED\n - PARTIAL_CANCELED\n - ABORTED\n - EXPIRED"},"mId":{"type":"string","description":"가맹점 ID.\n\n현재 tosspayments 가 쓰임."},"version":{"type":"string","description":"사용 중인 토스 페이먼츠 API 의 버전."},"paymentKey":{"type":"string","description":"결제 내역의 식별자 번호."},"orderId":{"type":"string","description":"주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키."},"transactionKey":{"type":"string","description":"거래 건에 대한 고유한 키 값.\n\n{@link paymentKey } 와 달리, 이를 사용할 일은 없더라."},"orderName":{"type":"string","description":"주문 이름.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 발급한 주문명."},"currency":{"type":"string","description":"화폐 단위.\n\n현재 토스 페이먼츠는 KRW 만 사용 가능."},"totalAmount":{"type":"number","description":"총 결제 금액."},"balanceAmount":{"type":"number","description":"취소할 수 있는 금액."},"suppliedAmount":{"type":"number","description":"공급가액."},"taxFreeAmount":{"type":"number","description":"면세액."},"vat":{"type":"number","description":"부가세."},"useEscrow":{"type":"boolean","description":"에스크로 사용 여부."},"cultureExpense":{"type":"boolean","description":"문화비 지출 여부.\n\n도석입, 공연 티켓, 박물관/미술관 입장권 등."},"requestedAt":{"type":"string","format":"date-time","description":"결제 요청 일시."},"approvedAt":{"type":"string","format":"date-time","nullable":true,"description":"결제 승인 일시."},"cancels":{"type":"array","items":{"$ref":"#/components/schemas/ITossPaymentCancel"},"nullable":true,"description":"결제 취소 내역."},"cashReceipt":{"$ref":"#/components/schemas/ITossCashReceipt.ISummary.Nullable","description":"현금 영수증 정보."}},"nullable":false,"required":["card","discount","easyPay","method","type","status","mId","version","paymentKey","orderId","transactionKey","orderName","currency","totalAmount","balanceAmount","suppliedAmount","taxFreeAmount","vat","useEscrow","cultureExpense","requestedAt","approvedAt","cancels","cashReceipt"],"description":"카드 결제 정보."},"ITossCardPayment.ICard":{"type":"object","properties":{"company":{"type":"string","description":"카드사 이름."},"number":{"type":"string","pattern":"[0-9]{16}","description":"카드 번호."},"installmentPlanMonths":{"type":"number","description":"할부 개월 수."},"isInterestFree":{"type":"boolean","description":"무이자 할부 적용 여부."},"approveNo":{"type":"string","description":"승인 번호."},"useCardPoint":{"type":"boolean","enum":[false],"description":"카드 포인트 사용 여부."},"cardType":{"type":"string","enum":["신용","체크","기프트"],"description":"카드 타입."},"ownerType":{"type":"string","enum":["개인","법인"],"description":"카드의 소유자 타입."},"acquireStatus":{"type":"string","enum":["READY","CANCELED","REQUESTED","COMPLETED","CANCEL_REQUESTED"],"description":"카드 결제의 매입 상태.\n\n - READY: 매입 대기\n - REQUESTED: 매입 요청됨\n - COMPLETED: 매입 완료\n - CANCEL_REQUESTED: 매입 취소 요청됨\n - CANCELD: 매입 취소됨"},"receiptUrl":{"type":"string","format":"uri","description":"영수증 URL."}},"nullable":false,"required":["company","number","installmentPlanMonths","isInterestFree","approveNo","useCardPoint","cardType","ownerType","acquireStatus","receiptUrl"],"description":"카드 정보."},"ITossCardPayment.IDiscount.Nullable":{"type":"object","properties":{"amount":{"type":"number","description":"카드사의 즉시 할인 프로모션을 적용한 금액."}},"nullable":true,"required":["amount"],"description":"카드사의 즉시 할인 프로모션 정보."},"ITossPaymentCancel":{"type":"object","properties":{"cancelAmount":{"type":"number","description":"취소 총액."},"cancelReason":{"type":"string","description":"취소 사유."},"taxFreeAmount":{"type":"number","description":"면세 처리된 금액."},"taxAmount":{"type":"number","description":"과세 처리된 금액."},"refundableAmount":{"type":"number","description":"결제 취소 후 환불 가능 잔액."},"canceledAt":{"type":"string","format":"date-time","description":"취소 일시."}},"nullable":false,"required":["cancelAmount","cancelReason","taxFreeAmount","taxAmount","refundableAmount","canceledAt"],"description":"결제 취소 정보."},"ITossCashReceipt.ISummary.Nullable":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ITossCashReceipt.Type","description":"현금 영수증의 종류."},"amount":{"type":"number","description":"현금 영수증 처리된 금액."},"taxFreeAmount":{"type":"number","description":"면세 처리된 금액."},"issueNumber":{"type":"string","description":"현금영수증 발급번호."},"receiptUrl":{"type":"string","description":"현금영수증 조회 페이지 주소."}},"nullable":true,"required":["type","amount","taxFreeAmount","issueNumber","receiptUrl"],"description":"현금 영수증 요약 정보."},"ITossCashReceipt.Type":{"type":"string","enum":["소득공제","지출증빙"],"description":"현금 영수증의 종류."},"ITossGiftCertificatePayment":{"type":"object","properties":{"giftCertificate":{"$ref":"#/components/schemas/ITossGiftCertificatePayment.IGiftCertificate","description":"상품권 정보."},"method":{"type":"string","enum":["상품권"],"description":"결제 수단."},"type":{"type":"string","enum":["NORMAL"],"description":"결제 타입.\n\n - NORMAL: 일반 결제\n - BILLING: 미리 등록한 카드에 의한 간편 결제."},"status":{"type":"string","enum":["READY","IN_PROGRESS","WAITING_FOR_DEPOSIT","DONE","CANCELED","PARTIAL_CANCELED","ABORTED","EXPIRED"],"description":"결제 상태.\n\n - READY\n - IN_PROGRESS\n - WAITING_FOR_DEPOSIT\n - DONE\n - CANCELED\n - PARTIAL_CANCELED\n - ABORTED\n - EXPIRED"},"mId":{"type":"string","description":"가맹점 ID.\n\n현재 tosspayments 가 쓰임."},"version":{"type":"string","description":"사용 중인 토스 페이먼츠 API 의 버전."},"paymentKey":{"type":"string","description":"결제 내역의 식별자 번호."},"orderId":{"type":"string","description":"주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키."},"transactionKey":{"type":"string","description":"거래 건에 대한 고유한 키 값.\n\n{@link paymentKey } 와 달리, 이를 사용할 일은 없더라."},"orderName":{"type":"string","description":"주문 이름.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 발급한 주문명."},"currency":{"type":"string","description":"화폐 단위.\n\n현재 토스 페이먼츠는 KRW 만 사용 가능."},"totalAmount":{"type":"number","description":"총 결제 금액."},"balanceAmount":{"type":"number","description":"취소할 수 있는 금액."},"suppliedAmount":{"type":"number","description":"공급가액."},"taxFreeAmount":{"type":"number","description":"면세액."},"vat":{"type":"number","description":"부가세."},"useEscrow":{"type":"boolean","description":"에스크로 사용 여부."},"cultureExpense":{"type":"boolean","description":"문화비 지출 여부.\n\n도석입, 공연 티켓, 박물관/미술관 입장권 등."},"requestedAt":{"type":"string","format":"date-time","description":"결제 요청 일시."},"approvedAt":{"type":"string","format":"date-time","nullable":true,"description":"결제 승인 일시."},"cancels":{"type":"array","items":{"$ref":"#/components/schemas/ITossPaymentCancel"},"nullable":true,"description":"결제 취소 내역."},"cashReceipt":{"$ref":"#/components/schemas/ITossCashReceipt.ISummary.Nullable","description":"현금 영수증 정보."}},"nullable":false,"required":["giftCertificate","method","type","status","mId","version","paymentKey","orderId","transactionKey","orderName","currency","totalAmount","balanceAmount","suppliedAmount","taxFreeAmount","vat","useEscrow","cultureExpense","requestedAt","approvedAt","cancels","cashReceipt"],"description":"상품권 결제 정보."},"ITossGiftCertificatePayment.IGiftCertificate":{"type":"object","properties":{"approveNo":{"type":"string","description":"승인 번호."},"settlementStatus":{"type":"string","enum":["COMPLETE","INCOMPLETE"],"description":"정산 상태."}},"nullable":false,"required":["approveNo","settlementStatus"],"description":"상품권 정보."},"ITossMobilePhonePayment":{"type":"object","properties":{"mobilePhone":{"$ref":"#/components/schemas/ITossMobilePhonePayment.IMobilePhone","description":"휴대폰 정보."},"method":{"type":"string","enum":["휴대폰"],"description":"결제 수단."},"type":{"type":"string","enum":["NORMAL"],"description":"결제 타입.\n\n - NORMAL: 일반 결제\n - BILLING: 미리 등록한 카드에 의한 간편 결제."},"status":{"type":"string","enum":["READY","IN_PROGRESS","WAITING_FOR_DEPOSIT","DONE","CANCELED","PARTIAL_CANCELED","ABORTED","EXPIRED"],"description":"결제 상태.\n\n - READY\n - IN_PROGRESS\n - WAITING_FOR_DEPOSIT\n - DONE\n - CANCELED\n - PARTIAL_CANCELED\n - ABORTED\n - EXPIRED"},"mId":{"type":"string","description":"가맹점 ID.\n\n현재 tosspayments 가 쓰임."},"version":{"type":"string","description":"사용 중인 토스 페이먼츠 API 의 버전."},"paymentKey":{"type":"string","description":"결제 내역의 식별자 번호."},"orderId":{"type":"string","description":"주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키."},"transactionKey":{"type":"string","description":"거래 건에 대한 고유한 키 값.\n\n{@link paymentKey } 와 달리, 이를 사용할 일은 없더라."},"orderName":{"type":"string","description":"주문 이름.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 발급한 주문명."},"currency":{"type":"string","description":"화폐 단위.\n\n현재 토스 페이먼츠는 KRW 만 사용 가능."},"totalAmount":{"type":"number","description":"총 결제 금액."},"balanceAmount":{"type":"number","description":"취소할 수 있는 금액."},"suppliedAmount":{"type":"number","description":"공급가액."},"taxFreeAmount":{"type":"number","description":"면세액."},"vat":{"type":"number","description":"부가세."},"useEscrow":{"type":"boolean","description":"에스크로 사용 여부."},"cultureExpense":{"type":"boolean","description":"문화비 지출 여부.\n\n도석입, 공연 티켓, 박물관/미술관 입장권 등."},"requestedAt":{"type":"string","format":"date-time","description":"결제 요청 일시."},"approvedAt":{"type":"string","format":"date-time","nullable":true,"description":"결제 승인 일시."},"cancels":{"type":"array","items":{"$ref":"#/components/schemas/ITossPaymentCancel"},"nullable":true,"description":"결제 취소 내역."},"cashReceipt":{"$ref":"#/components/schemas/ITossCashReceipt.ISummary.Nullable","description":"현금 영수증 정보."}},"nullable":false,"required":["mobilePhone","method","type","status","mId","version","paymentKey","orderId","transactionKey","orderName","currency","totalAmount","balanceAmount","suppliedAmount","taxFreeAmount","vat","useEscrow","cultureExpense","requestedAt","approvedAt","cancels","cashReceipt"],"description":"휴대폰 결제 정보."},"ITossMobilePhonePayment.IMobilePhone":{"type":"object","properties":{"carrier":{"type":"string","description":"통신사."},"customerMobilePhone":{"type":"string","description":"고객 휴대폰 번호."},"settlementStatus":{"type":"string","enum":["COMPLETED","INCOMPLETED"],"description":"정산 상태."}},"nullable":false,"required":["carrier","customerMobilePhone","settlementStatus"],"description":"휴대폰 정보."},"ITossTransferPayment":{"type":"object","properties":{"transfer":{"$ref":"#/components/schemas/ITossTransferPayment.ITransfer","description":"계좌 이체 정보."},"method":{"type":"string","enum":["계좌이체"],"description":"결제 수단."},"type":{"type":"string","enum":["NORMAL"],"description":"결제 타입.\n\n - NORMAL: 일반 결제\n - BILLING: 미리 등록한 카드에 의한 간편 결제."},"status":{"type":"string","enum":["READY","IN_PROGRESS","WAITING_FOR_DEPOSIT","DONE","CANCELED","PARTIAL_CANCELED","ABORTED","EXPIRED"],"description":"결제 상태.\n\n - READY\n - IN_PROGRESS\n - WAITING_FOR_DEPOSIT\n - DONE\n - CANCELED\n - PARTIAL_CANCELED\n - ABORTED\n - EXPIRED"},"mId":{"type":"string","description":"가맹점 ID.\n\n현재 tosspayments 가 쓰임."},"version":{"type":"string","description":"사용 중인 토스 페이먼츠 API 의 버전."},"paymentKey":{"type":"string","description":"결제 내역의 식별자 번호."},"orderId":{"type":"string","description":"주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키."},"transactionKey":{"type":"string","description":"거래 건에 대한 고유한 키 값.\n\n{@link paymentKey } 와 달리, 이를 사용할 일은 없더라."},"orderName":{"type":"string","description":"주문 이름.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 발급한 주문명."},"currency":{"type":"string","description":"화폐 단위.\n\n현재 토스 페이먼츠는 KRW 만 사용 가능."},"totalAmount":{"type":"number","description":"총 결제 금액."},"balanceAmount":{"type":"number","description":"취소할 수 있는 금액."},"suppliedAmount":{"type":"number","description":"공급가액."},"taxFreeAmount":{"type":"number","description":"면세액."},"vat":{"type":"number","description":"부가세."},"useEscrow":{"type":"boolean","description":"에스크로 사용 여부."},"cultureExpense":{"type":"boolean","description":"문화비 지출 여부.\n\n도석입, 공연 티켓, 박물관/미술관 입장권 등."},"requestedAt":{"type":"string","format":"date-time","description":"결제 요청 일시."},"approvedAt":{"type":"string","format":"date-time","nullable":true,"description":"결제 승인 일시."},"cancels":{"type":"array","items":{"$ref":"#/components/schemas/ITossPaymentCancel"},"nullable":true,"description":"결제 취소 내역."},"cashReceipt":{"$ref":"#/components/schemas/ITossCashReceipt.ISummary.Nullable","description":"현금 영수증 정보."}},"nullable":false,"required":["transfer","method","type","status","mId","version","paymentKey","orderId","transactionKey","orderName","currency","totalAmount","balanceAmount","suppliedAmount","taxFreeAmount","vat","useEscrow","cultureExpense","requestedAt","approvedAt","cancels","cashReceipt"],"description":"계좌 이체 결제 정보."},"ITossTransferPayment.ITransfer":{"type":"object","properties":{"bank":{"type":"string","description":"은행명."},"settlementStatus":{"type":"string","enum":["COMPLETED","INCOMPLETED"],"description":"이체 상태."}},"nullable":false,"required":["bank","settlementStatus"],"description":"계좌 이체 정보."},"ITossVirtualAccountPayment":{"type":"object","properties":{"secret":{"type":"string","description":"가상 계좌로 결제할 때 전달되는 입금 콜백을 검증하기 위한 값."},"virtualAccount":{"$ref":"#/components/schemas/ITossVirtualAccountPayment.IVirtualAccount","description":"가상 계좌 정보."},"method":{"type":"string","enum":["가상계좌"],"description":"결제 수단."},"type":{"type":"string","enum":["NORMAL"],"description":"결제 타입.\n\n - NORMAL: 일반 결제\n - BILLING: 미리 등록한 카드에 의한 간편 결제."},"status":{"type":"string","enum":["READY","IN_PROGRESS","WAITING_FOR_DEPOSIT","DONE","CANCELED","PARTIAL_CANCELED","ABORTED","EXPIRED"],"description":"결제 상태.\n\n - READY\n - IN_PROGRESS\n - WAITING_FOR_DEPOSIT\n - DONE\n - CANCELED\n - PARTIAL_CANCELED\n - ABORTED\n - EXPIRED"},"mId":{"type":"string","description":"가맹점 ID.\n\n현재 tosspayments 가 쓰임."},"version":{"type":"string","description":"사용 중인 토스 페이먼츠 API 의 버전."},"paymentKey":{"type":"string","description":"결제 내역의 식별자 번호."},"orderId":{"type":"string","description":"주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키."},"transactionKey":{"type":"string","description":"거래 건에 대한 고유한 키 값.\n\n{@link paymentKey } 와 달리, 이를 사용할 일은 없더라."},"orderName":{"type":"string","description":"주문 이름.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 발급한 주문명."},"currency":{"type":"string","description":"화폐 단위.\n\n현재 토스 페이먼츠는 KRW 만 사용 가능."},"totalAmount":{"type":"number","description":"총 결제 금액."},"balanceAmount":{"type":"number","description":"취소할 수 있는 금액."},"suppliedAmount":{"type":"number","description":"공급가액."},"taxFreeAmount":{"type":"number","description":"면세액."},"vat":{"type":"number","description":"부가세."},"useEscrow":{"type":"boolean","description":"에스크로 사용 여부."},"cultureExpense":{"type":"boolean","description":"문화비 지출 여부.\n\n도석입, 공연 티켓, 박물관/미술관 입장권 등."},"requestedAt":{"type":"string","format":"date-time","description":"결제 요청 일시."},"approvedAt":{"type":"string","format":"date-time","nullable":true,"description":"결제 승인 일시."},"cancels":{"type":"array","items":{"$ref":"#/components/schemas/ITossPaymentCancel"},"nullable":true,"description":"결제 취소 내역."},"cashReceipt":{"$ref":"#/components/schemas/ITossCashReceipt.ISummary.Nullable","description":"현금 영수증 정보."}},"nullable":false,"required":["secret","virtualAccount","method","type","status","mId","version","paymentKey","orderId","transactionKey","orderName","currency","totalAmount","balanceAmount","suppliedAmount","taxFreeAmount","vat","useEscrow","cultureExpense","requestedAt","approvedAt","cancels","cashReceipt"],"description":"가상 계좌 결제 정보."},"ITossVirtualAccountPayment.IVirtualAccount":{"type":"object","properties":{"accountNumber":{"type":"string","description":"계좌 번호."},"accountType":{"type":"string","enum":["일반","고정"],"description":"가상 계좌 타입."},"bank":{"type":"string","description":"은행명."},"customerName":{"type":"string","description":"고객 이름."},"dueDate":{"type":"string","format":"date","description":"입금 기한."},"expired":{"type":"boolean","description":"가상 계좌 만료 여부."},"settlementStatus":{"type":"string","enum":["COMPLETED","INCOMPLETED"],"description":"정산 상태."},"refundStatus":{"type":"string","enum":["COMPLETED","NONE","FAILED","PENDING","PARTIAL_FAILED"],"description":"환불 처리 상태.\n\n - NONE: 해당 없음\n - FAILED: 환불 실패\n - PENDING: 환불 처리중\n - PARTIAL_FAILED: 부분 환불 실패\n - COMPLETED: 환불 완료"}},"nullable":false,"required":["accountNumber","accountType","bank","customerName","dueDate","expired","settlementStatus","refundStatus"],"description":"가상 계좌 정보."},"ITossCashReceipt.ICreate":{"type":"object","properties":{"type":{"type":"string","enum":["소득공제","지출증빙"],"description":"현금 영수증의 종류."},"paymentKey":{"type":"string","description":"귀속 결제의 {@link ITossPayment.paymentKey }."},"orderId":{"type":"string","description":"주문의 식별자 ID."},"orderName":{"type":"string","description":"주문 이름."},"registrationNumber":{"type":"string","description":"현금 영수증 발급을 위한 개인 식별 번호.\n\n현금 영수증의 종류에 따라 휴대폰 번호나 주민등록번호 또는 사업자등록번호 및\n카드 번호를 입력할 수 있다."},"amount":{"type":"number","description":"현금 영수증을 발행할 금액."},"taxFreeAmount":{"type":"number","description":"면세 금액."},"businessNumber":{"type":"string","description":"사업자 등록번호."}},"nullable":false,"required":["type","paymentKey","orderId","orderName","registrationNumber","amount"],"description":"현금 영수증 입력 정보."},"ITossCashReceipt":{"type":"object","properties":{"receiptKey":{"type":"string","description":"현금 영수증의 식별자 키."},"type":{"$ref":"#/components/schemas/ITossCashReceipt.Type","description":"현금 영수증의 종류."},"orderId":{"type":"string","description":"주문의 식별자 ID."},"orderName":{"type":"string","description":"주문 이름."},"approvalNumber":{"type":"string","description":"현금 영수증 승인 번호."},"approvedAt":{"type":"string","format":"date-time","description":"현금 영수증 승인 일시."},"canceledAt":{"type":"string","format":"date-time","nullable":true,"description":"현금 영수증 취소 일시."},"receiptUrl":{"type":"string","description":"영수증 URL."}},"nullable":false,"required":["receiptKey","type","orderId","orderName","approvalNumber","approvedAt","canceledAt","receiptUrl"],"description":"현금 영수증 정보."},"ITossCashReceipt.ICancel":{"type":"object","properties":{"amount":{"type":"number","description":"취소 금액.\n\n미 입력시 현금 영수증에 기재된 {@link ITossCashReceipt.amount 총액}이 취소됨."}},"nullable":false,"description":"현금 영수증 취소 입력 정보."},"ITossPaymentWebhook":{"type":"object","properties":{"eventType":{"type":"string","enum":["PAYMENT_STATUS_CHANGED"],"description":"이벤트 타입."},"data":{"$ref":"#/components/schemas/ITossPaymentWebhook.IData","description":"이벤트 데이터."}},"nullable":false,"required":["eventType","data"],"description":"웹훅 이벤트 정보."},"ITossPaymentWebhook.IData":{"type":"object","properties":{"paymentKey":{"type":"string","description":"{@link ITossPayment } 의 식별자 키."},"orderId":{"type":"string","description":"주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키."},"status":{"type":"string","enum":["WAITING_FOR_DEPOSIT","DONE","CANCELED","PARTIAL_CANCELED"],"description":"결제 상태.\n\n - DONE: 결제 완료\n - CANCELED: 결제가 취소됨\n - PARTIAL_CANCELED: 결제가 부분 취소됨\n - WAITING_FOR_DEPOSIT: 입금 대기 중"}},"nullable":false,"required":["paymentKey","orderId","status"],"description":"웹훅 이벤트 데이터."},"ITossCardPayment.ICreate":{"type":"object","properties":{"method":{"type":"string","enum":["card"],"description":"결제 수단이 신용 카드임을 의미."},"cardNumber":{"type":"string","pattern":"[0-9]{16}","description":"카드 번호."},"cardExpirationYear":{"type":"string","pattern":"\\d{2}","description":"카드 만료 년도 (2 자리)."},"cardExpirationMonth":{"type":"string","pattern":"^(0[1-9]|1[012])$","description":"카드 만료 월 (2 자리)."},"cardPassword":{"type":"string","description":"카드 비밀번호."},"cardInstallmentPlan":{"type":"number","description":"할부 개월 수."},"amount":{"type":"number","description":"지불 총액."},"taxFreeAmount":{"type":"number","description":"면세금 총액."},"orderId":{"type":"string","description":"주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키."},"orderName":{"type":"string","description":"주문 이름.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 발급한 주문명."},"customerBirthday":{"type":"string","pattern":"^([0-9]{2})(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$","description":"고객의 생년월일.\n\n표기 형식 YYMMDD."},"customerEmail":{"type":"string","format":"email","description":"고객의 이메일."},"vbv":{"type":"object","properties":{"cavv":{"type":"string","description":"3D Secure 인증 세션에 대한 인증 값."},"xid":{"type":"string","description":"트랜잭션 ID."},"eci":{"type":"string","description":"3DS 인증 결과에 대한 코드 값."}},"nullable":false,"required":["cavv","xid","eci"],"description":"해외카드로 결제하는 경우 3DS 인증 적용을 위해 사용.\n\n3DS 인증 결과를 전송해야 하는 경우에만 필수."},"__approved":{"type":"boolean","description":"결제 승인 여부.\n\n오직 가짜 페이먼츠 서버 `fake-toss-payments-server` 에서만 사용되는 값으로써,\n결제 승인을 고의로 지연시키거나 할 때 사용된다. 이 값을 `false` 로 하면, 프론트\n어플리케이션이 토스 페이먼츠가 제공해주는 결제 창을 사용하여 결제를 진행하는\n상황을 시뮬레이션할 수 있다.\n\n본디 토스 페이먼츠 서버는 프론트 어플리케이션에서 백엔드 서버를 거치지 않고,\n토스 페이먼츠가 제공해주는 결제 창을 이용하여 직접 결제를 요청하는 경우,\n백엔드에서 이를 별도 {@link functional.payments.approve 승인} 처리해주기 전까지\n정식 결제로 인청치 아니한다.\n\n반면 백엔드 서버에서 토스 페이먼츠 서버의 API 를 호출하는 경우, 토스 페이먼츠는\n이를 그 즉시로 승인해주기, `fake-toss-payments-server` 에서 별도의 승인 처리가\n필요한 상황을 시뮬레이션하기 위해서는 이러한 속성이 필요한 것."}},"nullable":false,"required":["method","cardNumber","cardExpirationYear","cardExpirationMonth","amount","orderId"],"description":"신용 카드를 이용한 결제 신청 정보."},"ITossPayment.IApproval":{"type":"object","properties":{"orderId":{"type":"string","description":"주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키."},"amount":{"type":"number","description":"결제 총액."}},"nullable":false,"required":["orderId","amount"],"description":"결제 승인 정보."},"ITossPaymentCancel.ICreate":{"type":"object","properties":{"paymentKey":{"type":"string","description":"{@link ITossPayment } 의 식별자 키."},"cancelReason":{"type":"string","description":"취소 사유."},"cancelAmount":{"type":"number","description":"취소 총액."},"refundReceiveAccount":{"type":"object","properties":{"bank":{"type":"string","description":"은행 정보."},"accountNumber":{"type":"string","pattern":"^[0-9]{0,20}$","description":"계좌 번호."},"holderName":{"type":"string","description":"예금주."}},"nullable":false,"required":["bank","accountNumber","holderName"],"description":"환불 계좌 정보.\n\n결제를 가상 계좌로 하였을 때에만 해당함."},"taxAmount":{"type":"number","description":"과세 처리 금액."},"taxFreeAmount":{"type":"number","description":"면세 처리 금액."},"refundableAmount":{"type":"number","description":"결제 취소 후 환불 가능 잔액."}},"nullable":false,"required":["paymentKey","cancelReason"],"description":"결제 취소 신청 정보."},"ITossVirtualAccountPayment.ICreate":{"type":"object","properties":{"method":{"type":"string","enum":["virtual-account"],"description":"결제 수단이 가상 계좌임을 의미."},"orderId":{"type":"string","description":"주문 식별자 번호.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키."},"orderName":{"type":"string","description":"주문 이름.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 발급한 주문명."},"bank":{"type":"string","description":"은행명."},"customerName":{"type":"string","description":"고객 이름."},"amount":{"type":"number","description":"결제 총액."},"__approved":{"type":"boolean","description":"결제 승인 여부.\n\n오직 가짜 페이먼츠 서버 `fake-toss-payments-server` 에서만 사용되는 값으로써,\n결제 승인을 고의로 지연시키거나 할 때 사용된다. 이 값을 `false` 로 하면, 프론트\n어플리케이션이 토스 페이먼츠가 제공해주는 결제 창을 사용하여 결제를 진행하는\n상황을 시뮬레이션할 수 있다.\n\n본디 토스 페이먼츠 서버는 프론트 어플리케이션에서 백엔드 서버를 거치지 않고,\n토스 페이먼츠가 제공해주는 결제 창을 이용하여 직접 결제를 요청하는 경우,\n백엔드에서 이를 별도 {@link functional.payments.approve 승인} 처리해주기 전까지\n정식 결제로 인청치 아니한다.\n\n반면 백엔드 서버에서 토스 페이먼츠 서버의 API 를 호출하는 경우, 토스 페이먼츠는\n이를 그 즉시로 승인해주기, `fake-toss-payments-server` 에서 별도의 승인 처리가\n필요한 상황을 시뮬레이션하기 위해서는 이러한 속성이 필요한 것."}},"nullable":false,"required":["method","orderId","orderName","bank","customerName","amount"],"description":"가상 계좌를 이용한 결제 신청 정보."}},"securitySchemes":{"basic":{"type":"apiKey","name":"Authorization","in":"header"}}}} \ No newline at end of file +{ + "openapi": "3.0.1", + "servers": [ + { + "url": "http://localhost:30771", + "description": "fake" + }, + { + "url": "https://api.tosspayments.com", + "description": "real" + } + ], + "info": { + "title": "Toss Payments API", + "description": "Built by [fake-toss-payments-server](https://github.com/samchon/payments/tree/master/packages/toss-payments-server-api) with [nestia](https://github.com/samchon/nestia)", + "version": "6.0.6", + "license": { + "name": "MIT" + } + }, + "paths": { + "/v1/billing/authorizations/card": { + "post": { + "tags": [], + "parameters": [], + "requestBody": { + "description": "간편 결제 카드 등록 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ITossBilling.ICreate" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "간편 결제 카드 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ITossBilling" + } + } + } + } + }, + "summary": "간편 결제 카드 등록하기", + "description": "간편 결제 카드 등록하기.\n\n`billing.authorizations.card.create` 는 고객이 자신의 신록 카드를 서버에 등록해두고,\n매번 결제가 필요할 때마다 카드 정보를 반복 입력하는 일 없이 간편하게 결제를\n진행하고자 할 때, 호출되는 API 함수이다.\n\n참고로 `billing.authorizations.card.create` 는 클라이언트 어플리케이션이 토스\n페이먼츠가 제공하는 간편 결제 카드 등록 창을 사용하는 경우, 귀하의 백엔드 서버가 이를\n실 서비스에서 호출하는 일은 없을 것이다. 다만, 고객이 간편 결제 카드를 등록하는\n상황을 시뮬레이션하기 위하여, 테스트 자동화 프로그램 수준에서 사용될 수는 있다.", + "security": [ + { + "basic": [] + } + ] + } + }, + "/v1/billing/authorizations/{billingKey}": { + "post": { + "tags": [], + "parameters": [ + { + "name": "billingKey", + "in": "path", + "schema": { + "type": "string" + }, + "description": "대상 정보의 ", + "required": true + } + ], + "requestBody": { + "description": "고객 식별자 키", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ITossBilling.ICustomerKey" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "간편 결제 수단 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ITossBilling" + } + } + } + } + }, + "summary": "간편 결제로 등록한 수단 조회하기", + "description": "간편 결제로 등록한 수단 조회하기.\n\n`billing.authorizations.at` 은 고객이 간편 결제를 위하여 토스 페이먼츠 서버에\n등록한 결제 수단을 조회하는 함수이다.\n\n주로 클라이언트 어플리케이션이 토스 페이먼츠가 자체적으로 제공하는 결제 창을 사용하는\n경우, 그래서 프론트 어플리케이션이 귀하의 백엔드 서버에 `billingKey` 와` customerKey`\n만을 전달해주어, 상세 간편 결제 수단 정보가 필요할 때 사용한다.", + "security": [ + { + "basic": [] + } + ] + } + }, + "/v1/billing/{billingKey}": { + "post": { + "tags": [], + "parameters": [ + { + "name": "billingKey", + "in": "path", + "schema": { + "type": "string" + }, + "description": "간편 결제에 등록한 수단의 ", + "required": true + } + ], + "requestBody": { + "description": "주문 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ITossBilling.IPaymentStore" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "결제 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ITossPayment" + } + } + } + } + }, + "summary": "간편 결제에 등록한 수단으로 결제하기", + "description": "간편 결제에 등록한 수단으로 결제하기.\n\n`billing.pay` 는 간편 결제에 등록한 수단으로 결제를 진행하고자 할 때 호출하는 API\n함수이다.\n\n그리고 `billing.pay` 는 결제 수단 중 유일하게, 클라이언트 어플리케이션이 토스\n페이먼츠가 제공하는 결제 창을 사용할 수 없어, 귀하의 백엔드 서버가 토스 페이먼츠의\nAPI 함수를 직접 호출해야 하는 경우에 해당한다. 따라서 간편 결제에 관련하여 토스\n페이먼츠와 연동하는 백엔드 서버 및 프론트 어플리케이션을 개발할 때, 반드시 이 상황에\n대한 별도의 설계 및 개발이 필요하니, 이 점을 염두에 두기 바란다.\n\n더하여 `billing.pay` 는 철저히 귀사 백엔드 서버의 판단 아래 호출되는 API 함수인지라,\n이를 통하여 이루어지는 결제는 일절 {@link payments.approve } 가 필요 없다. 다만\n`billing.pay` 는 이처럼 부차적인 승인 과정 필요없이 그 즉시로 결제가 완성되니, 이를\n호출하는 상황에 대하여 세심히 주의를 기울일 필요가 있다", + "security": [ + { + "basic": [] + } + ] + } + }, + "/v1/cash-receipts": { + "post": { + "tags": [], + "parameters": [], + "requestBody": { + "description": "입력 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ITossCashReceipt.ICreate" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "현금 영수증 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ITossCashReceipt" + } + } + } + } + }, + "summary": "현금 영수증 발행하기", + "description": "현금 영수증 발행하기.", + "security": [ + { + "basic": [] + } + ] + } + }, + "/v1/cash-receipts/{receiptKey}/cancel": { + "post": { + "tags": [], + "parameters": [ + { + "name": "receiptKey", + "in": "path", + "schema": { + "type": "string" + }, + "description": "현금 영수증의 ", + "required": true + } + ], + "requestBody": { + "description": "취소 입력 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ITossCashReceipt.ICancel" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "취소된 현금 영수증 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ITossCashReceipt" + } + } + } + } + }, + "summary": "현금 영수증 취소하기", + "description": "현금 영수증 취소하기.", + "security": [ + { + "basic": [] + } + ] + } + }, + "/internal/webhook": { + "post": { + "tags": [], + "parameters": [], + "requestBody": { + "description": "웹훅 이벤트 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ITossPaymentWebhook" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "" + } + }, + "summary": "웹훅 이벤트 더미 리스너", + "description": "웹훅 이벤트 더미 리스너.\n\n`internal.webhook` 은 실제 토스 페이먼츠의 결제 서버에는 존재하지 않는 API 로써,\n`fake-toss-payments-server` 의 {@link Configuration.WEBHOOK_URL } 에 아무런 URL 을\n설정하지 않으면, `fake-toss-payments-server` 로부터 발생하는 모든 종류의 웹훅\n이벤트는 이 곳으로 전달되어 무의미하게 사라진다.\n\n따라서 `fake-toss-payments-server` 를 사용하여 토스 페이먼츠 서버와의 연동을 미리\n검증코자 할 때는, 반드시 {@link Configuration.WEBHOOK_URL } 를 설정하여 웹훅\n이벤트가 귀하의 백엔드 서버로 제대로 전달되도록 하자." + } + }, + "/internal/{paymentKey}/deposit": { + "put": { + "tags": [], + "parameters": [ + { + "name": "paymentKey", + "in": "path", + "schema": { + "type": "string" + }, + "description": "대상 가상 계좌 결제 정보의 ", + "required": true + } + ], + "responses": { + "200": { + "description": "입금 완료된 가상 꼐좌 결제 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ITossPayment" + } + } + } + } + }, + "summary": "가상 계좌에 입금하기", + "description": "가상 계좌에 입금하기.\n\n`internal.virtual_accounts.deposit` 은 실제 토스 페이먼츠의 결제 서버에는 존재하지\n않는 API 로써, 가상 계좌 결제를 신청한 고객이, 이후 가상 계좌에 목표 금액을 입금하는\n상황을 시뮬레이션할 수 있는 함수이다.\n\n즉 `internal.virtual_accounts.deposit` 는 고객이 스스로에게 가상으로 발급된 계좌에\n입금을 하고, 그에 따라 토스 페이먼츠 서버에서 webhook 이벤트가 발생하여 이를 귀하의\n백엔드 서버로 전송하는 일련의 상황을 테스트하기 위한 함수인 셈이다.", + "security": [ + { + "basic": [] + } + ] + } + }, + "/v1/payments/{paymentKey}": { + "get": { + "tags": [], + "parameters": [ + { + "name": "paymentKey", + "in": "path", + "schema": { + "type": "string" + }, + "description": "결제 정보의 ", + "required": true + } + ], + "responses": { + "200": { + "description": "결제 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ITossPayment" + } + } + } + } + }, + "summary": "결제 정보 조회하기", + "description": "결제 정보 조회하기.\n\n`payments.at` 은 결제 정보를 조회하는 함수이다.\n\n주로 클라이언트 어플리케이션이 토스 페이먼츠가 자체적으로 제공하는 결제 창을 사용하는\n경우, 그래서 프론트 어플리케이션이 귀하의 백엔드 서버에 `paymentKey` 등 극히 일부의\n식별자 정보만을 전달해주어, 상세 결제 정보가 필요할 때 사용한다.\n\n참고로 토스 페이먼츠는 다른 결제 PG 사들과 다르게, 클라이언트 어플리케이션에서 토스\n페이먼츠의 결제 창을 이용하여 진행한 결제가 바로 확정되는 것은 아니다. 귀사의 백엔드\n서버가 현재의 `payments.at` 을 통하여 해당 결제 정보를 확인하고, {@link approve } 를\n호출하여 직접 승인하기 전까지, 해당 결제는 확정되지 않으니, 이 점에 유의하기 바란다." + }, + "post": { + "tags": [], + "parameters": [ + { + "name": "paymentKey", + "in": "path", + "schema": { + "type": "string" + }, + "description": "대상 결제의 ", + "required": true + } + ], + "requestBody": { + "description": "주문 정보 확인", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ITossPayment.IApproval" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "승인된 결제 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ITossPayment" + } + } + } + } + }, + "summary": "결제 승인하기", + "description": "결제 승인하기.\n\n토스 페이먼츠는 귀사의 백엔드에서 일어난 결제가 아닌 프론트 어플리케이션의 결제 창에서\n이루어진 결제의 경우, 해당 서비스으 백엔드 서버로부터 결제를 승인받기 전까지, 이를\n확정하지 않는다. `payments.approve` 는 바로 이러한 상황에서, 해당 결제를 승인해주는\n함수이다.\n\n만일 귀하가 `fake-toss-payments-server` 를 이용하여 결제를 시뮬레이션하는 경우라면,\n결제 관련 API 를 호출함에 있어 {@link ITossCardPayment.ICreate.__approved } 내지\n{@link ITossVirtualAccountPayment.ICreate.__approved } 를 `false` 로 함으로써, 별도\n승인이 필요한 이러한 상황을 시뮬레이션 할 수 있다.", + "security": [ + { + "basic": [] + } + ] + } + }, + "/v1/payments/key-in": { + "post": { + "tags": [], + "parameters": [], + "requestBody": { + "description": "카드 결제 입력 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ITossCardPayment.ICreate" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "카드 결제 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ITossCardPayment" + } + } + } + } + }, + "summary": "카드로 결제하기", + "description": "카드로 결제하기.\n\n`payments.key_in` 은 카드를 이용한 결제를 할 때 호출되는 API 함수이다.\n\n참고로 `payments.key_in` 는 클라이언트 어플리케이션이 토스 페이먼츠가 자체적으로\n제공하는 결제 창을 사용하는 경우, 귀하의 백엔드 서버가 이를 실 서비스에서 호출하는\n일은 없을 것이다. 다만, 고객이 카드를 통하여 결제하는 상황을 시뮬레이션하기 위하여,\n테스트 자동화 프로그램 수준에서 사용될 수는 있다.\n\n그리고 귀하의 백엔드 서버가 `payments.key-in` 을 직접 호출하는 경우, 토스 페이먼츠\n서버는 이를 완전히 승인된 결제로 보고 바로 확정한다. 때문에 `payments.key-in` 을\n직접 호출하는 경우, 토스 페이먼츠의 결제 창을 이용하여 별도의 {@link approve } 가\n필요한 때 대비, 훨씬 더 세심한 주의가 요구된다.\n\n더하여 만약 귀하의 백엔드 서버가 `fake-toss-payments-server` 를 이용하여 고객의\n카드 결제를 시뮬레이션하는 경우, {@link ITossCardPayment.ICreate.__approved } 값을\n`false` 로 하여 카드 결제의 확정을 고의로 회피할 수 있다. 이를 통하여 토스\n페이먼츠의 결제 창을 이용한 카드 결제의 경우, 별도의 {@link approve } 가 필요한\n상황을 시뮬레이션 할 수 있다.", + "security": [ + { + "basic": [] + } + ] + } + }, + "/v1/payments/{paymentKey}/cancel": { + "post": { + "tags": [], + "parameters": [ + { + "name": "paymentKey", + "in": "path", + "schema": { + "type": "string" + }, + "description": "결제 정보의 ", + "required": true + } + ], + "requestBody": { + "description": "취소 입력 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ITossPaymentCancel.ICreate" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "취소된 결제 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ITossPayment" + } + } + } + } + }, + "summary": "결제 취소하기", + "description": "결제 취소하기.\n\n`payments.cancel` 은 결제를 취소하는 API 이다.\n\n결제 취소 입력 정보 {@link ITossPaymentCancel.ICreate } 에는 취소 사유를 비롯하여,\n고객에게 환불해 줄 금액과 부가세 및 필요시 환불 계좌 정보 등을 입력하게 되어있다.", + "security": [ + { + "basic": [] + } + ] + } + }, + "/v1/virtual-accounts": { + "post": { + "tags": [], + "parameters": [], + "requestBody": { + "description": "가상 결제 신청 정보.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ITossVirtualAccountPayment.ICreate" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "가상 계좌 결제 정보", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ITossVirtualAccountPayment" + } + } + } + } + }, + "summary": "가상 계좌로 결제 신청하기", + "description": "가상 계좌로 결제 신청하기.\n\n`virtual_accounts.create` 는 고객이 결제 수단을 가상 계좌로 선택하는 경우에 호출되는\nAPI 함수이다. 물론 고객이 이처럼 가상 계좌를 선택한 경우, 고객이 지정된 계좌에 돈을\n입금하기 전까지는 결제가 마무리된 것이 아니기에, {@link ITossPayment.status } 값은\n`WAITING_FOR_DEPOSIT` 이 된다.\n\n참고로 `virtual_accounts.create` 는 클라이언트 어플리케이션이 토스 페이먼츠가\n자체적으로 제공하는 결제 창을 사용하는 경우, 귀하의 백엔드 서버가 이를 실 서비스에서\n호출하는 일은 없을 것이다. 다만, 고객이 가상 계좌로 결제를 진행하는 상황을\n시뮬레이션하기 위하여, 테스트 자동화 프로그램 수준에서 사용될 수는 있다.\n\n그리고 `virtual_accounts.create` 이후에 고객이 지정된 계좌에 금액을 입금하거든, 토스\n페이먼츠 서버로부터 웹훅 이벤트가 발생되어 귀하의 백엔드 서버로 전송된다. 만약 연동\n대상 토스 페이먼츠 서버가 실제가 아닌 `fake-toss-payments-server` 라면,\n{@link internal.virtual_accounts.deposit } 를 호출하여, 고객이 가상 계좌에 입금하는\n상황을 시뮬레이션 할 수 있다.", + "security": [ + { + "basic": [] + } + ] + } + } + }, + "components": { + "schemas": { + "ITossBilling.ICreate": { + "type": "object", + "properties": { + "cardNumber": { + "type": "string", + "pattern": "[0-9]{16}", + "title": "카드 번호", + "description": "카드 번호." + }, + "cardExpirationYear": { + "type": "string", + "pattern": "\\d{2}", + "title": "카드 만료 년도 (2 자리)", + "description": "카드 만료 년도 (2 자리)." + }, + "cardExpirationMonth": { + "type": "string", + "pattern": "^(0[1-9]|1[012])$", + "title": "카드 만료 월 (2 자리)", + "description": "카드 만료 월 (2 자리)." + }, + "cardPassword": { + "type": "string", + "title": "카드 비밀번호", + "description": "카드 비밀번호." + }, + "customerBirthday": { + "type": "string", + "pattern": "^([0-9]{2})(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$", + "title": "고객의 생년월일", + "description": "고객의 생년월일.\n\n표기 형식 YYMMDD." + }, + "consumerName": { + "type": "string", + "title": "고객의 이름", + "description": "고객의 이름." + }, + "customerEmail": { + "type": "string", + "format": "email", + "title": "고객의 이메일", + "description": "고객의 이메일." + }, + "vbv": { + "type": "object", + "properties": { + "cavv": { + "type": "string", + "title": "3D Secure 인증 세션에 대한 인증 값", + "description": "3D Secure 인증 세션에 대한 인증 값." + }, + "xid": { + "type": "string", + "title": "트랜잭션 ID", + "description": "트랜잭션 ID." + }, + "eci": { + "type": "string", + "title": "3DS 인증 결과에 대한 코드 값", + "description": "3DS 인증 결과에 대한 코드 값." + } + }, + "nullable": false, + "required": [ + "cavv", + "xid", + "eci" + ], + "title": "해외카드로 결제하는 경우 3DS 인증 적용을 위해 사용", + "description": "해외카드로 결제하는 경우 3DS 인증 적용을 위해 사용.\n\n3DS 인증 결과를 전송해야 하는 경우에만 필수." + }, + "customerKey": { + "type": "string", + "title": "고객 식별자 키", + "description": "고객 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키." + } + }, + "nullable": false, + "required": [ + "cardNumber", + "cardExpirationYear", + "cardExpirationMonth", + "cardPassword", + "customerBirthday", + "customerKey" + ], + "description": "간편 결제 카드 등록 정보." + }, + "ITossBilling": { + "type": "object", + "properties": { + "mId": { + "type": "string", + "title": "가맹점 ID", + "description": "가맹점 ID.\n\n현재 tosspayments 가 쓰임." + }, + "billingKey": { + "type": "string", + "title": "{@link ITossBilling } 의 식별자 키", + "description": "{@link ITossBilling } 의 식별자 키." + }, + "method": { + "type": "string", + "enum": [ + "카드" + ], + "title": "결제 수단", + "description": "결제 수단." + }, + "cardCompany": { + "type": "string", + "title": "카드사 이름", + "description": "카드사 이름." + }, + "cardNumber": { + "type": "string", + "pattern": "[0-9]{16}", + "title": "카드 번호", + "description": "카드 번호." + }, + "authenticatedAt": { + "type": "string", + "format": "date-time", + "title": "인증 일시", + "description": "인증 일시." + }, + "customerKey": { + "type": "string", + "title": "고객 식별자 키", + "description": "고객 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키." + } + }, + "nullable": false, + "required": [ + "mId", + "billingKey", + "method", + "cardCompany", + "cardNumber", + "authenticatedAt", + "customerKey" + ], + "description": "간편 결제 등록 수단 정보.\n\n`ITossBilling` 은 간편 결제 등록 수단을 형상화한 자료구조 인터페이스로써, 고객이 자신의\n신용 카드를 서버에 등록해두고, 매번 결제가 필요할 때마다 카드 정보를 반복 입려하는 일\n없이 간편하게 결제를 진행하고자 할 때 사용한다." + }, + "ITossBilling.ICustomerKey": { + "type": "object", + "properties": { + "customerKey": { + "type": "string", + "title": "고객 식별자 키", + "description": "고객 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키." + } + }, + "nullable": false, + "required": [ + "customerKey" + ], + "description": "고객 식별자 정보." + }, + "ITossBilling.IPaymentStore": { + "type": "object", + "properties": { + "method": { + "type": "string", + "enum": [ + "billing" + ], + "title": "결제 수단이 간편 결제임을 의미함", + "description": "결제 수단이 간편 결제임을 의미함." + }, + "billingKey": { + "type": "string", + "title": "{@link IPaymentStore } 의 식별자 키", + "description": "{@link IPaymentStore } 의 식별자 키." + }, + "orderId": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키." + }, + "amount": { + "type": "number", + "title": "결제 총액", + "description": "결제 총액." + }, + "customerKey": { + "type": "string", + "title": "고객 식별자 키", + "description": "고객 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키." + } + }, + "nullable": false, + "required": [ + "method", + "billingKey", + "orderId", + "amount", + "customerKey" + ], + "description": "간편 결제를 이용한 결제 신청 정보." + }, + "ITossPayment": { + "oneOf": [ + { + "$ref": "#/components/schemas/ITossCardPayment" + }, + { + "$ref": "#/components/schemas/ITossGiftCertificatePayment" + }, + { + "$ref": "#/components/schemas/ITossMobilePhonePayment" + }, + { + "$ref": "#/components/schemas/ITossTransferPayment" + }, + { + "$ref": "#/components/schemas/ITossVirtualAccountPayment" + } + ], + "description": "결제 정보.\n\n`ITossPayment` 는 토스 페이먼츠의 결제 정보를 형상화한 자료구조이자 유니언 타입의\n인터페이스로써, if condition 을 통하여 method 값을 특정하면, 파생 타입이 자동으로\n지정된다.\n\n```typescript\nif (payment.method === \"카드\")\n payment.card; // payment be ITossCardPayment\n```" + }, + "ITossCardPayment": { + "type": "object", + "properties": { + "card": { + "$ref": "#/components/schemas/ITossCardPayment.ICard", + "title": "카드 정보", + "description": "카드 정보." + }, + "discount": { + "$ref": "#/components/schemas/ITossCardPayment.IDiscount.Nullable", + "title": "카드사의 즉시 할인 프로모션 정보", + "description": "카드사의 즉시 할인 프로모션 정보." + }, + "easyPay": { + "type": "string", + "enum": [ + "토스결제", + "페이코", + "삼성페이" + ], + "nullable": true, + "title": "간편결제로 결제한 경우 간편결제 타입 정보", + "description": "간편결제로 결제한 경우 간편결제 타입 정보." + }, + "method": { + "type": "string", + "enum": [ + "카드" + ], + "title": "결제 수단", + "description": "결제 수단." + }, + "type": { + "type": "string", + "enum": [ + "NORMAL", + "BILLING" + ], + "title": "결제 타입", + "description": "결제 타입.\n\n - NORMAL: 일반 결제\n - BILLING: 미리 등록한 카드에 의한 간편 결제." + }, + "status": { + "type": "string", + "enum": [ + "READY", + "IN_PROGRESS", + "WAITING_FOR_DEPOSIT", + "DONE", + "CANCELED", + "PARTIAL_CANCELED", + "ABORTED", + "EXPIRED" + ], + "title": "결제 상태", + "description": "결제 상태.\n\n - READY\n - IN_PROGRESS\n - WAITING_FOR_DEPOSIT\n - DONE\n - CANCELED\n - PARTIAL_CANCELED\n - ABORTED\n - EXPIRED" + }, + "mId": { + "type": "string", + "title": "가맹점 ID", + "description": "가맹점 ID.\n\n현재 tosspayments 가 쓰임." + }, + "version": { + "type": "string", + "title": "사용 중인 토스 페이먼츠 API 의 버전", + "description": "사용 중인 토스 페이먼츠 API 의 버전." + }, + "paymentKey": { + "type": "string", + "title": "결제 내역의 식별자 번호", + "description": "결제 내역의 식별자 번호." + }, + "orderId": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키." + }, + "transactionKey": { + "type": "string", + "title": "거래 건에 대한 고유한 키 값", + "description": "거래 건에 대한 고유한 키 값.\n\n{@link paymentKey } 와 달리, 이를 사용할 일은 없더라." + }, + "orderName": { + "type": "string", + "title": "주문 이름", + "description": "주문 이름.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 발급한 주문명." + }, + "currency": { + "type": "string", + "title": "화폐 단위", + "description": "화폐 단위.\n\n현재 토스 페이먼츠는 KRW 만 사용 가능." + }, + "totalAmount": { + "type": "number", + "title": "총 결제 금액", + "description": "총 결제 금액." + }, + "balanceAmount": { + "type": "number", + "title": "취소할 수 있는 금액", + "description": "취소할 수 있는 금액." + }, + "suppliedAmount": { + "type": "number", + "title": "공급가액", + "description": "공급가액." + }, + "taxFreeAmount": { + "type": "number", + "title": "면세액", + "description": "면세액." + }, + "vat": { + "type": "number", + "title": "부가세", + "description": "부가세." + }, + "useEscrow": { + "type": "boolean", + "title": "에스크로 사용 여부", + "description": "에스크로 사용 여부." + }, + "cultureExpense": { + "type": "boolean", + "title": "문화비 지출 여부", + "description": "문화비 지출 여부.\n\n도석입, 공연 티켓, 박물관/미술관 입장권 등." + }, + "requestedAt": { + "type": "string", + "format": "date-time", + "title": "결제 요청 일시", + "description": "결제 요청 일시." + }, + "approvedAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "title": "결제 승인 일시", + "description": "결제 승인 일시." + }, + "cancels": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ITossPaymentCancel" + }, + "nullable": true, + "title": "결제 취소 내역", + "description": "결제 취소 내역." + }, + "cashReceipt": { + "$ref": "#/components/schemas/ITossCashReceipt.ISummary.Nullable", + "title": "현금 영수증 정보", + "description": "현금 영수증 정보." + } + }, + "nullable": false, + "required": [ + "card", + "discount", + "easyPay", + "method", + "type", + "status", + "mId", + "version", + "paymentKey", + "orderId", + "transactionKey", + "orderName", + "currency", + "totalAmount", + "balanceAmount", + "suppliedAmount", + "taxFreeAmount", + "vat", + "useEscrow", + "cultureExpense", + "requestedAt", + "approvedAt", + "cancels", + "cashReceipt" + ], + "description": "카드 결제 정보." + }, + "ITossCardPayment.ICard": { + "type": "object", + "properties": { + "company": { + "type": "string", + "title": "카드사 이름", + "description": "카드사 이름." + }, + "number": { + "type": "string", + "pattern": "[0-9]{16}", + "title": "카드 번호", + "description": "카드 번호." + }, + "installmentPlanMonths": { + "type": "number", + "title": "할부 개월 수", + "description": "할부 개월 수." + }, + "isInterestFree": { + "type": "boolean", + "title": "무이자 할부 적용 여부", + "description": "무이자 할부 적용 여부." + }, + "approveNo": { + "type": "string", + "title": "승인 번호", + "description": "승인 번호." + }, + "useCardPoint": { + "type": "boolean", + "enum": [ + false + ], + "title": "카드 포인트 사용 여부", + "description": "카드 포인트 사용 여부." + }, + "cardType": { + "type": "string", + "enum": [ + "신용", + "체크", + "기프트" + ], + "title": "카드 타입", + "description": "카드 타입." + }, + "ownerType": { + "type": "string", + "enum": [ + "개인", + "법인" + ], + "title": "카드의 소유자 타입", + "description": "카드의 소유자 타입." + }, + "acquireStatus": { + "type": "string", + "enum": [ + "READY", + "CANCELED", + "REQUESTED", + "COMPLETED", + "CANCEL_REQUESTED" + ], + "title": "카드 결제의 매입 상태", + "description": "카드 결제의 매입 상태.\n\n - READY: 매입 대기\n - REQUESTED: 매입 요청됨\n - COMPLETED: 매입 완료\n - CANCEL_REQUESTED: 매입 취소 요청됨\n - CANCELD: 매입 취소됨" + }, + "receiptUrl": { + "type": "string", + "format": "uri", + "title": "영수증 URL", + "description": "영수증 URL." + } + }, + "nullable": false, + "required": [ + "company", + "number", + "installmentPlanMonths", + "isInterestFree", + "approveNo", + "useCardPoint", + "cardType", + "ownerType", + "acquireStatus", + "receiptUrl" + ], + "description": "카드 정보." + }, + "ITossCardPayment.IDiscount.Nullable": { + "type": "object", + "properties": { + "amount": { + "type": "number", + "title": "카드사의 즉시 할인 프로모션을 적용한 금액", + "description": "카드사의 즉시 할인 프로모션을 적용한 금액." + } + }, + "nullable": true, + "required": [ + "amount" + ], + "description": "카드사의 즉시 할인 프로모션 정보." + }, + "ITossPaymentCancel": { + "type": "object", + "properties": { + "cancelAmount": { + "type": "number", + "title": "취소 총액", + "description": "취소 총액." + }, + "cancelReason": { + "type": "string", + "title": "취소 사유", + "description": "취소 사유." + }, + "taxFreeAmount": { + "type": "number", + "title": "면세 처리된 금액", + "description": "면세 처리된 금액." + }, + "taxAmount": { + "type": "number", + "title": "과세 처리된 금액", + "description": "과세 처리된 금액." + }, + "refundableAmount": { + "type": "number", + "title": "결제 취소 후 환불 가능 잔액", + "description": "결제 취소 후 환불 가능 잔액." + }, + "canceledAt": { + "type": "string", + "format": "date-time", + "title": "취소 일시", + "description": "취소 일시." + } + }, + "nullable": false, + "required": [ + "cancelAmount", + "cancelReason", + "taxFreeAmount", + "taxAmount", + "refundableAmount", + "canceledAt" + ], + "description": "결제 취소 정보." + }, + "ITossCashReceipt.ISummary.Nullable": { + "type": "object", + "properties": { + "type": { + "$ref": "#/components/schemas/ITossCashReceipt.Type", + "title": "현금 영수증의 종류", + "description": "현금 영수증의 종류." + }, + "amount": { + "type": "number", + "title": "현금 영수증 처리된 금액", + "description": "현금 영수증 처리된 금액." + }, + "taxFreeAmount": { + "type": "number", + "title": "면세 처리된 금액", + "description": "면세 처리된 금액." + }, + "issueNumber": { + "type": "string", + "title": "현금영수증 발급번호", + "description": "현금영수증 발급번호." + }, + "receiptUrl": { + "type": "string", + "title": "현금영수증 조회 페이지 주소", + "description": "현금영수증 조회 페이지 주소." + } + }, + "nullable": true, + "required": [ + "type", + "amount", + "taxFreeAmount", + "issueNumber", + "receiptUrl" + ], + "description": "현금 영수증 요약 정보." + }, + "ITossCashReceipt.Type": { + "type": "string", + "enum": [ + "소득공제", + "지출증빙" + ], + "description": "현금 영수증의 종류." + }, + "ITossGiftCertificatePayment": { + "type": "object", + "properties": { + "giftCertificate": { + "$ref": "#/components/schemas/ITossGiftCertificatePayment.IGiftCertificate", + "title": "상품권 정보", + "description": "상품권 정보." + }, + "method": { + "type": "string", + "enum": [ + "상품권" + ], + "title": "결제 수단", + "description": "결제 수단." + }, + "type": { + "type": "string", + "enum": [ + "NORMAL" + ], + "title": "결제 타입", + "description": "결제 타입.\n\n - NORMAL: 일반 결제\n - BILLING: 미리 등록한 카드에 의한 간편 결제." + }, + "status": { + "type": "string", + "enum": [ + "READY", + "IN_PROGRESS", + "WAITING_FOR_DEPOSIT", + "DONE", + "CANCELED", + "PARTIAL_CANCELED", + "ABORTED", + "EXPIRED" + ], + "title": "결제 상태", + "description": "결제 상태.\n\n - READY\n - IN_PROGRESS\n - WAITING_FOR_DEPOSIT\n - DONE\n - CANCELED\n - PARTIAL_CANCELED\n - ABORTED\n - EXPIRED" + }, + "mId": { + "type": "string", + "title": "가맹점 ID", + "description": "가맹점 ID.\n\n현재 tosspayments 가 쓰임." + }, + "version": { + "type": "string", + "title": "사용 중인 토스 페이먼츠 API 의 버전", + "description": "사용 중인 토스 페이먼츠 API 의 버전." + }, + "paymentKey": { + "type": "string", + "title": "결제 내역의 식별자 번호", + "description": "결제 내역의 식별자 번호." + }, + "orderId": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키." + }, + "transactionKey": { + "type": "string", + "title": "거래 건에 대한 고유한 키 값", + "description": "거래 건에 대한 고유한 키 값.\n\n{@link paymentKey } 와 달리, 이를 사용할 일은 없더라." + }, + "orderName": { + "type": "string", + "title": "주문 이름", + "description": "주문 이름.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 발급한 주문명." + }, + "currency": { + "type": "string", + "title": "화폐 단위", + "description": "화폐 단위.\n\n현재 토스 페이먼츠는 KRW 만 사용 가능." + }, + "totalAmount": { + "type": "number", + "title": "총 결제 금액", + "description": "총 결제 금액." + }, + "balanceAmount": { + "type": "number", + "title": "취소할 수 있는 금액", + "description": "취소할 수 있는 금액." + }, + "suppliedAmount": { + "type": "number", + "title": "공급가액", + "description": "공급가액." + }, + "taxFreeAmount": { + "type": "number", + "title": "면세액", + "description": "면세액." + }, + "vat": { + "type": "number", + "title": "부가세", + "description": "부가세." + }, + "useEscrow": { + "type": "boolean", + "title": "에스크로 사용 여부", + "description": "에스크로 사용 여부." + }, + "cultureExpense": { + "type": "boolean", + "title": "문화비 지출 여부", + "description": "문화비 지출 여부.\n\n도석입, 공연 티켓, 박물관/미술관 입장권 등." + }, + "requestedAt": { + "type": "string", + "format": "date-time", + "title": "결제 요청 일시", + "description": "결제 요청 일시." + }, + "approvedAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "title": "결제 승인 일시", + "description": "결제 승인 일시." + }, + "cancels": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ITossPaymentCancel" + }, + "nullable": true, + "title": "결제 취소 내역", + "description": "결제 취소 내역." + }, + "cashReceipt": { + "$ref": "#/components/schemas/ITossCashReceipt.ISummary.Nullable", + "title": "현금 영수증 정보", + "description": "현금 영수증 정보." + } + }, + "nullable": false, + "required": [ + "giftCertificate", + "method", + "type", + "status", + "mId", + "version", + "paymentKey", + "orderId", + "transactionKey", + "orderName", + "currency", + "totalAmount", + "balanceAmount", + "suppliedAmount", + "taxFreeAmount", + "vat", + "useEscrow", + "cultureExpense", + "requestedAt", + "approvedAt", + "cancels", + "cashReceipt" + ], + "description": "상품권 결제 정보." + }, + "ITossGiftCertificatePayment.IGiftCertificate": { + "type": "object", + "properties": { + "approveNo": { + "type": "string", + "title": "승인 번호", + "description": "승인 번호." + }, + "settlementStatus": { + "type": "string", + "enum": [ + "COMPLETE", + "INCOMPLETE" + ], + "title": "정산 상태", + "description": "정산 상태." + } + }, + "nullable": false, + "required": [ + "approveNo", + "settlementStatus" + ], + "description": "상품권 정보." + }, + "ITossMobilePhonePayment": { + "type": "object", + "properties": { + "mobilePhone": { + "$ref": "#/components/schemas/ITossMobilePhonePayment.IMobilePhone", + "title": "휴대폰 정보", + "description": "휴대폰 정보." + }, + "method": { + "type": "string", + "enum": [ + "휴대폰" + ], + "title": "결제 수단", + "description": "결제 수단." + }, + "type": { + "type": "string", + "enum": [ + "NORMAL" + ], + "title": "결제 타입", + "description": "결제 타입.\n\n - NORMAL: 일반 결제\n - BILLING: 미리 등록한 카드에 의한 간편 결제." + }, + "status": { + "type": "string", + "enum": [ + "READY", + "IN_PROGRESS", + "WAITING_FOR_DEPOSIT", + "DONE", + "CANCELED", + "PARTIAL_CANCELED", + "ABORTED", + "EXPIRED" + ], + "title": "결제 상태", + "description": "결제 상태.\n\n - READY\n - IN_PROGRESS\n - WAITING_FOR_DEPOSIT\n - DONE\n - CANCELED\n - PARTIAL_CANCELED\n - ABORTED\n - EXPIRED" + }, + "mId": { + "type": "string", + "title": "가맹점 ID", + "description": "가맹점 ID.\n\n현재 tosspayments 가 쓰임." + }, + "version": { + "type": "string", + "title": "사용 중인 토스 페이먼츠 API 의 버전", + "description": "사용 중인 토스 페이먼츠 API 의 버전." + }, + "paymentKey": { + "type": "string", + "title": "결제 내역의 식별자 번호", + "description": "결제 내역의 식별자 번호." + }, + "orderId": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키." + }, + "transactionKey": { + "type": "string", + "title": "거래 건에 대한 고유한 키 값", + "description": "거래 건에 대한 고유한 키 값.\n\n{@link paymentKey } 와 달리, 이를 사용할 일은 없더라." + }, + "orderName": { + "type": "string", + "title": "주문 이름", + "description": "주문 이름.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 발급한 주문명." + }, + "currency": { + "type": "string", + "title": "화폐 단위", + "description": "화폐 단위.\n\n현재 토스 페이먼츠는 KRW 만 사용 가능." + }, + "totalAmount": { + "type": "number", + "title": "총 결제 금액", + "description": "총 결제 금액." + }, + "balanceAmount": { + "type": "number", + "title": "취소할 수 있는 금액", + "description": "취소할 수 있는 금액." + }, + "suppliedAmount": { + "type": "number", + "title": "공급가액", + "description": "공급가액." + }, + "taxFreeAmount": { + "type": "number", + "title": "면세액", + "description": "면세액." + }, + "vat": { + "type": "number", + "title": "부가세", + "description": "부가세." + }, + "useEscrow": { + "type": "boolean", + "title": "에스크로 사용 여부", + "description": "에스크로 사용 여부." + }, + "cultureExpense": { + "type": "boolean", + "title": "문화비 지출 여부", + "description": "문화비 지출 여부.\n\n도석입, 공연 티켓, 박물관/미술관 입장권 등." + }, + "requestedAt": { + "type": "string", + "format": "date-time", + "title": "결제 요청 일시", + "description": "결제 요청 일시." + }, + "approvedAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "title": "결제 승인 일시", + "description": "결제 승인 일시." + }, + "cancels": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ITossPaymentCancel" + }, + "nullable": true, + "title": "결제 취소 내역", + "description": "결제 취소 내역." + }, + "cashReceipt": { + "$ref": "#/components/schemas/ITossCashReceipt.ISummary.Nullable", + "title": "현금 영수증 정보", + "description": "현금 영수증 정보." + } + }, + "nullable": false, + "required": [ + "mobilePhone", + "method", + "type", + "status", + "mId", + "version", + "paymentKey", + "orderId", + "transactionKey", + "orderName", + "currency", + "totalAmount", + "balanceAmount", + "suppliedAmount", + "taxFreeAmount", + "vat", + "useEscrow", + "cultureExpense", + "requestedAt", + "approvedAt", + "cancels", + "cashReceipt" + ], + "description": "휴대폰 결제 정보." + }, + "ITossMobilePhonePayment.IMobilePhone": { + "type": "object", + "properties": { + "carrier": { + "type": "string", + "title": "통신사", + "description": "통신사." + }, + "customerMobilePhone": { + "type": "string", + "title": "고객 휴대폰 번호", + "description": "고객 휴대폰 번호." + }, + "settlementStatus": { + "type": "string", + "enum": [ + "COMPLETED", + "INCOMPLETED" + ], + "title": "정산 상태", + "description": "정산 상태." + } + }, + "nullable": false, + "required": [ + "carrier", + "customerMobilePhone", + "settlementStatus" + ], + "description": "휴대폰 정보." + }, + "ITossTransferPayment": { + "type": "object", + "properties": { + "transfer": { + "$ref": "#/components/schemas/ITossTransferPayment.ITransfer", + "title": "계좌 이체 정보", + "description": "계좌 이체 정보." + }, + "method": { + "type": "string", + "enum": [ + "계좌이체" + ], + "title": "결제 수단", + "description": "결제 수단." + }, + "type": { + "type": "string", + "enum": [ + "NORMAL" + ], + "title": "결제 타입", + "description": "결제 타입.\n\n - NORMAL: 일반 결제\n - BILLING: 미리 등록한 카드에 의한 간편 결제." + }, + "status": { + "type": "string", + "enum": [ + "READY", + "IN_PROGRESS", + "WAITING_FOR_DEPOSIT", + "DONE", + "CANCELED", + "PARTIAL_CANCELED", + "ABORTED", + "EXPIRED" + ], + "title": "결제 상태", + "description": "결제 상태.\n\n - READY\n - IN_PROGRESS\n - WAITING_FOR_DEPOSIT\n - DONE\n - CANCELED\n - PARTIAL_CANCELED\n - ABORTED\n - EXPIRED" + }, + "mId": { + "type": "string", + "title": "가맹점 ID", + "description": "가맹점 ID.\n\n현재 tosspayments 가 쓰임." + }, + "version": { + "type": "string", + "title": "사용 중인 토스 페이먼츠 API 의 버전", + "description": "사용 중인 토스 페이먼츠 API 의 버전." + }, + "paymentKey": { + "type": "string", + "title": "결제 내역의 식별자 번호", + "description": "결제 내역의 식별자 번호." + }, + "orderId": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키." + }, + "transactionKey": { + "type": "string", + "title": "거래 건에 대한 고유한 키 값", + "description": "거래 건에 대한 고유한 키 값.\n\n{@link paymentKey } 와 달리, 이를 사용할 일은 없더라." + }, + "orderName": { + "type": "string", + "title": "주문 이름", + "description": "주문 이름.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 발급한 주문명." + }, + "currency": { + "type": "string", + "title": "화폐 단위", + "description": "화폐 단위.\n\n현재 토스 페이먼츠는 KRW 만 사용 가능." + }, + "totalAmount": { + "type": "number", + "title": "총 결제 금액", + "description": "총 결제 금액." + }, + "balanceAmount": { + "type": "number", + "title": "취소할 수 있는 금액", + "description": "취소할 수 있는 금액." + }, + "suppliedAmount": { + "type": "number", + "title": "공급가액", + "description": "공급가액." + }, + "taxFreeAmount": { + "type": "number", + "title": "면세액", + "description": "면세액." + }, + "vat": { + "type": "number", + "title": "부가세", + "description": "부가세." + }, + "useEscrow": { + "type": "boolean", + "title": "에스크로 사용 여부", + "description": "에스크로 사용 여부." + }, + "cultureExpense": { + "type": "boolean", + "title": "문화비 지출 여부", + "description": "문화비 지출 여부.\n\n도석입, 공연 티켓, 박물관/미술관 입장권 등." + }, + "requestedAt": { + "type": "string", + "format": "date-time", + "title": "결제 요청 일시", + "description": "결제 요청 일시." + }, + "approvedAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "title": "결제 승인 일시", + "description": "결제 승인 일시." + }, + "cancels": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ITossPaymentCancel" + }, + "nullable": true, + "title": "결제 취소 내역", + "description": "결제 취소 내역." + }, + "cashReceipt": { + "$ref": "#/components/schemas/ITossCashReceipt.ISummary.Nullable", + "title": "현금 영수증 정보", + "description": "현금 영수증 정보." + } + }, + "nullable": false, + "required": [ + "transfer", + "method", + "type", + "status", + "mId", + "version", + "paymentKey", + "orderId", + "transactionKey", + "orderName", + "currency", + "totalAmount", + "balanceAmount", + "suppliedAmount", + "taxFreeAmount", + "vat", + "useEscrow", + "cultureExpense", + "requestedAt", + "approvedAt", + "cancels", + "cashReceipt" + ], + "description": "계좌 이체 결제 정보." + }, + "ITossTransferPayment.ITransfer": { + "type": "object", + "properties": { + "bank": { + "type": "string", + "title": "은행명", + "description": "은행명." + }, + "settlementStatus": { + "type": "string", + "enum": [ + "COMPLETED", + "INCOMPLETED" + ], + "title": "이체 상태", + "description": "이체 상태." + } + }, + "nullable": false, + "required": [ + "bank", + "settlementStatus" + ], + "description": "계좌 이체 정보." + }, + "ITossVirtualAccountPayment": { + "type": "object", + "properties": { + "secret": { + "type": "string", + "title": "가상 계좌로 결제할 때 전달되는 입금 콜백을 검증하기 위한 값", + "description": "가상 계좌로 결제할 때 전달되는 입금 콜백을 검증하기 위한 값." + }, + "virtualAccount": { + "$ref": "#/components/schemas/ITossVirtualAccountPayment.IVirtualAccount", + "title": "가상 계좌 정보", + "description": "가상 계좌 정보." + }, + "method": { + "type": "string", + "enum": [ + "가상계좌" + ], + "title": "결제 수단", + "description": "결제 수단." + }, + "type": { + "type": "string", + "enum": [ + "NORMAL" + ], + "title": "결제 타입", + "description": "결제 타입.\n\n - NORMAL: 일반 결제\n - BILLING: 미리 등록한 카드에 의한 간편 결제." + }, + "status": { + "type": "string", + "enum": [ + "READY", + "IN_PROGRESS", + "WAITING_FOR_DEPOSIT", + "DONE", + "CANCELED", + "PARTIAL_CANCELED", + "ABORTED", + "EXPIRED" + ], + "title": "결제 상태", + "description": "결제 상태.\n\n - READY\n - IN_PROGRESS\n - WAITING_FOR_DEPOSIT\n - DONE\n - CANCELED\n - PARTIAL_CANCELED\n - ABORTED\n - EXPIRED" + }, + "mId": { + "type": "string", + "title": "가맹점 ID", + "description": "가맹점 ID.\n\n현재 tosspayments 가 쓰임." + }, + "version": { + "type": "string", + "title": "사용 중인 토스 페이먼츠 API 의 버전", + "description": "사용 중인 토스 페이먼츠 API 의 버전." + }, + "paymentKey": { + "type": "string", + "title": "결제 내역의 식별자 번호", + "description": "결제 내역의 식별자 번호." + }, + "orderId": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키." + }, + "transactionKey": { + "type": "string", + "title": "거래 건에 대한 고유한 키 값", + "description": "거래 건에 대한 고유한 키 값.\n\n{@link paymentKey } 와 달리, 이를 사용할 일은 없더라." + }, + "orderName": { + "type": "string", + "title": "주문 이름", + "description": "주문 이름.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 발급한 주문명." + }, + "currency": { + "type": "string", + "title": "화폐 단위", + "description": "화폐 단위.\n\n현재 토스 페이먼츠는 KRW 만 사용 가능." + }, + "totalAmount": { + "type": "number", + "title": "총 결제 금액", + "description": "총 결제 금액." + }, + "balanceAmount": { + "type": "number", + "title": "취소할 수 있는 금액", + "description": "취소할 수 있는 금액." + }, + "suppliedAmount": { + "type": "number", + "title": "공급가액", + "description": "공급가액." + }, + "taxFreeAmount": { + "type": "number", + "title": "면세액", + "description": "면세액." + }, + "vat": { + "type": "number", + "title": "부가세", + "description": "부가세." + }, + "useEscrow": { + "type": "boolean", + "title": "에스크로 사용 여부", + "description": "에스크로 사용 여부." + }, + "cultureExpense": { + "type": "boolean", + "title": "문화비 지출 여부", + "description": "문화비 지출 여부.\n\n도석입, 공연 티켓, 박물관/미술관 입장권 등." + }, + "requestedAt": { + "type": "string", + "format": "date-time", + "title": "결제 요청 일시", + "description": "결제 요청 일시." + }, + "approvedAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "title": "결제 승인 일시", + "description": "결제 승인 일시." + }, + "cancels": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ITossPaymentCancel" + }, + "nullable": true, + "title": "결제 취소 내역", + "description": "결제 취소 내역." + }, + "cashReceipt": { + "$ref": "#/components/schemas/ITossCashReceipt.ISummary.Nullable", + "title": "현금 영수증 정보", + "description": "현금 영수증 정보." + } + }, + "nullable": false, + "required": [ + "secret", + "virtualAccount", + "method", + "type", + "status", + "mId", + "version", + "paymentKey", + "orderId", + "transactionKey", + "orderName", + "currency", + "totalAmount", + "balanceAmount", + "suppliedAmount", + "taxFreeAmount", + "vat", + "useEscrow", + "cultureExpense", + "requestedAt", + "approvedAt", + "cancels", + "cashReceipt" + ], + "description": "가상 계좌 결제 정보." + }, + "ITossVirtualAccountPayment.IVirtualAccount": { + "type": "object", + "properties": { + "accountNumber": { + "type": "string", + "title": "계좌 번호", + "description": "계좌 번호." + }, + "accountType": { + "type": "string", + "enum": [ + "일반", + "고정" + ], + "title": "가상 계좌 타입", + "description": "가상 계좌 타입." + }, + "bank": { + "type": "string", + "title": "은행명", + "description": "은행명." + }, + "customerName": { + "type": "string", + "title": "고객 이름", + "description": "고객 이름." + }, + "dueDate": { + "type": "string", + "format": "date", + "title": "입금 기한", + "description": "입금 기한." + }, + "expired": { + "type": "boolean", + "title": "가상 계좌 만료 여부", + "description": "가상 계좌 만료 여부." + }, + "settlementStatus": { + "type": "string", + "enum": [ + "COMPLETED", + "INCOMPLETED" + ], + "title": "정산 상태", + "description": "정산 상태." + }, + "refundStatus": { + "type": "string", + "enum": [ + "COMPLETED", + "NONE", + "FAILED", + "PENDING", + "PARTIAL_FAILED" + ], + "title": "환불 처리 상태", + "description": "환불 처리 상태.\n\n - NONE: 해당 없음\n - FAILED: 환불 실패\n - PENDING: 환불 처리중\n - PARTIAL_FAILED: 부분 환불 실패\n - COMPLETED: 환불 완료" + } + }, + "nullable": false, + "required": [ + "accountNumber", + "accountType", + "bank", + "customerName", + "dueDate", + "expired", + "settlementStatus", + "refundStatus" + ], + "description": "가상 계좌 정보." + }, + "ITossCashReceipt.ICreate": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "소득공제", + "지출증빙" + ], + "title": "현금 영수증의 종류", + "description": "현금 영수증의 종류." + }, + "paymentKey": { + "type": "string", + "title": "귀속 결제의 {@link ITossPayment", + "description": "귀속 결제의 {@link ITossPayment.paymentKey }." + }, + "orderId": { + "type": "string", + "title": "주문의 식별자 ID", + "description": "주문의 식별자 ID." + }, + "orderName": { + "type": "string", + "title": "주문 이름", + "description": "주문 이름." + }, + "registrationNumber": { + "type": "string", + "title": "현금 영수증 발급을 위한 개인 식별 번호", + "description": "현금 영수증 발급을 위한 개인 식별 번호.\n\n현금 영수증의 종류에 따라 휴대폰 번호나 주민등록번호 또는 사업자등록번호 및\n카드 번호를 입력할 수 있다." + }, + "amount": { + "type": "number", + "title": "현금 영수증을 발행할 금액", + "description": "현금 영수증을 발행할 금액." + }, + "taxFreeAmount": { + "type": "number", + "title": "면세 금액", + "description": "면세 금액." + }, + "businessNumber": { + "type": "string", + "title": "사업자 등록번호", + "description": "사업자 등록번호." + } + }, + "nullable": false, + "required": [ + "type", + "paymentKey", + "orderId", + "orderName", + "registrationNumber", + "amount" + ], + "description": "현금 영수증 입력 정보." + }, + "ITossCashReceipt": { + "type": "object", + "properties": { + "receiptKey": { + "type": "string", + "title": "현금 영수증의 식별자 키", + "description": "현금 영수증의 식별자 키." + }, + "type": { + "$ref": "#/components/schemas/ITossCashReceipt.Type", + "title": "현금 영수증의 종류", + "description": "현금 영수증의 종류." + }, + "orderId": { + "type": "string", + "title": "주문의 식별자 ID", + "description": "주문의 식별자 ID." + }, + "orderName": { + "type": "string", + "title": "주문 이름", + "description": "주문 이름." + }, + "approvalNumber": { + "type": "string", + "title": "현금 영수증 승인 번호", + "description": "현금 영수증 승인 번호." + }, + "approvedAt": { + "type": "string", + "format": "date-time", + "title": "현금 영수증 승인 일시", + "description": "현금 영수증 승인 일시." + }, + "canceledAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "title": "현금 영수증 취소 일시", + "description": "현금 영수증 취소 일시." + }, + "receiptUrl": { + "type": "string", + "title": "영수증 URL", + "description": "영수증 URL." + } + }, + "nullable": false, + "required": [ + "receiptKey", + "type", + "orderId", + "orderName", + "approvalNumber", + "approvedAt", + "canceledAt", + "receiptUrl" + ], + "description": "현금 영수증 정보." + }, + "ITossCashReceipt.ICancel": { + "type": "object", + "properties": { + "amount": { + "type": "number", + "title": "취소 금액", + "description": "취소 금액.\n\n미 입력시 현금 영수증에 기재된 {@link ITossCashReceipt.amount 총액}이 취소됨." + } + }, + "nullable": false, + "description": "현금 영수증 취소 입력 정보." + }, + "ITossPaymentWebhook": { + "type": "object", + "properties": { + "eventType": { + "type": "string", + "enum": [ + "PAYMENT_STATUS_CHANGED" + ], + "title": "이벤트 타입", + "description": "이벤트 타입." + }, + "data": { + "$ref": "#/components/schemas/ITossPaymentWebhook.IData", + "title": "이벤트 데이터", + "description": "이벤트 데이터." + } + }, + "nullable": false, + "required": [ + "eventType", + "data" + ], + "description": "웹훅 이벤트 정보." + }, + "ITossPaymentWebhook.IData": { + "type": "object", + "properties": { + "paymentKey": { + "type": "string", + "title": "{@link ITossPayment } 의 식별자 키", + "description": "{@link ITossPayment } 의 식별자 키." + }, + "orderId": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키." + }, + "status": { + "type": "string", + "enum": [ + "WAITING_FOR_DEPOSIT", + "DONE", + "CANCELED", + "PARTIAL_CANCELED" + ], + "title": "결제 상태", + "description": "결제 상태.\n\n - DONE: 결제 완료\n - CANCELED: 결제가 취소됨\n - PARTIAL_CANCELED: 결제가 부분 취소됨\n - WAITING_FOR_DEPOSIT: 입금 대기 중" + } + }, + "nullable": false, + "required": [ + "paymentKey", + "orderId", + "status" + ], + "description": "웹훅 이벤트 데이터." + }, + "ITossCardPayment.ICreate": { + "type": "object", + "properties": { + "method": { + "type": "string", + "enum": [ + "card" + ], + "title": "결제 수단이 신용 카드임을 의미", + "description": "결제 수단이 신용 카드임을 의미." + }, + "cardNumber": { + "type": "string", + "pattern": "[0-9]{16}", + "title": "카드 번호", + "description": "카드 번호." + }, + "cardExpirationYear": { + "type": "string", + "pattern": "\\d{2}", + "title": "카드 만료 년도 (2 자리)", + "description": "카드 만료 년도 (2 자리)." + }, + "cardExpirationMonth": { + "type": "string", + "pattern": "^(0[1-9]|1[012])$", + "title": "카드 만료 월 (2 자리)", + "description": "카드 만료 월 (2 자리)." + }, + "cardPassword": { + "type": "string", + "title": "카드 비밀번호", + "description": "카드 비밀번호." + }, + "cardInstallmentPlan": { + "type": "number", + "title": "할부 개월 수", + "description": "할부 개월 수." + }, + "amount": { + "type": "number", + "title": "지불 총액", + "description": "지불 총액." + }, + "taxFreeAmount": { + "type": "number", + "title": "면세금 총액", + "description": "면세금 총액." + }, + "orderId": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키." + }, + "orderName": { + "type": "string", + "title": "주문 이름", + "description": "주문 이름.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 발급한 주문명." + }, + "customerBirthday": { + "type": "string", + "pattern": "^([0-9]{2})(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$", + "title": "고객의 생년월일", + "description": "고객의 생년월일.\n\n표기 형식 YYMMDD." + }, + "customerEmail": { + "type": "string", + "format": "email", + "title": "고객의 이메일", + "description": "고객의 이메일." + }, + "vbv": { + "type": "object", + "properties": { + "cavv": { + "type": "string", + "title": "3D Secure 인증 세션에 대한 인증 값", + "description": "3D Secure 인증 세션에 대한 인증 값." + }, + "xid": { + "type": "string", + "title": "트랜잭션 ID", + "description": "트랜잭션 ID." + }, + "eci": { + "type": "string", + "title": "3DS 인증 결과에 대한 코드 값", + "description": "3DS 인증 결과에 대한 코드 값." + } + }, + "nullable": false, + "required": [ + "cavv", + "xid", + "eci" + ], + "title": "해외카드로 결제하는 경우 3DS 인증 적용을 위해 사용", + "description": "해외카드로 결제하는 경우 3DS 인증 적용을 위해 사용.\n\n3DS 인증 결과를 전송해야 하는 경우에만 필수." + }, + "__approved": { + "type": "boolean", + "title": "결제 승인 여부", + "description": "결제 승인 여부.\n\n오직 가짜 페이먼츠 서버 `fake-toss-payments-server` 에서만 사용되는 값으로써,\n결제 승인을 고의로 지연시키거나 할 때 사용된다. 이 값을 `false` 로 하면, 프론트\n어플리케이션이 토스 페이먼츠가 제공해주는 결제 창을 사용하여 결제를 진행하는\n상황을 시뮬레이션할 수 있다.\n\n본디 토스 페이먼츠 서버는 프론트 어플리케이션에서 백엔드 서버를 거치지 않고,\n토스 페이먼츠가 제공해주는 결제 창을 이용하여 직접 결제를 요청하는 경우,\n백엔드에서 이를 별도 {@link functional.payments.approve 승인} 처리해주기 전까지\n정식 결제로 인청치 아니한다.\n\n반면 백엔드 서버에서 토스 페이먼츠 서버의 API 를 호출하는 경우, 토스 페이먼츠는\n이를 그 즉시로 승인해주기, `fake-toss-payments-server` 에서 별도의 승인 처리가\n필요한 상황을 시뮬레이션하기 위해서는 이러한 속성이 필요한 것." + } + }, + "nullable": false, + "required": [ + "method", + "cardNumber", + "cardExpirationYear", + "cardExpirationMonth", + "amount", + "orderId" + ], + "description": "신용 카드를 이용한 결제 신청 정보." + }, + "ITossPayment.IApproval": { + "type": "object", + "properties": { + "orderId": { + "type": "string", + "title": "주문 식별자 키", + "description": "주문 식별자 키.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키." + }, + "amount": { + "type": "number", + "title": "결제 총액", + "description": "결제 총액." + } + }, + "nullable": false, + "required": [ + "orderId", + "amount" + ], + "description": "결제 승인 정보." + }, + "ITossPaymentCancel.ICreate": { + "type": "object", + "properties": { + "paymentKey": { + "type": "string", + "title": "{@link ITossPayment } 의 식별자 키", + "description": "{@link ITossPayment } 의 식별자 키." + }, + "cancelReason": { + "type": "string", + "title": "취소 사유", + "description": "취소 사유." + }, + "cancelAmount": { + "type": "number", + "title": "취소 총액", + "description": "취소 총액." + }, + "refundReceiveAccount": { + "type": "object", + "properties": { + "bank": { + "type": "string", + "title": "은행 정보", + "description": "은행 정보." + }, + "accountNumber": { + "type": "string", + "pattern": "^[0-9]{0,20}$", + "title": "계좌 번호", + "description": "계좌 번호." + }, + "holderName": { + "type": "string", + "title": "예금주", + "description": "예금주." + } + }, + "nullable": false, + "required": [ + "bank", + "accountNumber", + "holderName" + ], + "title": "환불 계좌 정보", + "description": "환불 계좌 정보.\n\n결제를 가상 계좌로 하였을 때에만 해당함." + }, + "taxAmount": { + "type": "number", + "title": "과세 처리 금액", + "description": "과세 처리 금액." + }, + "taxFreeAmount": { + "type": "number", + "title": "면세 처리 금액", + "description": "면세 처리 금액." + }, + "refundableAmount": { + "type": "number", + "title": "결제 취소 후 환불 가능 잔액", + "description": "결제 취소 후 환불 가능 잔액." + } + }, + "nullable": false, + "required": [ + "paymentKey", + "cancelReason" + ], + "description": "결제 취소 신청 정보." + }, + "ITossVirtualAccountPayment.ICreate": { + "type": "object", + "properties": { + "method": { + "type": "string", + "enum": [ + "virtual-account" + ], + "title": "결제 수단이 가상 계좌임을 의미", + "description": "결제 수단이 가상 계좌임을 의미." + }, + "orderId": { + "type": "string", + "title": "주문 식별자 번호", + "description": "주문 식별자 번호.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 자체적으로 관리하는 식별자 키." + }, + "orderName": { + "type": "string", + "title": "주문 이름", + "description": "주문 이름.\n\n토스 페이먼츠가 아닌, 이를 이용하는 서비스에서 발급한 주문명." + }, + "bank": { + "type": "string", + "title": "은행명", + "description": "은행명." + }, + "customerName": { + "type": "string", + "title": "고객 이름", + "description": "고객 이름." + }, + "amount": { + "type": "number", + "title": "결제 총액", + "description": "결제 총액." + }, + "__approved": { + "type": "boolean", + "title": "결제 승인 여부", + "description": "결제 승인 여부.\n\n오직 가짜 페이먼츠 서버 `fake-toss-payments-server` 에서만 사용되는 값으로써,\n결제 승인을 고의로 지연시키거나 할 때 사용된다. 이 값을 `false` 로 하면, 프론트\n어플리케이션이 토스 페이먼츠가 제공해주는 결제 창을 사용하여 결제를 진행하는\n상황을 시뮬레이션할 수 있다.\n\n본디 토스 페이먼츠 서버는 프론트 어플리케이션에서 백엔드 서버를 거치지 않고,\n토스 페이먼츠가 제공해주는 결제 창을 이용하여 직접 결제를 요청하는 경우,\n백엔드에서 이를 별도 {@link functional.payments.approve 승인} 처리해주기 전까지\n정식 결제로 인청치 아니한다.\n\n반면 백엔드 서버에서 토스 페이먼츠 서버의 API 를 호출하는 경우, 토스 페이먼츠는\n이를 그 즉시로 승인해주기, `fake-toss-payments-server` 에서 별도의 승인 처리가\n필요한 상황을 시뮬레이션하기 위해서는 이러한 속성이 필요한 것." + } + }, + "nullable": false, + "required": [ + "method", + "orderId", + "orderName", + "bank", + "customerName", + "amount" + ], + "description": "가상 계좌를 이용한 결제 신청 정보." + } + }, + "securitySchemes": { + "basic": { + "type": "apiKey", + "name": "Authorization", + "in": "header" + } + } + } +} \ No newline at end of file