Node.js SDK library for fincode byGMO

fincode for Node.jsはJavaScript/TypeScriptプロジェクトにおけるfincode APIの呼び出しを支援するAPIラッパーライブラリです。APIの呼び出しを支援するヘルパー関数とTypeScriptの型定義を提供し、型安全性を保ちつつ可読性の高いfincodeの組み込みを可能にします。

このライブラリはサーバーサイドNode.jsプロジェクトでの利用を想定しています。ブラウザ上で動作するアプリケーションにおいてfincodeを使用したい場合はfincode for ES Moduleを利用できます。

Getting Started

プロジェクトでnpmを使っている場合、npm経由でfincode for Node.jsをインストールできます。

$ npm i @fincode/node

# yarnやpnpmなど、npmと互換のあるパッケージ管理システムによるインストールも可能です。
$ yarn add @fincode/node

Usage

1. fincodeの管理画面からAPIキーを取得

テスト環境や本番環境の管理画面からAPIキーを取得します。

APIキーはシークレットキーである必要があります。

2. パッケージマネージャーからインストール

Getting Startedの手順に従い @fincode/node をプロジェクトにインストールします。

3. fincodeインスタンスの作成

createFincodeメソッドを呼び出し、fincodeインスタンスを作成します。

import { createFincode } from "@fincode/node"

const fincode = createFincode({
    apiKey: "m_****_**********", // Secret key
    isLiveMode: true,  // fincode Environment. true: Live mode, false: Test mode. default: false
    
    // Optional,
    options: {   
        // API Version
        version: "20211101",
        // Timeout
        timeout: 10000,
        // Proxy
        proxyAgent: "http://url.to.proxy:8080"
    }
})

(async () => {
    
    // Register a payment with idempotent key
    const createdPayment = await fincode.payments.create({
        pay_type: "Card",
        job_code: "CAPTURE",
        amount: "3000"
    }, {
        idempotentKey: "{{idempotent key}}"
    })
    // Execute a payment
    const executedPayment = await fincode.payment.execute(
        payment.id,
        {
            pay_type: createdPayment.pay_type,
            access_id: createdPayment.access_id,
            customer_id: "{{id of customer}}",
            card_id: "{{id of customer's card}}",
        }
    )
    // Retrieve a payment
    const payment = await fincode.payments.retrieve(executedPayment.id, { pay_type : "Card" })

    // Retrieve a list of payments
    const payments = await fincode.payments.retrieveList({
        pay_type: "Card",
        limit: 10,
        page: 1,
        total_amount_min: 1000,
        total_amount_max: 10000,
    })
})()

Call fincode API

fincodeインスタンスを作成することでfincode APIを呼び出すことができます。 fincodeインスタンスが持つメソッドは下記のように各APIと対応しています。

クエリパラメーターとヘッダー

ヘッダーはすべてのAPI呼び出しのオプショナル引数として渡すことができます。 ヘッダー情報は下記のようなオブジェクトに格納します。

{
    // idempotent_key に対応。冪等キー。
    idempotentKey?: string | undefined;
    // Tenant-Shops-Id に対応。テナントショップID。
    tenantShopId?: string | undefined;
    // Content-Type に対応。コンテンツタイプ。
    contentType?: string | undefined;
}

また、一覧取得APIなど一部のAPI呼び出しではオプショナル引数としてクエリパラメーターを渡すことができます。 クエリパラメーターは下記のようなオブジェクトに格納します。

{
    limit?: string | number | null
    page?: string | number | null
    count_only?: boolean | null
    // その他APIによって異なるクエリパラメーター
}

Payment API （決済API）

| API | | URL | 呼び出し方 | | :--- | :---------------------------------------- | :------------------------------ | :---------------------------------------------------------------- | | 決済 | 登録 | POST /v1/payments | fincode.payments.create(requestBody) | | | 実行 | PUT /v1/payments/{id} | fincode.payments.execute(id, requestBody) | | | 一覧取得 | GET /v1/payments | fincode.payments.retrieveList({ pay_type: payType}) | | | 取得 | GET /v1/payments/{id} | fincode.payments.retrieve(id, { pay_type: payType}) | | | 売上確定 | PUT /v1/payments/{id}/capture | fincode.payments.capture(id, requestBody) | | | キャンセル | PUT /v1/payments/{id}/cancel | fincode.payments.cancel(id, requestBody) | | | 再オーソリ | PUT /v1/payments/{id}/auth | fincode.payments.reauthorize(id, requestBody) | | | 金額変更 | PUT /v1/payments/{id}/change | fincode.payments.changeAmount(id, requestBody) | | | 3Dセキュア2.0認証実行(カード決済) | PUT /v1/secure2/{access_id} | fincode.payments.execute3DSecureAuth(access_id, requestBody) | | | 3Dセキュア2.0認証実行結果取得(カード決済) | GET /v1/secure2/{access_id} | fincode.payments.retrieve3DSecureAuthResult(access_id) | | | 認証後決済実行(カード決済) | PUT /v1/payments/{id}/secure | fincode.payments.executeAfter3DSecureAuth(id, requestBody) | | | バーコード取得(コンビニ決済) | PUT /v1/payments/{id}/barcode | fincode.payments.generateKonbiniPaymentBarcode(id, requestBody) |

Customer API （顧客API）

| API | | URL | 呼び出し方 | | :--- | :------- | :-------------------------- | :------------------------------------------ | | 顧客 | 登録 | POST /v1/customers | fincode.customers.create(requestBody) | | | 更新 | PUT /v1/customers/{id} | fincode.customers.update(id, requestBody) | | | 一覧取得 | GET /v1/customers | fincode.customers.retrieveList() | | | 取得 | GET /v1/customers/{id} | fincode.customers.retrieve(id) | | | 削除 | DELETE /v1/customers/{id} | fincode.customers.delete(id) |

Card API （カードAPI）

| API | | URL | 呼び出し方 | | :----- | :------- | :--------------------------------------------- | :-------------------------------------------------- | | カード | 登録 | POST /v1/customers/{customer_id}/cards | fincode.cards.create(customerId, requestBody) | | | 更新 | PUT /v1/customers/{customer_id}/cards/{id} | fincode.cards.update(customerId, id, requestBody) | | | 一覧取得 | GET /v1/customers/{customer_id}/cards | fincode.cards.retrieveList(customerId) | | | 取得 | GET /v1/customers/{customer_id}/cards/{id} | fincode.cards.retrieve(customerId, id) | | | 削除 | DELETE /v1/customers/{customer_id}/cards/{id} | fincode.cards.delete(customerId, id) |

Plan API (プランAPI)

| API | | URL | 呼び出し方 | | :----- | :------- | :---------------------- | :-------------------------------------- | | プラン | 登録 | POST /v1/plans | fincode.plans.create(requestBody) | | | 更新 | PUT /v1/plans/{id} | fincode.plans.update(id, requestBody) | | | 一覧取得 | GET /v1/plans | fincode.plans.retrieveList() | | | 取得 | GET /v1/plans/{id} | fincode.plans.retrieve(id) | | | 削除 | DELETE /v1/plans/{id} | fincode.plans.delete(id) |

Subscription API (サブスクリプションAPI)

| API | | URL | 呼び出し方 | | :--------------------- | :------- | :---------------------------------- | :---------------------------------------------- | | サブスクリプション | 登録 | POST /v1/subscriptions | fincode.subscriptions.create(requestBody) | | | 更新 | PUT /v1/subscriptions/{id} | fincode.subscriptions.update(id, requestBody) | | | 一覧取得 | GET /v1/subscriptions | fincode.subscriptions.retrieveList() | | | 取得 | GET /v1/subscriptions/{id} | fincode.subscriptions.retrieve(id) | | | 解約 | DELETE /v1/subscriptions/{id} | fincode.subscriptions.cancel(id) | | サブスクリプション結果 | 一覧取得 | GET /v1/subscriptions/{id}/result | fincode.subscriptions.retrieveResultList(id) |

Session API (リダイレクト型API)

| API | | URL | 呼び出し方 | | :------------ | :--- | :----------------------- | :----------------------------------------------------- | | 決済URL | 作成 | POST /v1/sessions | fincode.paymentSessions.create(requestBody) | | カード登録URL | 作成 | POST /v1/card_sessions | fincode.cardRegistrationSessions.create(requestBody) |

Payment Bulk API (一括決済API)

| API | | URL | 呼び出し方 | | :--------------- | :------- | :------------------------------ | :-------------------------------------------------------------------------- | | 一括決済 | 登録 | POST /v1/payments/bulk | fincode.bulkPayments.create(pay_type, process_plan_date, file, file_name) | | | 一覧取得 | GET /v1/payments/bulk | fincode.bulkPayments.retrieveList() | | | 削除 | DELETE /v1/payments/bulk/{id} | fincode.bulkPayments.delete(id) | | 一括決済詳細情報 | 一覧取得 | GET /v1/payments/bulk/{id} | fincode.bulkPayments.retrieveDetailList(id) |

Platform API (プラットフォームAPI)

| API | | URL | 呼び出し方 | | :--------------- | :------- | :----------------------- | :------------------------------------------ | | プラットフォーム | 一覧取得 | GET /v1/platforms | fincode.platforms.retrieveList() | | | 取得 | GET /v1/platforms/{id} | fincode.platforms.retrieve(id) | | | 更新 | PUT /v1/platforms/{id} | fincode.platforms.update(id, requestBody) |

Platform Account API (プラットフォーム売上API)

| API | | URL | 呼び出し方 | | :--------------------------- | :------- | :--------------------------------------- | :------------------------------------------------- | | プラットフォーム売上 | 一覧取得 | GET /v1/platform_accounts | fincode.platformAccounts.retrieveList() | | | 取得 | GET /v1/platform_accounts/{id} | fincode.platformAccounts.retrieve(id) | | プラットフォーム売上サマリー | 一覧取得 | GET /v1/platform_accounts/{id}/summary | fincode.platformAccounts.retrieveSummaryList(id) |

Tenant API (テナントAPI)

| API | | URL | 呼び出し方 | | :----------------------- | :--------------------- | :----------------------------------------------- | :--------------------------------------------------------- | | テナント | 一覧取得 | GET /v1/tenants | fincode.tenants.retrieveList() | | | 取得 | GET /v1/tenants/{id} | fincode.tenants.retrieve(id) | | | 新規作成(新規ユーザー) | POST /v1/tenant_entries | fincode.tenants.createWithNewUser(requestBody) | | | 新規作成(既存ユーザー) | POST /v1/tenant_entries | fincode.tenants.createWithExistingUser(requestBody) | | テナント本番環境申請情報 | 取得 | GET /v1/contracts/examinations_v2/tenants/{id} | fincode.tenants.retrieveExaminationInfoV2(id) | | | 更新 | PUT /v1/contracts/examinations_v2/tenants/{id} | fincode.tenants.updateExaminationInfoV2(id, requestBody) | | テナント契約情報 | 取得 | GET /v1/contracts/{id} | fincode.tenants.retrieveContract(id) | | 本番環境 | 申請 | POST /v1/contracts/examinations | fincode.tenants.requestExamination(requestBody) | | 審査ファイル | アップロード | | | | テナント決済手段追加 | 申請 | | |

Account API (売上入金API)

| API | | URL | 呼び出し方 | | :----------- | :------- | :----------------------------- | :---------------------------------------- | | 売上入金 | 一覧取得 | GET /v1/accounts | fincode.accounts.retrieveList() | | | 取得 | GET /v1/accounts/{id} | fincode.accounts.retrieve(id) | | 売上入金詳細 | 取得 | GET /v1/accounts/{id}/detail | fincode.accounts.retrieveDetailList(id) |

Webhook Setting API (Webhook設定API)

| API | | URL | 呼び出し方 | | :---------- | :------- | :--------------------------------- | :------------------------------------------------ | | Webhook設定 | 登録 | POST /v1/webhook_settings | fincode.webhookSettings.create(requestBody) | | | 一覧取得 | GET /v1/webhook_settings | fincode.webhookSettings.retrieveList() | | | 取得 | GET /v1/webhook_settings/{id} | fincode.webhookSettings.retrieve(id) | | | 更新 | PUT /v1/webhook_settings/{id} | fincode.webhookSettings.update(id, requestBody) | | | 削除 | DELETE /v1/webhook_settings/{id} | fincode.webhookSettings.delete(id) |

Requirements

このSDKは下記の環境で動作します。

| 環境 | バージョン | | :------ | :--------- | | Node.js | >=12.0.0 |