プラットフォーム向け Issuing および金融口座サンプルアプリ

Stripe Next.js のサンプルアプリを使って、Issuing とプラットフォーム向け金融口座の導入を開始しましょう。

Stripe Issuing と金融口座のプラットフォーム向けドキュメントと SDK 一式に加え、Next.js のサンプルアプリも提供しています。

baas.stripe.dev にあるサンプルアプリのデモか、GitHub リポジトリをご覧ください。

コードにアクセスする

サンプルアプリは、TypeScript、React、Material UI を活用した Next.js アプリです。Stripe サンプルの GitHub リポジトリからプロジェクトをフォークして、含まれているコンポーネントをアプリの開始点として使用することができます。

アプリの機能

このアプリでは、次のようなさまざまな使用方法の例を紹介しています。

Stripe Connect アカウント登録を使用して、規制に準拠した連結アカウントの登録用に顧客確認 (KYC) 情報を収集する
アカウント情報と残高を表示する
金融口座の取引表示
ACH または電信送金を使用した外部口座への送金をシミュレーションする
ACH クレジットの受け取りをシミュレーションする
ApexCharts を使用してインバウンドとアウトバウンドの資金のフローを視覚化する
規則に準拠した方法でカード保有者を作成する
金融口座を発行可能残高としてカードを作成
機密情報であるカード番号を PCI に準拠した方法で表示する
カードのオーソリをシミュレーションする
決済用リンクから支払いを受けて、Stripe 決済残高から金融口座に資金を送金します
テストヘルパーを利用してアカウントに影響する操作をシミュレーションする

コンポーネントの内訳

以降のセクションでは、サンプルアプリの各コンポーネントの仕組みを大まかに紹介します。

Issuing API と機能または金融口座 API と機能について詳しく知ることができます。

アカウントの作成

アカウント作成フローは以下の 4 つのステップで構成されています。

transfers、card_issuing、treasury のケイパビリティを持つ連結アカウントを作成します。

const account = await stripe.accounts.create({
  country: 'US',
  email: email,
  capabilities: {
    transfers: {requested: true},
    treasury: {requested: true},
    card_issuing: {requested: true},
  },
  controller: {
    dashboard: {type: "none"},
    losses: {payments: "application"},
    requirement_collection: "application",
    fees: {payer: "application"}
  },
});

金融口座の作成。

const financialAccount = await stripe.treasury.financialAccounts.create(
  {
    supported_currencies: ['usd'],
    features: {
      card_issuing: {requested: true},
      deposit_insurance: {requested: true},
      financial_addresses: {aba: {requested: true}},
      inbound_transfers: {ach: {requested: true}},
      intra_stripe_flows: {requested: true},
      outbound_payments: {
        ach: {requested: true},
        us_domestic_wire: {requested: true},
      },
      outbound_transfers: {
        ach: {requested: true},
        us_domestic_wire: {requested: true},
      },
    },
  },
  {stripeAccount: account.id},
);

Connect アカウント登録リンクを作成し、そのリンクを使用して新規連結アカウントをリダイレクトして、リクエストされたケイパビリティに必要なプロフィール情報を収集します。

const { url } = await stripe.accountLinks.create({
  type: 'account_onboarding',
  account: accountId,
  refresh_url: host + '/onboard',
  return_url: host + '/onboard',
  collect: 'eventually_due',
});

アカウント残高

アカウント残高カードは stripe.treasury.financialAccounts.list API のみを使用します。

const financialAccounts = await stripe.treasury.financialAccounts.list({
  stripeAccount: StripeAccountID,
});
const financialAccount = financialAccounts.data[0];

上記のコマンドのペイロードには、現在の残高 (現金) とアウトバウンド資金からなる残高オブジェクトが含まれています。

{
  "id": "fa_...",
 ...
  "balance": {
    "cash": { "usd": 534214 },
    "inbound_pending": { "usd": 0 },
    "outbound_pending": { "usd": 2200 }
  },
 ...
  "supported_currencies": [ "usd" ]
}

入出金チャート

資金移動チャートは stripe.treasury.transactions.list API のみを使用します。

const fa_transactions = await stripe.treasury.transactions.list(
  {
    financial_account: financialAccount.id,
    order_by: 'created',
    limit: 100,
  },
  {stripeAccount: StripeAccountID},
);

レスポンスは、プラス/マイナスの残高および作成日でグループ化されます。その後、データは ApexCharts に移植され、売上フローの動的な表示が作成されます。

{
  "id": "{{TRANSACTION_ID}}",
  "object": "treasury.transaction",
  "created": "{{T}}",
  ...
  "flow": "{{OUTBOUND_PAYMENT_ID}}",
  "flow_type": "outbound_payment",
  "status": "open",
  "amount": -1000,
  "currency": "usd",
  "balance_impact": {
    "cash": -1000,
    "inbound_pending": 0,
    "outbound_pending": 1000,
  },
  "entries": {
    "data": [
      {
        "id": "{{TRANSACTION_ENTRY_ID}}",
        "object": "treasury.transaction_entry",
        ...
        "created": "{{T}}",
        "effective_at": "{{T}}",
        "currency": "usd",
        "balance_impact": {
          "cash": -1000,
          "inbound_pending": 0,
          "outbound_pending": 1000,
        }
      }
    ],
    "has_more": false,
    "object": "list",
    "url": "/v1/treasury/transaction_entries?financial_account={{FINANCIAL_ACCOUNT_ID}}&transaction={{TRANSACTION_ID}}"
  }
}

取引リスト

取引リストは stripe.treasury.transactions.list API を使用します。

const fa_transactions = await stripe.treasury.transactions.list(
  {
    financial_account: financialAccount.id,
    order_by: 'created',
    limit: 100,
  },
  {stripeAccount: StripeAccountID},
);

transactions テーブルの列は、次のマッピングを使用して transaction オブジェクトから解析されます。

created → 日付
amount → 金額 / 通貨
flow_type → タイプ
status → ステータス
description → 説明

送金インターフェイス

サンプルアプリの送金機能は、プラットフォーム向け金融口座の OutboundPayment 機能を使用しています。OutboundPayments を使って、第三者の外部口座に送金できます。

const outboundPayment = await stripe.treasury.outboundPayments.create(
  {
    financial_account: financialAccount.id,
    amount: amount,
    currency: 'usd',
    statement_descriptor: req.descriptor,
    destination_payment_method_data: {
      type: 'us_bank_account',
      us_bank_account: {
        account_holder_type: 'individual',
        routing_number: '110000000',
        account_number: '000000000009',
      }
    }
  },
  {
    stripeAccount: StripeAccountId
  },
);

Issuing カード保有者の作成

金融口座からの資金を使用するために Stripe Issuing を使用してカードを発行する前に、カード会員 を作成する必要があります。カード会員を作成するには、stripe.issuing.cardholders.create API を使用します。

const cardholder = await stripe.issuing.cardholders.create(
  {
    type: 'individual',
    name: firstName + ' ' + lastName,
    email: email,
    individual: {
      first_name: firstName,
      last_name: lastName,
      dob: {day: day, month: month, year: year}
    },
    billing: {
      address: {
        city: city,
        line1: address1,
        state: state,
        postal_code: postalCode,
        country: country,
      },
    },
  },
  {
    stripeAccount: StripeAccountId,
  }
);

カードを発行する

Cardholder を作成した後、stripe.issuing.cards.create API を使用して Cardholder にカードを発行できます。

const card = await stripe.issuing.cards.create(
  {
    cardholder: req.body.cardholderid,
    financial_account: financialAccount.id,
    currency: 'usd',
    type: 'virtual',
    status: 'active',
  },
  {stripeAccount: StripeAccountId},
);

カードのリスト

stripe.issuing.cards.list API からのデータを使用して、カードのリストをレンダリングします。

const cards = await stripe.issuing.cards.list(
  {limit: 10},
  {stripeAccount: StripeAccountID},
);

カードのオーソリリスト

stripe.issuing.authorizations.list API を使用して、特定のカードのオーソリを取得します。次の例では、リストに表示するオーソリを最新の 10 件に制限しています。

const card_authorizations = await stripe.issuing.authorizations.list(
  {
    card: cardId,
    limit: 10,
  },
  {stripeAccount: StripeAccountID},
);

authorization テーブルの列は、次のマッピングを使用して response オブジェクトから解析されます。

created → 日付
amount → 金額 / 金額の通貨
card.cardholder.name → カードに記載されている名前
card.last4 → 末尾 4 桁
approved → 承認済み
status → ステータス
merchant_data.name → 加盟店
merchant_data.category → 加盟店カテゴリー

テストヘルパー

サンプルアプリは、口座への資金の追加、連結アカウントの資金を回収するための決済用リンクの作成、金融口座への入金などの特定のアクションを実行できるテスト環境のヘルパーを備えています。ほとんどのテストヘルパーには、テストデータを生成 ボタンまたは テストデータ をクリックするとアクセスできます。

受領したクレジットのテストヘルパー

テスト環境では、ReceivedCredit Test Helpers を使用して、金融口座に資金を追加できます。このテストヘルパーは、外部の銀行口座から金融口座への送金をシミュレートします。

const receivedCredit = await stripe.testHelpers.treasury.receivedCredits.create(
  {
    amount: 50000,
    currency: 'usd',
    financial_account: financialAccount.id,
    network: 'ach',
  },
  {stripeAccount: StripeAccountId},
);

決済フォームへのリンクと入金

決済用リンクを使用して、金融口座に関連付けられている連結アカウントに資金を追加できます。

支払い完了後に連結アカウントに追加される金額を決定する Price を作成します。

const prices = await stripe.prices.list(
  {
    limit: 1,
    active: true,
    type: 'one_time',
  },
  {stripeAccount: StripeAccountId,},
);

let price;

if (prices.data.length < 1) {
  price = await stripe.prices.create(
    {
      unit_amount: 1000,
      currency: 'usd',
      product_data:
        {
          name: 'Unit',
      },
    },
    {stripeAccount: StripeAccountId,},
  );
} else {
  price = prices.data[0];
}

価格を取得した後、Stripe は PaymentLink を作成し、お客様は決済を完了するために顧客をリダイレクトします。前のステップの Price id を使用して price パラメーターの値を設定します。デフォルト値を使用する場合は、このパラメーターを含めないでください。

const paymentLink = await stripe.paymentLinks.create(
  {
    line_items: [
      {
        price: price.id,
        quantity: 1,
        adjustable_quantity: {enabled: true},
      },
    ],
  },
  {stripeAccount: StripeAccountId,},
);

連結アカウントの支払い残高からの入金

Payouts は連結アカウントの決済残高から金融口座に入金できます。Payouts を実行するには、以下の手順に従ってください。

連結アカウント用に外部口座が設定されているかどうかを確認します。そのためには、accounts.retrieve API を使用して、Account オブジェクトを取得し、external_account プロパティが設定されているかどうかを確認します。

const responseAccount = await stripe.accounts.retrieve(StripeAccountID);
const accountExternalAccount = responseAccount.external_accounts.data[0];

let hasExternalAccount = false;

if (accountExternalAccount) {
  hasExternalAccount = true;
}

連結アカウントに外部口座がない場合、金融口座を外部口座として設定できます。

const financialAccounts = await stripe.treasury.financialAccounts.list(
  {expand: ['data.financial_addresses.aba.account_number']},
  {
    stripeAccount: StripeAccountId,
  },
);

const financialAccount = financialAccounts.data[0];

await stripe.accounts.createExternalAccount(StripeAccountId, {
  external_account: {
    object: 'bank_account',
    country: 'US',
    currency: 'usd',
    account_number:
      financialAccount.financial_addresses[0].aba.account_number,
    routing_number:
      financialAccount.financial_addresses[0].aba.routing_number,
  },
});

連結アカウントの外部口座への Payouts を開始します。この場合、外部口座は金融口座です。

const balance = await stripe.balance.retrieve({
  stripeAccount: StripeAccountId,
});

const payout = await stripe.payouts.create(
  {
    amount: balance.available[0].amount,
    currency: 'usd',
  },
  {stripeAccount: StripeAccountId},
);