トークンの流れ

定期的に決済を繰り返す場合はトークンを使用します。後の決済で使用するためにコンシューマーのクレジットカード情報を保存しておくのと同じ方法でトークンを保存し、後でコンシューマーに請求を行えるようになります。

ペイディのトークンサービスには、次のように様々なメリットがあります。

  • クレジットカードを使用しないコンシューマーに対して、定期的に請求を行えるようになります。通常のペイディの時と同じく、コンシューマーがクレジットカードの情報を求められることはありません。コンシューマーはメールアドレスと電話番号だけで安全かつ手軽に定期購入を行えます。
  • 定期購入の決済でクレジットカードを使用する場合、決済が否決される一番の理由がクレジットカードの有効期限切れです。ペイディのトークンには有効期限がないため、定期購入の決済が滞りなく進みやすくなります。
  • トークンを作成する時点では、コンシューマーに対する請求が一切行われません。トークンを作成する操作と決済を開始する操作は、それぞれ別のリクエストを通じて行います。このように柔軟性が高くなっているため、コンシューマーに対してすぐに請求を行うことも、「お試し期間」が過ぎるのを待ってから請求を行うこともできます。
  • トークンを作成する時点では金額を指定せず、トークンを使って決済データを作成する度に金額を指定するため、マーチャントは月毎に請求金額を変更できます。

  トークンを使用する流れ

[how-to diagram]

トークンの作成

トークンはコンシューマーがPaidy Checkout経由で作成します。 まず、コンシューマーがマーチャントの支払いページで決済方法としてペイディを選択すると、Paidy Checkoutが開始し、ユーザー認証を行ってトークンを作成します。 次に、マーチャントがバックエンドシステムにトークンIDを保存します。以後、マーチャントはこのトークンを使ってコンシューマーの代わりに決済を開始できるようになります。

トークンが発行された時点では、決済はまだ開始していません。このトークンとは、単にコンシューマーのペイディアカウントを識別するだけのものです。 トークンを使用する決済を新たに開始したい段階で、マーチャントがAPI経由でリクエストを送信する必要があります。そうするとペイディが検証を行い、検証が成功すると決済開始となります。トークンを使用する決済の場合でも、決済を処理する段階で決済のAuthorizeが行われます。つまり、トークンが有効な場合でも、そのトークンを利用して作成した決済は与信審査により否決される可能性があります。

トークンの管理

トークンが作成されたら、マーチャントはペイディAPIを利用してトークンを管理していきます。マーチャントはトークンのSuspend（一時的に無効化）、Resume（回復）、Delete（削除）といった操作を行えます。

  • SuspendリクエストもDeleteリクエストもトークンを使用できなくするという点では同じ機能を持ちますが、Suspendリクエストがトークンを「一時的に」無効化するのに対し、Deleteリクエストはトークンを永久に使用できなくします。
  • 無効化したトークンを再び有効にして決済を開始できる状態に戻すのが、Resumeリクエストです。

コンシューマーもペイディサポートに電話することで、トークンを一時的に無効化したり、回復したりできます。一時的に無効化されたトークンを回復できるのは、無効化した本人だけです。つまり、コンシューマーはマーチャントが一時的に無効化したトークンを回復できませんし、その逆も同様です。

トークンのライフサイクル

[token lifecycle diagram]

  • ステータス

    説明

  • ACTIVE

    正常に作成されたトークンに付与される初期状態のステータスです。また、トークンを回復した後もステータスがACTIVEになります。ステータスがACTIVEでないトークンを使って決済を開始することはできません。
    ステータスがACTIVEであるトークンに対して行えるリクエストは、決済開始、一時的に無効化、削除、1件取得、すべて取得です。

  • SUSPENDED

    マーチャント（API経由）あるいはコンシューマー（ペイディサポートに電話）が一時的に無効化したトークンに付与されるステータスです。一時的に無効化したトークンを使って決済を開始することはできません。マーチャントもコンシューマーもトークンを一時的に無効化できますが、そのトークンを回復できるのは無効化した本人だけですので、ご注意ください。 そのため、コンシューマーが無効化したトークンをマーチャントが回復させようとするとエラーが返されます。その逆も同様です。
    ステータスがSUSPENDEDであるトークンに対して行えるリクエストは、回復、削除、1件取得、すべて取得です。

  • DELETED

    マーチャントが正しく削除したトークンに付与されるステータスです。削除したトークンを使って決済を開始することはできません。また、回復することも不可能になります。
    トークンには有効期限がないため、不要になったトークンはDeleteリクエストで無効化していただく必要があります。
    ステータスがDELETEDであるトークンに対して行えるリクエストは、1件取得だけです。

  トークンのAPIについて

ペイディAPIを使って簡単かつ安全にトークンを管理できるようになります。API経由で行える操作は次の通りです。

  • トークンを一時的に無効化：statusをSUSPENDEDに変更します。一時的に無効化したトークンを使って決済データを作成することはできませんが、 マーチャントはResumeリクエストを送信することで再びトークンを有効な状態に戻すことができます。
  • トークンの回復: statusをACTIVEに変更します。 回復させたトークンは決済データを作成するために再び使用できるようになります。 マーチャントが回復できるのは、自分で無効化したトークンだけです。
  • トークンの削除: statusをDELETEDに変更します。 削除したトークンは、決済データを作成するために使用できなくなるだけでなく、回復することも不可能になります。
  • トークンの取得: 単体のtokenオブジェクトをリクエストして取得します。
  • すべてのトークンを取得: statusがACTIVEあるいはSUSPENDEDのtokenオブジェクトをすべてリクエストして取得します。

安全な通信

ネットワーク通信を暗号化し、インターネット上に存在するウェブサイトが本物であることを確認するために業界で標準的に採用されているプロトコルが、TLSです。ペイディはこのTLSのバージョン1.1以降をサポートしています。さらに、あらゆるデータを安全にやり取りするために、HTTPS通信を利用しています。

  トークンの作成

トークンはPaidy Checkoutを通じて発行されます。コンシューマーがPaidy Checkoutでメールアドレスと携帯電話の番号を入力すると、ペイディはSMS経由でコンシューマーの認証を行います。これが成功して新しいトークンが作成されたら、マーチャントはトークンを保存しておき、以降はコンシューマーの代わりに新しく決済データを作成できるようになります。 トークンが作成された時点で決済がAuthorizeされるわけではない、という点にご注意ください。決済のAuthorizeは、トークンを使って決済を処理する段階で行われます。つまり、トークンが有効な場合でも、そのトークンを利用して作成した決済は与信審査により否決される可能性があります。

単一の定期購入で使用するトークンは、コンシューマー毎に一度だけ作成されます。しかし、同じマーチャントの別の定期購入商品、あるいは他のマーチャントの商品に対しては別のトークンを使用するため、コンシューマーが複数のトークンを持つことができるようになっています。

トークンに有効期限はありません。トークンが不要になった場合は、ペイディAPI経由でDeleteリクエストを送信してください。

  トークンの一時的な無効化

トークンを一時的に無効化する際は、/tokens/{id}/suspendエンドポイント（{id}の部分はペイディのトークンID）にPOSTリクエストを送信します。リクエストが成功するとトークンのステータスがSUSPENDEDに変わり、そのトークンを使用して決済を開始しようとしても、エラーが返ります。

トークンの一時的な無効化

SuspendリクエストでもDeleteリクエストでも、トークンを「無効化」できます。ただし、あとで決済データの新規作成に使用できるよう、トークンを回復できます。一方、削除されたトークンは回復不可能であり、新規決済を作成するために使用することはできなくなります。

例：


curl -X "POST" "https://api.paidy.com/tokens/tok_WK5KjCEAAA0RvPp9/suspend" \
  -H "Content-Type: application/json" \
  -H "Paidy-Version: 2018-04-10" \
  -H "Authorization: Bearer $secret_key" \
  -d $'{
	"reason": {
		"code": "fraud.suspected",
		"description": "Token suspended because fraud suspected."
	},
	"wallet_id": "default"
	}'

取り扱う商品、業務上の手続き、顧客サービスに関するルールはマーチャント毎に異なるため、トークンを一時的に無効化する理由も様々です。以下に、マーチャントがトークンを一時的に無効化するケースとして考えられる、ほんの一部の例を示します。

  • トークンを使用して発生した請求額が正しくないという指摘をコンシューマーから受けたため、確認を行うまでの間、そのトークンで新規に決済を開始しないようにする場合
  • コンシューマーから定期購入を一時中断してもらいたいというリクエストがあった場合（長期間、家を空けるなど）
  • コンシューマーとの間にトラブル（支払いの滞納など）があったため、支払いが正常に行われるまでの間、そのトークンで新規に決済を開始しないようにする場合
  • トークンの利用に関して疑わしい挙動がみられる場合

リクエストには、トークンを一時的に無効化する理由を含める必要があります。reasonのcodeについては、次の表にあるいずれかのコードを指定してください。この表にないコードを送信した場合、システムはエラーを返します。 descriptionフィールドは、トークンを一時的に無効化する理由を補足するのに使用できます。

  • コード

    用途

  • consumer.requested

    コンシューマーから電話で「トークンを一時的に無効化してもらいたい」という要望があった場合、このコードを使用してください。

  • merchant.requested

    マーチャント自身の判断でトークンを一時的に無効化する場合はこのコードを使用してください。

  • fraud.suspected

    トークンの利用に関して疑わしい挙動がみられる場合はこのコードを使用してください。

  • general

    その他のケースではこのコードを使用してください。

トークンの状態がACTIVEであることをペイディ側で確認した上で、トークンが一時的に無効化されます。一時的に無効化されたトークンには、無効化をリクエストした人物（authority）についての情報が付与されます。API経由でトークンが無効化された場合、このauthorityフィールドの値は「merchant」になります。

マーチャントはAPI経由で、コンシューマーはペイディサポートに電話することで、トークンを一時的に無効化することができます。 無効化したのがコンシューマーであっても、マーチャント自身であっても、トークンが一時的に無効化された場合はWebhookの通知（設定している場合）によってそのことが知らされます。

  トークンの回復

一時的に無効化したトークンの使用を再開する際は、APIを利用してResumeリクエストを送信します。コンシューマーとマーチャントはどちらもトークンを一時的に無効化できますが、この一時的に無効化されたトークンを回復できるのは無効化した本人（Authority）だけです。コンシューマーによって一時的に無効化されたトークンをマーチャントが回復しようとしても（あるいはその逆の場合でも）、リクエストは失敗します。

トークンの回復

例：


curl -X "POST" "https://api.paidy.com/tokens/tok_WK5KjCEAAA0RvPp9/resume" \
  -H "Content-Type: application/json" \
  -H "Paidy-Version: 2018-04-10" \
  -H "Authorization: Bearer $secret_key" \
  -d $'{
         "wallet_id": "default",
         "reason": {
            "code": "consumer.requested",
            "description": "Consumer wants to continue with the subscription."
         }
      }'

取り扱う商品、業務上の手続き、顧客サービスに関するルールはマーチャント毎に異なるため、トークンを回復する理由も様々です。自分で一時的に無効化したトークンをマーチャントが後から回復するケースとして考えられる、ほんの一部の例を以下に示します。

  • トークンを使用して発生した請求額についてコンシューマーと揉めたため、そのトークンを一時的に無効化していたが、後で問題が解決した場合
  • 長期間、家を空けるなどの理由で一時的に中断していた定期購入を、コンシューマーが再開したいと求めている場合
  • コンシューマーとの間にトラブルがあり、取引を一時停止していた（例：支払いを待っていた）が、後でその問題が解決した場合
  • トークンの利用に関して疑わしい挙動がみられたため調査を行ったが、詐欺行為とは無関係だと確認できた場合

リクエストには、トークンの状態を変更する理由を含める必要があります。reasonのcodeについては、次の表にあるいずれかのコードを指定してください。 この表にないコードを送信した場合、システムはエラーを返します。 descriptionフィールドは、トークンを一時的に無効化する理由を補足するのに使用できます。

  • コード

    用途

  • consumer.requested

    トークンの利用を再開してもらいたいというリクエストをコンシューマーから受けた場合に使用します。

  • merchant.requested

    マーチャント自身の判断でトークンを回復する場合に使用します。

  • general

    その他のケースではこのコードを使用してください。

トークンの状態がSUSPENDEDであることをペイディ側で確認した上で、トークンが回復されます。 リクエストが成功するとトークンのステータスがACTIVEに変わり、再び新規決済を開始できるようになります。

マーチャントはAPI経由で、コンシューマーはペイディサポートに電話することでトークンを回復することができます。回復したのがコンシューマーであっても、マーチャント自身であっても、トークンが回復された場合はWebhookの通知（設定している場合）によってそのことが知らされます。

  トークンの削除

トークンを削除する際は、APIを利用してDeleteリクエストを送信します。このリクエストによって実際にトークンが削除されるわけではありませんが、トークンが永久に無効な状態になるため、以後はそのトークンを使用する新規決済を開始できなくなります。しかし、tokenオブジェクトは引き続きAPI経由で取得できます。

マーチャントだけがAPI経由でトークンを削除できます。その際、削除するトークンの状態はACTIVEでもSUSPENDEDでも構いません。

トークンの削除

例：

curl -X "POST" "https://api.paidy.com/tokens/tok_WK5KjCEAAA0RvPp9/delete" \
  -H "Content-Type: application/json" \
  -H "Paidy-Version: 2018-04-10" \
  -H "Authorization: Bearer $secret_key" \
  -d $'{
         "wallet_id": "default",
         "reason": {
            "code": "subscription.expired",
            "description": "This subscription no longer available."
         }
      }'

取り扱う商品、業務上の手続き、顧客サービスに関するルールはマーチャント毎に異なるため、トークンを削除する理由も様々です。以下に、マーチャントがトークンを削除するケースとして考えられる、ほんの一部の例を示します。

  • コンシューマーから定期購入をキャンセルしてもらいたいというリクエストがあった場合
  • コンシューマーとの間に度々トラブルがあり、マーチャント自身が定期購入をキャンセルしたい場合
  • トークンの利用に関して疑わしい挙動がみられたため調査を行い、実際にそのトークンが詐欺目的で利用されていることが判明した場合

リクエストには、トークンを削除する理由を含める必要があります。reasonのcodeについては、次の表にあるいずれかのコードを指定してください。この表にないコードを送信した場合、システムはエラーを返します。descriptionフィールドは、トークンを一時的に無効化する理由を補足するのに使用できます。

  • コード

    用途

  • consumer.requested

    コンシューマーからトークンを削除するよう求められた場合に使用します。

  • subscription.expired

    定期購入やキャンペーンの期間が過ぎた場合に使用します。

  • merchant.requested

    マーチャント自身の判断でトークンを削除する場合に使用します。

  • fraud.detected

    悪意のある挙動があったためにトークンをキャンセルする場合に使用します。

  • general

    その他のケースではこのコードを使用してください。

リクエストが成功するとトークンのステータスがDELETEDに変わり、そのトークンを使用して決済を開始しようとしてもエラーが返されるようになります。

  特定のトークンを取得

API経由でtokenオブジェクトを取得することで、特定のトークンの状態や、そのトークンを一時的に無効化した人物を確認することができます。このリクエストでは、指定したtokenオブジェクトのみが返されます。

特定のトークンを取得

特定のトークンを取得する際は、/tokens/{id}エンドポイント（{id}の部分はペイディのトークンID）にGETリクエストを送信します。 例：


curl -X "GET" "https://api.paidy.com/tokens/tok_WK5KjCEAAA0RvPp9" \
  -H "Content-Type: application/json" \
  -H "Paidy-Version: 2018-04-10" \
  -H "Authorization: Bearer $secret_key"

状態がACTIVEあるいはSUSPENDEDのトークンのみを返す「Retrieve all（すべて取得）」リクエストと異なり、このリクエストではトークンの状態（ACTIVE、SUSPENDED、あるいはDELETED）によらず単一のトークンが返されます。

  トークンをすべて取得

マーチャントが取り引きするすべてのコンシューマーを対象にして、トークンの全リストを取得できます。このリクエストで取得できるリストには、有効（ACTIVE）なトークンと一時的に無効化（SUSPENDED）されたトークンのみが含まれます。永久に無効化（DELETED）されたトークンはリストに含まれません。

トークンをすべて取得

トークンをすべて取得するには、/tokens/エンドポイントにGETリクエストを送信します。 例：


curl -X "GET" "https://api.paidy.com/tokens/" \
 -H "Content-Type: application/json" \
 -H "Paidy-Version: 2018-04-10" \
 -H "Authorization: Bearer $secret_key"

取得できるtokenオブジェクトは、最新のトークンを先頭にして配列に降順で並んでいます。このリクエストを使用すれば、その日に作成されたトークンの一覧を毎日チェックすることができます。