mage2pro / square-php-sdk
PHP client library for the Square Connect v2 API
Requires
- php: >=5.3.3
- ext-curl: *
- ext-json: *
- ext-mbstring: *
Requires (Dev)
- phpunit/phpunit: ~4.0
- satooshi/php-coveralls: ~0.6.1
- squizlabs/php_codesniffer: ~2.0
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
: Theid
of the customer you want to retrieve. Use the->getId()
fuction on a customer object to thecustomer_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
: Theid
of the customer you want to update. Use the->getId()
fuction on a customer object to thecustomer_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
: Theid
of the customer you want to retrieve. Use the->getId()
fuction on a customer object to thecustomer_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
: Theid
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
: Theid
of the customer whose card you want to delete.$card_id
: Theid
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
: Theid
of the transaction you want to retrieve. Use the->getId()
fuction on a transaction object to get thetransaction_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
: Theid
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
: Theid
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
: Theid
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.