{"id":15043898,"url":"https://github.com/samchon/payments","last_synced_at":"2025-05-15T11:06:43.432Z","repository":{"id":39675873,"uuid":"432478265","full_name":"samchon/payments","owner":"samchon","description":"Korean Payment System with Mockup servers of PGs","archived":false,"fork":false,"pushed_at":"2025-03-04T10:07:50.000Z","size":1772,"stargazers_count":342,"open_issues_count":2,"forks_count":31,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-15T09:50:30.201Z","etag":null,"topics":["fake","iamport","korea","nestia","nestjs","payment","server","toss","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samchon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["samchon"]}},"created_at":"2021-11-27T14:09:34.000Z","updated_at":"2025-05-14T02:13:56.000Z","dependencies_parsed_at":"2023-09-20T14:39:33.873Z","dependency_job_id":"ef73db07-70f7-4b60-9319-448dbdad2b7f","html_url":"https://github.com/samchon/payments","commit_stats":{"total_commits":151,"total_committers":6,"mean_commits":"25.166666666666668","dds":"0.42384105960264906","last_synced_commit":"9cc02f5f1e5572f369610fb339b853a1b5982605"},"previous_names":["samchon/payments","samchon/fake-toss-payments-server"],"tags_count":36,"template":false,"template_full_name":"samchon/backend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samchon%2Fpayments","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samchon%2Fpayments/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samchon%2Fpayments/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samchon%2Fpayments/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samchon","download_url":"https://codeload.github.com/samchon/payments/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254319700,"owners_count":22051071,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fake","iamport","korea","nestia","nestjs","payment","server","toss","typescript"],"created_at":"2024-09-24T20:49:47.879Z","updated_at":"2025-05-15T11:06:43.414Z","avatar_url":"https://github.com/samchon.png","language":"TypeScript","funding_links":["https://github.com/sponsors/samchon"],"categories":[],"sub_categories":[],"readme":"# Payments System\n## Outline\n[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/samchon/payments/tree/master/LICENSE)\n[![Build Status](https://github.com/samchon/payments/workflows/build/badge.svg)](https://github.com/samchon/payments/actions?query=workflow%3Abuild)\n\n통합 결제 시스템과 PG사 연동 라이브러리 모음.\n\n본 저장소 `@samchon/payments` 는 [통합 결제 시스템](https://github.com/samchon/payments/tree/master/packages/payment-backend)과 PG 사 연동 라이브러리를 모아놓은 저장소이다. 여기서 말하는 [통합 결제 시스템](https://github.com/samchon/payments/tree/master/packages/payment-backend)이란, [아임포트](https://github.com/samchon/payments/tree/master/packages/fake-iamport-server)와 [토스 페이먼츠](https://github.com/samchon/payments/tree/master/packages/fake-toss-payments-server) 등의 PG사들을 일괄 관리할 수 있는 시스템을 뜻한다. 더하여 [통합 결제 시스템](https://github.com/samchon/payments/tree/master/packages/payment-backend)은 MSA (Micro Service Architecture) 를 고려하여 설계된 프로젝트로써, 귀하의 서비스 중 결제 부문만을 따로이 분리하여 관리할 수 있게 해 준다.\n\n더하여 [통합 결제 시스템](https://github.com/samchon/payments/tree/master/packages/payment-backend)이 연동하게 될 PG 사들의 목업 서버를 구현, 이들을 통하여 백엔드 수준의 테스트 자동화 프로그램을 구성할 수 있도록 해준다. 이는 결제 PG 사들이 프론트 어플리케이션과 연동한 수기 테스트를 필요로 하기에, [통합 결제 시스템](https://github.com/samchon/payments/tree/master/packages/payment-backend)이 자동화된 테스트 프로그램을 구성할 수 없음에 따른, 테스트 커버리지의 하락을 해결하기 위함이다.\n\n  - [`@samchon/payment-backend`](https://github.com/samchon/payments/tree/master/packages/payment-backend): 통합 결제 시스템\n  - [`fake-iamport-server`](https://github.com/samchon/payments/tree/master/packages/fake-iamport-server): 아임포트 목업 서버\n  - [`fake-toss-payments-server`](https://github.com/samchon/payments/tree/master/packages/fake-toss-payments-server): 토스 페이먼츠 목업 서버\n\n더불어 본 저장소 `@samchon/payments` 는 [통합 결제 시스템](https://github.com/samchon/payments/tree/master/packages/payment-backend) 및 각각의 PG 사와 연동할 수 있는 SDK (Software Development Kit) 라이브러리들을 제공한다. 귀하는 이를 통하여 [통합 결제 시스템](https://github.com/samchon/payments/tree/master/packages/payment-backend) 및 PG 사 서버와 매우 간편하게, 또한 타입 안전하게 연동할 수 있다. 아래 예제 코드 또한, 이러한 SDK 를 활용한 간편하고 타입 안전한 개발 사례의 하나.\n \n  - [`@samchon/payment-api`](https://github.com/samchon/payments/tree/master/packages/payment-api): 통합 결제 시스템 연동 API\n  - [`iamport-server-api`](https://github.com/samchon/payments/tree/master/packages/iamport-server-api): 아임포트 서버 연동 API\n  - [`toss-payments-server-api`](https://github.com/samchon/payments/tree/master/packages/toss-payments-server-api): 토스 페이먼츠 서버 연동 API\n\n```typescript\nimport { TestValidator } from \"@nestia/e2e\";\nimport api from \"@samchon/payment-api\";\nimport { IPaymentHistory } from \"@samchon/payment-api/lib/structures/payments/IPaymentHistory\";\nimport { IPaymentWebhookHistory } from \"@samchon/payment-api/lib/structures/payments/IPaymentWebhookHistory\";\nimport toss from \"toss-payments-server-api\";\nimport { ITossPayment } from \"toss-payments-server-api/lib/structures/ITossPayment\";\nimport { sleep_for } from \"tstl/thread/global\";\nimport typia from \"typia\";\nimport { v4 } from \"uuid\";\n\nimport { PaymentConfiguration } from \"../../../src\";\nimport { FakePaymentStorage } from \"../../../src/providers/payments/FakePaymentStorage\";\nimport { TossAsset } from \"../../../src/services/toss/TossAsset\";\n\nexport async function test_api_toss_vbank_payment(\n    connection: api.IConnection,\n): Promise\u003cIPaymentHistory\u003e {\n    //----\n    // 결제의 원천이 되는 주문 정보\n    //----\n    /**\n     * 귀하의 백엔드 서버가 발행한 주문 ID.\n     */\n    const yourOrderId: string = v4();\n\n    /**\n     * 주문 금액.\n     */\n    const yourOrderPrice: number = 19_900;\n\n    /* -----------------------------------------------------------\n        결제 내역 등록\n    ----------------------------------------------------------- */\n    /**\n     * 토스 페이먼츠 시뮬레이션\n     *\n     * 고객이 프론트 어플리케이션에서, 토스 페이먼츠가 제공하는 팝업 창을 이용, 카드 결제를\n     * 하는 상황을 시뮬레이션 한다. 고객이 카드 결제를 마치거든, 프론트 어플리케이션에\n     * {@link ITossPayment.paymentKey} 가 전달된다.\n     *\n     * 이 {@link ITossPayment.paymentKey} 와 귀하의 백엔드에서 직접 생성한\n     * {@link ITossPayment.orderId yourOrderId} 를 잘 기억해두었다가, 이를 다음 단계인\n     * {@link IPaymentHistory} 등록에 사용하도록 하자.\n     */\n    const payment: ITossPayment =\n        await toss.functional.v1.virtual_accounts.create(\n            await TossAsset.connection(\"test-toss-payments-create-id\"),\n            {\n                // 가상 계좌 정보\n                method: \"virtual-account\",\n                bank: \"신한\",\n                customerName: \"Samchon\",\n\n                // 주문 정보\n                orderId: yourOrderId,\n                orderName: \"something\",\n                amount: yourOrderPrice,\n\n                // 고의 미승인 처리\n                __approved: false,\n            },\n        );\n    typia.assert(payment);\n\n    /**\n     * 웹훅 URL 설정하기.\n     *\n     * 웹훅 URL 을 테스트용 API 주소, internal.webhook 으로 설정.\n     */\n    const webhook_url: string = `http://127.0.0.1:${PaymentConfiguration.API_PORT()}${\n        api.functional.payments.internal.webhook.METADATA.path\n    }`;\n\n    /**\n     * 결제 이력 등록하기.\n     *\n     * 앞서 토스 페이먼츠의 팝업 창을 이용하여 가상 계좌 결제를 진행하고 발급받은\n     * {@link ITossPayment.paymentKey}, 그리고 귀하의 백엔드에서 직접 생성한\n     * {@link ITossPayment.orderId yourOrderId} 를 각각 {@link IPaymentVendor.uid} 와\n     * {@link IPaymentSource.id} 로 할당하여 {@link IPaymentReservation} 레코드를\n     * 발행한다.\n     *\n     * 참고로 결제 이력을 등록할 때 반드시 비밀번호를 설정해야 하는데, 향후 결제 이력을\n     * 조회할 때 필요하니, 이를 반드시 귀하의 백엔드 서버에 저장해두도록 한다.\n     */\n    const history: IPaymentHistory =\n        await api.functional.payments.histories.create(connection, {\n            vendor: {\n                code: \"toss.payments\",\n                store_id: \"test-toss-payments-create-id\",\n                uid: payment.paymentKey,\n            },\n            source: {\n                schema: \"some-schema\",\n                table: \"some-table\",\n                id: yourOrderId,\n            },\n            webhook_url, // 테스트용 웹훅 URL\n            price: yourOrderPrice,\n            password: \"some-password\",\n        });\n    typia.assert(history);\n\n    /* -----------------------------------------------------------\n        웹훅 이벤트 리스닝\n    ----------------------------------------------------------- */\n    /**\n     * 입금 시뮬레이션하기.\n     *\n     * 고객이 자신 앞을 발급된 계좌에, 결제 금액을 입금하는 상황 시뮬레이션.\n     */\n    await toss.functional.internal.deposit(\n        await TossAsset.connection(\"test-toss-payments-create-id\"),\n        payment.paymentKey,\n    );\n\n    // 웹훅 이벤트가 귀하의 백엔드 서버로 전달되기를 기다림.\n    await sleep_for(1_000);\n\n    /**\n     * 웹흑 리스닝 시뮬레이션.\n     *\n     * 귀하의 백엔드 서버가 웹훅 이벤트를 수신한 상황을 가정한다.\n     */\n    const webhook: IPaymentWebhookHistory | undefined =\n        FakePaymentStorage.webhooks.back();\n\n    // 이하 웹훅 데이터를 통한 입금 여부 검증\n    TestValidator.equals(\"webhook\")(!!webhook)(true);\n    TestValidator.equals(\"history.id\")(history.id)(webhook?.current.id);\n    TestValidator.equals(\"paid_at\")(!!webhook?.previous.paid_at)(false);\n    TestValidator.equals(\"paid_at\")(!!webhook?.current.paid_at)(true);\n\n    // 웹훅 데이터 삭제\n    FakePaymentStorage.webhooks.pop_back();\n\n    return history;\n}\n```\n\n\n\n\n## Setup\n본 [통합 결제 시스템](https://github.com/samchon/payments/tree/master/packages/payment-backend)은 NodeJS 및 Postgres 가 필요하다.\n\n[통합 결제 시스템](https://github.com/samchon/payments/tree/master/packages/payment-backend)의 설치 매뉴얼을 읽고, 이를 잘 따라하도록 하자.\n\n  - [설치 매뉴얼](https://github.com/samchon/payments/tree/master/packages/payment-backend#2-installation)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamchon%2Fpayments","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamchon%2Fpayments","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamchon%2Fpayments/lists"}