Take Payments

Reporting API Guide

Read information about multiparty transactions processed with the Transactions API.

This document provides guidance for working with the Reporting API.

Server Side
Languages Supported
Additional Resources

Requirements and limitations

  • The Reporting API only supports multiparty transaction reporting.
  • The Reporting API is not supported in sandbox.

Assumptions

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

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.

Process flow

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
               );
Prev
< Transactions API Overview
Next
Reporting API Technical Reference >

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow