Stripe Payments ＞ SOURCES ／ ソース

docs

Payments > SOURCES > Payment Methods
・Supported Payment Methods on the Sources API
・Sources APIでサポートされている支払い方法

Sources APIを介して利用できるさまざまな支払い方法とメカニズムについて学ぶ

Sourcesオブジェクトを使用すると？

単一のAPIでさまざまな支払い方法を受け入れることができる
・ソースは顧客の支払い手段を表し、Stripe APIとともに使用して支払いを作成できる
・ソースは直接請求することも、後で再利用するためCustomerオブジェクトに関連付けすることもできる

4つの主要な特性

Sources APIでサポートされている各支払い方法は、4つの主要な特性によって定義されている
・これらの特性の組み合わせによって、支払元をどのように請求可能にするか、および支払を完了するための請求リクエストでの使用方法が決まる

プルまたはプッシュ ：支払い方法のための資金があなたの顧客からどのように振り込まれるか
フロー ：支払いを認証するために顧客が取らなければならない行動の種類
使用法 ： Sourceが再利用可能かどうか
同期または非同期 ：課金結果を即時に確認できるか、後でのみ確認できるか
Sources APIを使用して支払い方法を受け入れる方法を示す完全な例については、このサンプルのEコマースストアをチェックし、GitHubでそのソースコードを参照してくれ

サポートされている支払い方法

ダッシュボード内にある「支払いの設定」で、利用可能な支払い方法を有効にできる
・有効化は通常すぐに行われる。追加の契約を必要とせず、また長いプロセスを含まない
・詳細なリストについては、利用可能な支払い方法とそれらのサポートされている地域(の決済手段ガイド)を見てくれ

・次の表(抜粋)は、前述の主な特徴とサポートされている支払い方法を対応付けたものである

-	-	NONE	REDIRECT
PULL	SYNCHRONOUS	Cards	3D Secure

使い捨てまたは再利用可能

特定の支払い方法
・顧客が再度支払いプロセスを完了しなくても、追加の支払いに再利用できるソースを作成できる

再利用可能なSourceオブジェクト
・そのusageプロパティが’reusable'設定されている

逆に、Sourceオブジェクトが1回しか使用できない場合
・'susage’プロパティは’single_use’に設定され、顧客が支払いをするたびにSourceオブジェクトを作成する必要がある
・このようなSourceオブジェクトはCustomerオブジェクトに関連付けされるべきではなく、代わりに直接 chargeされるべきである
・これらは一度だけ chargeすることができ、それらのSourceオブジェクトの'status’プロパティは charge時に’consumed’へ変わる

再利用可能なソース
・再利用するために Customerオブジェクトに関連付けする必要がある（直接chargeされた場合、Sourceオブジェクトの'status’プロパティは’consumed'へ変わる）
・ソースを顧客に添付する方法、および顧客のソースリストを管理する方法については、 ソースおよび顧客ガイドを参照してくれ


・Stripe Sources APIにおける決済の抽象化

docs

Payments > SOURCES > Best Practices
・Best Practices Using Sources
・ソースを使用したベストプラクティス

単一のAPIを通じてさまざまな支払い方法を受け入れるためのベストプラクティス
・チェックアウトフローを設計するときにSources APIの柔軟性を考慮することで、追加の支払い方法をサポートするために必要な変更を最小限に抑えることができる

カード決済の一般的な流れ

カード決済のための典型的なチェックアウトフロー（ 3D Secureを除く）
・カード情報を集めてソースを作成し、そしてすぐにそれをchargeリクエストをするために使用する
・追加の措置を講じる必要はない
・また、カードによる支払いでは同期確認が行われるため、支払いが成功し、資金が保証されているかどうかをすぐに確認できる
・WebHookの使用は不要である

ウェブフックを必要とする用途

他の支払い方法では、ソースがchargeableになり、 chargeリクエストを行うために使用される準備が整う前（例：iDEAL）に、customerに追加のアクションを求める場合がある（例：リダイレクト）
・この遷移は一般に非同期的に発生し、顧客があなたのウェブサイトを離れた後にも発生する可能性がある
・これらの理由から、chargeを作成するためにsourceがchargeableになる時期を判断するには、integrationでWebフックを使用することが不可欠である

次のWebhookイベントがsourceのstatusの変更について通知するために送信される

イベント	説明	提案されたアクション
source.chargeable	Sourceオブジェクトは、顧客が支払いを認証および確認した後、chargeableになる	Create a Charge.
source.failed	顧客が支払いの認証を拒否したため、Sourceオブジェクトはchargeableになることができなくかった	注文をキャンセルし、オプションで支払いフローに顧客を再参加させる
source.canceled	Sourceオブジェクトは有効期限が切れており、請求の作成には使用できない	注文をキャンセルし、オプションで支払いフローに顧客を再参加させる

Source作成

Sourcesを作成するとき
・source.chargeable Webhookを受け取って処理するときに注文を取得できるように、内部注文表現に source IDを記録する必要がある
・効率的な検索のために、このsource属性に基づいて注文オブジェクトに必ずインデックスを付けてくれ

Charge作成

あなたはsourceを chargeするのにsource.chargeableウェブフックに頼るべきである
・Webhookを受信したら、受け取ったソースIDに基づいて内部の注文表現を検索し、注文が支払い待ちになっていることを確認する

chargeリクエストを行う際
・競合状態を回避するために、内部注文IDを idempotency keyとして使用することを強くお勧めする
・さらに、ソースが再利用可能であり、それを再利用したい場合は、課金する前に必ずそれを Customerオブジェクトに関連付けしてくれ
・使い捨ておよび再利用可能なソースの処理方法およびそれらが顧客とどのようにやり取りするかについての詳細は、 使い捨てまたは再利用可能およびソースおよび顧客ガイドを参照してくれ

・ソースの作成と同様に、 charge.succeeded Webhooksを受け取って処理したときに注文を取得できるように、内部の注文表現に charge IDを記録する必要がある

確認ページ

顧客が支払いを承認するために必要なアクションを実行した後（例えば、彼らがリダイレクトを辿った後など）
・注文の状態を示す確認ページを表示する必要がある
・注文を内部的に調査することによってこれを行うことができる

確認ページをさらに合理化したい場合
・ウェブフックの配信待ち時間は保証されていないため、確認ページをさらに合理化したい場合は、クライアントサイドコードで関連するソースのステータスを調べることができる
・ あなたのソースがchargeableになったことを検出したら、source.chargeableウェブフックが到着するのを待たずにそのソースを使ってChargeの作成を開始することができる
・一部の種類のソースは、chargeableとなるまでに数分（または数日）かかる場合がある
・あなたがソースを調査することにした場合、私たちはあなたがある時点でタイムアウトして、彼らの注文が支払い確認を待っていることを顧客に告げること、そして非同期に彼らに支払い確認Eメールを送ることを勧める
・下の表には、各Sourceのステータスに対して推奨される顧客向けメッセージが表示されている

・顧客があなたのページを離れると、クライアントサイドの調査が停止することに注意することも重要である
・これは、あなたがあなたの顧客の注文を見失わないようにするためにsource.chargeableウェブフックに対してもintegrateしなければならないことを意味する

・Stripe.jsを使用している場合は、 stripe.retrieveSource()を使用して独自の調査を実装できる

・下の表には、ソースのステータスに基づいて表示できる、顧客に向けられた可能性のあるメッセージの推奨事項が含まれている

STATUS	顧客向けメッセージング
Source is chargeable	あなたの注文は受け取られましたそして支払い確認を待っています。
Source is canceled	支払いが失敗し、注文を処理できませんでした。
Source is failed	支払いが失敗し、注文を処理できませんでした。
Source is still pending after polling for a while	あなたの注文は受け取られましたそして支払い確認を待っています。

・Chargeを作成すると（そしてユーザーがまだ確認ページにいる場合）、Chargeのステータスに基づいて次のメッセージを表示できる

STATUS	顧客向けメッセージング
Charge is pending	あなたの注文は受け取られましたそして支払い確認を待っています。
Charge is failed	支払いが失敗し、注文を処理できませんでした。
Charge is succeeded	お支払いは確認され、注文は完了です。

注文確認

charge.succeeded webhookを受け取った後にのみあなたの注文を確認してくれ（すぐにまたは一定時間後に）
・支払い確認には非同期支払いに何日もかかることがあるため、この段階でお客様にEメールを送信することを強くお勧めする

キャンセルと失敗

あなたはsource.canceledとsource.failed webhooksを聞いて、関係するソースに関連した注文をキャンセルすることを確認するべきである
・あなたが上記のベストプラクティスに従うならば、あなたは以前にchargeableだったsourceのsource.canceledウェブフックを決して受け取るべきではない（あなたのsource.chargeableハンドラはソースがキャンセルされるのを防ぐためにすぐにchargeを作ったはずである）
・chargeable ではなく pendingのままのソースについては、source.canceled Webhookを受け取ることになる
・これは、通常、顧客がチェックアウトフローを早めに行ったことを示している
・顧客が支払いを拒否したとき、または支払いスキームレベルで技術的な失敗が発生したときに、 source.failedフックを受け取ることも可能である

・受け取った chargeに関連する注文を確実にキャンセルするには、 charge.failedフックを確認する必要がある
・これらの各イベントについて、注文が失敗したことを顧客に連絡し、支払いフローに再度参加するように招待することをお勧めする

doc

Payments > SOURCES > Sources & Customers
・Sources and Customers
・ソースと顧客

・Customerオブジェクトを使用してソースを関連付けおよび管理する方法を学ぶ

Sourceオブジェクト

そのusageパラメーターで示されているように、 使い捨てまたは再使用可能にすることができる
・ソースは直接chargedできるが、 再利用可能なソースは、後で再利用できるように常にCustomerオブジェクトに関連付けする必要がある
・再利用可能なソースをCustomerオブジェクトに添付すると、以前にアプリやWebサイトで使用したことのある再利用可能な支払い方法のリストを顧客に提示できる

再利用可能なソース

特定の支払い方法（例： SEPA口座引き落とし）は再利用可能なソースをサポートしているので、あなたは顧客が再度支払いプロセスを完了する必要なしに追加の支払いを作成することができる
・reusableソースは、そのusageパラメータがreusableに設定されている

chargeリクエストを行う前に、再利用可能なソースをCustomerオブジェクトに関連付けする必要がある
・最初に関連付けせずに再利用可能なソースをchargeすると、そのchargeは消費される（そのステータスはchargeable から consumedへ変わる ）
・消費されたソースは更なる支払いには使用できない

新しいCustomerオブジェクトへのソースの添付

Customerオブジェクトを作成して、1つのAPI呼び出しでソースを関連付けすることができる
・あなたがこの顧客に会うのが初めての場合、これは役に立つ

// Set your secret key: remember to change this to your live secret key in production

// See your keys here: https://dashboard.stripe.com/account/apikeys

\Stripe\Stripe::setApiKey("sk_test_xxxx");



$customer = \Stripe\Customer::create([

  "email" => "paying.user@example.com",

  "source" => "src_18eYalAHEMiOZZp1l9ZTjSU0",

]);

・これは顧客の最初で唯一の支払い方法であるため、 ソースはCustomerオブジェクトの default sourceプロパティの値になる
・ソースを指定せずにcustomerパラメータを使用して請求を行うと、デフォルトのソースが自動的に選択される

既存のCustomerオブジェクトへのソースの関連付け

Customerオブジェクトの default sourceプロパティの値を更新
・デフォルトのソースを持つCustomerオブジェクトを更新すると、これによって既存のソースが自動的に切り離され、指定されたソースが新しいデフォルトとして追加される

Customerオブジェクトの default sourceプロパティの値を追加
・既存のデフォルトを置き換えずにソースを追加するには、以下に示すようにattachメソッドを使用する

// Set your secret key: remember to change this to your live secret key in production

// See your keys here: https://dashboard.stripe.com/account/apikeys

\Stripe\Stripe::setApiKey("sk_test_xxxx");



$customer = \Stripe\Customer::retrieve("cus_AFGbOSiITuJVDs");

$customer->sources->create(["source" => "src_18eYalAHEMiOZZp1l9ZTjSU0"]);

・ここでは、 Customerオブジェクトにデフォルトのソースがすでに存在している可能性があるため、新しく追加されたソースはデフォルトのソースにはならない
・但し、 Customerオブジェクトを更新してdefault_source値としてソースを指定することで、default sourceを変更できる

// Set your secret key: remember to change this to your live secret key in production

// See your keys here: https://dashboard.stripe.com/account/apikeys

\Stripe\Stripe::setApiKey("sk_test_xxxx");



\Stripe\Customer::update(

  "cus_AFGbOSiITuJVDs",

  [

    'default_source' => 'src_18eYalAHEMiOZZp1l9ZTjSU0',

  ]

);

・Stripe Q24。After attaching the source to the customer object, how do I check from the customer object?

関連付けソースをCharging

chargeリクエストを行うとき
・Customerオブジェクトとソースの両方を指定する必要がある

// Set your secret key: remember to change this to your live secret key in production

// See your keys here: https://dashboard.stripe.com/account/apikeys

\Stripe\Stripe::setApiKey("sk_test_xxxx");



$charge = \Stripe\Charge::create([

  "amount" => 1099,

  "currency" => "eur",

  "customer" => "cus_AFGbOSiITuJVDs",

  "source" => "src_18eYalAHEMiOZZp1l9ZTjSU0",

]);

ソースを指定せずにCustomerオブジェクトをchargeしようとすると
・Stripeは顧客のデフォルトのソースを使用する

CustomerからSourceオブジェクトを切り離す

特定のCustomerオブジェクトからソースを削除する必要がある場合は、そのソースを切り離すことができる
・detachされるとソースのステータスがconsumedに変わるので、一度detachすると使用することはできない
・chargeの作成には使用できなくなる

\Stripe\Stripe::setApiKey("sk_test_xxxx");



$customer = \Stripe\Customer::retrieve("cus_EiDcmm669r4cwb");

$customer->sources->retrieve("src_1EEnBAJiXAQvfxv3m86YDQVk")->detach();

デフォルトのソースID（src_xxxx）をdetachするとどうなるの？
・他のソースIDが自動的にデフォルトとなる
・この時の選定方法は不明

使い捨てのソース

使い捨てのソースは、顧客が支払いをするたびに作成する必要があり、再利用することはできない
・そのため、それらを顧客に永久に関連付けすることはお勧めできない

支払いを特定のCustomerオブジェクトに関連付ける場合
・ソースが関連付けされていなくても、ソースでchargeリクエストを行うときにcustomerパラメータを含めることができる
・ここで言う支払いと「ch_xxxx」なので注意が必要。カード情報の意味ではない
・例えば、(Customerオブジェクトに関連付けされていない)4111111111111111のソースID（src_xxxx）を指定した場合、4111111111111111のソースID（src_xxxx）で支払いが行われるが、4111111111111111カード情報はCustomerオブジェクトに関連付けされない
・つまり、トークンIDみたいな使い方もできる

// Set your secret key: remember to change this to your live secret key in production

// See your keys here: https://dashboard.stripe.com/account/apikeys

\Stripe\Stripe::setApiKey("sk_test_xxxx");



$charge = \Stripe\Charge::create([

  "amount" => 1099,

  "currency" => "eur",

  "customer" => "cus_AFGbOSiITuJVDs",

  "source" => "src_18eYalAHEMiOZZp1l9ZTjSU0",

]);

・逆に、Charge::createする際、customereパラメータ指定する場合は、"source"パラメータとして、トークンID（tok_xxxx）を指定不可。これは恐らく、CustomerオブジェクトにTokenオブジェクトを関連付けられないため。Chargeオブジェクトをcreateする際、下記パラメータの組み合わせは不可だから
Customer Token デモ3 参照

結果のChargeオブジェクト
・CustomerオブジェクトとSourceオブジェクトの両方を直接参照していなくても、それらを参照する

doc

Payments > SOURCES > Connect Platforms
・Connect Platforms Using the Sources API
・Sources APIを使用してプラットフォームを接続する