Checkout で顧客の納税者番号を収集する
顧客の納税者番号と法人名を請求書に表示することは一般的な要件であり、この要件を満たすには、Checkout で納税番号の収集を有効にします。このガイドでは、すでに Checkout が導入されていることを前提としています。まだ導入されていない場合は、ガイドをご覧ください。
サポートされる納税番号の種類
Checkout は、特定の地域で以下の納税者番号を収集します。
国 | 列挙値 | 説明 | 例 |
---|---|---|---|
アイスランド | is_vat | アイスランドの VAT | 123456 |
アイルランド | eu_vat | European VAT number | IE1234567AB |
アラブ首長国連邦 | ae_trn | アラブ首長国連邦の TRN | 123456789012345 |
イギリス | eu_vat | Northern Ireland VAT number | XI123456789 |
イギリス | gb_vat | イギリスの VAT 番号 | GB123456789 |
イタリア | eu_vat | European VAT number | IT12345678912 |
インド | in_gst | インドの GST 番号 | 12ABCDE3456FGZH |
エジプト | eg_tin | エジプトの納税者番号 | 123456789 |
エストニア | eu_vat | European VAT number | EE123456789 |
オーストラリア | au_abn | オーストラリア事業者登録番号 (AU ABN) | 12345678912 |
オーストリア | eu_vat | European VAT number | ATU12345678 |
オマーン | om_vat | オマーンの VAT 番号 | OM1234567890 |
オランダ | eu_vat | European VAT number | NL123456789B12 |
カザフスタン | kz_bin | カザフスタンの企業識別番号 | 123456789012 |
カナダ | ca_bn | カナダの BN | 123456789 |
カナダ | ca_gst_hst | カナダの GST/HST 番号 | 123456789RT0002 |
カナダ | ca_pst_bc | カナダの PST 番号 (ブリティッシュコロンビア) | PST-1234-5678 |
カナダ | ca_pst_mb | カナダの PST 番号 (マニトバ) | 123456-7 |
カナダ | ca_pst_sk | カナダの PST 番号 (サスカチュワン) | 1234567 |
カナダ | ca_qst | カナダの QST 番号 (ケベック) | 1234567890TQ1234 |
キプロス | eu_vat | European VAT number | CY12345678Z |
ギリシャ | eu_vat | European VAT number | EL123456789 |
クロアチア | eu_vat | European VAT number | HR12345678912 |
ケニア | ke_pin | ケニア税務当局の個人識別番号 | P000111111A |
サウジアラビア | sa_vat | サウジアラビアの VAT | 123456789012345 |
ジョージア | ge_vat | ジョージアの VAT | 123456789 |
シンガポール | sg_gst | シンガポールの GST | M12345678X |
スイス | ch_vat | スイスの VAT 番号 | CHE-123.456.789 MWST |
スウェーデン | eu_vat | European VAT number | SE123456789123 |
スペイン | es_cif | スペインの NIF 番号 (以前のスペインの CIF 番号) | A12345678 |
スペイン | eu_vat | European VAT number | ESA1234567Z |
スロバキア | eu_vat | European VAT number | SK1234567891 |
スロベニア | eu_vat | European VAT number | SI12345678 |
タイ | th_vat | タイの VAT | 1234567891234 |
チェコ共和国 | eu_vat | European VAT number | CZ1234567890 |
チリ | cl_tin | チリの TIN | 12.345.678-K |
デンマーク | eu_vat | European VAT number | DK12345678 |
ドイツ | eu_vat | European VAT number | DE123456789 |
トルコ | tr_tin | トルコの納税者番号 | 0123456789 |
ナイジェリア | ng_tin | ナイジェリアの納税者番号 | 12345678-0001 |
ニュージーランド | nz_gst | ニュージーランドの GST 番号 | 123456789 |
ノルウェー | no_vat | ノルウェーの VAT 番号 | 123456789MVA |
バーレーン | bh_vat | バーレーンの VAT 番号 | 123456789012345 |
ハンガリー | eu_vat | European VAT number | HU12345678 |
フィンランド | eu_vat | European VAT number | FI12345678 |
フランス | eu_vat | European VAT number | FRAB123456789 |
ブルガリア | eu_vat | European VAT number | BG0123456789 |
ベルギー | eu_vat | European VAT number | BE0123456789 |
ポーランド | eu_vat | European VAT number | PL1234567890 |
ポルトガル | eu_vat | European VAT number | PT123456789 |
マルタ | eu_vat | European VAT number | MT12345678 |
メキシコ | mx_rfc | メキシコの RFC 番号 | ABC010203AB9 |
ラトビア | eu_vat | European VAT number | LV12345678912 |
リトアニア | eu_vat | European VAT number | LT123456789123 |
ルーマニア | eu_vat | European VAT number | RO1234567891 |
ルクセンブルグ | eu_vat | European VAT number | LU12345678 |
ロシア | ru_inn | ロシアの INN | 1234567891 |
ロシア | ru_kpp | ロシアの KPP | 123456789 |
南アフリカ | za_vat | 南アフリカの VAT 番号 | 4123456789 |
韓国 | kr_brn | 韓国の BRN | 123-45-67890 |
納税者番号の収集を有効にする
納税者番号の収集が有効になっていると、Checkout は、顧客の場所に基づいて納税者番号収集フォームの表示と非表示を切り替えます。納税者番号収集でサポートされている場所に顧客が所在する場合は、顧客がビジネス上の購入であることを示すためのチェックボックスが表示されます。顧客がこのボックスをチェックすると、顧客が納税者番号とビジネスの正式名称を入力できるフィールドが表示されます。顧客の配送先住所が使用できる場合には、Checkout はその住所を使用して顧客の所在地を判断します。配送先住所がない場合には、顧客の請求先住所が使用されます。顧客が入力できる納税者番号は 1 つのみです。
新規顧客
新規顧客の納税者番号収集を有効にするには、Checkout セッションを作成する際に、tax_id_collection[enabled]
を true
に設定します。
注
上記のコードサンプルは、payment
モードで納税者番号の収集が有効化されたセッションを作成します。subscription
モードで納税者番号の収集を有効にするには、subscription
モードセッション作成リクエストで、緑でハイライトされた部分と同じ変更を行います。
Checkout をさらに設定して、customer_creation を使用するための Customer を新規で作成することもできます。この場合、Checkout はセッション中に収集された納税者番号情報をその新しい Customer に保存します。それ以外の場合、納税者番号情報を引き続き customer_details.tax_ids で利用できます。
既存の顧客
セッションの作成時に既存の顧客を渡すと、Checkout はセッションで収集された納税番号情報を使用してその顧客を更新します。Checkout は、収集されたビジネス名を顧客の name プロパティに保存し、収集された納税番号を顧客の customer.tax_ids 配列に追加します。ビジネス名を収集することにより顧客の既存の Name (名前) オブジェクトが上書きされる場合があるため、セッション作成時に customer_update[name]
を auto
に設定する必要があります。
注意
Checkout は、顧客に既存の納税者番号がない場合のみに納税者番号を収集します。顧客に 1 つ以上の納税者番号が保存されている場合、Checkout は、納税者番号の収集が有効になっていても、納税者番号の収集フォームを表示しません。
既存の顧客の住所をすでに収集している場合、顧客の既存の住所、または決済時に収集する住所のいずれかに基づいて場所を判定できます。デフォルトでは、Checkout は顧客の場所を判定するために、顧客の既存の住所を探します。
既存の顧客の住所が保存されていない場合、決済時に入力される請求先住所または配送先住所を基に場所を判定することができます。決済時に入力された請求先住所を使用して顧客の場所を判定する旨を指定するには、customer_update[address]
を auto
に設定する必要があります。
注
customer_update[address]
を auto
に設定すると、Checkout は顧客に以前保存された住所を、セッション中に入力された住所に置き換えます。
既存の顧客の配送先住所を収集している場合、決済時に入力される配送先住所を基にする必要があります。このためには、 customer_update[shipping]
を auto
に設定する必要があります。
注
customer_update[shipping]
を auto
に設定すると、Checkout は顧客に以前保存された配送先住所を、セッション中に入力された配送先住所に置き換えます。
注
上記のコードサンプルは、payment
モードで納税番号の収集が有効化されたセッションを作成します。subscription
モードで納税番号の収集を有効にするには、subscription
mode セッション作成リクエストに、緑でハイライトされた部分と同じ変更を行います。
セッション後に顧客の納税者番号の詳細を取得する
Checkout は、生成された Session (セッション) オブジェクトに提供された納税者番号を含めます。各セッションの完了後に、Checkout は checkout.session.completed イベントを送信します。これは Webhook エンドポイントでリッスンできます。納税者番号を Session オブジェクトから取得する場合には、納税者番号はセッションの customer_details.tax_ids 配列で取得できます。
{ "object": { "id": "cs_test_a1dJwt0TCJTBsDkbK7RcoyJ91vJxe2Y", "object": "checkout.session", ... "customer": "cus_id_of_new_customer", "customer_details": { ... "tax_ids": [ {
Checkout はさらに、Customer (顧客) オブジェクトがセッションに関連付けられている場合、収集された納税者番号とビジネス名をこのオブジェクトに保存します。決済時に収集された納税者番号は、顧客の customer.tax_ids 配列でアクセスできます。また、owner[type]
パラメーターを顧客 ID の customer
および owner[customer]
に指定することで、顧客に保存されたすべての納税者番号を Tax ID リソースで取得することもできます。すべての新しい納税者番号には関連付けられているビジネスの正式名称が含まれ、Checkout はそれを顧客の name プロパティに保存します。このようにすることで、収集された法人名がその顧客のサブスクリプションのインボイスに常に表示されることになります。
組み込みをテストする
テスト環境では、サポートされている納税番号の種類の、正しい形式で任意の英数字文字列を入力できます (eu_vat
の DE123456789
など)。サンプルの納税番号の一覧については、顧客の納税者番号ガイドをご覧ください。また、テスト用の納税番号を使用してさまざまな検証ステータスフローをテストすることもできます (ビジネスの納税番号のテストをご覧ください)。
検証
Checkout は、セッションの際にチェックを行って、指定された納税者番号が正しい形式であることを確認します。セッションでは提供された納税者番号が有効かどうかの検証は行われません。Checkout で収集された顧客情報の有効性を、ご自身で確認する必要があります。そのためにお手伝いとして、Stripe では、オーストラリア事業者登録 (ABN) 番号、ヨーロッパの付加価値税 (EU VAT) 番号、およびイギリスの付加価値税 (GB VAT) 番号の政府データベースと照らし合わせる非同期の検証を自動的に行います。Stripe が実行する検証の詳細、およびそれらの検証結果を使用する方法については、顧客の納税者番号ガイドをご覧ください。