# Get settlements for a merchant

This endpoint allows you to retrieve BECs-cleared settlement details for a specific merchant on a given date.

Endpoint: GET /reporting/merchants/{mid}/settlements?settlementDate={settlementDate}
Version: 1.0
Security: JWT

## Path parameters:

  - `mid` (string, required)
    The merchant ID associated with the Tyro account. Used to identify the merchant whose settlement data is being retrieved.

## Query parameters:

  - `settlementDate` (string, required)
    Requested settlement date (YYYY-MM-DD). Must be within the past 3 years.

## Header parameters:

  - `Authorization` (string, required)

## Response 200 fields (application/json):

  - `mid` (string, required)
    The merchant ID associated with the Tyro account. Used to identify the merchant whose settlement data is being retrieved.

  - `settlementDate` (string, required)
    Requested settlement date (YYYY-MM-DD). Must be within the past 3 years.

  - `settlements` (array, required)
    List of settlements for the specified merchant on the given date. If the array is empty, it may indicate that the merchant does not settle via BECS, or no settlement occurred on that date.

  - `settlements.clearingPaymentId` (string)
    ID of the clearing payment run used to bundle transactions for a settlement.

  - `settlements.grossAmount` (number)
    Signed gross amount settled, in cents.
    Example: 10001

  - `settlements.settlementDetails` (array, required)
    Multiple settlement entries may be returned due to settlement splits by scheme, by location, or due to additional settlement destinations such as loan repayments or ATO garnishees.

  - `settlements.settlementDetails.type` (string, required)
    Settlement type indicating the destination account for the payment or transfer. More values may be added in the future.
    Enum: "EXTERNAL_BANK_ACCOUNT", "ATO", "TYRO_TRANSACTION_ACCOUNT", "TYRO_BANK_ACCOUNT", "LOAN"

  - `settlements.settlementDetails.institutionName` (string)
    Name of the institution receiving the settlement.

  - `settlements.settlementDetails.bsb` (string)
    BSB code in the format 'XXXXXX'.
    Example: "123456"

  - `settlements.settlementDetails.accountNumber` (string)
    Account number of the settlement destination, partially masked.
    Example: "*****7890"

  - `settlements.settlementDetails.accountName` (string)
    Name associated with the settlement destination account.

  - `settlements.settlementDetails.settlementAmount` (number)
    Signed amount settled, in cents.
    Example: -10001

  - `settlements.settlementDetails.lastUpdatedAt` (string)
    Indicates the time of the latest settlement status update. The format of the date time is the notation as defined by [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6)
    Example: "2023-10-01T12:00:00.00Z"

  - `settlements.settlementDetails.settlementStatus` (string)
    Status of the settlement.
  * SENT - The settlement has been successfully sent from Tyro to the merchant’s destination financial institution. Note: The actual deposit time into the merchant’s account is determined by their bank and is not known by Tyro.
  * PENDING - The settlement process has been initiated by Tyro, but funds have not yet left Tyro’s systems.
  * ON_HOLD - The settlement is currently withheld. This may occur due to account suspension, suspected fraud, or participation in a net settlement arrangement. Funds are retained by Tyro until resolution.
  * RESUBMISSION_INITIATED - The settlement got returned back by customer's bank and Tyro initiated its resubmission.
  * RESUBMISSION_SENT - The settlement got returned back by customer's bank and resubmission was successfully sent from Tyro.
  * RESUBMISSION_ON_HOLD - The settlement got returned back by customer's bank and resubmission is on hold and funds are withheld by Tyro.
  * WITHHELD_BY_ACQUIRER - The settlement failed and funds are withheld by Tyro.
  * WITHHELD_BY_BANK - The settlement failed and funds are withheld by the customer's bank.
    Enum: "SENT", "PENDING", "ON_HOLD", "RESUBMISSION_INITIATED", "RESUBMISSION_SENT", "RESUBMISSION_ON_HOLD", "WITHHELD_BY_ACQUIRER", "WITHHELD_BY_BANK"

  - `settlements.settlementDetails.lodgementReference` (string)
    Lodgement reference provided with the settlement to the receiving institution, up to 18 characters.

## Response 400 fields (application/json):

  - `error` (string)

  - `errorCode` (string)

  - `errors` (array)

  - `message` (string)

## Response 403 fields (application/json):

  - `error` (string)