Deprecated
This API is deprecated, see below for guidance on what to use instead.
Transactions API

Build with Transactions

Note

Transactions API is deprecated. The API functionality is split into the new Payments API and a more robust Orders API. For more information, Payments and Refunds Overview and Orders: What it Does .

Build a custom integration with Transactions API to process online payments.

Web
Backend
Transactions API
PHP (5.x) (SDK)

Warning

The Payment Card Industry Data Security Standard (PCI DSS) defines important security requirements for the storage, processing, and transmission of payment card information (card numbers, cardholder names, and so on). To conform to these requirements, minimize security risk, and ensure customer privacy, NEVER store, process, or transmit payment card information or other confidential customer information.

Prerequisites and assumptions Permalink Get a link to this section

To use the Transactions API, the following must be true:

  • You have a Square account enabled for payment processing. If you have not enabled payment processing on your account (or you are not sure), visit squareup.com/activate.

  • You are using HTTPS. HTTPS is required for all production Square API calls. HTTP calls are only supported for developing and testing on localhost.


Additionally, this guide makes the following assumptions:

  • You have read the What It Does topic for this product.

  • You are familiar with basic web development. If you are new to web development, you should read Getting started with the Web by Mozilla.org before continuing.

  • You can create and run websites on localhost or a development server. If you are new to testing web pages locally, you should read Run Local Web Servers before continuing.

Information you will need Permalink Get a link to this section

To use the steps in this topic, you need:

  • A valid access token. You should test with Sandbox credentials whenever possible. For more information, see Square API Access Tokens.

  • An active location ID. Copy a developer account location ID from the Locations page of your Square application in the Developer Dashboard or set the Developer Dashboard to Sandbox mode and then copy a Sandbox location ID.

Step 1: Set some useful variables Permalink Get a link to this section

Set some variables with your required information.

$accessToken = "YOUR_ACCESS_TOKEN";
$locationId = "YOUR_LOCATION_ID";

Step 2: Set the customer data Permalink Get a link to this section

// Create a new Charge request object
$chargeBody = new \SquareConnect\ChargeRequest() ;

// Create an Address object with shipping info
$shippingAddress = new \SquareConnect\Address() ;
$shippingAddress->setAddressLine1("123 Main St");
$shippingAddress->setLocality("San Francisco");
$shippingAddress->setAdministrativeDistrictLevel1("CA");
$shippingAddress->setPostalCode("94114");
$shippingAddress->setCountry("US");

// Create an Address object with billing info
$billingAddress = new \SquareConnect\Address() ;
$billingAddress->setAddressLine1("1500 Electric Ave");
$billingAddress->setAddressLine2("Suite 600");
$billingAddress->setLocality("New York City");
$billingAddress->setAdministrativeDistrictLevel1("NY");
$billingAddress->setPostalCode("20003");
$billingAddress->setCountry("US");

// Set the customer info
$chargeBody->setBuyerEmailAddress("thebuyer@example.com");
$chargeBody->setShippingAddress($shippingAddress);
$chargeBody->setBillingAddress($billingAddress);
``

Step 3: Set the payment information Permalink Get a link to this section

Configure payment information with the charge amount and a test nonce .

Did you know?

Businesses located in the United States or Canada can set an amount as low as 1 cent (amount = 1). If located in Australia, Japan or the United Kingdom, the amount must be a minimum of 100 cents (amount = 100).

$cardNonce = "fake-card-nonce-ok";
$idempotencyKey = uniqid();

// Set the charge amount to 10 USD
$chargeAmount =  new \SquareConnect\Money() ;
$chargeAmount->setAmount(1000);
$chargeAmount->setCurrency("USD");

// Set the payment information
$chargeBody->setIdempotencyKey($idempotencyKey);
$chargeBody->setCardNonce($cardNonce);
$chargeBody->setAmount($chargeAmount);

Step 4: Set the transaction metadata Permalink Get a link to this section

You can include notes and reference IDs from other systems to make cross-referencing transaction information easier.

$chargeBody->setReferenceId("Confirmation #12345");
$chargeBody->setNote("This is (not) a helpful note!");

Step 5: Call Charge Permalink Get a link to this section

Call the Charge endpoint to process the payment. While Charge returns results immediately, there is a slight delay between processing the transaction and the information being available in RetreiveTransaction or ListTransactions. Transactions processed through Square APIs will only ever have a single Tender object, but transactions processed with a Square reader may have multiple Tender objects.

// Create and configure a new API client object
$defaultApiConfig = new \SquareConnect\Configuration();
$defaultApiConfig->setAccessToken($accessToken);
$defaultApiClient = new \SquareConnect\ApiClient($defaultApiConfig) ;

$transactionsApi = new \SquareConnect\Api\TransactionsApi($defaultApiClient);

try {

  $apiResponse = $transactionsApi->charge($locationId, $chargeBody);

  // For now, just print the result to the screen
  echo "<pre>" . print_r($apiResponse, true) . "</pre>";

} catch (\SquareConnect\ApiException $e) {
  echo "<hr>" .
       "The SquareConnect\Api\TransactionsApi object threw an exception.<br>" .
       "API call: <code>TransactionsApi->charge</code>" .
       "<pre>" . var_dump($e) . "</pre>";
  throw $e;
}

Next steps

Now that you have a basic build in place, expand on it with these recipes!