@miraipay/node

@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 () => {
    // 決済を登録（冪等キー付き）
    const createdPayment = await miraipay.payments.create(
        { pay_type: "Card", job_code: "CAPTURE", amount: "3000" },
        { 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)

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 を参照してください。