Settlement model
- Rakesh Kumar Jena
- Rakesh Jena (Unlicensed)
Details on Groovs model to help you understand the data and how to maximise the integration benefits
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. |
Access our Swagger documentation here
On this page: