/connect-php-sdk

PHP client library for the Square Connect APIs

Primary LanguagePHPApache License 2.0Apache-2.0

Square logo

Square Connect PHP SDK

Build Status PHP version Apache-2 license

If you have feedback about the new SDKs, or just want to talk to other Square Developers, request an invite to the new slack community for Square Developers

This repository contains a generated PHP client SDK for the Square Connect APIs. Check out our API specification repository for the specification and template files we used to generate this.

If you are looking for a sample e-commerce application using these APIs, check out the connect-api-examples repository.

To learn more about the Square APIs in general, head on over to the Square API documentation

Requirements

Installing

Option 1: With Composer

The PHP SDK is available on Packagist. To add it to Composer, simply run:

$ php composer.phar require square/connect

Or add this line under "require" to your composer.json:

"require": {
    ...
    "square/connect": "*",
    ...
}

And then install your composer dependencies with

$ php composer.phar install
Option 2: From GitHub

Clone this repository, or download the zip into your project's folder and then add the following line in your code:

require('connect-php-sdk/autoload.php');

Note: you might have to change the path depending on your project's folder structure.

Option 3: Without Command Line Access

If you cannot access the command line for your server, you can also install the SDK from github. Download the SDK from github with this link, unzip it and add the following line to your php files that will need to access the SDK:

require('connect-php-sdk-master/autoload.php');

Note: you might have to change the path depending on where you place the SDK in relation to your other php files.

Getting Started

Please follow the installation procedure:

Retrieve your location IDs

require 'vendor/autoload.php';

$access_token = 'YOUR_ACCESS_TOKEN';
# setup authorization
$api_config = new \SquareConnect\Configuration();
$api_config->setHost("https://connect.squareup.com");
$api_config->setAccessToken($access_token);
$api_client = new \SquareConnect\ApiClient($api_config);
# create an instance of the Location API
$locations_api = new \SquareConnect\Api\LocationsApi($api_client);

try {
  $locations = $locations_api->listLocations();
  print_r($locations->getLocations());
} catch (\SquareConnect\ApiException $e) {
  echo "Caught exception!<br/>";
  print_r("<strong>Response body:</strong><br/>");
  echo "<pre>"; var_dump($e->getResponseBody()); echo "</pre>";
  echo "<br/><strong>Response headers:</strong><br/>";
  echo "<pre>"; var_dump($e->getResponseHeaders()); echo "</pre>";
  exit(1);
}

Charge the card nonce

require 'vendor/autoload.php';

$access_token = 'YOUR_ACCESS_TOKEN';

# setup authorization
$api_config = new \SquareConnect\Configuration();
$api_config->setHost("https://connect.squareup.com");
$api_config->setAccessToken($access_token);
$api_client = new \SquareConnect\ApiClient($api_config);

# create an instance of the Payments API class
$payments_api = new \SquareConnect\Api\PaymentsApi($api_client);
$location_id = 'YOUR_LOCATION_ID'
$nonce = 'YOUR_NONCE'

$body = new \SquareConnect\Model\CreatePaymentRequest();

$amountMoney = new \SquareConnect\Model\Money();

# Monetary amounts are specified in the smallest unit of the applicable currency.
# This amount is in cents. It's also hard-coded for $1.00, which isn't very useful.
$amountMoney->setAmount(100);
$amountMoney->setCurrency("USD");

$body->setSourceId($nonce);
$body->setAmountMoney($amountMoney);
$body->setLocationId($location_id);

# Every payment you process with the SDK must 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.
$body->setIdempotencyKey(uniqid());

try {
    $result = $payments_api->createPayment($body);
    print_r($result);
} catch (\SquareConnect\ApiException $e) {
    echo "Exception when calling PaymentsApi->createPayment:";
    var_dump($e->getResponseBody());
}

How to configure sandbox environment

require 'vendor/autoload.php';

$access_token = 'YOUR_SANDBOX_ACCESS_TOKEN';
# setup authorization
$api_config = new \SquareConnect\Configuration();
$api_config->setHost("https://connect.squareupsandbox.com");
$api_config->setAccessToken($access_token);
$api_client = new \SquareConnect\ApiClient($api_config);
# create an instance of the Location API
$locations_api = new \SquareConnect\Api\LocationsApi($api_client);

Documentation for API Endpoints

All URIs are relative to https://connect.squareup.com

Class Method HTTP request Description
ApplePayApi registerDomain POST /v2/apple-pay/domains RegisterDomain
CashDrawersApi listCashDrawerShiftEvents GET /v2/cash-drawers/shifts/{shift_id}/events ListCashDrawerShiftEvents
CashDrawersApi listCashDrawerShifts GET /v2/cash-drawers/shifts ListCashDrawerShifts
CashDrawersApi retrieveCashDrawerShift GET /v2/cash-drawers/shifts/{shift_id} RetrieveCashDrawerShift
CatalogApi batchDeleteCatalogObjects POST /v2/catalog/batch-delete BatchDeleteCatalogObjects
CatalogApi batchRetrieveCatalogObjects POST /v2/catalog/batch-retrieve BatchRetrieveCatalogObjects
CatalogApi batchUpsertCatalogObjects POST /v2/catalog/batch-upsert BatchUpsertCatalogObjects
CatalogApi catalogInfo GET /v2/catalog/info CatalogInfo
CatalogApi deleteCatalogObject DELETE /v2/catalog/object/{object_id} DeleteCatalogObject
CatalogApi listCatalog GET /v2/catalog/list ListCatalog
CatalogApi retrieveCatalogObject GET /v2/catalog/object/{object_id} RetrieveCatalogObject
CatalogApi searchCatalogObjects POST /v2/catalog/search SearchCatalogObjects
CatalogApi updateItemModifierLists POST /v2/catalog/update-item-modifier-lists UpdateItemModifierLists
CatalogApi updateItemTaxes POST /v2/catalog/update-item-taxes UpdateItemTaxes
CatalogApi upsertCatalogObject POST /v2/catalog/object UpsertCatalogObject
CheckoutApi createCheckout POST /v2/locations/{location_id}/checkouts CreateCheckout
CustomersApi createCustomer POST /v2/customers CreateCustomer
CustomersApi createCustomerCard POST /v2/customers/{customer_id}/cards CreateCustomerCard
CustomersApi deleteCustomer DELETE /v2/customers/{customer_id} DeleteCustomer
CustomersApi deleteCustomerCard DELETE /v2/customers/{customer_id}/cards/{card_id} DeleteCustomerCard
CustomersApi listCustomers GET /v2/customers ListCustomers
CustomersApi retrieveCustomer GET /v2/customers/{customer_id} RetrieveCustomer
CustomersApi searchCustomers POST /v2/customers/search SearchCustomers
CustomersApi updateCustomer PUT /v2/customers/{customer_id} UpdateCustomer
EmployeesApi listEmployees GET /v2/employees ListEmployees
EmployeesApi retrieveEmployee GET /v2/employees/{id} RetrieveEmployee
InventoryApi batchChangeInventory POST /v2/inventory/batch-change BatchChangeInventory
InventoryApi batchRetrieveInventoryChanges POST /v2/inventory/batch-retrieve-changes BatchRetrieveInventoryChanges
InventoryApi batchRetrieveInventoryCounts POST /v2/inventory/batch-retrieve-counts BatchRetrieveInventoryCounts
InventoryApi retrieveInventoryAdjustment GET /v2/inventory/adjustment/{adjustment_id} RetrieveInventoryAdjustment
InventoryApi retrieveInventoryChanges GET /v2/inventory/{catalog_object_id}/changes RetrieveInventoryChanges
InventoryApi retrieveInventoryCount GET /v2/inventory/{catalog_object_id} RetrieveInventoryCount
InventoryApi retrieveInventoryPhysicalCount GET /v2/inventory/physical-count/{physical_count_id} RetrieveInventoryPhysicalCount
LaborApi createBreakType POST /v2/labor/break-types CreateBreakType
LaborApi createShift POST /v2/labor/shifts CreateShift
LaborApi deleteBreakType DELETE /v2/labor/break-types/{id} DeleteBreakType
LaborApi deleteShift DELETE /v2/labor/shifts/{id} DeleteShift
LaborApi getBreakType GET /v2/labor/break-types/{id} GetBreakType
LaborApi getEmployeeWage GET /v2/labor/employee-wages/{id} GetEmployeeWage
LaborApi getShift GET /v2/labor/shifts/{id} GetShift
LaborApi listBreakTypes GET /v2/labor/break-types ListBreakTypes
LaborApi listEmployeeWages GET /v2/labor/employee-wages ListEmployeeWages
LaborApi listWorkweekConfigs GET /v2/labor/workweek-configs ListWorkweekConfigs
LaborApi searchShifts POST /v2/labor/shifts/search SearchShifts
LaborApi updateBreakType PUT /v2/labor/break-types/{id} UpdateBreakType
LaborApi updateShift PUT /v2/labor/shifts/{id} UpdateShift
LaborApi updateWorkweekConfig PUT /v2/labor/workweek-configs/{id} UpdateWorkweekConfig
LocationsApi createLocation POST /v2/locations CreateLocation
LocationsApi listLocations GET /v2/locations ListLocations
LocationsApi retrieveLocation GET /v2/locations/{location_id} RetrieveLocation
LocationsApi updateLocation PUT /v2/locations/{location_id} UpdateLocation
MerchantsApi listMerchants GET /v2/merchants ListMerchants
MerchantsApi retrieveMerchant GET /v2/merchants/{merchant_id} RetrieveMerchant
MobileAuthorizationApi createMobileAuthorizationCode POST /mobile/authorization-code CreateMobileAuthorizationCode
OAuthApi obtainToken POST /oauth2/token ObtainToken
OAuthApi renewToken POST /oauth2/clients/{client_id}/access-token/renew RenewToken
OAuthApi revokeToken POST /oauth2/revoke RevokeToken
OrdersApi batchRetrieveOrders POST /v2/locations/{location_id}/orders/batch-retrieve BatchRetrieveOrders
OrdersApi createOrder POST /v2/locations/{location_id}/orders CreateOrder
OrdersApi payOrder POST /v2/orders/{order_id}/pay PayOrder
OrdersApi searchOrders POST /v2/orders/search SearchOrders
OrdersApi updateOrder PUT /v2/locations/{location_id}/orders/{order_id} UpdateOrder
PaymentsApi cancelPayment POST /v2/payments/{payment_id}/cancel CancelPayment
PaymentsApi cancelPaymentByIdempotencyKey POST /v2/payments/cancel CancelPaymentByIdempotencyKey
PaymentsApi completePayment POST /v2/payments/{payment_id}/complete CompletePayment
PaymentsApi createPayment POST /v2/payments CreatePayment
PaymentsApi getPayment GET /v2/payments/{payment_id} GetPayment
PaymentsApi listPayments GET /v2/payments ListPayments
RefundsApi getPaymentRefund GET /v2/refunds/{refund_id} GetPaymentRefund
RefundsApi listPaymentRefunds GET /v2/refunds ListPaymentRefunds
RefundsApi refundPayment POST /v2/refunds RefundPayment
ReportingApi listAdditionalRecipientReceivableRefunds GET /v2/locations/{location_id}/additional-recipient-receivable-refunds ListAdditionalRecipientReceivableRefunds
ReportingApi listAdditionalRecipientReceivables GET /v2/locations/{location_id}/additional-recipient-receivables ListAdditionalRecipientReceivables
TransactionsApi captureTransaction POST /v2/locations/{location_id}/transactions/{transaction_id}/capture CaptureTransaction
TransactionsApi charge POST /v2/locations/{location_id}/transactions Charge
TransactionsApi createRefund POST /v2/locations/{location_id}/transactions/{transaction_id}/refund CreateRefund
TransactionsApi listRefunds GET /v2/locations/{location_id}/refunds ListRefunds
TransactionsApi listTransactions GET /v2/locations/{location_id}/transactions ListTransactions
TransactionsApi retrieveTransaction GET /v2/locations/{location_id}/transactions/{transaction_id} RetrieveTransaction
TransactionsApi voidTransaction POST /v2/locations/{location_id}/transactions/{transaction_id}/void VoidTransaction
V1EmployeesApi createEmployee POST /v1/me/employees CreateEmployee
V1EmployeesApi createEmployeeRole POST /v1/me/roles CreateEmployeeRole
V1EmployeesApi createTimecard POST /v1/me/timecards CreateTimecard
V1EmployeesApi deleteTimecard DELETE /v1/me/timecards/{timecard_id} DeleteTimecard
V1EmployeesApi listCashDrawerShifts GET /v1/{location_id}/cash-drawer-shifts ListCashDrawerShifts
V1EmployeesApi listEmployeeRoles GET /v1/me/roles ListEmployeeRoles
V1EmployeesApi listEmployees GET /v1/me/employees ListEmployees
V1EmployeesApi listTimecardEvents GET /v1/me/timecards/{timecard_id}/events ListTimecardEvents
V1EmployeesApi listTimecards GET /v1/me/timecards ListTimecards
V1EmployeesApi retrieveCashDrawerShift GET /v1/{location_id}/cash-drawer-shifts/{shift_id} RetrieveCashDrawerShift
V1EmployeesApi retrieveEmployee GET /v1/me/employees/{employee_id} RetrieveEmployee
V1EmployeesApi retrieveEmployeeRole GET /v1/me/roles/{role_id} RetrieveEmployeeRole
V1EmployeesApi retrieveTimecard GET /v1/me/timecards/{timecard_id} RetrieveTimecard
V1EmployeesApi updateEmployee PUT /v1/me/employees/{employee_id} UpdateEmployee
V1EmployeesApi updateEmployeeRole PUT /v1/me/roles/{role_id} UpdateEmployeeRole
V1EmployeesApi updateTimecard PUT /v1/me/timecards/{timecard_id} UpdateTimecard
V1ItemsApi adjustInventory POST /v1/{location_id}/inventory/{variation_id} AdjustInventory
V1ItemsApi applyFee PUT /v1/{location_id}/items/{item_id}/fees/{fee_id} ApplyFee
V1ItemsApi applyModifierList PUT /v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id} ApplyModifierList
V1ItemsApi createCategory POST /v1/{location_id}/categories CreateCategory
V1ItemsApi createDiscount POST /v1/{location_id}/discounts CreateDiscount
V1ItemsApi createFee POST /v1/{location_id}/fees CreateFee
V1ItemsApi createItem POST /v1/{location_id}/items CreateItem
V1ItemsApi createModifierList POST /v1/{location_id}/modifier-lists CreateModifierList
V1ItemsApi createModifierOption POST /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options CreateModifierOption
V1ItemsApi createPage POST /v1/{location_id}/pages CreatePage
V1ItemsApi createVariation POST /v1/{location_id}/items/{item_id}/variations CreateVariation
V1ItemsApi deleteCategory DELETE /v1/{location_id}/categories/{category_id} DeleteCategory
V1ItemsApi deleteDiscount DELETE /v1/{location_id}/discounts/{discount_id} DeleteDiscount
V1ItemsApi deleteFee DELETE /v1/{location_id}/fees/{fee_id} DeleteFee
V1ItemsApi deleteItem DELETE /v1/{location_id}/items/{item_id} DeleteItem
V1ItemsApi deleteModifierList DELETE /v1/{location_id}/modifier-lists/{modifier_list_id} DeleteModifierList
V1ItemsApi deleteModifierOption DELETE /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id} DeleteModifierOption
V1ItemsApi deletePage DELETE /v1/{location_id}/pages/{page_id} DeletePage
V1ItemsApi deletePageCell DELETE /v1/{location_id}/pages/{page_id}/cells DeletePageCell
V1ItemsApi deleteVariation DELETE /v1/{location_id}/items/{item_id}/variations/{variation_id} DeleteVariation
V1ItemsApi listCategories GET /v1/{location_id}/categories ListCategories
V1ItemsApi listDiscounts GET /v1/{location_id}/discounts ListDiscounts
V1ItemsApi listFees GET /v1/{location_id}/fees ListFees
V1ItemsApi listInventory GET /v1/{location_id}/inventory ListInventory
V1ItemsApi listItems GET /v1/{location_id}/items ListItems
V1ItemsApi listModifierLists GET /v1/{location_id}/modifier-lists ListModifierLists
V1ItemsApi listPages GET /v1/{location_id}/pages ListPages
V1ItemsApi removeFee DELETE /v1/{location_id}/items/{item_id}/fees/{fee_id} RemoveFee
V1ItemsApi removeModifierList DELETE /v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id} RemoveModifierList
V1ItemsApi retrieveItem GET /v1/{location_id}/items/{item_id} RetrieveItem
V1ItemsApi retrieveModifierList GET /v1/{location_id}/modifier-lists/{modifier_list_id} RetrieveModifierList
V1ItemsApi updateCategory PUT /v1/{location_id}/categories/{category_id} UpdateCategory
V1ItemsApi updateDiscount PUT /v1/{location_id}/discounts/{discount_id} UpdateDiscount
V1ItemsApi updateFee PUT /v1/{location_id}/fees/{fee_id} UpdateFee
V1ItemsApi updateItem PUT /v1/{location_id}/items/{item_id} UpdateItem
V1ItemsApi updateModifierList PUT /v1/{location_id}/modifier-lists/{modifier_list_id} UpdateModifierList
V1ItemsApi updateModifierOption PUT /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id} UpdateModifierOption
V1ItemsApi updatePage PUT /v1/{location_id}/pages/{page_id} UpdatePage
V1ItemsApi updatePageCell PUT /v1/{location_id}/pages/{page_id}/cells UpdatePageCell
V1ItemsApi updateVariation PUT /v1/{location_id}/items/{item_id}/variations/{variation_id} UpdateVariation
V1LocationsApi listLocations GET /v1/me/locations ListLocations
V1LocationsApi retrieveBusiness GET /v1/me RetrieveBusiness
V1TransactionsApi createRefund POST /v1/{location_id}/refunds CreateRefund
V1TransactionsApi listBankAccounts GET /v1/{location_id}/bank-accounts ListBankAccounts
V1TransactionsApi listOrders GET /v1/{location_id}/orders ListOrders
V1TransactionsApi listPayments GET /v1/{location_id}/payments ListPayments
V1TransactionsApi listRefunds GET /v1/{location_id}/refunds ListRefunds
V1TransactionsApi listSettlements GET /v1/{location_id}/settlements ListSettlements
V1TransactionsApi retrieveBankAccount GET /v1/{location_id}/bank-accounts/{bank_account_id} RetrieveBankAccount
V1TransactionsApi retrieveOrder GET /v1/{location_id}/orders/{order_id} RetrieveOrder
V1TransactionsApi retrievePayment GET /v1/{location_id}/payments/{payment_id} RetrievePayment
V1TransactionsApi retrieveSettlement GET /v1/{location_id}/settlements/{settlement_id} RetrieveSettlement
V1TransactionsApi updateOrder PUT /v1/{location_id}/orders/{order_id} UpdateOrder

Documentation For Models

Documentation For Authorization

oauth2

  • Type: OAuth
  • Flow: accessCode
  • Authorization URL: https://connect.squareup.com/oauth2/authorize
  • Scopes:
  • BANK_ACCOUNTS_READ: HTTP Method: GET Grants read access to bank account information associated with the targeted Square account. For example, to call the Connect v1 ListBankAccounts endpoint.
  • CUSTOMERS_READ: HTTP Method: GET Grants read access to customer information. For example, to call the ListCustomers endpoint.
  • CUSTOMERS_WRITE: HTTP Method: POST, PUT, DELETE Grants write access to customer information. For example, to create and update customer profiles.
  • EMPLOYEES_READ: HTTP Method: GET Grants read access to employee profile information. For example, to call the Connect v1 Employees API.
  • EMPLOYEES_WRITE: HTTP Method: POST, PUT, DELETE Grants write access to employee profile information. For example, to create and modify employee profiles.
  • INVENTORY_READ: HTTP Method: GET Grants read access to inventory information. For example, to call the RetrieveInventoryCount endpoint.
  • INVENTORY_WRITE: HTTP Method: POST, PUT, DELETE Grants write access to inventory information. For example, to call the BatchChangeInventory endpoint.
  • ITEMS_READ: HTTP Method: GET Grants read access to business and location information. For example, to obtain a location ID for subsequent activity.
  • ITEMS_WRITE: HTTP Method: POST, PUT, DELETE Grants write access to product catalog information. For example, to modify or add to a product catalog.
  • MERCHANT_PROFILE_READ: HTTP Method: GET Grants read access to business and location information. For example, to obtain a location ID for subsequent activity.
  • ORDERS_READ: HTTP Method: GET Grants read access to order information. For example, to call the BatchRetrieveOrders endpoint.
  • ORDERS_WRITE: HTTP Method: POST, PUT, DELETE Grants write access to order information. For example, to call the CreateCheckout endpoint.
  • PAYMENTS_READ: HTTP Method: GET Grants read access to transaction and refund information. For example, to call the RetrieveTransaction endpoint.
  • PAYMENTS_WRITE: HTTP Method: POST, PUT, DELETE Grants write access to transaction and refunds information. For example, to process payments with the Payments or Checkout API.
  • PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS: HTTP Method: POST, PUT, DELETE Allow third party applications to deduct a portion of each transaction amount. Required to use multiparty transaction functionality with the Payments API.
  • PAYMENTS_WRITE_IN_PERSON: HTTP Method: POST, PUT, DELETE Grants write access to payments and refunds information. For example, to process in-person payments.
  • SETTLEMENTS_READ: HTTP Method: GET Grants read access to settlement (deposit) information. For example, to call the Connect v1 ListSettlements endpoint.
  • TIMECARDS_READ: HTTP Method: GET Grants read access to employee timecard information. For example, to call the Connect v2 SearchShifts endpoint.
  • TIMECARDS_WRITE: HTTP Method: POST, PUT, DELETE Grants write access to employee shift information. For example, to create and modify employee shifts.
  • TIMECARDS_SETTINGS_READ: HTTP Method: GET Grants read access to employee timecard settings information. For example, to call the GetBreakType endpoint.
  • TIMECARDS_SETTINGS_WRITE: HTTP Method: POST, PUT, DELETE Grants write access to employee timecard settings information. For example, to call the UpdateBreakType endpoint.

oauth2ClientSecret

  • Type: API key
  • API key parameter name: Authorization
  • Location: HTTP header

Pagination of V1 Endpoints

V1 Endpoints return pagination information via HTTP headers. In order to obtain response headers and extract the batch_token parameter you will need to follow the following steps:

  1. Use the full information endpoint methods of each API to get the response HTTP Headers. They are named as their simple counterpart with a WithHttpInfo suffix. Hence listEmployeeRoles would be called listEmployeeRolesWithHttpInfo. This method returns an array with 3 parameters: $response, $http_status, and $http_headers.
  2. Use $batch_token = \SquareConnect\ApiClient::getV1BatchTokenFromHeaders($http_headers) to extract the token and proceed to get the following page if a token is present.

Example

<?php
...
$api_instance = new SquareConnect\Api\V1EmployeesApi();
$order = null;
$limit = 20;
$batch_token = null;
$roles = array();

try {
    do {
        list($result, $status, $headers) = $api_instance->listEmployeeRolesWithHttpInfo($order, $limit, $batch_token);
        $batch_token = \SquareConnect\ApiClient::getV1BatchTokenFromHeaders($headers);
        $roles = array_merge($roles, $result);
    } while (!is_null($batch_token));
    print_r($roles);
} catch (Exception $e) {
    echo 'Exception when calling V1EmployeesApi->listEmployeeRolesWithHttpInfo: ', $e->getMessage(), PHP_EOL;
}
?>

Contributing

Send bug reports, feature requests, and code contributions to the API specifications repository, as this repository contains only the generated SDK code. If you notice something wrong about this SDK in particular, feel free to raise an issue here.

License

Copyright 2017 Square, Inc.

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.