Squareと連携してクレジットカード決済機能を実装する

Shopping Cart 拡張アプリでは、決済サービスと連携することで、ECサイトにクレジットカード決済機能を実装することができます。このエントリーでは決済サービスとして Square と連携して、クレジットカード決済機能を実装する手順を説明します。

Square でクレジットカード決済を実装する場合の注意点

Square でクレジットカード決済を実装する場合、以下の場合は使用できませんのでご注意ください。

• 税計算方式が「積み上げ」に設定されている
• 税計算端数処理が「四捨五入」もしくは「切り上げ」に設定されている

クレジットカード決済機能を実装する

Squareと連携してクレジットカード決済機能を実装するには、以下の設定をする必要があります。

• クレジットカード決済で使用するサービスとして Square を選択する
• クレジットカード決済用の決済方法を登録する

また、a-blog cms を設置しているディレクトリに .env ファイルが作成されている必要があります。

クレジットカード決済で使用するサービスとして Square を選択する

連携するクレジットカード決済を選択する

クレジットカード決済を利用できるようにするためには、連携するクレジットカード決済を選択する必要があります。Shopping Cart 設定 > 基本設定 > 決済サービス設定で設定することができます。

クレジットカード決済用の決済方法を登録する

クレジットカード決済用の決済方法を登録する場合はブロック名を「creditcard」にする必要があります。

クレジットカード決済用の決済方法を登録する場合はブロック名を「creditcard」にする必要があるので、ブロック名を「creditcard」と入力した決済方法を Shopping Cart 設定 > 注文画面設定 > 決済方法と手数料で登録してください。

Square との連携

Square との連携は以下の手順で行います。

1. アプリケーションを新規作成または選択する
2. アプリケーションのOAuth設定をする
3. a-blog cms と Square を OAuth 認証する
4. Square を利用したクレジットカード決済に必要な HTML をテンプレートに記述する

1. アプリケーションを新規作成または選択する

まず、Square Developer にログインし、Applications 選択ページへ移動します。Square Developer のアカウントがなければ以下のURLから新規作成してください。

Applications 選択ページへ移動すると ↓ のような画面になっています。

アプリケーション選択ページ

次に、Shopping Cart 拡張アプリと連携させたいアプリケーションを新規作成または選択し、アプリケーションの個別の設定ページへ移動します。

2. アプリケーションの OAuth 設定をする

アプリケーションの個別ページ

アプリケーションの個別の設定ページへ移動すると、↑ のような画面になっています。

画面左のメニューから、アプリケーションの OAuth 設定ページに移動します。開発中であれば Sandbox タブ、本番運用なら Production タブを選択します。（画像は Sandbox タブ）

OAuth 設定ページを開いたら、「Application ID」と「Application Secret」をメモ帳などに控えておいてください。

最後に、「Redirect URL」に https://ドメイン名/bid/ブログID/admin/app_shopping_cart_square_callback/と設定して保存します。https:// から始まるURLでないと登録できませんので注意してください。

a-blog cms と Square を OAuth 認証する

Square 側の設定ができたら、今度は a-blog cms 側の設定を行います。

まず、a-blog cmsの起動ファイルである、index.php と同じ階層に .env ファイルを設置します。a-blog cms をインストールした際に env.txt として設置してあるファイルを .env にリネームしていただければ ok です。

次に、拡張アプリの設定を行います。ShoppingCart 設定 > 決済サービスとの連携タブを選択してください。

Square との OAuth 認証が完了する前の設定画面

先程メモ帳に控えた、「Application ID」と「Application Secret」を入力します。Sandbox（テスト運用）モードで認証する場合は、Sandbox（テスト運用）モードの設定 の入力欄に、Production（本番運用）モードで認証する場合は、Production（本番運用）モードの設定の入力欄に「Application ID」と「Application Secret」を入力してください。また、Sandbox（テスト運用）モードで認証する場合は、Sandboxモードのチェックボックスを有効にしてください。

「Application ID」と「Application Secret」の入力ができたら、一度「保存」ボタンをクリックし、設定を保存してください。保存すると、「認証する」ボタンがクリックできるようになります。

「認証する」ボタンがクリックできるようになったのを確認したら、「認証する」ボタンをクリックし、Square と OAuth 認証を行います。認証ページに遷移するので、ページ内の「許可」ボタンをクリックして認証を許可します。

認証の許可後、Shopping Cart 設定ページにリダイレクトされた画面

認証の許可後、Shopping Cart 設定ページに自動的にリダイレクトされます。リダイレクト後の画面は ↑ のような画面になっています。ここまでで、OAuth 認証は完了しましたが、Square との連携はまだ完了できていません。ここまでの設定ができると、店舗というセレクトボックスが選択できるようになります。店舗のセレクトボックスから、アプリケーションで使用する店舗を選択して、保存してください。

OAuth 認証と店舗の設定が完了すると、認証ステータスが緑色になります。

店舗の設定が完了すると、Square との OAuth 認証は完了です。↑ 画像のように、認証ステータスが緑色になっていたらSquareとの連携が完了しています。

開発者向けの Square アカウントを起動する手順は以下になります。

1. Squareの ダッシュボード を開く
2. 「Sandbox Test Accounts」のアカウントの「Open」ボタンをクリック
3. CMSの管理画面に戻り、再度「認証」ボタンをクリックする

Square Sandbox とは

Square Sandbox とは、Square API のテストを行うために Square が用意している特別な環境です。

例えば、本番環境で Square API を利用したクレジットカード決済を行った場合は決済手数料がかかりますが、Sandbox 環境ではクレジットカードが実際に請求されることはなく、実際の銀行で支払いが処理されることはないため、決済手数料はかかりません。

Sandbox 環境では通常のクレジットカードは使用できません。Sandbox Payments に記載されているテスト用のクレジットカードを使用する必要がありますのでご注意ください。

Square を利用したクレジットカード決済に必要なテンプレートを記述する

最後に、Square を利用したクレジットカード決済に必要な テンプレートを記述します。

まず、Square と連携してクレジットカード決済をするために必要なJavaScript ライブラリを読み込みます。head要素内に下記のコードを記述してください。

<!-- BEGIN_MODULE Admin_InjectTemplate id="%{PAYMENT_SERVICE}-js" -->
<!-- END_MODULE Admin_InjectTemplate -->

次に、クレジットカード情報の入力欄を表示します。 クレジットカード情報の入力欄を表示したい箇所に下記のコードを記述してください。

<div
  id="js-sq-card-container"
  data-square-three-d-secure="true"
  data-square-amount="3000"
  data-square-currency-code="JPY"
  data-square-intent="CHARGE"
  data-square-seller-keyed-in="false"
  data-square-customer-initiated="true"
  data-square-billing-contact-given-name="太郎"
  data-square-billing-contact-family-name="山田"
  data-square-billing-contact-email="info@example.com"
  data-square-billing-contact-phone="090-0123-4567"
  data-square-billing-contact-country-code="JP"
  data-square-billing-contact-postal-code="4500002"
  data-square-billing-contact-state="愛知県"
  data-square-billing-contact-city="名古屋市中村区"
  data-square-billing-contact-address-line1="モンマートビル5階"
  data-square-billing-contact-address-line2="名駅3丁目18-5"
>
  <!-- Squareのカード入力用コンポーネントが表示されます -->
</div>

3Dセキュア機能を有効にするため、 data-square-three-d-secure 属性の値に true を設定し、決済情報及び決済者情報を設定してください。決済者情報は必須ではありませんが、セキュリティのため、できるだけ多くの情報を設定してください。

data 属性についての説明は以下になります。

• 注1：これらの値はSquareによるクレジットカード情報のトークン化が行われるとき、つまりクレジットカード情報を入力するフォームを送信するときに評価されます。
• 注2：これらの値は、まず document.querySelector() での検索に使用され、見つかればその value を使い、なければ指定値を生の文字列として扱います。

最後に、先程読み込んだJavaScriptライブラリを活用してクレジットカード情報入力用のコンポーネントを初期化します。 Admin_InjectTemplate モジュールで JavaScript ライブラリを読み込めていた場合、acmsSquare というオブジェクトが参照できるようになっています。acmsSquare オブジェクト の creditCard メソッドを実行することでクレジットカード情報入力用のコンポーネントを初期化できます。そのとき、第１引数に、クレジットカード入力要コンポーネントを表示したい要素をセレクター形式で指定してください。サンプルコードでは、先程 クレジットカード情報の入力欄を表示したい箇所に記述した要素を指定しています。

<script>  
  window.addEventListener('DOMContentLoaded', () => {
    if (document.querySelector('#js-sq-card-container')) {
      acmsSquare.creditCard('#js-sq-card-container');
    }
  });
</script>

creditCard メソッドを実行することで、クレジットカード情報入力用のコンポーネントを囲む form 要素の送信ボタンをクリックしたときに、Squareと通信し、クレジットカードの識別情報を取得します。

Square から取得した、クレジットカード識別情報は、「square-nonce」というフィールドに格納されます。このフィールドは JavaScript によって自動で追加されます。

<input type="hidden" name="square-nonce" value="取得したクレジットカード情報">
<input type="hidden" name="field[]" value="square-nonce">

ここまでできたら、Square と連携したクレジットカード決済機能が実装できています。実際に決済フォームからクレジットカード決済を試してみてください。

クレジットカード決済の失敗を表示する

不正なクレジットカード番号で決済が行われた場合など、クレジットカード決済でエラーとなることがあります。決済時にエラーが起きたことを表示できるようにするため、決済フォームでクレジットカード決済が失敗した場合、creditcard というフィールドの auth オプションがエラー判定されるようになっています。

そのため、決済フォームに、creditcard フィールドの auth オプションがエラー判定されたときのコードを書いておくと、クレジットカード決済が失敗した場合のエラーメッセージを表示可能です。以下はサンプルのソースコードです。

<div role="alert" aria-live="assertive">
  <div class="validator-result-{creditcard:v#auth}">
    <p class="form-error-text">クレジットカード認証に失敗しました。</p>
  </div>
</div>

オプション

payments オブジェクトの creditCard メソッドは第2引数にオプションを設定することができます。オプションは以下の項目が利用可能です。

オプション設定例

オプションを設定する例になります。

<script>
  acmsSquare.creditCard('#js-sq-card-container', {
    submitterElementOrSelector: '#js-shoppingForm-submit'
    callbacks: {
      cardBrandChanged(event) {
        console.info(event)
      },
      errorClassAdded(event) {
        console.info(event)
      },
      errorClassRemoved(event) {
        console.info(event)
      },
      escape(event) {
        console.info(event)
      },
      focusClassAdded(event) {
        console.info(event)
      },
      focusClassRemoved(event) {
        console.info(event)
      },
      postalCodeChanged(event) {
        console.info(event)
      },
      submit(event) {
        console.info(event)
      },
    },
    focus: 'cardNumber', // or (focus) => { focus('cardNumber') }
    recalculateSize: (recalculateSize) => {
      document
        .querySelector('.js-recalculate-size-trigger')
        .addEventListener('change', () => {
            recalculateSize();
         });
    },
    squareCardOptions: {
      postalCode: '',
      includeInputLabels: true,
      style: {
         "input": {
           "color": "red",
         },
         "@media screen and (max-width: 600px)": {
           "input": {
             "fontSize": "12px",
           }
         }
       }
     },
  });
</script>

イベント

Square 用の JavaScriptライブラリ では以下のイベントを用意しています。イベントを活用することで、特定のアクションが発生した時に処理を挟み込めます。

イベント設定例

window.addEventListener('acmsSquareTokenizeSuccessed', (event) => {
  // クレジットカード情報の取得に成功したとき
  console.info(event)
})

window.addEventListener('acmsSquareTokenizeFailed', (event) => {
  // クレジットカード情報の取得に失敗したとき
  console.info(event)
})

メールテンプレートで利用可能な変数

Square を利用して決済した場合、メールテンプレートで以下の変数が利用可能です。

お取引一覧のメモをカスタマイズする Ver. 2.2.2〜

Square のお取引一覧ページ

Square のお取引一覧ページに表示されるメモをカスタマイズすることができます。デフォルト値は "a-blog cms による決済" です。

購入フォームにカスタムフィールドで square-note の値として、任意のメモを送信することで、Square のお取引一覧ページに表示されるメモを任意のテキストにカスタマイズできます。

以下は フォームのサンプルコードになります。

<input type="hidden" name="square-note" value="ウェブサイト決済" />
<input type="hidden" name="field[]" value="square-note" />

上記の例では、お取引一覧ページに表示されるメモを "ウェブサイト決済" という文字にカスタマイズしています。

おめでとうございます。ついに、ECサイトにクレジットカード決済機能を導入することができました。ここまでできたら ECサイトとしての機能はひととおり実装できているでしょう。