作成したAPEXアプリケーションは以下のように動作します。
SquareのPayment APIを呼び出すために、開発者アカウントを作成します。開発者アカウントを作成すると、Developer Dashboardにアクセスできるようになります。開発者アカウントを作成する際に、店舗やアプリケーションといったサンドボックス環境を使用するために必要な、最低限の設定が行われます。
Oracle APEXのアプリケーションよりSquareのPayment APIを呼び出す処理は、以下の説明を参考に実装しています。
Take a Card Payment with the Web Payments SDK
https://developer.squareup.com/docs/web-payments/take-card-payment上記のではサーバー側はNode.js（JavaScript）で実装されています。PL/SQLの実装に変更するために、以下のPayment APIのリファレンスを参照しています。
Create payment
以下より実装について説明します。
アプリケーション作成ウィザードを起動し、空のアプリケーションを作成します。名前はSquare Paymentとします。Squareで決済を行う実装は、すべてホーム・ページに行います。
アプリケーションの作成をクリックします。
アプリケーション定義の置換文字列として、Payment APIの引数となる値を設定します。
置換文字列として次の３つ、SQUARE_APP_ID、SQUARE_LOCATION_ID、SQUARE_ENDPOINTを設定します。
置換文字列SQUARE_APP_IDには、作成済みのアプリケーションのCredentialsのSandbox Application IDの値を設定します。
置換文字列SQUARE_LOCATION_IDには、LocationsのLocation IDを設定します。
置換文字列SQUARE_ENDPOINTには、サンドボックス環境を呼び出すエンドポイントを設定します。
https://connect.squareupsandbox.com
Payment APIを呼び出すために、Web資格証明を作成します。資格証明に使う値はSandbox Access tokenです。この値を表示させ、どこかに一時保管しておきます。
ワークスペース・ユーティリティのWeb資格証明を開きます。
作成済みのWeb資格証明の一覧が表示されます。その画面で作成をクリックし、新たなWeb資格証明の作成を始めます。
Square Payment APIに使用するWeb資格証明は、以下の情報で作成します。
名前はSquare Cred、静的IDはSQUARE_CREDとします。認証タイプはHTTPヘッダー、資格証明名（つまりHTTPヘッダー名）はAuthorization、資格証明シークレットとして、Bearerで始めて空白で区切り、Sandbox Access tokenを繋げた値を設定します。
Bearer Sandbox_Access_tokenの値
URLに対して有効については、サンドボックスとプロダクションの双方のAPIのエンドポイントを設定しておきます。
https://connect.squareupsandbox.com
https://connect.squareup.com
以上で作成をクリックします。
Web資格証明としてSquare Cred（静的IDはSQUARE_CRED）が作成されました。
ホーム・ページにいくつかのコンポーネントを配置します。
最初に決済する金額を入力するページ・アイテムを作成します。
ページ・アイテムの識別の名前はP1_AMOUNT、タイプとして数値フィールドを選択します。ラベルはAmountとします。
Squareのドキュメントでは決済金額を$1で決め打ちして実装しているため、このページ・アイテムに対応するコンポーネントはありません。
カード情報を入力するリージョンを作成します。
識別のタイトルはCard Container、タイプとして静的コンテンツを選択します。リージョンの描画はSquareより提供されているSDKによって実行するため、APEX側では余計な修飾は省きます。外観のテンプレートにBlack with Attributesを選択し、詳細の静的IDとしてcard-containerを指定します。
Payment APIを呼び出すボタンを作成します。
識別のボタン名はPAY、ラベルはPayとします。外観のホットをオンにします。
動作のアクションとして動的アクションで定義を選択しますが、動的アクションは作成しません。詳細の静的IDにcard-buttonを設定します。このボタンをクリックしたときに呼び出されるハンドラは、ページ・プロパティのJavaScriptのファンクションおよびグローバル変数の宣言で定義します。
ページ・プロパティのJavaScriptのファイルURLとして以下を設定します。
https://sandbox.web.squarecdn.com/v1/square.js
ファンクションおよびグローバル変数の宣言として、以下を記述します。
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| const appId = '&SQUARE_APP_ID.'; | |
| const locationId = '&SQUARE_LOCATION_ID.'; | |
| async function initializeCard(payments) { | |
| const card = await payments.card(); | |
| await card.attach('#card-container'); | |
| return card; | |
| } | |
| // Call this function to send a payment token, buyer name, and other details | |
| // to the project server code so that a payment can be created with | |
| // Payments API | |
| async function createPayment(token) { | |
| apex.server.process( | |
| "CREATE_PAYMENT", | |
| { | |
| x01: token, | |
| x02: locationId, | |
| pageItems: ["P1_AMOUNT"] | |
| }, | |
| { | |
| success: (data) => { | |
| return data; | |
| }, | |
| error: (data) => { | |
| throw new Error(data); | |
| } | |
| } | |
| ); | |
| } | |
| // This function tokenizes a payment method. | |
| // The ‘error’ thrown from this async function denotes a failed tokenization, | |
| // which is due to buyer error (such as an expired card). It's up to the | |
| // developer to handle the error and provide the buyer the chance to fix | |
| // their mistakes. | |
| async function tokenize(paymentMethod) { | |
| const tokenResult = await paymentMethod.tokenize(); | |
| if (tokenResult.status === 'OK') { | |
| return tokenResult.token; | |
| } else { | |
| let errorMessage = `Tokenization failed-status: ${tokenResult.status}`; | |
| if (tokenResult.errors) { | |
| errorMessage += ` and errors: ${JSON.stringify( | |
| tokenResult.errors | |
| )}`; | |
| } | |
| throw new Error(errorMessage); | |
| } | |
| } | |
| document.addEventListener('DOMContentLoaded', async function () { | |
| if (!window.Square) { | |
| throw new Error('Square.js failed to load properly'); | |
| } | |
| const payments = window.Square.payments(appId, locationId); | |
| let card; | |
| try { | |
| card = await initializeCard(payments); | |
| } catch (e) { | |
| console.error('Initializing Card failed', e); | |
| return; | |
| } | |
| // Step 5.2: create card payment | |
| async function handlePaymentMethodSubmission(event, paymentMethod) { | |
| event.preventDefault(); | |
| try { | |
| // disable the submit button as we await tokenization and make a | |
| // payment request. | |
| cardButton.disabled = true; | |
| const token = await tokenize(paymentMethod); | |
| const paymentResults = await createPayment(token); | |
| // displayPaymentResults('SUCCESS'); | |
| apex.message.showPageSuccess("Payment Success!") | |
| console.debug('Payment Success', paymentResults); | |
| } catch (e) { | |
| cardButton.disabled = false; | |
| // displayPaymentResults('FAILURE'); | |
| aepx.message.clearErrors(); | |
| apex.message.showErrors([ | |
| { | |
| type: "error", | |
| location: "page", | |
| message: "Payment Failed!", | |
| unsafe: false | |
| } | |
| ]); | |
| console.error(e.message); | |
| } | |
| } | |
| const cardButton = document.getElementById( | |
| 'card-button' | |
| ); | |
| cardButton.addEventListener('click', async function (event) { | |
| await handlePaymentMethodSubmission(event, card); | |
| }); | |
| }); |
Squareのドキュメントにある元のコードとの違いは、大きく２点あります。
ファンクションcreatePaymentの呼び出し先をNode.jsによる実装から、Ajaxコールバックに置き替えています。そのためfetchでの呼び出しの代わりにapex.server.processを使うようにしています。
Payment APIの呼び出しの成功および失敗の表示はapex.messageを使った通知に置き替えています。そのため、IDがpayment-status-containerのDIV要素は作成せず、そのDIV要素を更新するファンクションdisplayPaymentResultsも削除しています。
SquareのPayment APIの呼び出しはAjaxコールバックより行います。
AjaxコールバックとしてCREATE_PAYMENTを作成し、以下のコードを記述します。Payment APIの仕様に従ってリクエストとなるJSONドキュメントを作成し、/v2/paymentsを呼び出しています。
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| declare | |
| l_request clob; | |
| l_response clob; | |
| l_idempotency_key varchar2(35); | |
| l_source_id varchar2(64); -- token | |
| l_location_id varchar2(32); -- location id | |
| l_amount_money_amount number; | |
| e_create_payment_failed exception; | |
| begin | |
| -- guid for idempotency_key. | |
| l_idempotency_key := regexp_replace(lower(rawtohex(sys_guid())),'(........)(....)(....)(................)','\1-\2-\3-\4'); | |
| l_amount_money_amount := to_number(:P1_AMOUNT); | |
| l_source_id := apex_application.g_x01; | |
| l_location_id := apex_application.g_x02; | |
| select json_object( | |
| key 'source_id' value l_source_id, | |
| key 'location_id' value l_location_id, | |
| key 'idempotency_key' value l_idempotency_key, | |
| key 'amount_money' value json_object( | |
| key 'amount' value l_amount_money_amount, | |
| key 'currency' value 'JPY' | |
| ) | |
| ) into l_request from dual; | |
| apex_debug.info(l_request); | |
| apex_web_service.clear_request_headers(); | |
| apex_web_service.set_request_headers('Square-Version','2023-08-16',p_reset => false); | |
| apex_web_service.set_request_headers('Content-Type','application/json',p_reset => false); | |
| l_response := apex_web_service.make_rest_request( | |
| p_url => :SQUARE_ENDPOINT || '/v2/payments' | |
| ,p_http_method => 'POST' | |
| ,p_body => l_request | |
| ,p_credential_static_id => 'SQUARE_CRED' | |
| ); | |
| if apex_web_service.g_status_code <> 200 then | |
| raise e_create_payment_failed; | |
| end if; | |
| htp.p(l_response); | |
| end; |
以上でSquareのPayment APIを呼び出すサンプルは完成です。アプリケーションを実行すると、この記事の先頭のGIF動画のように動作します。
Oracle APEXのアプリケーション作成の参考になれば幸いです。
完
