Issuing と Treasury のサンプルアプリ

Stripe Next.js のサンプルアプリを使用して、Issuing と Treasury の独自の実装を始めましょう。

Stripe Issuing と Treasury のドキュメントと SDK 一式に加えて、Next.js アプリのサンプルを提供しています。

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

コードにアクセスする

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

アプリの機能

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

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

コンポーネントの内訳

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

詳細は Issuing の API と機能または Treasury の 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"}
  },
});

Stripe Treasury の金融口座を作成します。

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];

上記のコマンドのペイロードには、現在の balance (現金) とアウトバウンドの資金で構成される balance オブジェクトが含まれます。

{
  "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 → 説明

送金インターフェイス

サンプルアプリの送金機能は、Stripe Treasury の 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 を使用してカードを発行し、Treasury の金融口座から資金を使用するには、Cardholder を作成する必要があります。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 テストヘルパーを使用して、Treasury の金融口座に資金を追加することができます。このテストヘルパーは、外部の銀行口座から金融口座への送金の受け取りをシミュレーションします。

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,},
);

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

入金により、連結アカウントの支払い残高から、その連結アカウントの Treasury の金融口座に売上を送金できます。入金を実行するには、以下のステップを実行します。

連結アカウント用に外部口座が設定されているかどうかを確認します。そのためには、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;
}

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

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,
  },
});

連結アカウントの外部口座への入金を開始します。このケースでは、外部口座は Treasury の金融口座です。

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

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