README

This repository contains a generated PHP client SDK for the Square Connect APIs v2. 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

PHP >= 5.4.0
A Square account and developer application (for authorization)

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.

Usage

There are five main objects that you'll be using, depending on what you want to do, each one is explained in more detail below.

<?php
$transaction_api = new \SquareConnect\Api\TransactionApi();
$customerCard_api = new \SquareConnect\Api\CustomerCardApi();
$customer_api = new \SquareConnect\Api\CustomerApi();
$location_api = new \SquareConnect\Api\LocationApi();
$refund_api = new \SquareConnect\Api\RefundApi();
?>

Locations

You'll need to list locations for your square account before doing most API calls because the location_id is a in the url for most endpoints.

$location_api = new \SquareConnect\Api\LocationApi();

List Locations

$location_api->listLocations($authorization);

$authorization : Your access token (sandbox, personal, or OAuth)

Response: \SquareConnect\Model\ListLocationsResponse

$location_api->listLocations($authorization)->getErrors();
$location_api->listLocations($authorization)->getLocations();

See all the functions you can use with the ->getLocations() response in the location model

Customers

Customers are end-users of a business and can be associated with transactions.

$customer_api = new \SquareConnect\Api\CustomerApi();

List Customers

$customer_api->listCustomers($authorization, $cursor = null);

$authorization : Your access token (sandbox, personal, or OAuth)
$cursor : This is an optional argument that specifies which page of customers to retrieve. Learn more about pagination here.

Response: \SquareConnect\Model\ListCustomersResponse

$customer_api->listCustomers($authorization)->getErrors();
$customer_api->listCustomers($authorization)->getCustomers();
$customer_api->listCustomers($authorization)->getCursor();

See all the functions you can use with the ->getCustomers() response in the customer model.

Create Customer

$customer_api->createCustomer($authorization, $body);

$authorization : Your access token (sandbox, personal, or OAuth)
$body : The body is a SquareConnect\Model\CreateCustomerRequest object that you'll have to build with the information of your customer.

Response: \SquareConnect\Model\CreateCustomersResponse

$customer_api->createCustomer($authorization, $body)->getErrors();
$customer_api->createCustomer($authorization, $body)->getCustomer();

See all the functions you can use with the ->getCustomer() response in the customer model.

Retrieve Customer

$customer_api->retrieveCustomer($authorization, $customer_id);

$authorization : Your access token (sandbox, personal, or OAuth)
$customer_id : The id of the customer you want to retrieve. Use the ->getId() fuction on a customer object to the customer_id of a retrieved customer.

Response: \SquareConnect\Model\RetrieveCustomerResponse

$customer_api->retrieveCustomer($authorization, $customer_id)->getErrors();
$customer_api->retrieveCustomer($authorization, $customer_id)->getCustomer();

See all the functions you can use with the ->getCustomer() response in the customer model. Update Customer

$customer_api->updateCustomer($authorization, $customer_id, $body)

$authorization : Your access token (sandbox, personal, or OAuth)
$customer_id : The id of the customer you want to update. Use the ->getId() fuction on a customer object to the customer_id of a retrieved customer.
$body : The body is a SquareConnect\Model\UpdateCustomerRequest object that you'll have to build with the information of your customer.

Response: \SquareConnect\Model\UpdateCustomerResponse

$customer_api->updateCustomer($authorization, $customer_id, $body)->getErrors();
$customer_api->updateCustomer($authorization, $customer_id, $body)->getCustomer();

See all the functions you can use with the ->getCustomer() response in the customer model

Delete Customer

$customer_api->deleteCustomer($authorization, $customer_id)

$authorization : Your access token (sandbox, personal, or OAuth)
$customer_id : The id of the customer you want to retrieve. Use the ->getId() fuction on a customer object to the customer_id of a retrieved customer.

Response: \SquareConnect\Model\DeleteCustomerResponse

$customer_api->deleteCustomer($authorization, $customer_id)->getErrors();

Customers Cards

Customers Cards on file allow merchants to charge customers without them providing their credit card every time. Learn more here: Saving Customer Information

$customerCard_api = new \SquareConnect\Api\CustomerCardApi();

Create Customer Card

$customerCard_api->createCustomerCard($authorization, $customer_id, $body);

$authorization : Your access token (sandbox, personal, or OAuth)
$customer_id : The id of the customer you want to associate the card with.
$body : The body is a SquareConnect\Model\CreateCustomerCardRequest object that you'll have to build with the information of your customer's card.

Response: \SquareConnect\Model\CreateCustomerCardResponse

$customerCard_api->createCustomerCard($authorization, $customer_id, $body)->getErrors();
$customerCard_api->createCustomerCard($authorization, $customer_id, $body)->getCard();

See all the functions you can use with the ->getCard() response in the card model

Delete Customer Card

$customerCard_api->deleteCustomerCard($authorization, $customer_id, $card_id)

$authorization : Your access token (sandbox, personal, or OAuth)
$customer_id : The id of the customer whose card you want to delete.
$card_id : The id of the card you want to delete.

Response: \SquareConnect\Model\DeleteCustomerCardResponse

$customerCard_api->deleteCustomerCard($authorization, $customer_id, $card_id)->getErrors();

Transactions

$transaction_api = new \SquareConnect\Api\TransactionApi();

List Transactions

$transaction_api->listTransactions($authorization, $location_id, $begin_time = null, $end_time = null, $sort_order = null, $cursor = null)

$authorization : Your access token (sandbox, oauth or personal)
$location_id : The id of the location you are requesting the transactions for.
$begin_time : The beginning of the requested reporting period, in RFC 3339 format. (optional)
$end_time The end of the requested reporting period, in RFC 3339 format. (optional)
$sort_order The order in which results are listed in the response (ASC for chronological, DESC for reverse-chronological). (optional)
$cursor : An optional pagination cursor to retrieve the next set of results for your original query to the endpoint. Learn more about pagination here.

Response: \SquareConnect\Model\ListTransactionsResponse

$transaction_api->listTransactions($authorization, $location_id)->getErrors();
$transaction_api->listTransactions($authorization, $location_id)->getTransactions();
$transaction_api->listTransactions($authorization, $location_id)->getCursor();

See all the functions you can use with the ->getTransactions() response in the transaction model

Charge (Create Transaction)

$transaction_api->charge($authorization, $location_id, $body);

$authorization : Your access token (sandbox, personal, or OAuth)
$location_id : The id of the location you are creating the transactions for.
$body : The body is a SquareConnect\Model\ChargeRequest object that you'll have to build with the information of your transaction.

Response: \SquareConnect\Model\ChargeResponse

$transaction_api->charge($authorization, $location_id, $body)->getErrors();
$transaction_api->charge($authorization, $location_id, $body)->getTransaction();

See all the functions you can use with the ->getTransactions() response in the transaction model

Retrieve Transaction

$transaction_api->retrieveTransaction($authorization, $location_id, $transaction_id);

$authorization : Your access token (sandbox, personal, or OAuth)
$location_id : The id of the location you are retrieving the transaction for.
$transaction_id : The id of the transaction you want to retrieve. Use the ->getId() fuction on a transaction object to get the transaction_id

Response: \SquareConnect\Model\RetrieveTransactionResponse

$transaction_api->retrieveTransaction($authorization, $location_id, $transaction_id)->getErrors();
$transaction_api->retrieveTransaction($authorization, $location_id, $transaction_id)->getTransaction();

See all the functions you can use with the ->getTransactions() response in the transaction model

Capture Transaction Charges a card that was previously authorized. See delayed capture transactions for more information.

$transaction_api->captureTransaction($authorization, $location_id, $transaction_id);

$authorization : Your access token (sandbox, personal, or OAuth)
$location_id : The id of the location you are retrieving the transaction for.
$transaction_id : The id of the previously authorized transaction you want to capture.

Response: \SquareConnect\Model\CaptureTransactionResponse

$transaction_api->captureTransaction($authorization, $location_id, $transaction_id)->getErrors();

Void Transaction Voids a previous card authorization. See delayed capture transactions for more information.

$transaction_api->voidTransaction($authorization, $location_id, $transaction_id);

$authorization : Your access token (sandbox, personal, or OAuth)
$location_id : The id of the location you are retrieving the transaction for.
$transaction_id : The id of the previously authorized transaction you want to void.

Response: \SquareConnect\Model\VoidTransactionResponse

$transaction_api->voidTransaction($authorization, $location_id, $transaction_id)->getErrors();

Refunds

$refund_api = new \SquareConnect\Api\RefundApi();

List Refunds

$refund_api->listRefunds($authorization, $location_id, $begin_time = null, $end_time = null, $sort_order = null, $cursor = null)

$authorization : Your access token (sandbox, oauth or personal)
$location_id : The id of the location you are requesting the refunds for.
$begin_time : The beginning of the requested reporting period, in RFC 3339 format. (optional)
$end_time The end of the requested reporting period, in RFC 3339 format. (optional)
$sort_order The order in which results are listed in the response (ASC for chronological, DESC for reverse-chronological). (optional)
$cursor : An optional pagination cursor to retrieve the next set of results for your original query to the endpoint. Learn more about pagination here.

Response: \SquareConnect\Model\ListRefundsResponse

$refund_api->listRefunds($authorization, $location_id)->getErrors();
$refund_api->listRefunds($authorization, $location_id)->getCursor();

Create Refund

$refund_api->createRefund($authorization, $location_id, $transaction_id, $body)

$authorization : Your access token (sandbox, oauth or personal)
$location_id : The id of the location you are requesting the refunds for.
$transaction_id : The id of the previously charged transaction you want to refund.
$body : The body is a SquareConnect\Model\CreateRefundRequest object that you'll have to build with the information of your refund.

Response: \SquareConnect\Model\CreateRefundResponse

$refund_api->deleteCustomer($authorization, $customer_id)->getErrors();
$refund_api->deleteCustomer($authorization, $customer_id)->getRefund();

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

mage2pro / square-php-sdk

Maintainers

Details

README

Requirements

Installing

With Composer

From GitHub

Usage

Locations

Customers

Customers Cards

Transactions

Refunds

Contributing

License