generated from samchon/backend
-
-
Notifications
You must be signed in to change notification settings - Fork 29
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #161 from samchon/features/integrate
Documentation about integration
- Loading branch information
Showing
25 changed files
with
15,169 additions
and
907 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| MIT License | ||
|
|
||
| Copyright (c) 2021 Samchon | ||
|
|
||
| Permission is hereby granted, free of charge, to any person obtaining a copy | ||
| of this software and associated documentation files (the "Software"), to deal | ||
| in the Software without restriction, including without limitation the rights | ||
| to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | ||
| copies of the Software, and to permit persons to whom the Software is | ||
| furnished to do so, subject to the following conditions: | ||
|
|
||
| The above copyright notice and this permission notice shall be included in all | ||
| copies or substantial portions of the Software. | ||
|
|
||
| THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | ||
| IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | ||
| FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | ||
| AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | ||
| LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | ||
| OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE | ||
| SOFTWARE. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,12 +1,171 @@ | ||
| # Payment System | ||
| 결제 시스템. | ||
| # Payments System | ||
| ## Outline | ||
| [](https://github.com/samchon/payments/tree/master/LICENSE) | ||
| [](https://github.com/samchon/payments/actions?query=workflow%3Abuild) | ||
|
|
||
| - fake-iamport-server | ||
| - fake-toss-payments-server | ||
| - payment-backend | ||
| 통합 결제 시스템과 PG사 연동 라이브러리 모음. | ||
|
|
||
| 이하 클라이언트용 SDK 라이브러리. | ||
| 본 저장소 `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) 를 고려하여 설계된 프로젝트로써, 귀하의 서비스 중 결제 부문만을 따로이 분리하여 관리할 수 있게 해 준다. | ||
|
|
||
| - iamport-server-api | ||
| - toss-payments-server-api | ||
| - payment-api | ||
| 더하여 [통합 결제 시스템](https://github.com/samchon/payments/tree/master/packages/payment-backend)이 연동하게 될 PG 사들의 목업 서버를 구현, 이들을 통하여 백엔드 수준의 테스트 자동화 프로그램을 구성할 수 있도록 해준다. 이는 결제 PG 사들이 프론트 어플리케이션과 연동한 수기 테스트를 필요로 하기에, [통합 결제 시스템](https://github.com/samchon/payments/tree/master/packages/payment-backend)이 자동화된 테스트 프로그램을 구성할 수 없음에 따른, 테스트 커버리지의 하락을 해결하기 위함이다. | ||
|
|
||
| - [`payment-backend`](https://github.com/samchon/payments/tree/master/packages/payment-backend): 통합 결제 시스템 | ||
| - [`fake-iamport-server`](https://github.com/samchon/payments/tree/master/packages/fake-iamport-server): 아임포트 목업 서버 | ||
| - [`fake-toss-payments-server`](https://github.com/samchon/payments/tree/master/packages/fake-toss-payments-server): 토스 페이먼츠 목업 서버 | ||
|
|
||
| 더불어 본 저장소 `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 를 활용한 간편하고 타입 안전한 개발 사례의 하나. | ||
|
|
||
| - [`payment-api`](https://github.com/samchon/payments/tree/master/packages/payment-api): 통합 결제 시스템 연동 API | ||
| - [`iamport-server-api`](https://github.com/samchon/payments/tree/master/packages/iamport-server-api): 아임포트 서버 연동 API | ||
| - [`toss-payments-server-api`](https://github.com/samchon/payments/tree/master/packages/toss-payments-server-api): 토스 페이먼츠 서버 연동 API | ||
|
|
||
| ```typescript | ||
| import { TestValidator } from "@nestia/e2e"; | ||
| import api from "payment-api"; | ||
| import { IPaymentHistory } from "payment-api/lib/structures/payments/IPaymentHistory"; | ||
| import { IPaymentWebhookHistory } from "payment-api/lib/structures/payments/IPaymentWebhookHistory"; | ||
| import toss from "toss-payments-server-api"; | ||
| import { ITossPayment } from "toss-payments-server-api/lib/structures/ITossPayment"; | ||
| import { sleep_for } from "tstl/thread/global"; | ||
| import typia from "typia"; | ||
| import { v4 } from "uuid"; | ||
|
|
||
| import { PaymentConfiguration } from "../../../src"; | ||
| import { FakePaymentStorage } from "../../../src/providers/payments/FakePaymentStorage"; | ||
| import { TossAsset } from "../../../src/services/toss/TossAsset"; | ||
|
|
||
| export async function test_api_toss_vbank_payment( | ||
| connection: api.IConnection, | ||
| ): Promise<IPaymentHistory> { | ||
| //---- | ||
| // 결제의 원천이 되는 주문 정보 | ||
| //---- | ||
| /** | ||
| * 귀하의 백엔드 서버가 발행한 주문 ID. | ||
| */ | ||
| const yourOrderId: string = v4(); | ||
|
|
||
| /** | ||
| * 주문 금액. | ||
| */ | ||
| const yourOrderPrice: number = 19_900; | ||
|
|
||
| /* ----------------------------------------------------------- | ||
| 결제 내역 등록 | ||
| ----------------------------------------------------------- */ | ||
| /** | ||
| * 토스 페이먼츠 시뮬레이션 | ||
| * | ||
| * 고객이 프론트 어플리케이션에서, 토스 페이먼츠가 제공하는 팝업 창을 이용, 카드 결제를 | ||
| * 하는 상황을 시뮬레이션 한다. 고객이 카드 결제를 마치거든, 프론트 어플리케이션에 | ||
| * {@link ITossPayment.paymentKey} 가 전달된다. | ||
| * | ||
| * 이 {@link ITossPayment.paymentKey} 와 귀하의 백엔드에서 직접 생성한 | ||
| * {@link ITossPayment.orderId yourOrderId} 를 잘 기억해두었다가, 이를 다음 단계인 | ||
| * {@link IPaymentHistory} 등록에 사용하도록 하자. | ||
| */ | ||
| const payment: ITossPayment = | ||
| await toss.functional.v1.virtual_accounts.store( | ||
| await TossAsset.connection("test-toss-payments-store-id"), | ||
| { | ||
| // 가상 계좌 정보 | ||
| method: "virtual-account", | ||
| bank: "신한", | ||
| customerName: "Samchon", | ||
|
|
||
| // 주문 정보 | ||
| orderId: yourOrderId, | ||
| orderName: "something", | ||
| amount: yourOrderPrice, | ||
|
|
||
| // 고의 미승인 처리 | ||
| __approved: false, | ||
| }, | ||
| ); | ||
| typia.assert(payment); | ||
|
|
||
| /** | ||
| * 웹훅 URL 설정하기. | ||
| * | ||
| * 웹훅 URL 을 테스트용 API 주소, internal.webhook 으로 설정. | ||
| */ | ||
| const webhook_url: string = `http://127.0.0.1:${PaymentConfiguration.API_PORT()}${ | ||
| api.functional.payments.internal.webhook.METADATA.path | ||
| }`; | ||
|
|
||
| /** | ||
| * 결제 이력 등록하기. | ||
| * | ||
| * 앞서 토스 페이먼츠의 팝업 창을 이용하여 가상 계좌 결제를 진행하고 발급받은 | ||
| * {@link ITossPayment.paymentKey}, 그리고 귀하의 백엔드에서 직접 생성한 | ||
| * {@link ITossPayment.orderId yourOrderId} 를 각각 {@link IPaymentVendor.uid} 와 | ||
| * {@link IPaymentSource.id} 로 할당하여 {@link IPaymentReservation} 레코드를 | ||
| * 발행한다. | ||
| * | ||
| * 참고로 결제 이력을 등록할 때 반드시 비밀번호를 설정해야 하는데, 향후 결제 이력을 | ||
| * 조회할 때 필요하니, 이를 반드시 귀하의 백엔드 서버에 저장해두도록 한다. | ||
| */ | ||
| const history: IPaymentHistory = | ||
| await api.functional.payments.histories.store(connection, { | ||
| vendor: { | ||
| code: "toss.payments", | ||
| store_id: "test-toss-payments-store-id", | ||
| uid: payment.paymentKey, | ||
| }, | ||
| source: { | ||
| schema: "some-schema", | ||
| table: "some-table", | ||
| id: yourOrderId, | ||
| }, | ||
| webhook_url, // 테스트용 웹훅 URL | ||
| price: yourOrderPrice, | ||
| password: "some-password", | ||
| }); | ||
| typia.assert(history); | ||
|
|
||
| /* ----------------------------------------------------------- | ||
| 웹훅 이벤트 리스닝 | ||
| ----------------------------------------------------------- */ | ||
| /** | ||
| * 입금 시뮬레이션하기. | ||
| * | ||
| * 고객이 자신 앞을 발급된 계좌에, 결제 금액을 입금하는 상황 시뮬레이션. | ||
| */ | ||
| await toss.functional.internal.deposit( | ||
| await TossAsset.connection("test-toss-payments-store-id"), | ||
| payment.paymentKey, | ||
| ); | ||
|
|
||
| // 웹훅 이벤트가 귀하의 백엔드 서버로 전달되기를 기다림. | ||
| await sleep_for(1_000); | ||
|
|
||
| /** | ||
| * 웹흑 리스닝 시뮬레이션. | ||
| * | ||
| * 귀하의 백엔드 서버가 웹훅 이벤트를 수신한 상황을 가정한다. | ||
| */ | ||
| const webhook: IPaymentWebhookHistory | undefined = | ||
| FakePaymentStorage.webhooks.back(); | ||
|
|
||
| // 이하 웹훅 데이터를 통한 입금 여부 검증 | ||
| TestValidator.equals("webhook")(!!webhook)(true); | ||
| TestValidator.equals("history.id")(history.id)(webhook?.current.id); | ||
| TestValidator.equals("paid_at")(!webhook?.previous.paid_at)(false); | ||
| TestValidator.equals("paid_at")(!!webhook?.current.paid_at)(true); | ||
|
|
||
| // 웹훅 데이터 삭제 | ||
| FakePaymentStorage.webhooks.pop_back(); | ||
|
|
||
| return history; | ||
| } | ||
| ``` | ||
|
|
||
|
|
||
|
|
||
|
|
||
| ## Setup | ||
| 본 [통합 결제 시스템](https://github.com/samchon/payments/tree/master/packages/payment-backend)은 NodeJS 및 Postgres 가 필요하다. | ||
|
|
||
| [통합 결제 시스템](https://github.com/samchon/payments/tree/master/packages/payment-backend)의 설치 매뉴얼을 읽고, 이를 잘 따라하도록 하자. | ||
|
|
||
| - [설치 매뉴얼](https://github.com/samchon/payments/tree/master/packages/payment-backend#2-installation) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.