課金オブジェクトに関するAPIの仕様変更を行います

以下のスケジュールの通り、課金オブジェクトに関するAPIの仕様変更を行います。

  • 2014/12/22(月)よりテスト環境のみ
  • 2015/01/19(月)より商用環境を含む全ての環境

変更点は、

  1. 仮売上状態の課金オブジェクトのpaidプロパティがtrueに変わります
  2. 課金リストを取得するAPIが「失敗した課金」も含めてレスポンスするようになります

となっており、

  • 仮売上の作成の成功判定にpaid: falseを確認している方
  • 課金の一覧取得時に仮売上かどうかをpaid: falseで判定している方
  • 課金の一覧に失敗した課金が含まれる場合を想定されない実装をされている方

に該当する利用者の方が影響を受けます。

テスト環境では既に仕様変更について適用されていますので、以下の詳細をご一読の上、今一度ご自身の実装の動作をご確認下さい。

1. 仮売上状態の課金オブジェクトのpaidプロパティ

paidはbooleanでカードの与信枠の確保を示すものですが、 これまで、仮売上状態の課金オブジェクトは、paid: falseとして表現されてしまっておりました。

決済に失敗した課金オブジェクトも同様にpaid: falseとなっているため、これらが並んだ場合に見分けることが難しい状態1でした。

そこで、上記の状態を正しいものにするため、仮売上状態の課金オブジェクトのプロパティがpaid: trueに変更致します。

今回の仕様変更に関する課金オブジェクトの状態とpaidプロパティとの対応は次の通りです。

課金の状態 従来 今後 備考
仮売上 false true -
実売上 true true 変更なし
決済失敗 false false 変更なし

現在、仮売上の成功の判定にpaid: falseを条件付けている方は、商用環境の仕様の変更日(2015/01/19)までに、 captured: falseおよびfailure_message: nullを確認するようにプログラムを修正して下さい。 仕様の変更日以降ではpaid: true, captured: falseで仮売上の成功とみなすようにしてください。

なお、この変更前に作成されたイベントオブジェクトに含まれるChargeオブジェクトのプロパティは遡って修正致しませんのでご了承下さい。

2. 課金リストのAPIに「失敗した課金」を追加

従来、作成された課金オブジェクトの一覧のAPIでは、仮売上もしくは実売上となった課金オブジェクトのリストが取得出来ていました。

今回、上記の課金オブジェクトの仕様変更に合わせて、決済に失敗した課金もリストに含むようになります。 同時に、paid,capturedパラメータを指定することで作成された課金の絞込が可能になります。

絞込を行う際のパラメータの条件は次の通りです。

絞り込む条件 paid captured
仮売上状態の課金 - false
実売上状態の課金 - true
仮売上もしくは実売上(作成に成功した課金) true -
作成に失敗した課金 false -
すべて - -

従来と同等の課金一覧の結果を取得したい場合、商用環境の仕様の変更日(2015/01/19)までに、 paid: trueを指定するようにプログラムを修正してください。変更日以前にpaid: trueを含むリクエストを送信しても、結果には影響しません。

2014/1/22に上記表の絞り込む条件の文が作成に失敗したかどうかについて不明瞭であったため修正致しました

課金の状態で絞り込む

各状態の課金を抽出するRubyによる実装のサンプルを以下に示します。 この例はRubyライブラリのバージョン3.2.2以降でのみ動作します。

同等の機能がJava、Node.js、PHP、Pythonのライブラリのバージョン2.2.2以降でも提供されます。

仮売上のリストを抽出する

1
2
3
4
5
6
require 'webpay'
webpay = WebPay.new('test_secret_eHn4TTgsGguBcW764a2KA8Yd')
charges = webpay.charge.all(captured: false)

puts charges.first.paid #=> true
puts charges.first.captured #=> false

実売上のリストを抽出する

1
2
3
4
5
6
require 'webpay'
webpay = WebPay.new('test_secret_eHn4TTgsGguBcW764a2KA8Yd')
charges = webpay.charge.all(captured: true)

puts charges.first.paid #=> true
puts charges.first.captured #=> true

仮売上および実売上(与信枠の確保に成功した課金)のリストを抽出する

1
2
3
4
5
6
require 'webpay'
webpay = WebPay.new('test_secret_eHn4TTgsGguBcW764a2KA8Yd')
charges = webpay.charge.all(paid: true)

puts charges.first.paid #=> true
puts charges.first.captured #=> unknown

決済に失敗した課金のリストを抽出する

1
2
3
4
5
6
require 'webpay'
webpay = WebPay.new('test_secret_eHn4TTgsGguBcW764a2KA8Yd')
charges = webpay.charge.all(paid: false)

puts charges.first.paid #=> false
puts charges.first.captured #=> false

今回の変更で影響を受ける方には、誠にお手数をおかけいたしますが、 新たに失敗した課金の抽出が可能となりますので、購入者のどのような問題に影響を受けているかなどの分析に役立てて頂けますと幸いです。


  1. 厳密には決済に失敗した課金にはfailure_messageプロパティに情報が含まれています。 決済に失敗した課金オブジェクトとは「カードの情報を含むパラメータに誤りはないが、カードの状態(利用停止や利用限度額に達しているなど)が原因で決済を行えなかった」ことを指すもので、 このリクエスト時にはエラーレスポンスが返されるため、uuidを用いて再度リクエストを行うか、発行されたイベントオブジェクトの中身を取り出さない限りは、実際に失敗した課金が作成されていることを感知出来ません。