Useful Links

Payment processing example: Node.js

There are two sections in this README.

Setup - Provides instructions for you to download and run the app.
Application Flow - Provides an overview of how the Square Web Payments SDK integrates in the Node.js example.

Setup

Create a file named .env in the root directory of this example. .env.example is an example of what the .env file should look like. Fill in values for SQUARE_APPLICATION_ID, SQUARE_ACCESS_TOKEN, and SQUARE_LOCATION_ID with your sandbox or production credentials. WARNING: never save your credentials in your code.
Ensure you have npm installed (npm -v in your terminal). If not please follow the instructions for your OS: https://www.npmjs.com/get-npm
Open your terminal and type the following to install the packages:
```
npm install
```
Then to run the server in production mode:
```
npm start
```
Or to run in sandbox mode:
```
npm test
```
Open a browser and navigate to localhost:3000
Test with different payment options. For more information on testing in sandbox mode, follow the guide: Testing using the API sandbox. You can find more testing values in this article.

Note that if you are not using your sandbox credentials and you enter real credit card information, YOU WILL CHARGE THE CARD.

Application Flow

This Node.js web application implements the Square Online payment solution to charge a payment source (debit card, credit card, ACH transfers, and digital wallet payment methods).

Square Online payment solution is a 2-step process:

Generate a token - Use the Square Web Payments SDK to accept payment source information and generate a secure payment token.

NOTE: The Web Payments SDK renders the card inputs and digital wallet buttons that make up the payment form and returns a secure payment token. For more information, see the Web Payments SDK Overview.
Charge the payment source using the token - Using a server-side component, that uses the Connect V2 Payments API, you charge the payment source using the secure payment token.

The following sections describe how the Node JS sample implements these steps.

Step 1: Generate a Token

When the page loads it renders the form defined in the views/index.pug file. The page also downloads and executes the following scripts:

Square Web Payments SDK - It is a library that provides the Payment objects you use in sq-payment-flow.js. For more information about the library, see Web Payments SDK Reference.

sq-payment-flow.js - This code provides two things:

Initializes objects for various supported payment methods including card payments, bank payments, and digital wallet payments. Each of the following files handles unique client logic for a specific payment method to generate a payment token:
- sq-card-pay.js
- sq-ach.js
- sq-google-pay.js
- sq-apple-pay.js

Provides the global method that fires a fetch request to the server after receiving the payment token.

window.createPayment = async function(token) {
  const dataJsonString = JSON.stringify({
    token
  });

  try {
    const response = await fetch('process-payment', {
      method: 'POST',
      headers: {
      'Content-Type': 'application/json'
      },
      body: dataJsonString
    });

    const data = await response.json();

    if (data.errors && data.errors.length > 0) {
      if (data.errors[0].detail) {
        window.showError(data.errors[0].detail);
      } else {
        window.showError('Payment Failed.');
      }
    } else {
      window.showSuccess('Payment Successful!');
    }
  } catch (error) {
    console.error('Error:', error);
  }
}

Step 2: Charge the Payment Source Using the Token

All the remaining actions take place in the routes/index.js file. This server-side component uses the Square Node.js SDK library to call the Connect V2 Payments API to charge the payment source using the token as shown in the following code fragment.

...
router.post('/process-payment', async (req, res) => {
  const token = req.body.token;

  // length of idempotency_key should be less than 45
  const idempotencyKey = uuidv4();

  // get the currency for the location
  const locationResponse = await locationsApi.retrieveLocation(process.env.SQUARE_LOCATION_ID);
  const currency = locationResponse.result.location.currency;

  // Charge the customer's card
  const requestBody = {
    idempotencyKey,
    sourceId: token,
    amountMoney: {
      amount: 100, // $1.00 charge
      currency
    }
  };

  try {
    const { result: { payment } } = await paymentsApi.createPayment(requestBody);

    const result = JSON.stringify(payment, (key, value) => {
      return typeof value === "bigint" ? parseInt(value) : value;
    }, 4);

    res.json({
      result
    });
  } catch (error) {
    res.json(error.result);
  }
});
...

License

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.