Stripe Connect内の子アカウントユーザーの明細を取得する方法

現在運用中の Stripe Connect を使ったサービスで、子アカウントユーザーより「入金の明細がほしい」と言われたため、アップデートするために Stripe API を色々触った知見をメモします。

balanceTransactions API

調査した結果、balanceTransactionsを使うのが妥当だと判断しました。

使い方

interface BalanceData {
  created: number
  fee: number
  net: number
  amount: number
}

const balanceAscSortByCreated = (a: BalanceData, b: BalanceData): number => {
  if (a.created > b.created) return 1
  else if (a.created < b.created) return -1
  return 0
}

export const getBalances = async (
  { year: number; month: number },
  stripeAccount: string,
  limit = 100
): Promise<BalanceData[]> => {
  // お好きにvalidationしてください。
  if (year < 2021 || year > 2050) throw Error('year invalid.')
  else if (month < 1 || month > 12) throw Error('month invalid.')

  const startTime =
    moment(`${year}-${('00' + String(month)).slice(-2)}-01 00:00`)
      .startOf('M')
      .toDate()
      .getTime() / 1000
  const endTime =
    moment(`${year}-${('00' + String(month)).slice(-2)}-01 00:00`)
      .endOf('M')
      .toDate()
      .getTime() / 1000

  const balances: BalanceData[] = []
  let lastBalanceId: string | undefined

  do {
    //
    const { data: balanceList } = await stripe.balanceTransactions.list(
      { limit, starting_after: lastBalanceId },
      { stripeAccount }
    )

    // sort.
    balanceList.sort(balanceAscSortByCreated)

    // add validation.
    if (balanceList.length === 0) break

    // add.
    balanceList.forEach((balanceData) => {
      if (balanceData.created > startTime && balanceData.created < endTime) {
        balances.push({
          created: balanceData.created * 1000,
          amount: balanceData.amount,
          net: balanceData.net,
          fee: balanceData.fee
        })
      }
    })

    // loop validation.
    const isBeforeMonth = balanceList[0].created < startTime
    if (balanceList.length < limit || !isBeforeMonth) {
      lastBalanceId = balanceList[0].id
    } else {
      lastBalanceId = undefined
    }
  } while (lastBalanceId)

  // sort created.
  balances.sort(balanceAscSortByCreated)

  return balances
}

getBalances関数の引数に、year、month、stripeAccountIdを渡すことで、以下のように描画することができます。

出力内容

とりあえず Table 表示しただけなので、今後お金の変動グラフを作りより見やすくする予定です。

豆知識

Stripe API の調査する際は、公式ドキュメントよりもライブラリーの中を見ることをオススメします。
Stripe SDK は、非常にコードが読みやすく、コメントが充実してます。
ドキュメントはボリュームが多く探すのが大変ですが、ライブラリーだと VSCode の検索機能や補完によって、求めていた API を探すのがドキュメントより効率がよい時が多々ありました。

以上、