請求書の複数 (一部) 支払いのサポートを追加しました互換性に関わる変更

新規情報

請求書とクレジットノートで複数 (一部) 支払いのサポートを導入する予定です。請求書が過払いと不定期決済をサポートするようになりました。加えて、Invoice オブジェクトに confirmation_secret フィールドを追加し、Payment Element の使用サポートを強化する予定です。

この変更により互換性が失われる理由

• Invoice オブジェクトから payment_intent、charge、paid、paid_out_of_band フィールドを削除しました。
• PaymentIntent オブジェクトと Charge オブジェクトから invoice フィールドが削除されました。
• application_fee_amount フィールドおよび transfer_data フィールドがインボイスオブジェクトから削除されました。Stripe 上で作成された支払いについて、payments.data.payment.payment_intent をインボイスオブジェクトで展開することで、これらのフィールドが元となっている PaymentIntent を通じてアクセスできるようになります。
• Credit Note オブジェクトのrefund フィールドを廃止し、refunds 配列に置き換えました。
• Invoice オブジェクトの amount_paid フィールドに不定期決済が反映されるようになりました。

影響

決済と請求書の接続を表す Invoice Payment オブジェクトを導入し、関連オブジェクトから以前の請求書と決済のポインターを削除しました。1 つの請求書を 1 回の決済で一括払いする必要があると仮定しないようにシステムを更新し、新しい Invoice Payment オブジェクトを使用して決済と請求書の関係を把握する必要があります。

invoice.payments 配列で決済情報を調べる

invoice.payments は、Invoice オブジェクトを操作する際に payments プロパティを展開することで調べることができます。

curl -G https://api.stripe.com/v1/invoices/{INVOICE_ID} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "expand[]"=payments

invoice.payments 配列は、請求書に関連付けられているすべての決済と、それぞれの割り当てと決済ステータスのリストを提供します。

決済と請求書の関連付けには、新しい Invoice Payment エンドポイント を使用する

Payment Intent と Invoice オブジェクトの関係を理解するには、List Invoice Payment エンドポイント を使用します。

curl -G https://api.stripe.com/v1/invoice_payments \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "payment[type]"=payment_intent \
  -d "payment[payment_intent]"={PAYMENT_INTENT_ID}

Payment Element の実装には confirmation_secret を使用します

Payment Element の実装、特にサブスクリプションの実装では、以前は invoice.payment_intent.client_secret または latest_invoice.payments.data.payment.payment_intent.client_secret の拡張に依存していましたが、confirmation_secret を展開することで、Invoice オブジェクトの新しい invoice.confirmation_secret.client_secret フィールドを使用できるようになりました。

curl -G https://api.stripe.com/v1/invoices/{INVOICE_ID} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "expand[]"=confirmation_secret

PaymentIntents を使用して application_fee_amount と transfer_data にアクセスする

Invoice オブジェクトから application_fee_amount フィールドおよび transfer_data フィールドが削除されたため、元となっている PaymentIntent を介して Stripe で作成された支払いについてこれらのフィールドにアクセスできるようになりました。請求書の取得時に payments.data.payment.payment_intent を拡張してください。

curl -G https://api.stripe.com/v1/invoices/{INVOICE_ID} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "expand[]"="payments.data.payment.payment_intent"

その後、拡張された PaymentIntent オブジェクトから invoice.payments.data[i].payment.payment_intent.application_fee_amount および invoice.payments.data[i].payment.payment_intent.transfer_data にアクセスできます。これらのフィールドは決済方式が payment_intent のときに Stripe 上で作成された支払いにのみ利用できます。

不定期決済の請求書を特定する

paid_out_of_band フィールドの削除により、invoice.payments プロパティを使用して、帯域外決済の請求書を特定できるようになりました。

請求書が完全に支払われたかどうかを確認するには、請求書ステータス が 支払い済み であること、amount_due が 0 より大きいこと、および invoice.payments 配列内の PaymentIntent タイプ の決済の合計が 0 であることを確認します。

請求書の一部が不定期に支払われているかどうかを確認するには、amount_due が 0 を超え、invoice.payments 配列の PaymentIntent タイプの決済の合計が amount_paid 未満であることを確認します。

変更点

アップグレード