Details on Groov's model to help you understand the insights entity and how to maximise the integration benefits
A settlement object represents the funding/payout a seller (account ledger) receives from their commerce/payment partner/provider, based on either an automated payout schedule or a manual orchestration, depending on the sellers county/industry setup with its commerce/payment partner provider. Further details of the object can be found in Settlement model page.
Settlement data dictionary
What is a Settlement object on Groov platform?
A settlement object represents the funding/payout a seller (account ledger) receives from their commerce/payment partner/provider, based on either an automated payout schedule or a manual orchestration, depending on the sellers county/industry setup with its commerce/payment partner provider. Further details of the object can be found in Settlement model page.
Context of Settlement Summary insights resource
What does Settlement Summary insights resource on Groov platform provide?
Settlement summary insights resource provides an easy way to get an aggregated/rolled up view of a seller's (account ledger) payout/funding received from its commerce/payment partner/provider. You will be able to- slice and dice the settlement summary amounts via a Daily, Monthly or Yearly timeline view
- query by Groovs ledger account identifier or your internal system/platform identifier
- define a milestone date that acts as your reference point to run your query on.
- query on how long in the past you want to go wrt either daily, monthly or yearly snapshots
- view rolled-up insights for a particular account (eg: MID - Merchant ID in case of commerce/payment accounts)
- view rolled up insights across one or more commerce/payment partner/provider accounts.
Insights Dictionary
Query Model
| Attribute | Type | Required/Optional | enum | Description |
|---|---|---|---|---|
| institutionAccountId | string | Required (Conditional) | the Institution record identifer for which the summary/rolled up insights/merics is requested. This OR the ledgerAccountId will be mandatory | |
| ledgerAccountId | string | Required (Conditional) | the Groov record identifier for which the summary/rolled up insights/metrics is requested. This OR the institutionAccountId will be mandatory | |
| partnerSource | array[string] (query) | Optional | <name of partner sources that Groov supports> | name of the partner system(s) for which you want the insights. This will be an enum list provided by Groov. Leaving this blank will fetch the results for all partners that the ledgerAccount has settlement for. |
| metricUnit | string | Required | daily monthly yearly | defines the unit by which the summary insights need to be aggregated |
| metricLength | Integer | Required | defines the length of the units across which the summary insights need to be aggregated. If metricLength is day, a max of 90 is honoured for metricLength | |
| metricReferenceDate | date | Optional | indicates the reference date to use to drive the summary reporting across metricLength and metricUnit. If no date is passed, sys_date is used | |
| sort | array[string] (query) | Optional | Sorting criteria in the format: property(:asc | desc). Multiple sort criteria are supported. By default is: 'sort=metricGeneratedDate:desc' |
Insights response data construct
| Attribute | Type | Description |
|---|---|---|
| institutionAccountId | string | the Institution record identifier for which the summary/rolled up insights/metrics is requested. This will be as provided in the request parameter |
| ledgerAccountId | string | the Groov record identifier for which the summary has been provided. This will be as provided in the request parameter |
| metricGeneratedDate | date | Date on which the Insights metric as requested was generated |
| metricReferenceDate | date | indicates the reference date that has been used to drive the summary reporting across metricLength and metricUnit. If no date was provided in the request parameter, the default sys_date is used |
| metricSummaryByPartnerList | list | Lists the settlement metrics aggregated by Partner (PSPs/Payment Providers/ Commerce Account Providers) |
| object | string | String representing the object’s type. Objects of the same type share the same value. Value is "list" |
| data | array of hashes | The list of all aggregated settlement grouped by partners |
| partnerSource | string | name of the partner system |
| settlementSummaryList | list | Lists the settlement metrics that have been aggregated across a period of time |
| object | string | String representing the object’s type. Objects of the same type share the same value. Value is "list" |
| data | array of hashes | The list of all aggregated settlement amounts |
| partnerAccountId | string | This will be the account Id (for Payment partners will be MID for example) as maintained on the Partner system against which the funds are settled by the partner |
| metricUnit | string | defines the unit by which the summary insights need to be aggregated. This is as provided in the request parameter |
| date | string | DDMMYYYY: // ISO-8601 format only provided in response if metricUnit is day |
| month | string | MM: Two-digit month (01 = January, and so on) // ISO-8601 format only provided in response if metricUnit is day or month |
| year | string | YYYY: Four-digit year // ISO-8601 format |
| countTransactions | integer | This provides an aggregated count of all types of relate transactions that form the settlement total. |
| amount | integer | aggregated/summarised settlement amount (in pence) across the aggregated time period that has been paid out to the merchants/ledgers funding account i.e has been settled with the merchant/ledger |
| currency | currency | Three-letter ISO currency code representing the default currency in which the settlement amount value was aggregated |
Access our Swagger documentation here
On this page: