Settlement model

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. A settlement is always associated with atleast one transaction (and a payment object record as a minimum). In a normal context a settlement record will be made up of an aggregated set of transactions entries accrued by the seller across a period of time (normally a day if its a daily payout/settlement, so its related to the setup frequency with its provider). The settlement will take into account any revenue generated across a period of time and will deduct any fees/charges/outstanding collections to arrive at the aggregated funding amount that forms part of that settlement. This can be derived by querying the 'Related transactions' attribute set in the settlement object as defined below

Every payout will have an associated external account (normally a Bank account of the seller) where the funds get paid out to. The details of the external account can be retrieved by querying on the funding account attribute in the settlement object as detailed below. if it is a Bank account, this would directly map to a bank statement record on the sellers bank account.

Data Dictionary


Attribute	Type	Description
object	string	value is "settlement"
id	string	identifier of the settlement record on Groov platform
partnerSource	string	name of the partner system
ledgerAccountid	string	id of the merchant account ledger entry as setup on Groov platform.
amount	integer	amount (in pence) to be paid out to the merchants funding account
currency	currency	Three-letter ISO currency code representing the default currency in which the settlement record was created/initiated
transaction	string	identifier of the transaction record on Groov platform that reflects this settlement amount Expansion is enabled for this attribute
relatedtransactions	list	Lists the transactions that have been aggregate to arrive at the settlement amount. Expansion is enabled for this attribute
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 transactions that make up the settlement object and account for the aggregated settlement amount as maintained on different partner sources
id	string	identifier of the transaction record on Groov platform
source_id	string	identifier of the transaction as recorded on partner source system
category	string	transaction category values
gross_amount	integer	Gross value of transaction in pence
currency	currency	Three-letter ISO currency code representing the default currency in which the payment record was captured
fee	integer	Fees paid for transaction based on transaction type (in pence)
net_amount	integer	Net amount for this transaction, in pence
created_date	timestamp	Date the payment was created in the commerce or partner platform
statement_narrative	string	the narrative displayed on the merchants funding account statement as provided by the partner platform
funding_account	string	identifier of the funding account of the merchant the settlement was made to. Query using the identifier on the external account (Bank Account) object toretrieve details of the account
status	string	Reflects the status of the settlement that’s to be paid out or paid out to the merchat funding account. Status values as enums will be: pending - settlement not yet initiated in_progress - settlement initiated to funding account but not yet credited settled - settlement amount paid to merchant funding account failed - settlement failed cancelled - settlement cancelled
scheduled	boolean	Returns true if the settlement was created by an automated payout schedule on the partner platform, and false if it was requested manually. Values: true or false
method	string	Indicates the method used to initiate the settlement from the partner platform. Values: standard instant
related_original_settlement	string	lists the original Groov platform settlement id if the current settlement reverses another previous one. To limit the number of calls to the API, and the size of the responses, our REST API to support the expansion of this
related_reversedby_settlement	string	If the settlement was reversed, this is the Groov platform ID of the settlement that reverses this record. To limit the number of calls to the API, and the size of the responses, our REST API to support the expansion of this
related_settlement_exception_transaction	string	lists the Groov platform's transaction ID that would have been created as a result of the failed or cancelled settlement To limit the number of calls to the API, and the size of the responses, our REST API to support the expansion of this
settlement_exception_code	string	The code that indicates the exact reason a settlement record went into exception (failed or cancelled). The possible values could be: account_closed - The bank account has been closed. account_frozen -The bank account has been frozen. bank_account_restricted - The bank account has restrictions on either the type, or the number, of payouts allowed. This normally indicates that the bank account is a savings or other non-checking account. bank_ownership_changed - The destination bank account is no longer valid because its branch has changed ownership. could_not_process - The bank could not process this payout. debit_not_authorized - Debit transactions are not approved on the bank account declined - The bank has declined this transfer. insufficient_funds - Your payment provider account has insufficient funds to cover the payout. invalid_account_number - The routing number seems correct, but the account number is invalid. incorrect_account_holder_name - Funding bank notified merchants payment provider that the bank account holder name on file is incorrect. incorrect_account_holder_address - Funding bank notified merchants payment provider that the bank account holder address on file is incorrect. incorrect_account_holder_tax_id - Funding bank notified merchants payment provider that the bank account holder tax ID on file is incorrect. invalid_currency - The bank was unable to process this payout because of its currency. This is probably because the bank account cannot accept payments in that currency. no_account - The bank account details on file are probably incorrect. No bank account could be located with those details. unsupported_card - The bank no longer supports payouts to this card. other_reason - Any other reason thats not known at this point in time.
environment_mode	string	This relates to the partner platforms environment connection type. values: test or live
live_connection	string	This is the Groov platforms connection environment type, will be test if it’s a sandbox mode or will be live if its Production mode. Can be controlled via Groov dashboard/Portal or can be called via unfieid API values: test or live
funds_available_date	timestamp	a likely date the settlement amount will be available in the merchants funding account
created_date	timestamp	Date the settlement was created in the commerce or partner platform
modifiedDate	date	Date the record was last updated in the our system.