docs: Add reference guide for processing payments with Square

[AishaBlake]

Description

Adding a reference guide for working with Square to help shore up the e-commerce documentation. I've gone back and forth on this a bit, trying to decide how far to take it. Having gone through the Square documentation, it seems to me like the existing plugin doesn't correctly place the required reference to Square's library.

I feel like it's probably worth creating a starter to make this easier for people but also that something like that goes beyond what I set out to do in this PR. I've opened an issue for creating a Square starter.

In the meantime, the goal of this PR is to give people a starting point. Folks should have an idea of the capabilities of Square, be able to hook up an app, and get a nonce (token) back when submitting the payment form.

I'd love feedback on where screenshots might be most helpful!

Related Issues

Fixes #20224
Addresses #19768

[laurieontech]

This is awesome!
Did an editor's review. But want to do a technical walkthrough as well.

[laurieontech]

A couple more comments. Almost done with checking the functionality :)

[wardpeet]

Hey,

This will have a performance impact on gatsby because of the script tag. I propose to do something like the following so we only load the SDK when the component is used, even better is to move it into the PaymentForm.

The example of square isn't that great because the UI gets recreated when javascript loads with buttons and all of that, it introduces layouts shift and restyling operations. This can be taxing on low power devices where CPU is slow.

I'm happy to hop on a call or have a chat about this in LA :)

https://codesandbox.io/s/square-gatsby-qzitt

const loadSquareSdk = () => {
  return new Promise((resolve, reject) => {
    const sqPaymentScript = document.createElement("script")
    sqPaymentScript.src = "https://js.squareup.com/v2/paymentform"
    sqPaymentScript.crossorigin = "anonymous"
    sqPaymentScript.onload = () => {
      resolve()
    }
    sqPaymentScript.onerror = () => {
      reject(`Failed to load ${sqPaymentScript.src}`)
    }
    document.getElementsByTagName("head")[0].appendChild(sqPaymentScript)
  })
}

const IndexPage = () => {
  const [squareStatus, setSquareStatus] = useState(null)

  useEffect(() => {
    loadSquareSdk()
      .then(() => {
        setSquareStatus("SUCCESS")
      })
      .catch(() => setSquareStatus("ERROR"))
  }, []) // on mount we add the js script dynamicly

  return (
    <Layout>

      {squareStatus === "ERROR" &&
        "Failed to load SquareSDK, Please refresh the page"}
      {squareStatus === "SUCCESS" && (
        <PaymentForm paymentForm={window.SqPaymentForm} />
      )}
    </Layout>
  )
}

[AishaBlake]

Thanks so much for weighing in, @wardpeet! Your example is enough to help me rewrite that part of the guide. (I would love to pair on this or anything else, regardless.) This will also help me address Laurie's most recent comment. 😄

[jonniebigodes]

@AishaBlake i have the starter almost complete, there's still a couple of items to be addressed and based on that i would like to ask you a couple of things.
1- Should the starter include the whole process of processing the payments? I mean i've checked the documentation and at first glance it might be possible to implement a serverless function to handle the final part of the payment flow.
2- I've checked the codesandbox @wardpeet put up together and based on the code this document is using, i was able to change it to a functional version with hooks, should you be interested in using the hook version or go with the already existing version.

Feel free to provide feedback

[AishaBlake]

@jonniebigodes I'd make it as complete as you can and use hooks but it's totally up to you. This will be your starter to maintain, so those decisions are also yours. I'm grateful that you're taking this on and happy to provide feedback where I can.

[jonniebigodes]

@AishaBlake probably i didn't explain myself properly. What i meant to say regarding the hooks approach was to aim for consistency in both the documentation and starter. If a single code base can be used for both aspects.

Feel free to provide feedback.

[AishaBlake]

@jonniebigodes I think I understand. I think the hooks approach makes sense (and I can always adjust the guide laster if need be). I very intentionally left much of the code Square gives you, only adding labels for inputs and making it work. I would expect your starter to improve upon that base, not necessarily match it exactly. Feel free to link to your code in the relevant issue and tag me when you're ready for direct feedback!

[AishaBlake]

@laurieontech checking in on this. Were you able to have another look and did the update clarify things for you?

[laurieontech]

I somehow lost track of this thinking it was the PR about the starter. Will look now!

[laurieontech]

This helps a lot, a couple things.

1. Are the middle two examples both meant to have title paymentform.js? That confused me a bit.
2. The second to last code snippet is quite long. Even though we're giving examples it verges into tutorial land potentially? What about having an example repo and linking to it through out instead? Just an idea.

[AishaBlake]

Yes, they're both meant to have the same filename. I've broken the file into two pieces. I could include the whole file in the second code block but, as you said, it's already super long. Not all of that code is strictly necessary but I waffled back and forth between this and leaving things out which would potentially cause different confusion. It may be simpler to link to an example repo. I don't know if the one I sent you is sufficient...

[laurieontech]

I think the one you sent me is likely exactly right!

[AishaBlake]

I think the one you sent me is likely exactly right!

Added!

[laurieontech]

Made a recommendation to highlight a couple code snippet lines, let me know if you think those are accurate.

[laurieontech]

LGTM!

[muescha]

@jonniebigodes:
i see you have commited your serverless solution as a starter (
#21586 chore: add Square Starter to the starters list)

maybe also include somehow about this serverless to this doc so that others know about it?

[jonniebigodes]

@muescha see my comment in here if you don't mind.