Paidy Checkout

主要なPCブラウザやモバイル端末の場合であれば例外なく、Paidy Checkoutを利用して決済プロセスを安全かつスムーズに進めることができます。コンシューマーは数回クリックするだけで、手間をかけずに素早く支払いを行うことができます。Paidy Checkoutは既存の支払いページに組み込んで使用するため、セッション管理やリダイレクトに手間がかかったり、コンシューマーが支払いページを途中で離脱してしまうリスクもありません。

Paidy Checkoutの流れ

Paidy Checkoutは大きく別けて次の2つの要素で構成されています。

  • Checkout JS: 決済を開始する、あるいはトークンを作成するために必要なデータをPaidyに送るJavaScriptライブラリ。
  • Checkout app: マーチャントのウェブサイトに表示される「Checkoutアプリケーション」。コンシューマーはCheckoutアプリケーションに従って決済プロセスを進め、必要な情報を入力します。

Paidy Checkout

  1. コンシューマーが決済方法としてPaidy Checkoutを選択すると、クライアント側のページでCheckout JSスクリプトにデータが渡され、Checkoutアプリケーションが立ち上がります。
  2. Checkoutアプリケーション内でコンシューマーが携帯電話番号とメールアドレスを入力すると、このデータがPaidyに送信されます。
  3. SMS経由でコンシューマーのもとに4桁の認証コードが届きます。
  4. コンシューマーはCheckoutアプリケーションに従って決済プロセスを進め、必要な情報を入力します。通常の決済の場合、アプリケーションがコンシューマーに追加の情報を求めることがあります(Paidy決済ではコンシューマーが複数の決済オプションを選択できるようになっており、その選択内容によってはコンシューマーが追加の情報を求められます)。
  5. Paidyがリクエストを処理し、マーチャントが準備したJavaScriptのコールバック関数を実行してクライアント側のウェブページに結果を返します。
  6. このPayment IDあるいはトークンIDをマーチャントのバックエンドシステムに保存します。このIDは非常に重要なものです。
  7. Paidy Checkoutは処理結果をクライアント側のウェブページに返します。そのため、マーチャントのバックエンドシステムで直接データを受け取りたい場合はWebhookを実装する必要があります。 Webhookの実装は必須ではありませんが、強く推奨されます。

新たに作成されたのがトークンであれば、そのトークンを使用する決済をAPI経由で開始できます。通常の決済を開始したのであれば、API経由でその決済のCaptureや管理を行うことができます。

決済用にPaidy Checkoutを導入

通常の決済やトークンを作成する際はPaidy Checkoutを利用します。 通常の決済用にPaidy Checkoutを導入するには:

支払いページのテンプレートを更新する

日本語の文字をJSON形式で送信する際、意図しない文字(?や□)に文字化けすることがあります。送信時の文字化けを避け、テキストがPaidyのユーザーインターフェイスに正しく表示されるよう、送信前にテキストがUTF-8でエンコードされていることを必ず確認するようにしてください。

ステップ1: Checkout JSスクリプトを支払いページのテンプレートに埋め込みます。 例:

  
    <script type="text/javascript" src="https://apps.paidy.com/"></script>
  

ステップ2: マーチャントダッシュボードにログインして公開鍵を控えておきます。テストや運用時に使用する鍵はマーチャントダッシュボードにまとめてリストアップされています。間違った公開鍵を選ばないようご注意ください。

ステップ3: 支払いページのテンプレートにマーチャント固有の設定を施します。

  • パラメーター

    説明

  • api_key

    string

    必須

    Paidyと通信を行う際はこの公開鍵でマーチャントのアカウントが識別されるため、この属性が必ず必要になります。

  • logo_url

    string

    必須ではありません

    Checkoutアプリケーションのヘッダー部分に表示できるカスタムロゴのURL。値を指定しない場合はPaidyのロゴが表示されます。

  • closed

    function

    必須ではありません

    Checkoutアプリケーションの終了時に呼び出されるコールバック関数。 ここではコールバックとしてAuthorizeの結果(成功・失敗、あるいはチェックアウトのプロセスが完了する前にコンシューマーがPaidy Checkoutを終了)が返されます。 決済の場合、コールバックとして必ずAuthorizeの結果(成功・失敗、あるいはチェックアウトのプロセスが完了する前にコンシューマーがPaidy Checkoutを終了)が返されます。コールバック関数の利用は必須ではありませんが、実装しておくことが推奨されます。

  • metadata

    string

    必須ではありません

    マーチャントは自分で定義した決済に関する補足的なデータをこのフィールドに保存できます。このフィールドにはキーと値のセットを20件まで追加できます。 metadataフィールドはマーチャント設定でもペイロードデータ内でも設定できます。この両方で設定した場合、ペイロードデータで指定している値によってマーチャント設定の値が上書きされますので、ご注意ください。

ステップ4: 注文データをCheckout JSスクリプトに渡します。

  • パラメーター

    説明

  • amount

    double

    必須

    税、送料を含み、値引きの対象であればさらにそれを適用した後の決済総額。

  • currency

    string

    必須

    決済で使用する通貨を示す、ISO4217通貨コードに準じた値(初期値はJPY)。

  • store_name

    string

    必須ではありません

    Checkoutアプリケーションのヘッダー部分、MyPaidy、マーチャントダッシュボードに表示される店舗名。

  • buyer

    object

    必須

    コンシューマーの氏名、メールアドレス、携帯電話番号を含むbuyerオブジェクト

  • buyer_data

    object

    必須

    コンシューマーの購入履歴に関する情報を含むbuyer_dataオブジェクト

  • order

    object

    必須

    Orderデータ

  • shipping_address

    object

    必須

    Shipping addressデータ

  • description

    string

    必須ではありません

    注文の概要。

  • metadata

    string

    必須ではありません

    マーチャントは自分で定義した決済に関する補足的なデータをこのフィールドに保存できます。このフィールドにはキーと値のセットを20件まで追加できます。metadataフィールドはマーチャント設定でもペイロードデータ内でも設定できます。この両方で設定した場合、ペイロードデータで指定している値によってマーチャント設定の値が上書きされますので、ご注意ください。

Buyer オブジェクト

  • パラメーター

    説明

  • email

    string

    必須

    コンシューマーのメールアドレス。

  • name1

    string

    必須

    コンシューマーの氏名(漢字表記)。 姓と名をスペースで区切る必要があります(例:山田 太郎)。 スペースは半角(Unicode U+0020)でも全角(U+3000)でも構いません。

  • name2

    string

    必須ではありません

    コンシューマーの氏名(カタカナ表記)。 姓と名をスペースで区切る必要があります(例:ヤマダ タロウ)。 スペースは半角(Unicode U+0020)でも全角(U+3000)でも構いません。

  • phone

    string

    必須

    コンシューマーの電話番号(例:09011112222)。コンシューマーがテキストメッセージを受信できる日本の携帯電番号です。

  • dob

    string

    必須ではありません

    コンシューマーの生年月日(提供された場合のみ)。YYYY-MM-DD形式。

Buyer data オブジェクト:

  • パラメーター

    説明

  • age

    integer

    必須

    コンシューマーがマーチャントの店舗でアカウントを作成してから経過した日数。

  • order_count

    integer

    必須

    コンシューマーがマーチャントと取引を開始してから現在までに行った注文総数。キャンセル、拒否、返金された取引はこれに含めず、またPaidy決済も除外します。

  • ltv

    double

    必須

    Lifetime value(顧客の生涯価値)の略語であり、コンシューマーがマーチャントと取引を開始してから現在までに行った注文の総額(円)を示します。キャンセル、拒否、返金された取引はこれに含めず、またPaidy決済も除外します。

  • last_order_amount

    double

    必須

    最後に行った注文の金額(円)。Paidy決済は除外します。

  • last_order_at

    integer

    必須

    コンシューマーが最後に注文してから経過した日数、またPaidy決済も除外します。

Order オブジェクト:

  • パラメーター

    説明

  • items

    object

    必須

    Itemsオブジェクトの配列。このオブジェクトを使用し、値引き額を示す負の値をunit_priceにセットした状態で「discount order item(値引き項目)」を作成することでも、コンシューマーの注文商品を値引きすることができます。

  • order_ref

    string

    必須ではありません

    マーチャントが割り当てる注文IDまたはカートID。order_refフィールドは必須項目ではありません。また、一意の値を指定する必要もありません。

  • shipping

    double

    必須ではありません

    注文にかかる配送料の総額。

  • tax

    double

    必須ではありません

    注文にかかる消費税の総額。

Items オブジェクト:

  • パラメーター

    説明

  • id

    string

    必須ではありません

    注文商品の商品ID。任意のフィールドであり、送信後はマーチャントダッシュボードとMyPaidyの両方に表示されます。

  • quantity

    integer

    必須

    注文商品の数。

  • title

    string

    必須ではありません

    注文商品(または値引き/クーポン)の名称。任意のフィールドですが、ペイロードに含めて送信することが推奨されます。送信後はマーチャントダッシュボードとMyPaidyの両方に表示され、注文商品を識別できるようになります。送信しない場合、注文商品の数量と単価以外は表示されません。

  • unit_price

    double

    必須

    注文商品の単価。注文商品(order item)に値引きやクーポンを指定する場合、unit_priceに必ず負の値をセットし、注文の決済総額からその金額が差し引かれるようにしてください。

  • description

    string

    必須ではありません

    注文商品の説明。MyPaidyやマーチャントダッシュボードには表示されないフィールドですので、ご注意ください。

Shipping address オブジェクト:

  • パラメーター

    説明

  • line1

    string

    必須ではありません

    建物名と部屋番号(国内の住所の場合)。

  • line2

    string

    必須ではありません

    番地(国内の住所の場合)。

  • city

    string

    必須ではありません

    市区町村。

  • state

    string

    必須ではありません

    都道府県。

  • zip

    string

    必須

    郵便番号(NNN-NNNN形式)。
    重要:zipは必須フィールドです。addressオブジェクトに含まれる他のフィールドはいずれも必須項目ではありませんが、このzipフィールドとともに他のフィールドを1つ以上指定する必要があります。shipping addressのフィールドを2つ提供しなければ、リクエストは失敗します。

Paidy Checkoutの例

  
<html>
    <body>
      <button id="paidy-checkout-button" onclick="paidyPay()">Paidyでお支払い</button>
      <script type="text/javascript" src="https://apps.paidy.com/"></script>
      <script type="text/javascript">
                      var config = {
                           "api_key": "pk_0000_000000000000000",
                           "logo_url": "http://www.paidy.com/images/logo.png",
                           "closed": function(callbackData) {
                                /*
                                Data returned in the callback:
                                callbackData.id,
                                callbackData.amount,
                                callbackData.currency,
                                callbackData.created_at,
                                callbackData.status 
                                */     
                           }
                      };
                      var paidyHandler = Paidy.configure(config); 
                      function paidyPay() {
                           var payload = {
                                "amount": 10000,
                                "currency" : "JPY",
                                "store_name": "Paidy sample store",
                                "buyer": {
                                     "email": "successful.payment@paidy.com",
                                     "name1": "山田 太郎",
                                     "name2": "ヤマダ タロウ",
                                     "phone" : "08000000001",
                                     "dob": "1990-10-25"
                                },
                                "buyer_data": {
                                     "age": 29,
                                     "order_count": 1000,
                                     "ltv": 250000,
                                     "last_order_amount": 20000,
                                     "last_order_at": 20
                                },
                                "order": {
                                     "items": [
                                          {
                                               "id":"PDI001",
                                               "quantity":1,
                                               "title":"Paidyスニーカー",
                                               "unit_price":10000,
                                               "description":" "
                                          }
                                     ],
                                     "order_ref": "20161214ato06",
                                     "shipping": 0,
                                     "tax": 0
                                },
                                "shipping_address": {
                                     "line1": "AXISビル 10F",
                                     "line2": "六本木4-22-1",
                                     "city": "港区",
                                     "state": "東京都",
                                     "zip": "106-2004"
                                },
                                "description" : "Sample store"
                      };
                      paidyHandler.launch(payload);
     };
     </script>
  </body>
</html>
  

レスポンス

処理完了後、マーチャントが準備したJavaScriptのコールバック関数が実行されます。Authorizeのリクエストが成功した場合でも、失敗した場合でも、コールバックとして以下のフィールドがすべて返されます。

  • パラメーター

    説明

  • amount

    double

    注文総額。

  • currency

    double

    決済で使用する通貨を示す、ISO4217通貨コードに準じた値(初期値はJPY)。

  • created_at

    string

    決済データが作成された日時(ISO 8601のフォーマットに準じるUTC)。

  • id

    string

    新規決済データの一意なID。 このPayment IDは必ず「pay_」で始まります。

  • status

    string

    Authorizeのステータス。Authorizeが成功した場合は「AUTHORIZED」、失敗した場合は「REJECTED」になります。


チェックアウトのプロセスが完了する前にコンシューマーがPaidy Checkoutを終了した場合、コールバックとしてstatusフィールド(値は「closed」)のみが返されます。

決済の状態を示すCLOSEDと混同しないようにしてください。マーチャントダッシュボードで決済の状態が「CLOSED」と表示されている場合、正しく完了した決済、あるいはマーチャントがキャンセルした決済を示します。一方、コールバックとして返される「closed」は、チェックアウトのプロセスが完了する前にコンシューマーがPaidy Checkoutを終了した、つまりPaidy決済が存在しないことを示します。

決済データの検証

Paidy Checkoutが作成した決済データは、API用の秘密鍵を使ってマーチャント側のバックエンドシステムからリクエストを送信することで検証していただく必要があります。これはセキュリティを確保するために必要な作業ですので、省略することはできません。

決済のAuthorizeを行う際、マーチャントが準備したJavaScriptのコールバック関数をPaidy Checkoutが実行し、Payment IDが返されます。このPayment IDを保存する前にデータを検証し、フロントエンドのブラウザからPaidyに送信されたデータが途中で改ざんされていないことを確かめておく必要があります。 この検証を行うには、マーチャント側のバックエンドシステムからAPI用の秘密鍵を使ってGET /payments/{id}にリクエストを送信します。

必要な検証の流れ

  • JavaScriptのコールバック関数からバックエンドシステムにPayment IDを送信します。
  • バックエンドシステムから/payments/{id}エンドポイント({id}の部分はPayment ID)にGETリクエストを送信します。このリクエストの処理が成功すると決済オブジェクト全体が返ってきます。
  • amountフィールドの値を探し、Authorizeリクエストの際に送信されたものと同じ値であることを確認します。
  • 値が同じであれば決済データは有効ですので、安心して決済オブジェクトをデータベースに保存できます。

Checkoutアプリケーションのカスタマイズ

Checkoutアプリケーションのヘッダー部分に表示されるPaidyのlogo_urlはマーチャント独自のものに変更できます。 マーチャント独自のロゴを表示する方法

  • まずは支払いページのテンプレートにて、マーチャント設定の「logo_url」を変更します(ステップ3を参照)。
  • 次に、Paidy Checkoutを導入するページと同じドメイン内に画像ファイルを配置していることを確認します。

最適画像サイズは184ピクセル x 184ピクセル、推奨画像形式は.png、.jpg、.gifです。

トークン用にPaidy Checkoutを導入

通常の決済やトークンを作成する際はPaidy Checkoutを利用します。 トークン用にPaidy Checkoutを導入するには:

支払いページのテンプレートを更新する

日本語の文字をJSON形式で送信する際、意図しない文字(?や□)に文字化けすることがあります。送信時の文字化けを避け、テキストがPaidyのユーザーインターフェイスに正しく表示されるよう、送信前にテキストがUTF-8でエンコードされていることを必ず確認するようにしてください。

ステップ1: Checkout JSスクリプトを支払いページのテンプレートに埋め込みます。 例:

  
    <script type="text/javascript" src="https://apps.paidy.com/"></script>
  

ステップ2: マーチャントダッシュボードにログインして公開鍵を控えておきます。テストや運用時に使用する鍵はマーチャントダッシュボードにまとめてリストアップされています。間違った公開鍵を選ばないようご注意ください。

ステップ3: 支払いページのテンプレートにマーチャント固有の設定を施します。

  • パラメーター

    説明

  • api_key

    string

    必須

    Paidyと通信を行う際はこの公開鍵でマーチャントのアカウントが識別されるため、この属性が必ず必要になります。

  • logo_url

    string

    必須ではありません

    Checkoutアプリケーションのヘッダー部分に表示できるカスタムロゴのURL。値を指定しない場合はPaidyのロゴが表示されます。

  • closed

    function

    必須ではありません

    Checkoutアプリケーションの終了時に呼び出されるコールバック関数。 トークンの場合、リクエストが成功した場合にのみコールバック関数が実行されます。 コールバック関数の利用は必須ではありませんが、実装しておくことが推奨されます。

  • metadata

    string

    必須ではありません

    マーチャントは自分で定義した決済に関する補足的なデータをこのフィールドに保存できます。このフィールドにはキーと値のセットを20件まで追加できます。 metadataフィールドはマーチャント設定でもペイロードデータ内でも設定できます。この両方で設定した場合、ペイロードデータで指定している値によってマーチャント設定の値が上書きされますので、ご注意ください。

  • token

    object

    必須ではありません

    トークン関連の設定を行うフィールドが含まれるオブジェクトです。このオブジェクトが存在すれば、トークンを使用する場合の処理手順に従ってリクエストが処理されます。存在しない場合は通常の決済フローに従ってリクエストが処理されます。

Tokenオブジェクト:

  • パラメーター

    説明

  • wallet_id

    string

    必須ではありません

    マーチャントが指定するウォレットIDです。傘下に複数のマーチャントが存在する大規模なマーチャント、あるいは他のマーチャントの代理となる決済サービスプロバイダーの場合は、それぞれのマーチャントをこのwallet_idを使用して識別できます。初期値は「default」に設定されていますが、このフィールドの値を空にした状態で送信しないでください。値を設定するか、tokenオブジェクトにこのフィールドを含めずに送信を行う必要があります。

  • type

    string

    必須

    トークンの種類です。トークンの場合、フィールドの値は「recurring」にする必要があります。

  • description

    string

    必須ではありません

    マーチャントが定義する、トークンの説明。

ステップ4: 注文データをCheckout JSスクリプトに渡します。

  • パラメーター

    説明

  • store_name

    string

    必須ではありません

    Checkoutアプリケーションのヘッダー部分、MyPaidy、マーチャントダッシュボードに表示される店舗名。

  • buyer

    object

    必須

    コンシューマーの氏名、メールアドレス、携帯電話番号を含むbuyerオブジェクト

  • description

    string

    必須ではありません

    注文の概要。

  • metadata

    string

    必須ではありません

    マーチャントは自分で定義した決済に関する補足的なデータをこのフィールドに保存できます。このフィールドにはキーと値のセットを20件まで追加できます。metadataフィールドはマーチャント設定でもペイロードデータ内でも設定できます。この両方で設定した場合、ペイロードデータで指定している値によってマーチャント設定の値が上書きされますので、ご注意ください。

Buyer object:

  • パラメーター

    説明

  • email

    string

    必須

    コンシューマーのメールアドレス。

  • name1

    string

    必須

    コンシューマーの氏名(漢字表記)。 姓と名をスペースで区切る必要があります(例:山田 太郎)。 スペースは半角(Unicode U+0020)でも全角(U+3000)でも構いません。

  • name2

    string

    必須ではありません

    コンシューマーの氏名(カタカナ表記)。 姓と名をスペースで区切る必要があります(例:ヤマダ タロウ)。 スペースは半角(Unicode U+0020)でも全角(U+3000)でも構いません。

  • phone

    string

    必須

    コンシューマーの電話番号(例:09011112222)。コンシューマーがテキストメッセージを受信できる日本の携帯電番号です。

  • dob

    string

    必須ではありません

    コンシューマーの生年月日(提供された場合のみ)。YYYY-MM-DD形式。

Paidy Checkoutの例

  
<html>
    <body>
      <button id="paidy-checkout-button" onclick="paidyPay()">Paidyでお支払い</button>
      <script type="text/javascript" src="https://apps.paidy.com/"></script>
      <script type="text/javascript">
                      var config = {
                           "api_key": "pk_0000_000000000000000",
                           "logo_url": "http://www.paidy.com/images/logo.png",
                           "closed": function(callbackData) {
                                /*
                                Data returned in the callback:
                                callbackData.id,
                                callbackData.amount,
                                callbackData.currency,
                                callbackData.created_at,
                                callbackData.status 
                                */     
                           },
                           "token": {
                                "wallet_id": "default",
                                "type": "recurring",
                            }
                      };
                      var paidyHandler = Paidy.configure(config); 
                      function paidyPay() {
                           var payload = {
                                "store_name": "Paidy sample store",
                                "buyer": {
                                     "email": "successful.payment@paidy.com",
                                     "name1": "山田 太郎",
                                     "name2": "ヤマダ タロウ",
                                     "phone" : "08000000001",
                                     "dob": "1990-10-25"
                                }
                      };
                      paidyHandler.launch(payload);
     };
     </script>
  </body>
</html>
  

レスポンス

処理完了後、マーチャントが準備したJavaScriptのコールバック関数が実行されます。リクエストが成功した場合はマーチャントが準備したJavaScriptのコールバック関数が実行され、コールバックとして以下のフィールドが返されます。トークンを作成する場合は処理成功時にのみコールバック関数が実行されます。

  • パラメーター

    説明

  • token_id

    string

    Paidyが生成する、「tok_」で始まるトークンID。

  • created_at

    string

    トークンが作成された日時(ISO 8601のフォーマットに準じるUTC)。

  • status

    string

    トークンのステータスを示します。リクエストが成功した場合、値は必ずACTIVEになります。

Checkoutアプリケーションのカスタマイズ

Checkoutアプリケーションのヘッダー部分に表示されるPaidyのlogo_urlはマーチャント独自のものに変更できます。 マーチャント独自のロゴを表示する方法

  • まずは支払いページのテンプレートにて、マーチャント設定の「logo_url」を変更します(ステップ3を参照)。
  • 次に、Paidy Checkoutを導入するページと同じドメイン内に画像ファイルを配置していることを確認します。

最適画像サイズは184ピクセル x 184ピクセル、推奨画像形式は.png、.jpg、.gifです。

ブラウザ対応状況

主要なブラウザについてはすべて、複数のバージョンで動作確認を行いつつ開発を進めていますが、すでにセキュリティ関連のアップデートが終了しているブラウザはサポート対象外にしています。今後のサポート改善のためにも、Paidy Checkoutをご利用中にいずれかのブラウザで問題が発生した場合は、お手数ですが弊社までご連絡いただけましたら幸いです。

サポートしているウェブブラウザおよびそのバージョン

  • Internet Explorer―Microsoft社のライフサイクルポリシーに基づいてサポートを行っており、2017年2月15日以降はInternet Explorer 10以上をサポートしています。
  • ChromeおよびSafari―すべてのプラットフォームのものを、バージョンリリース後から3年間サポートします。
  • Firefox―デスクトップ版をバージョンリリース後から3年間サポートします。Android版とiOS版のFirefox(最新バージョン)については、バグレポートに基づいて対応を取ってはいますが、隅々まで動作確認を行っているわけではありません。

推奨されるプラットフォームのバージョン

  • iOS 8.2以降
  • Android 4.4以降

トラブルシューティング

  • パス/エラーの表示

    主な原因(解決策)

  • ERROR

    Paidy configuration JSON is missing required parameters

    構成オブジェクトが存在しない、あるいは不完全。Paidy.configure()に渡す構成オブジェクトのフォーマットを確認し、必要なキーと値がすべて揃っているかどうかチェックします。

  • /payments

    503 Service unavailable or connection refused

    決済サービスが稼働していない、またはサーバーやポートの設定が不適切。設定が正しいかどうか確認します。

  • /payments

    401 Unauthorized

    公開鍵が間違っている。マーチャントダッシュボードにログインして公開鍵の値を確認します。次に、マーチャント設定で適切な公開鍵を使用していることを確認します。