@miraipay/node

English summary: @miraipay/node is the official Node.js SDK for MIRAI Pay's external API (pay/v1). This package is in beta (0.x) — MIRAI Pay's public host (api.miraikei.com) is not yet routable, so point baseUrl at your own MIRAI Pay endpoint until then. Breaking changes may land on any 0.x release.

MIRAI Pay の外部公開API（pay/v1）を Node.js / TypeScript から呼び出すための公式 SDK です。

主な特徴:

• createMiraiPay で初期化。公開識別子はすべて MiraiPay にリブランド
• test/live は API キーのプレフィックス（sk_test_mp_... / sk_live_mp_...）から自動判定
• base URL は単一。テスト/本番でホストを切り替える必要はない
• ヘッダは X-Workspace-Id（MIRAI Pay のワークスペース指定）/ Idempotency-Key
• invoices（請求書）・feeRates（手数料率）リソースを提供（pay/v1 固有のエンドポイント）

ベータ版（0.x）について: MIRAI Pay の公開ホスト（api.miraikei.com）はまだルーティングされていません。 開通するまでは baseUrl オプションでご自身の MIRAI Pay エンドポイント（dev環境など）を指定してください。 0.x の間は破壊的変更が入る可能性があります。1.0.0 は公開ホスト開通後にリリースします。

Getting Started

npm install @miraipay/node

1. MIRAI Pay 開発者コンソールから API キーを取得

/[orgId]/pay/developers/api-keys からシークレットキー（sk_test_mp_... または sk_live_mp_...）を発行します。 このSDKはシークレットキー専用です（pk_... の公開キーはブラウザ向け SDK @miraipay/js 用で、このSDKでは使えません）。

2. MiraiPay クライアントを作成

import { createMiraiPay } from "@miraipay/node"

const miraipay = createMiraiPay({
    apiKey: "sk_test_mp_xxxxxxxxxxxxxxxx", // test/live はこのプレフィックスから自動判定

    // api.miraikei.com が未開通の間は明示的に指定する
    baseUrl: "https://your-dev-endpoint.example.com/api/v1/pay",

    // Optional
    options: {
        timeout: 10000,
        proxyAgent: "http://url.to.proxy:8080",
        // 既定のワークスペース(org_unit)ID。全リクエストの X-Workspace-Id 既定値になる
        // (呼び出しごとの headers.workspaceId で上書き可能)。ベースワークスペース
        // (「ビジネス」)発行キーのみ有効。ワークスペース発行キーはサーバー側で
        // 既にそのワークスペースに固定されているため省略可能。
        workspaceId: "{{org_unit id}}",
    },
})

;(async () => {
    // 決済を登録（冪等キー付き）
    // buyer_name / buyer_email は必須（MIRAI Pay 拡張）:
    // すべての決済で請求書が自動発行され、buyer_email へ交付されます
    const createdPayment = await miraipay.payments.create(
        {
            pay_type: "Card",
            job_code: "CAPTURE",
            amount: "3000",
            buyer_name: "山田 太郎",
            buyer_email: "[email protected]",
        },
        { idempotentKey: "{{idempotent key}}" },
    )

    // 決済を実行
    const executedPayment = await miraipay.payments.execute(createdPayment.id, {
        pay_type: createdPayment.pay_type,
        access_id: createdPayment.access_id,
        customer_id: "{{id of customer}}",
        card_id: "{{id of customer's card}}",
    })

    // 決済を取得
    const payment = await miraipay.payments.retrieve(executedPayment.id, { pay_type: "Card" })

    // 決済一覧を取得
    const payments = await miraipay.payments.retrieveList({ pay_type: "Card", limit: 10, page: 1 })
})()

MIRAI Pay API の呼び出し

miraipay インスタンスの各メソッドが pay/v1 の各エンドポイントに対応しています。

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

ヘッダーはすべてのAPI呼び出しのオプショナル引数として渡せます。

{
    // Idempotency-Key に対応。冪等キー（決済の二重実行防止）。
    idempotentKey?: string
    // X-Workspace-Id に対応。対象ワークスペース(org_unit)のID。未指定なら
    // options.workspaceId(クライアント初期化時の既定値)、それも無ければ既定(base)ワークスペース。
    workspaceId?: string
    // Content-Type に対応。
    contentType?: string
}

一覧取得APIなど一部の呼び出しでは、クエリパラメーターもオプショナル引数として渡せます。

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

Payment API （決済API）

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

請求書の自動発行（MIRAI Pay 拡張）

MIRAI Pay はすべての決済で請求書を自動発行し、メールで交付します。このため決済登録 （payments.create）では以下の 2 フィールドが必須です（fincode API にはない MIRAI Pay 拡張）。

| フィールド | 用途 | | :--- | :--- | | buyer_name | 請求書の宛名（交付先名称） | | buyer_email | 請求書リンクの送信先。売上確定（capture）後に自動送信されます |

顧客登録（customers.create）でも name / email は必須です（MIRAI Pay 拡張）。 サブスクリプションの各回課金では、決済ではなく顧客の name / email が宛名・交付先として 使われます。SDK 外（fincode ダッシュボード等）で作られた name / email 未登録の顧客を subscriptions.create で指定した場合は 422 になります。

Customer API （顧客API）

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

Card API （カードAPI）

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

Plan API (プランAPI)

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

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

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

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

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

Payment Bulk API (一括決済API)

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

Account API (売上入金API)

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

Invoice API (請求書API) — MIRAI Pay 独自

MIRAI Pay 独自に追加したリソースです。リクエスト/レスポンスのフィールドはあえて緩い型（Record<string, unknown>）にしています。

| API | | URL | 呼び出し方 | | :----- | :--- | :-------------------------------------------- | :-------------------------------------------------------------- | | 請求書 | 登録 | POST /invoices | miraipay.invoices.create(requestBody) | | | 一覧取得 | GET /invoices | miraipay.invoices.retrieveList() | | | 取得 | GET /invoices/{id} | miraipay.invoices.retrieve(id) | | | 送付(オープン) | PUT /invoices/{id}/open | miraipay.invoices.open(id) | | | キャンセル | PUT /invoices/{id}/cancel | miraipay.invoices.cancel(id) | | | 外部入金済みへ | PUT /invoices/{id}/paid-externally | miraipay.invoices.markPaidExternally(id) | | | バーチャル口座再発行 | PUT /invoices/{id}/virtual-account/refresh | miraipay.invoices.refreshVirtualAccount(id) |

Fee Rates API (手数料率API) — MIRAI Pay 独自

| API | | URL | 呼び出し方 | | :-------- | :--- | :---------------- | :----------------------------------- | | 手数料率 | 取得 | GET /fee-rates | miraipay.feeRates.retrieve() |

Webhook Setting API (Webhook設定API)

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

Webhook の配信自体は fincode（決済処理基盤）から直接行われます。署名検証は Fincode-Signature ヘッダで行ってください（MIRAI Pay 独自の署名付け・再送は現時点では未提供です）。

エラーハンドリング

import { MiraiPayAPIError, MiraiPaySDKError } from "@miraipay/node"

try {
    await miraipay.payments.retrieve("pay_xxxxxxxx")
} catch (e) {
    if (e instanceof MiraiPayAPIError) {
        // MIRAI Pay / fincode からのエラー応答（e.status, e.errors）
    } else if (e instanceof MiraiPaySDKError) {
        // ネットワークエラー・レスポンスのパース失敗など、SDK内部のエラー
    }
}

テスト

npm test        # モックのみ・ネットワーク不要（PRごとのCIで実行）
npm run test:e2e # 実際に MIRAI Pay API を叩く E2E（.env.test に実キーが必要。opt-in）

*.e2e.test.ts は実際の sk_test_mp_... キーと到達可能な baseUrl を要求します。ローカルで実行する場合は .env.test.example を .env.test にコピーし、値を埋めてください。

Requirements

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

License

UNLICENSED — MIRAIKEI Inc. の許諾なく使用・複製・再配布はできません。詳細は LICENSE を参照してください。