DEV Community: Toru Furukawa

Publications

Toru Furukawa — Wed, 12 Jan 2022 00:50:01 +0000

Toru Furukawa (2021). Stripe Connect Data Models and Fund Flows. https://zenn.dev/toruf/books/stripe-connect-2021
Toru Furukawa (2020). Stripe データのコンセプト. https://dev.to/torufurukawa/stripe-17n9
Toru Furukawa (2018). Twitter 広告と API を組み合わせたインタラクティブなキャンペーン. https://www.slideshare.net/torufurukawa/twitter-api-121399949
Toru Furukawa (2013). Tast failed, then..., PyCon APAC 2013, https://pyvideo.org/pycon-apac-2013-in-japan/test-failed-then-by-torufurukawa.html

Stripe データのコンセプト

Toru Furukawa — Tue, 08 Dec 2020 23:20:58 +0000

Stripe という決済 SaaS の存在を、最近知りました。いろんな API を組み合わせて、いろんな決済処理を実装できます。個々の API エンドポイントのパラメータや挙動はドキュメントがあり、テストモードで簡単に試せます。

一方、外側からみて、Stripe におけるデータオブジェクトのコンセプトが分かると、個々の API をやみくもに調べるよりは、設計の役に立つような気がします。決済というのが、そもそも比較的抽象度の高い概念です。サービス上のユーザー体験が API と 1対1 で対応しないことがあります。そんなときは、少しレイヤーを上げた視点もあるといいんじゃないかなー、と思います。

そこで JP_Stripes Advent Calendar 2020 にぶらさがって、自分なりの解釈をまとめました。

以下、クレジットカードでの支払いを想定します。

Payment Intent

Payment Intent は 1回の「支払い」の設定、状態、処理を管理するオブジェクトです。設定というのは「1000円」みたいな情報です。

状態というは、カード番号が必要だとか、認証が必要だとか、処理中だとか、キャンセルされたとかです。

状態遷移をするときに、裏側では必要に応じて、クレジットカードのシステムと通信が走ります。

とりあえず、どんなのか試したいときは、Integration Builder
が、手っ取り早いです。もう少し細かい説明もあります。

大雑把な状態遷移はこんな感じ。

requires_payment_method: Payment Method （クレジットカード番号など）が必要。
requires_confirmation: アプリケーションによる確認（これでOKっす、って指定する API コール）が必要。
requires_action: 何かアクションが必要。3Dセキュアのパスワード入力とか。
processing: 処理中。大抵、数秒で、次の状態に遷移する。
succeeded: 支払い完了。クレジットカードの引き落とし日を楽しみにしてください
canceled: アプリケーションがキャンセルした。

決済に失敗したら、requires_payment_method に遷移します。

破線枠の状態は、スキップする場合がある状態を表します。正確に分岐を明示すると、ごちゃごちゃするので省略しました。

Payment Intent は支払いの行動を追跡・処理するオブジェクトです。カード番号なんかを直接管理しません。

Payment Method

Payment Method は支払い方法・手段を表すオブジェクトです。クレジットカードによる支払いの場合、クレジットカード番号、有効期限、CVC などを保持します。

Payment Intent を作ってから、フロントエンドで Payment Method を作成して Payment Intent と関連づけることができます。

反対に、先に Payment Method を作成して（＝クレジットカード番号を入力させて）から、Payment Intent を作成して関連づけてもよいです。クレジットカードのブランドによって、挙動を変えたいような場合に有効な順序です。

Customer

会員的な概念があって、繰り返し利用するクレジットカード番号を保存したい、というケースがあると思います。その場合は、Payment Method を Customer オブジェクトに attach します。

Customer オブジェクトは、顧客、より正確には支払いをする主体を表します。B2C だったらおそらくは会員とかユーザーという概念に対応します。

ひとつの Customer は、0個以上の Payment Method と関連づけられます。ひとつの Payment Method は、0〜1個の Customer と関連づけられます。

Payment Method を一度 Customer と関連づけると、他の Customer と関連づけることはできません。

サブスクリプション・ビジネス

Customer と Payment Method の関連づけができれば、毎月バッチを走らせると月額課金ができます。「毎月3,000円支払ってくれたら、うちで飼っている猫が、毎朝、朝食をとっている動画を見せてあげる」みたいなサービスを作れるわけです。やったね。

さて Billing と呼ばれるサービス・API群を使うと、このへんの処理を自動化できます。月に一度決済をするだけならいいんですが、バッチを回すだけより、もうちょい複雑なコンセプトが絡みます。

世の中には3つの嘘があります。嘘、ひどい嘘、定期的に決済するだけ、です。

まずは、定期的に決済するだけに必要なデータオブジェクトを、順番に見ていきましょう。

Product と Price

まず商品と料金体系を定義します。

Product は商品やサービスを表す抽象的な概念です。たとえば「猫の朝食動画ストリーミング」というサービスを表します。

Price は、Product と関連づいた価格体系を表します。ひとつの Product に対して、複数の Price を関連づけられます。

複数の Price の用途は大きくふたつあります。複数通貨の場合です。月額3,000円と、月額30ドルを用意するとかですね。

もうひとつは期間が違う場合です。月額3,000円と、年額30,000円を用意するような場合です。

これで商品と価格体系の定義ができました。

「猫の夕食動画ストリーミング」というサービスを追加する場合や、「朝夕バンドル」を追加する場合には、Product 側を変更するとすっきりするでしょう。

3ヶ月ごと、半年ごとの価格体系を追加するときは、Price を操作するのがよいでしょう。

ただ Price 側でいろいろ定義したり、後述する Coupon を使ったりして、いろんなバリエーションを作れます。このあたりこそが、設計者の腕の見せ所だと思います。

Subscription

Subscription オブジェクトは、定期課金の契約の定義と状態の保持、それから関連する自動化処理のトリガーの役割があります。

「ある Customer が、ある Price にサブスクライブする」という契約を定義するのがSubscription です。Price で定義したとおり、Customer に関連づいた Payment Method から資金を回収したいよ、という契約です。

注意すべきは Customer は支払いの主体だ、ということです。たとえば「3ユーザーまで視聴可」みたいな契約のとき、Customer はおそらく「ユーザー」には関連づかず、支払いをする代表ユーザーのみを表すことになるでしょう。

先払いの契約を想定しているため、契約開始時に最初の請求が発生します。

しかし Subscription は契約を保持するだけで、直接決済をしません。じゃあ、どうするかっていうと、支払いが必要になったとき、自動的に Invoice オブジェクトをつくります。

Invoice

Invoice オブジェクトは1回の請求行為を表します。猫ストリームの例では「今月ぶんの3,000円を請求するのだ」という活動です。

未払いだとか、支払い済みだとか、期限切れだとか、もういらねぇよ（void）などの状態を持ちます。

請求の状態を持ちますが、支払いを直接管理しません。じゃあどうするのかというと、ここで最初に出てきた Payment Intent が登場します。Invoice が資金の回収ができる条件がそろうと、自動的に Payment Intent を作り、実行しようとします。

Payment Intent は、Customer -> Subscription -> Invoice と伝搬・継承してきた Payment Method から、支払いを回収しようとします。その結果は、今度は逆向きに Invoice -> Subscription のほうに伝搬していきます。

Invoice が回収に失敗したとき、スマートリトライなる自動化処理があり、なんとなくいいタイミングでリトライします。それでも失敗し続けると、諦めます。その場合に、未回収だけど subscription を生かしておく、subscription をキャンセルするなどの挙動定義は、ダッシュボードで設定できます。

trial

さて、めでたくサブスクリプション・ビジネスのサービスが開発できました。やったね！　すると、マーケティング担当とか、グロース担当とかが、こういうことを言い出すわけです。

「今月サブスクしたら、一ヶ月無料キャンペーンをしよう！」

だるいですね。

初月無料キャンペーンのだるいところは、契約開始日と資金回収開始日がずれてしまうことです。そんなデータ構造持ってねぇよ、って言いたくなりますよね。

そこで trial です。Subscription オブジェクトを作るときに、使用期間を指定できます。これは subscription が始まってからしばらく無料が続き、そのあとで最初の支払いを発生させるためのパラメータです。

Subscription を作った時点では、0円の invoice が作られます。支払いは発生しないので Payment Intent は作られず、Invoice はすぐに paid 状態になります。そのため subscription は生きたままです。

trial 期間が終わると、そこから支払いサイクルが始まり、Invoice -> Payment Intent の連鎖が始まります。

Coupon

やりました。開発者のみなさんは、trial をも乗り越えました。すると、グロース担当（）が言うわけです。

「競合が似たサービスを作ってきた！　継続してもらうために、既存顧客を2ヶ月間 50% オフにしよう！」

はー。だるいですね。

「難しかったら、1ヶ月でもいいよ」

そういう問題じゃねーよ、お前のギャラを120%オフにすんぞ。

それはそれとして、Coupon オブジェクトが使えるかもしれません。Subscription に Coupon を関連づけると、その Subscription の今後の請求に割引が適用されます。定義できる割引の挙動には、以下のようなパラメータがあります。

何%オフにするか、◯◯円引きにするか
1度だけか、指定した回数か、ずーっとか
クーポン適用できる期限
クーポンを適用できる最大数
など

物理的に配るクーポン、デジタルクーポンを管理するものではありません。「Subscription に適用する割引」を表す、抽象的な概念です。

Coupon が適用された結果、支払いサイクルで請求額が0円になる場合もあます。そのときは、0円の Invoice が作られます。

おわりに

バッチでできなくもないんですが、ワークフロー的な挙動をある程度 SaaS に任せられると、だるさから開放されることも多いと思います。ここでは、基本的なコンセプトを、自分なりにまとめてみました。

よいお年を。

Disclaimer: この記事は、公開されている情報を、個人が解釈して書き記したものです。所属する組織と関係ありそうに見えるかもしれませんが、関係ありません。

Disclaimer 2: 所属する組織の人々へ。この文書は、勤務時間外に、個人の機材を使って、個人の解釈をまとめたものです。仕事ではないので、仕事として何か言ってこないでください。もちろん問題があったら修正・削除します。よろ。

入門自然言語処理 pp.225-241

Toru Furukawa — Sat, 17 Feb 2018 02:56:30 +0000

5.6 変換を利用したタグ付け。一旦大雑把にタグ付けしたあと、教師あり学習したルールでさらに修正を加えていく。

6章は、テキスト分類の学習。

「a」、[e]、「i」で終わる名前は女性の名前であることが多く、「k」、「o」、「r」、「s」、「t」で終わる名前は男性であることが多い。

訳注: [...]日本語の場合は「男」や「夫」は男性、「子」は女性といった考え方をすることができる。

へー。なるほどね。

入門自然言語処理 pp.215-225

Toru Furukawa — Wed, 07 Feb 2018 22:56:21 +0000

5.4 自動タグ付けの続き。「's」で終わる単語は所有格名詞、のような正規表現にタグ付けをする。タグ付けされたコーパスの頻出単語からルックアップテーブルを作る、残りはとりあえずよくあるタグである名詞としてタグ付けする。と、そこそこの精度でタグ付けができるようだ。もちろんルックアップテーブルや正規表現パターンを増やせば精度はあがるけど、ある程度からは向上しない。

たぶん、時事ニュース記事なのか、ある特定の分野の学術論文なのか、はあちゅうのブログなのか、とかがあらかじめ分かっていれば、より適切なタグ付けモデルを作ることがきるんだろう。

5.5 Nグラムタグ付け。直前の単語も考慮することで、文脈によるタグ付けが可能になる。未知語にもある程度対応できる。

入門自然言語処理 pp.204-215

Toru Furukawa — Wed, 07 Feb 2018 00:08:25 +0000

5.3 は、Python の辞書に関する説明。nltk.defaultdict と collections.defaultdict は同じものらしい。たぶん標準ライブラリに defaultdict が追加される前に、nltk に defaultdict が入ってたのであろうと想像する。

>>> import collections
>>> collections.defaultdict
<class 'collections.defaultdict'>
>>> import nltk
>>> nltk.defaultdict
<class 'collections.defaultdict'>
>>> collections.defaultdict == nltk.defaultdict
True

5.4 は自動タグ付け。

入門自然言語処理 pp.199-203

Toru Furukawa — Tue, 30 Jan 2018 23:53:31 +0000

5.2 はタグ付きコーパスの続き。

タグの NN$ のように、$がついているとプロットするときのラベルとしてパースでいないので、雑に削除するコードを昨日書いた。んだけど、これはよくないことに気づく。

読み進めていくと、NN タグは spam のような一般的な名詞、 NN$ タグは spam's のような所有格名詞を表す。

import nltk
tagged_words = nltk.corpus.brown.tagged_words(categories="news")
dist = nltk.FreqDist(tag.replace("$", r"\$") for (word, tag) in tagged_words)
dist.plot()

入門自然言語処理 pp.195-198

Toru Furukawa — Mon, 29 Jan 2018 22:19:44 +0000

5.2 タグ付きコーパスの導入。単語とタグのタプルとして、コーパスが格納されている。tagged_words() メソッドでイテレートできる。

tagged_sents() なら、 [[(word, tag), (word, tag), ...], [...], ...] として文ごとにイテレートできる。

Python 3.6 + matplotlib==2.1.1 では、p.198 のプロットするサンプルでエラーが出る。FreqDict のキーに「PP$」のように $ が入っていて、この $をパースできないようだ。ここで根本原因を解決するのは本来の目的ではないので、適当に済ませる。

import nltk
tagged_words = nltk.corpus.brown.tagged_words(categories="news")
dist = nltk.FreqDist(tag.replace("$", "") for (word, tag) in tagged_words)
dist.plot()

入門自然言語処理 pp.118-195

Toru Furukawa — Sun, 28 Jan 2018 23:17:24 +0000

4章はほとんどPythonの基礎なので、読み飛ばし。

5章はタグ付きコーパス。5.1 でタグ付けの方法を紹介。

入門自然言語処理 pp.86-117

Toru Furukawa — Thu, 25 Jan 2018 23:16:33 +0000

3.2章は、Python の基本的な文字列処理。3.3 は Unicode とエンコーディングの考え方。Python 2 を前提にしているので、 u"..." とか。3.4、3.5 は正規表現と nltk の検索関数。

import nltk
from nltk.corpus import gutenberg, nps_chat

moby = nltk.Text(gutenberg.words("melville-moby_dick.txt"))
moby.findall(r"<a> (<.*>) <man>")

chat = nltk.Text(nps_chat.words())
chat.findall(r"<.*> <.*> <bro>")
chat.findall(r"<l.*>{3,}")

3.6 は正規化、ステミング。

東京公共交通オープンデータチャレンジ

Toru Furukawa — Wed, 24 Jan 2018 22:45:36 +0000

東京公共交通オープンデータチャレンジという、アプリコンテスト＋アイデアコンテストがある。東京の交通機関のAPIやデータを活用しましょうってことらしい。

ここがつらいよ東京公共交通オープンデータチャレンジAPI というまとめがあるくらい、なかなか大変そうではある。でも、いままで全然こんなデータはなかったんだから、こういうことでちょっとずつ進んでいくとよいのかも知れない。NAVITIME や Google はすごいな、と改めて思う。

入門自然言語処理 pp.83-86

Toru Furukawa — Tue, 23 Jan 2018 22:22:47 +0000

ウェブのテキストを取得する方法。nltk 3.2.5 では、サンプルがそのまま動かない。3.1.2章のHTML処理をするには、以下のようにする。

$ pip install beautifulsoup4

$ python
Python 3.6.3 (default, Dec 14 2017, 14:27:23)
...
>>> import nltk
>>> from bs4 import BeautifulSoup
>>> url = "http://news.bbc.co.uk/2/hi/health/2284783.stm"
>>> html = urlopen(url).read()
>>> html = html.decode()
>>> soup = BeautifulSoup(html, "html.parser")
>>> raw = soup.get_text()
>>> tokens = nltk.word_tokenize(raw)
>>> text = nltk.Text(tokens)
>>> text.concordance("gene")
Displaying 7 of 7 matches:
hey say too few people now carry the gene for blondes to last beyond the next
blonde hair is caused by a recessive gene . In order for a child to have blond
...

入門自然言語処理 p.79

Toru Furukawa — Mon, 08 Jan 2018 02:32:43 +0000

あまりに頭に入っていない気がするので、練習問題をいくつかやってみることにする。私は手を動かして、何かを作って、理解する必要がある傾向がある。効率は悪いけれど、そういうパターンらしいのでしょうがない。

https://github.com/torufurukawa/learn-nlp

リポジトリを作ったんだけど、initial commit のプッシュがうまくいかなくて時間を使った。SourceTree を使って clone するときに https を使ったらしく、push のときに SSH の認証情報を渡してもだめだった、というオチである。何をやっているんだか。

とりあえず数行で解決する問題を、1問解いてプッシュしておいた。