Twilio Voiceで決済〜任意のペイメントプロセッサが利用できるようになりました！

読む所要時間: 9 分

March 30, 2022
執筆者
Nikita Chheda
Twilion
Justin Pirie
Twilion

genericPayConnJP

この記事はNikita Chhedaがこちらで公開した記事（英語）を日本語化したものです。

Twilio Voiceにおける汎用型Payコネクタについてパブリックベータ版の提供を開始いたしました。汎用Payコネクタは、Twilio <Pay>とAgent Assist Payをフロントエンドとして顧客からの支払いの意思表示を取り込み、想定のペイメントプロセッサ（外部）に渡すことにより、音声による支払い（決済）を可能とします。それだけでなく、PCI準拠を目指していない場合でも汎用Payコネクタを使えば、機密性の高い決済データの取り扱いを回避し、PCI準拠の方法で音声による支払いを受け付けることができます。

既存のPayコネクタを使用している場合、既存のAPIエンドポイント/chargeおよび/tokenizeに馴染みがあると思います。これらは汎用Payコネクタでは非推奨となり、今後は単一のルートエンドポイント/を使用するようになります。汎用Payコネクタでは、どのペイメントプロセッサでも使用できることに加え、ペイメントプロセッサにカスタムパラメータを渡す機能が追加され、取引に関連する追加の文脈情報（オーソリ、手数料免除、返金など）を送信できます。

汎用Payコネクタは、お客様とペイメントプロセッサの間の橋渡し役となります。お客様のペイメントプロセッサはトランザクションを処理し、その結果をTwilioに報告します。

これまで、Payコネクタには指定型という種別もありました。お客様のペイメントプロセッサがTwilioの指定型Payコネクタ（原稿執筆時点でStripe、CardConnect、Base Commerce、Chase Paymentech、Braintree）の一覧に含まれていない場合、今回リリースの汎用Payコネクタを使用いただくという棲み分けになります。

汎用Payコネクタのアーキテクチャ

VoicePayArchJP

上記の図を以下に説明します。

  1. Twilio電話番号とお客様との間で通話が確立されます。
  2. TwilioはTwiMLインストラクション（TwiML言語）の<Pay>動詞句を実行します。お客様はクレジットカード番号、有効期限、郵便番号、CVV（PIN番号）を入力するガイダンスを聞きます。(コールセンターのオペレータが、オペレーター支援型の支払い機能の下に支払いに関連する情報を収集することも可能です。)
  3. Twilio Voiceのインフラは、該当の支払い関連情報を汎用Payコネクタに渡します。
  4. 汎用Payコネクタは、HTTPS POSTリクエストを通じて、指定されたペイメントプロセッサに支払い関連情報を渡します。
  5. ペイメントプロセッサは実際の支払いトランザクションを処理し、トランザクションの結果を汎用Payコネクタに送り返します。
  6. Twilioはこの結果情報をHTTPリクエストとして、<Pay>動詞句で指定されたアクションURLに送信します。（オペレーター支援型のPayments APIを使用している場合はstatusCallback URLに送信します。）

汎用Payコネクタの使用方法

前提条件

  1. Twilio Voice対応のTwilio電話番号 〜 電話番号はこちらから購入できます。
  2. コネクタを使用するためにPCIフラグを有効化。
  3. Twilioコンソール画面から汎用Payコネクタをインストール＋設定。
  4. アプリケーションでPayコネクタを呼び出し（例: TwiML言語経由）。
  5. ルートエンドポイント '/' からAPIを呼び出すようにアプリケーションコードを更新。

アーキテクチャを実現してみましょう

このリリースでは、これまで馴染みのあったエンドポイント /charge と /tokenize の代わりにユニバーサルに利用できるルートエンドポイント / をご用意し、支払いトランザクションの種別を指定するためのmethodパラメータを追加しました。プライベートベータ版でレガシーのAPIエンドポイントを使用していたアプリケーションは、ルートエンドポイント / を使用するようにコードを修正してください。

このブログ記事では、Charge型とTokenize型のトランザクションを処理するためのTwiML言語の書き方、そして2つのトランザクション種別に対してTwilio側で期待するペイメントプロセッサへのリクエストとレスポンスオブジェクトの特徴や構造について紹介します。

Charge型のトランザクション

Charge型トランザクションは、提供する商品またはサービスの対価として、顧客が提供する支払方法（例: クレジットカード）に対して直ちに課金することを意味します。

汎用Payコネクタを使用してCharge型トランザクションを処理したい場合、<Pay>動詞句にchargeAmount属性を含め、その値を0より大きな値にセットしなくてはなりません（以下参照）。（オペレーター支援型の支払い機能を利用する場合には、Payments APIでPayセッションを開始する必要があります。）

<Pay chargeAmount="10.00">

汎用Payコネクタは、ペイメントプロセッサで設定されたURLにHTTPS POSTリクエストを送信します。以下は、送信されるPOSTリクエストのボディの例です。トランザクション種別を示す「method」プロパティに値「charge」がセットされていることに注目してください。

{
  "method" : "charge",
  "transaction_id" : "transaction_id",
  "cardnumber" : "4111111111111111",
  "cvv":"123",
  "expiry_month":"08",
  "expiry_year":"2022",
  "description":"pizza",
  "amount":"10.0",
  "currency_code":"USD",
  "postal_code":"94111"
}

ペイメントプロセッサからのCharge型のレスポンスは通常以下のとおりです。

{
  "charge_id":"ch_a9dc6297cd1a4fb095e61b1a9cf2dd1d",
  "Error_code":null,
  "Error_message":null
}

Tokenize型のトランザクション

Tokenize型トランザクションは、ユーザーが提供する支払い情報（例: クレジットカードやACHデビットの情報）に基づき、課金を行う代わりにペイメントプロセッサからトークンを取得することを意味します。トークンは通常保存され、将来支払い情報を再度要求することなく、ユーザーに課金できます。トークンは、ペイメントゲートウェイまたはペイメントプロセッサによって提供されます。

Tokenize型トランザクションを行うには、<Pay>動詞句でchargeAmount属性の値を "0" に設定するか、chargeAmount属性をそもそも省略する必要があります（以下参照）。（オペレーター支援型の支払い機能を利用する場合には、Payment APIを使用して新しいPayセッションを開始する必要があります。）

<Pay chargeAmount="0"> または <Pay>

以下は、送信されるPOSTリクエストのボディの例です。トランザクション種別を示す「method」プロパティに値「tokenize」がセットされていることに注目してください。

{
  "method" : "tokenize",
  "transaction_id" : "transaction_id",
   "cardnumber" : "4111111111111111",
   "cvv":"123",
   "expiry_month":"08",
   "expiry_year":"2022",
   "description":"pizza",
   "postal_code":"94111"
}

ペイメントプロセッサからのTokenize型のレスポンスは通常以下のとおりです

{
  "token_id":"tok_54f5f89e649a4ffe9f136010188ee80e",
  "Error_code":null,
  "Error_message":null
}

カスタムパラメータ

<Pay>動詞句を使用する場合、<Parameter>名詞句を使用してペイメントプロセッサにカスタムパラメータを送信できます。この機能を使用すると、トランザクションに関する追加の文脈情報を送信できます。たとえば、手数料を免除する、手数料を請求する、返金を処理するなど、ペイメントプロセッサに通知できます。想定するユースケースや選択したペイメントプロセッサによって、どういったカスタムパラメータが利用可能かが決定されます。

リクエストのフォーマットは同じで、以下のようにパラメータを追加できます。

<Pay chargeAmount=10.00>

<Parameter name=”foo” value=”bar”>

</Pay>

以下は、ペイメントプロセッサに送信されるPOSTリクエストのボディの例です。

{
  "method" : "charge"
  "transaction_id" : "transaction_id",
  "cardnumber" : "4111111111111111",
  "cvv":"123",
  "amount":"10.0",
  "currency_code":"USD",
  "expiry_month":"08",
  "expiry_year":"2022",
  "description":"pizza",
  "postal_code":"94111"
  "parameters" : 
   {
     "foo" :  "bar"
   }
}

ペイメントプロセッサからのCharge型のレスポンス（カスタムパラメータ付き）は通常以下のとおりです。

{
  "charge_id":"any_id",
  "error_code":null,
  "error_message":null,
  "parameters" : 
   {
     "foo" : "bar"
   }
}

汎用Payコネクタの詳細については、APIドキュメントをご確認ください。

コミュニケーションの未来を創造しましょう！

関連投稿

関連リソース

A newspaper article

Twilio Docs

APIからSDK、サンプルアプリまで

言語とプラットフォームの API リファレンス ドキュメント、SDK、ヘルパー ライブラリ、クイックスタート、チュートリアル。
An Open book

リソース・センター

最新の電子ブック、業界レポート、ウェビナー

顧客エンゲージメントの専門家から学び、自社のコミュニケーションを改善しましょう。
User group reactions

Ahoy

Twilio の開発者コミュニティ ハブ

コミュニケーションとデジタル エンゲージメント エクスペリエンスを構築するためのベスト プラクティス、コード サンプル、インスピレーション。