Square eCommerce

Take Online Payments with Square APIs in 3 Steps

A screenshot of Square Payment Form documentation and a code editor
STEP ONE

Create a new Square API application.

Calls to Square’s API are authenticated using application IDs and authorization tokens (either a personal access token or an OAuth token).

To create a new application, first log in to the Application Dashboard using your Square account.

Then click + New Application and give the application a name.

Note the Application ID and Personal Access Token assigned to the application.


Step 2

Add Square’s payment form to your checkout flow.

Square provides an example payment form in the Square Developer documentation site that uses Square’s paymentform JavaScript object to request a valid card nonce from Square servers and include it in the form data before sending it to your payment processing page. To use the sample form, set applicationID to the application ID you generated in the previous step:

var applicationId = '{{ SET THE APPLICATION ID HERE}}';

The sample form has minimal formatting and only includes the fields required to create a valid card nonce (card number, CVV, expiration date, and postal code). You will need to extend the sample form to collect other useful payment information (e.g., charge amount and currency used) and apply styles that make the form match your site. For example:

Example payment form

Step 3

Use Square’s API to charge the card.

The final step is to add code to your payment processing page that initializes a Square API client:

// Create and configure a new Configuration object
$accessToken = "{{ SET YOUR PERSONAL ACCESS TOKEN HERE }}" ;
$locationID = null ;
$configuration = new \SquareConnect\Configuration() ;
$configuration->setHost("https://connect.squareup.com") ;
$configuration->setApiKey('Authorization', $accessToken) ;
$apiClientConfig = new \SquareConnect\ApiClient($configuration) ;

// Create a LocationApi client to load the location ID
$locClient = new \SquareConnect\Api\$apiClientConfig;

// Grab the location key for the configured store
try {
   $apiResponse = $locClient->listLocations($accessToken)->getLocations() ;
   $locationID = $apiResponse[0]['id'] ;
} catch (Exception $e) {
  // Handle the exception
}

Packages the transaction information as a ChargeRequest (including the card nonce retrieved by the payment form in the previous step):

// Package the charge amount and currency as a Money object
$chargeAmount = new \SquareConnect\Model\Money ;
$chargeAmount->setAmount(intval($_POST['amount'])) ;
$chargeAmount->setCurrency($_POST['currency']) ;

// Package the card information and purchase amount as a ChargeRequest
$chargeDetails = new \SquareConnect\Model\ChargeRequest() ;
$chargeDetails->setCardNonce($_POST['nonce']) ;
$chargeDetails->setAmountMoney($chargeAmount) ;
$chargeDetails->setIdempotencyKey(uniqid()) ;

And calls the Transaction API’s charge endpoint to process the card:

// Create a TransactionApi client to charge the card using our form info
$txClient = new \SquareConnect\Api\TransactionApi($apiClientConfig) ;

// Call the TransactionApi to charge the cardNumber
try {
  $apiResult = $txClient->charge($accessToken, $locationID,$chargeDetails);
} catch (Exception $e) {
  // Handle the exception
}

Note: In order for an eCommerce payment to potentially qualify for Square chargeback protection, you must also provide a buyer email address and a billing or shipping address.

The charge endpoint runs the card information included in the nonce object and provides a response indicating if the card was successfully captured or declined. Successful transactions can then be reviewed in the Sales Dashboard for your Square account.

Open your developer account now.