Reporting API Guide
Read information about multiparty transactions processed with the Transactions API.
This document provides guidance for working with the Reporting API.
Requirements and limitations
- The Reporting API only supports multiparty transaction reporting.
- The Reporting API is not supported in sandbox.
This guide makes the following assumptions:
How to use it — Reporting API data model
Square accounts that receive payment as part of a multiparty transaction can use the Reporting API to request information on credits (receivables) and debits (refunds). For example, consider a hosting platform that charges a fee to process eCommerce payments on behalf of merchants. The platform owner can use the Reporting API to pull information on the receivables and refunds processed (across all merchants) in the last month.
Credits from multiparty transactions are modeled as
AdditionalRecipientReceivable objects. Debits from multiparty
refunds are modeled as
To maintain the privacy and security of the owner of the original transaction,
AdditionalRecipient objects only
contain a subset of the information normally available in a transaction object:
- The originating transaction ID.
- The location ID credited with the originating transaction.
- The distribution amount credited to the additional recipient.
- A list of additional recipient refunds related to the original transaction.
The originating transaction information is provided for reference. But applications cannot use the originating
transaction information to read additional details without explicitly granted
PAYMENT_READ permission for the account
that owns the transaction information.
How it works — Reporting API process flow
Multiparty transactions credit portions of a transaction's net profit to the application that creates and processes the transaction.
The Reporting API lets account owners pull information related to multiparty transactions outside the normal transaction process flow.
Reporting API Setup
Step 1: Create and configure the API client
To create the API client, you need to set your authorization token and the application location ID you want information from.
1// Include the Square Connect API resources 2require_once '/local/path/to/sdk/SquareConnect/autoload.php'; 3 4$authzToken = "YOUR_AUTHZ_TOKEN"; // set/load your authorization token 5$locationId = "YOUR_LOCATION_ID"; // set/load your location ID 6 7// Create and configure a new API client object 8$defaultApiConfig = new \SquareConnect\Configuration(); 9$defaultApiConfig->setAccessToken($authzToken); 10$defaultApiClient = new \SquareConnect\ApiClient($defaultApiConfig) ;
Next, create your Reporting API client.
// Create a ReportingApi client to report on multiparty transactions $reportingApi = new SquareConnect\Api\ReportingApi($defaultApiClient);
Step 2: Set the filtering criteria
The Reporting API returns multiparty transaction information for a specific ocation and date range. Specify dates in UTC date-time format.
// Set the date range for the multiparty transaction report $beginTime = '2016-01-15T00:00:00Z'; $endTime = '2016-01-31T00:00:00Z';
Step 3: List credits
Use the ListAdditionalRecipientReceivables endpoint to list all credits (receivables) to your location as part of a multiparty transaction.
$apiResponse = $reportingApi->listAdditionalRecipientReceivables( $locationId, $beginTime, $endTime );
Step 4: List refunds
Use the ListAdditionalRecipientReceivableRefunds endpoint to list debits (refunds) from your location as part of a multiparty transaction.
$apiResponse = $reportingApi->listAdditionalRecipientReceivableRefunds( $locationId, $beginTime, $endTime );