====== API integration ======

The Wizard's Toolkit has functions to make integrating with APIs easier for the developer.  These functions are kept in the /wtk/lib folder and are named after the company they are integrating with.

These include:

  * PayPal
    * wtkPayPalOneItem
    * wtkShoppingCart
    * wtkViewCart
    * wtkBuyNow
    * wtkBuyRedir
    * wtkSubscribePayPal
    * wtkUnSubscribePayPal
  * Twilio (for sending SMS)
    * wtkSendSMS
  * Google
    * wtkGmap (create a Google map with markers where your locations are)
    * wtkGetTimeZoneFromGeoCodes
    * wtkMapLink (create link to map)
  * Social (various functions for social media)
    * wtkSocialSmartLayer (AddThis)
    * wtkSocialFollowUs (AddThis)
    * wtkHtmShowSocial (AddThis)
    * wtkHtmShowTwitter

Currently the **Stripe** API integration is being worked on and should be added to the Wizard's Toolkit by June 2022.

===== Returning to SPA from APIs =====

When you need to give a link to a website so it can return a user to a page within your SPA (Single Page Application), you can do so by calling the **wtkSPArestart** function which accepts the optional parameter of HTML you want to prepend the HTML template it uses.  In this way you can do some data-driven code based on incoming parameters to the page.

The goal is to allow a user who is already logged in to your website or app to use an API to go to an outside website then return without having to re-login.  For example when using PayPal or Stripe and the user is taken to their servers for payment processing and you pass them the URL to return to upon either cancellation or success.  The **apiKey** is how a SPA knows that a user is signed-in so you pass that and the page you want them to return to (via the **p** parameter) to the outside provider.  For example in your PHP for calling **Stripe** to set up account links you would do the following:

    $pgApiKey = wtkGetPost('apiKey');
    $pgRefreshURL = $gloWebBaseURL . '/admin/?p=cancel&apiKey=' . $pgApiKey;
    $pgReturnURL = $gloWebBaseURL . '/admin/?p=thanks&apiKey=' . $pgApiKey;
    $pgResponse = $stripe->accountLinks->create([
        'account' => $pgStripeAcctId,
        'refresh_url' => $pgRefreshURL,
        'return_url' => $pgReturnURL,
        'type' => 'account_onboarding',
      ]
    );


This would then expect you to have **cancel.htm** and **thanks.htm** files in your /admin directory.  Then in your /admin/index.php you would simply add this one line in order to receive the request, pull in the HTML into your /wtk/htm/spa.htm template and hide/unhide the proper divs and menu navigation.


  wtkSPArestart($pgHtm); // only triggered when returning from outside APIs
 

The **wtkSPArestart** will only do anything if all the following criteria are met:

  * $gloSiteDesign PHP variable is set to 'SPA' (which always is the case in the /admin folder)
  * apiKey parameter is passed
  * p parameter is passed

If any one of those parameters are not set, then nothing happens.  If all are set but the apiKey is not valid, then the [[https://wizardstoolkit.com/docs/files/wtk-lib-utils.html#function_wtkDeadPage|wtkDeadPage]] function is called which ends the user's session.

When all parameters are passed and the apiKey is valid, the HTML file will be pulled in and displayed as the mainPage from your /wtk/htm/spa.htm file.  The valid apiKey allows skipping re-logging in.

For example the thanks.htm page could look like this.

  <div class="container">
      <br><br>
      <div class="card green lighten-4">
          <div class="card-content center">
              <h2>Authorization Success!</h2>
              <br><p>Your connection to Stripe has succeeded.</p>
          </div>
      </div>
  </div>