Skip to content

Razorholt/connect-php-sdk

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

79 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Square Connect PHP SDK Build Status

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

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
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.

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
\SquareConnect\Configuration::getDefaultConfiguration()->setAccessToken($access_token);
# create an instance of the Location API
$locations_api = new \SquareConnect\Api\LocationsApi();

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
\SquareConnect\Configuration::getDefaultConfiguration()->setAccessToken($access_token);
# create an instance of the Transaction API class
$transactions_api = new \SquareConnect\Api\TransactionsApi();
$location_id = 'YOUR_LOCATION_ID'
$nonce = 'YOUR_NONCE'

$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.00, which isn't very useful.
    "amount_money" => array (
        "amount" => 100,
        "currency" => "USD"
    ),
    # 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.
    "idempotency_key" => uniqid()
);

try {
    $result = $transactions_api->charge($location_id,  $request_body);
    print_r($result);
} catch (\SquareConnect\ApiException $e) {
    echo "Exception when calling TransactionApi->charge:";
    var_dump($e->getResponseBody());
}

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
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
LocationsApi listLocations GET /v2/locations ListLocations
OrdersApi batchRetrieveOrders POST /v2/locations/{location_id}/orders/batch-retrieve BatchRetrieveOrders
OrdersApi createOrder POST /v2/locations/{location_id}/orders CreateOrder
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 Creates an employee for a business.
V1EmployeesApi createEmployeeRole POST /v1/me/roles Creates an employee role you can then assign to employees.
V1EmployeesApi createTimecard POST /v1/me/timecards Creates a timecard for an employee. Each timecard corresponds to a single shift.
V1EmployeesApi deleteTimecard DELETE /v1/me/timecards/{timecard_id} Deletes a timecard. Deleted timecards are still accessible from Connect API endpoints, but the value of their deleted field is set to true. See Handling deleted timecards for more information.
V1EmployeesApi listCashDrawerShifts GET /v1/{location_id}/cash-drawer-shifts Provides the details for all of a location's cash drawer shifts during a date range. The date range you specify cannot exceed 90 days.
V1EmployeesApi listEmployeeRoles GET /v1/me/roles Provides summary information for all of a business's employee roles.
V1EmployeesApi listEmployees GET /v1/me/employees Provides summary information for all of a business's employees.
V1EmployeesApi listTimecardEvents GET /v1/me/timecards/{timecard_id}/events Provides summary information for all events associated with a particular timecard.
V1EmployeesApi listTimecards GET /v1/me/timecards Provides summary information for all of a business's employee timecards.
V1EmployeesApi retrieveCashDrawerShift GET /v1/{location_id}/cash-drawer-shifts/{shift_id} Provides the details for a single cash drawer shift, including all events that occurred during the shift.
V1EmployeesApi retrieveEmployee GET /v1/me/employees/{employee_id} Provides the details for a single employee.
V1EmployeesApi retrieveEmployeeRole GET /v1/me/roles/{role_id} Provides the details for a single employee role.
V1EmployeesApi retrieveTimecard GET /v1/me/timecards/{timecard_id} Provides the details for a single timecard.
V1EmployeesApi updateEmployee PUT /v1/me/employees/{employee_id} V1 UpdateEmployee
V1EmployeesApi updateEmployeeRole PUT /v1/me/roles/{role_id} Modifies the details of an employee role.
V1EmployeesApi updateTimecard PUT /v1/me/timecards/{timecard_id} Modifies a timecard's details. This creates an API_EDIT event for the timecard. You can view a timecard's event history with the List Timecard Events endpoint.
V1ItemsApi adjustInventory POST /v1/{location_id}/inventory/{variation_id} Adjusts an item variation's current available inventory.
V1ItemsApi applyFee PUT /v1/{location_id}/items/{item_id}/fees/{fee_id} Associates a fee with an item, meaning the fee is automatically applied to the item in Square Register.
V1ItemsApi applyModifierList PUT /v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id} Associates a modifier list with an item, meaning modifier options from the list can be applied to the item.
V1ItemsApi createCategory POST /v1/{location_id}/categories Creates an item category.
V1ItemsApi createDiscount POST /v1/{location_id}/discounts Creates a discount.
V1ItemsApi createFee POST /v1/{location_id}/fees Creates a fee (tax).
V1ItemsApi createItem POST /v1/{location_id}/items Creates an item and at least one variation for it.
V1ItemsApi createModifierList POST /v1/{location_id}/modifier-lists Creates an item modifier list and at least one modifier option for it.
V1ItemsApi createModifierOption POST /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options Creates an item modifier option and adds it to a modifier list.
V1ItemsApi createPage POST /v1/{location_id}/pages Creates a Favorites page in Square Register.
V1ItemsApi createVariation POST /v1/{location_id}/items/{item_id}/variations Creates an item variation for an existing item.
V1ItemsApi deleteCategory DELETE /v1/{location_id}/categories/{category_id} Deletes an existing item category.
V1ItemsApi deleteDiscount DELETE /v1/{location_id}/discounts/{discount_id} Deletes an existing discount.
V1ItemsApi deleteFee DELETE /v1/{location_id}/fees/{fee_id} Deletes an existing fee (tax).
V1ItemsApi deleteItem DELETE /v1/{location_id}/items/{item_id} Deletes an existing item and all item variations associated with it.
V1ItemsApi deleteModifierList DELETE /v1/{location_id}/modifier-lists/{modifier_list_id} Deletes an existing item modifier list and all modifier options associated with it.
V1ItemsApi deleteModifierOption DELETE /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id} Deletes an existing item modifier option from a modifier list.
V1ItemsApi deletePage DELETE /v1/{location_id}/pages/{page_id} Deletes an existing Favorites page and all of its cells.
V1ItemsApi deletePageCell DELETE /v1/{location_id}/pages/{page_id}/cells Deletes a cell from a Favorites page in Square Register.
V1ItemsApi deleteVariation DELETE /v1/{location_id}/items/{item_id}/variations/{variation_id} Deletes an existing item variation from an item.
V1ItemsApi listCategories GET /v1/{location_id}/categories Lists all of a location's item categories.
V1ItemsApi listDiscounts GET /v1/{location_id}/discounts Lists all of a location's discounts.
V1ItemsApi listFees GET /v1/{location_id}/fees Lists all of a location's fees (taxes).
V1ItemsApi listInventory GET /v1/{location_id}/inventory Provides inventory information for all of a merchant's inventory-enabled item variations.
V1ItemsApi listItems GET /v1/{location_id}/items Provides summary information for all of a location's items.
V1ItemsApi listModifierLists GET /v1/{location_id}/modifier-lists Lists all of a location's modifier lists.
V1ItemsApi listPages GET /v1/{location_id}/pages Lists all of a location's Favorites pages in Square Register.
V1ItemsApi removeFee DELETE /v1/{location_id}/items/{item_id}/fees/{fee_id} Removes a fee assocation from an item, meaning the fee is no longer automatically applied to the item in Square Register.
V1ItemsApi removeModifierList DELETE /v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id} Removes a modifier list association from an item, meaning modifier options from the list can no longer be applied to the item.
V1ItemsApi retrieveItem GET /v1/{location_id}/items/{item_id} Provides the details for a single item, including associated modifier lists and fees.
V1ItemsApi retrieveModifierList GET /v1/{location_id}/modifier-lists/{modifier_list_id} Provides the details for a single modifier list.
V1ItemsApi updateCategory PUT /v1/{location_id}/categories/{category_id} Modifies the details of an existing item category.
V1ItemsApi updateDiscount PUT /v1/{location_id}/discounts/{discount_id} Modifies the details of an existing discount.
V1ItemsApi updateFee PUT /v1/{location_id}/fees/{fee_id} Modifies the details of an existing fee (tax).
V1ItemsApi updateItem PUT /v1/{location_id}/items/{item_id} Modifies the core details of an existing item.
V1ItemsApi updateModifierList PUT /v1/{location_id}/modifier-lists/{modifier_list_id} Modifies the details of an existing item modifier list.
V1ItemsApi updateModifierOption PUT /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id} Modifies the details of an existing item modifier option.
V1ItemsApi updatePage PUT /v1/{location_id}/pages/{page_id} Modifies the details of a Favorites page in Square Register.
V1ItemsApi updatePageCell PUT /v1/{location_id}/pages/{page_id}/cells Modifies a cell of a Favorites page in Square Register.
V1ItemsApi updateVariation PUT /v1/{location_id}/items/{item_id}/variations/{variation_id} Modifies the details of an existing item variation.
V1LocationsApi listLocations GET /v1/me/locations Provides details for a business's locations, including their IDs.
V1LocationsApi retrieveBusiness GET /v1/me Get a business's information.
V1TransactionsApi createRefund POST /v1/{location_id}/refunds Issues a refund for a previously processed payment. You must issue a refund within 60 days of the associated payment.
V1TransactionsApi listBankAccounts GET /v1/{location_id}/bank-accounts Provides non-confidential details for all of a location's associated bank accounts. This endpoint does not provide full bank account numbers, and there is no way to obtain a full bank account number with the Connect API.
V1TransactionsApi listOrders GET /v1/{location_id}/orders Provides summary information for a merchant's online store orders.
V1TransactionsApi listPayments GET /v1/{location_id}/payments Provides summary information for all payments taken by a merchant or any of the merchant's mobile staff during a date range. Date ranges cannot exceed one year in length. See Date ranges for details of inclusive and exclusive dates.
V1TransactionsApi listRefunds GET /v1/{location_id}/refunds Provides the details for all refunds initiated by a merchant or any of the merchant's mobile staff during a date range. Date ranges cannot exceed one year in length.
V1TransactionsApi listSettlements GET /v1/{location_id}/settlements Provides summary information for all deposits and withdrawals initiated by Square to a merchant's bank account during a date range. Date ranges cannot exceed one year in length.
V1TransactionsApi retrieveBankAccount GET /v1/{location_id}/bank-accounts/{bank_account_id} Provides non-confidential details for a merchant's associated bank account. This endpoint does not provide full bank account numbers, and there is no way to obtain a full bank account number with the Connect API.
V1TransactionsApi retrieveOrder GET /v1/{location_id}/orders/{order_id} Provides comprehensive information for a single online store order, including the order's history.
V1TransactionsApi retrievePayment GET /v1/{location_id}/payments/{payment_id} Provides comprehensive information for a single payment.
V1TransactionsApi retrieveSettlement GET /v1/{location_id}/settlements/{settlement_id} Provides comprehensive information for a single settlement, including the entries that contribute to the settlement's total.
V1TransactionsApi updateOrder PUT /v1/{location_id}/orders/{order_id} Updates the details of an online store order. Every update you perform on an order corresponds to one of three actions:

Documentation For Models

Documentation For Authorization

oauth2

  • Type: OAuth
  • Flow: accessCode
  • Authorization URL: https://connect.squareup.com/oauth2/authorize
  • Scopes:
  • MERCHANT_PROFILE_READ: GET endpoints related to a merchant's business and location entities. Almost all Connect API applications need this permission in order to obtain a merchant's location IDs
  • PAYMENTS_READ: GET endpoints related to transactions and refunds
  • PAYMENTS_WRITE: POST, PUT, and DELETE endpoints related to transactions and refunds. E-commerce applications must request this permission
  • CUSTOMERS_READ: GET endpoints related to customer management
  • CUSTOMERS_WRITE: POST, PUT, and DELETE endpoints related to customer management
  • SETTLEMENTS_READ: GET endpoints related to settlements (deposits)
  • BANK_ACCOUNTS_READ: GET endpoints related to a merchant's bank accounts
  • ITEMS_READ: GET endpoints related to a merchant's item library
  • ITEMS_WRITE: POST, PUT, and DELETE endpoints related to a merchant's item library
  • ORDERS_READ: GET endpoints related to a merchant's orders
  • ORDERS_WRITE: POST, PUT, and DELETE endpoints related to a merchant's orders
  • EMPLOYEES_READ: GET endpoints related to employee management
  • EMPLOYEES_WRITE: POST, PUT, and DELETE endpoints related to employee management
  • TIMECARDS_READ: GET endpoints related to employee timecards
  • TIMECARDS_WRITE: POST, PUT, and DELETE endpoints related to employee timecards
  • PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS: Allow third party applications to deduct a portion of each transaction amount.

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.

About

PHP client library for the Square Connect APIs

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • PHP 100.0%