Menu Apps

Processing a card payment (PHP)

After the SqPaymentForm generates a card nonce and you submit it to your server, you finish processing the payment by sending a request to the Charge endpoint with the details of the transaction.

If your server is implemented in PHP, you can use the SquareConnect client library to simplify making requests to all Connect v2 endpoints.

Installing the SquareConnect PHP library

The SquareConnect client library is available via Composer. To add it to your project, first add the following dependency to your application's composer.json file:

{
  "require": {
    "square/connect": "*",
    <OTHER DEPENDENCIES>
  }
}

(You can also add this dependency by running php composer.phar require square/connect)

Then, download your application's dependencies by running:

php composer.phar install

Retrieving your location IDs

Every Square merchant's business consists of one or more locations. Every payment a merchant processes is associated with one of these locations (even online payments). In order to process a payment with Connect v2, you need to know which location you want to associate the payment with.

The SquareConnect library has an easy method for obtaining a business' location IDs: the listLocations method.

Paste the following into a locations-test.php file and run it with php locations-test.php. Be sure to specify your personal access token where indicated. The details of your business' locations will appear in the console.

<?php

require 'vendor/autoload.php';

$access_token = "YOUR_PERSONAL_ACCESS_TOKEN";

SquareConnect\Configuration::getDefaultConfiguration()->setAccessToken($access_token);

$locations_api = new \SquareConnect\Api\LocationsApi();

echo $locations_api->listLocations();

Charging the card nonce

Now that you've generated a card nonce with the SqPaymentForm and you have a way to retrieve a business' location IDs, you can charge a buyer's card, like so:

require 'vendor/autoload.php';

# Assume you have assigned values to the following variables:
#   $nonce
#   $location_id
#   $access_token

SquareConnect\Configuration::getDefaultConfiguration()->setAccessToken($access_token);
$transactions_api = new \SquareConnect\Api\TransactionsApi();

$request_body = array (

  "card_nonce" => $nonce,

  # Monetary amounts are specified in the smallest unit of the applicable currency.
  # This amount is in cents. It's also hard-coded for $1, which is not very useful.
  "amount_money" => array (
    "amount" => 100,
    "currency" => "USD"
  ),

  # Every payment you process for a given business have a unique idempotency key.
  # If you're unsure whether a particular payment succeeded, you can reattempt
  # it with the same idempotency key without worrying about double charging
  # the buyer.
  "idempotency_key" => uniqid()
);

# The SDK throws an exception if a Connect endpoint responds with anything besides 200 (success).
# This block catches any exceptions that occur from the request.
try {
  print_r($transactions_api->charge($location_id, $request_body));
} catch (Exception $e) {
  echo "Caught exception " . $e->getMessage();
}

The value returned by charge is an array that contains all of the details of the processed transaction.

Trying it out

A full sample that uses the SqPaymentForm and the SquareConnect library is available on Github. See the sample's README for information on running the sample.

If you want to test out charging cards without actually moving any money, you can configure the sample to communicate with Connect v2 sandbox endpoints. For more information, see Using the API sandbox.

Learn about OAuth

So far in this tutorial, you've used your personal access token, which gives you full access to your own business' data. If you are developing an application for other businesses to use as well, you use the OAuth API to generate access tokens for those businesses.

The OAuth flow in Connect v2 is identical to the flow in v1. Learn more about the OAuth flow at https://docs.connect.squareup.com/api/oauth/#oauth-overview. Code samples for the OAuth flow are available at https://github.com/square/connect-api-examples/tree/master/connect-examples/oauth.

Important: In order for your app to process payments on behalf of another merchant, the merchant must authorize your application with the PAYMENTS_WRITE OAuth permission.

Was this page helpful?