> ## Documentation Index > Fetch the complete documentation index at: https://docs.rinne.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Contract effects > How to list the guarantees, fiduciary assignments and ownership transfers creditors registered against your card receivables, and use them to explain a settlement that looks late or short A contract effect is a contract a creditor (a bank, a fund, a lender) registered at the receivables registrars against a merchant's future card receivables: a guarantee, a fiduciary assignment, an ownership transfer. While it is in force, part or all of what the merchant would receive on a settlement date goes to the creditor instead. Listing the effects lets you explain a settlement that looks late or short by a contract, instead of chasing it as a missing payment. Two endpoints return them: * [`GET /v1/receivables/contract-effects`](/api-reference/company-receivables/list-contract-effects-on-your-receivables): the effects on your own company's document. * [`GET /v1/merchants/receivables/contract-effects`](/api-reference/receivables/list-contract-effects-on-your-merchants-receivables): for an organization, the effects on its merchants' documents. > [!NOTE] > > Contract effects are **informational copies** of what the registrars report. Rinne never applies them to your balance, your ledger or your transactions: they explain a settlement, they do not change it. What you actually receive is still what the [settlement](/concepts/settlement-items) shows. ## How contract effects reach you ```mermaid theme={null} graph LR accTitle: How contract effects reach you accDescr: A creditor registers a contract at a registrar. Rinne refreshes its copy from a daily snapshot of active effects. You list the effects and compare them with pending settlements. R[Creditor registers a contract at a registrar] --> S[Daily snapshot of active effects] S --> C[Rinne refreshes its copy] C --> A[You list the effects] A --> M[You compare them with pending settlements] style R fill:#7B89FF,color:#fff style S fill:#5B68EB,color:#fff style C fill:#4A56D9,color:#fff style A fill:#5B68EB,color:#fff style M fill:#7B89FF,color:#fff ``` 1. A creditor registers a contract against the merchant's card receivables at a registrar. Neither Rinne nor the merchant creates it through Rinne, and Rinne does not change or cancel it. 2. Once a day, Rinne receives a snapshot of every contract effect active on its merchants and refreshes its copy: new effects appear, changed ones are updated, and the ones the snapshot no longer reports become `CANCELLED`. 3. You list the effects with one of the two endpoints. 4. You compare each effect's `expected_settlement_date`, `effect_type` and value with the settlements you are waiting for. A settlement due on a date an `ACTIVE` effect covers may be paid, in part or in full, to the effect's beneficiary instead of to the merchant. ## What to know before you reconcile > [!NOTE] > > **Effects are keyed by merchant document.** A contract is registered on a CNPJ or CPF, not on a merchant. An effect on a document applies to every merchant (company) with that document under the organization, and the API returns it once, not once per merchant. That is why there is no per-merchant endpoint: filter by `merchant_document` instead. > [!NOTE] > > **Effects are not linked to a receivable unit or a transaction.** The registrars do not say which sales a contract consumes, so an effect carries no transaction ID and no receivable-unit ID. Matching an effect to a specific sale is an inference you make from the document, the settlement date and the value. > [!NOTE] > > **Effects are never applied to balances.** They are copies of what the registrars report, kept for reference. A balance, a ledger entry or a settlement item never changes because an effect was created, updated or cancelled. > [!WARNING] > > **Effects are only as fresh as the last snapshot.** A contract registered or cancelled after the latest snapshot shows up in the next one. Before you conclude that no effect covers a settlement, check the snapshot dates as described in [Snapshot freshness](#snapshot-freshness). > [!NOTE] > > **The list returns `ACTIVE` effects by default.** Effects that have been lifted are `CANCELLED`; ask for them with `status=CANCELLED`, or for both with `status=ACTIVE,CANCELLED`. ## Effect types `effect_type` uses the registrars' vocabulary: | `effect_type` | Meaning | | - | - | | `OWNERSHIP_TRANSFER` | The receivables were assigned to the beneficiary: the settlement is theirs. | | `GUARANTEE` | The receivables back a loan or credit line: while the guarantee is in force, the covered value of the settlement is paid to the beneficiary. | | `GUARANTEE_PLEDGE` | A guarantee by pledge (*penhor*) of the receivables. | | `GUARANTEE_FIDUCIARY_ASSIGNMENT` | A guarantee by fiduciary assignment (*cessão fiduciária*) of the receivables. | | `JUDICIAL_SEIZURE` | A court order seized the receivables. | | `FINANCIAL_RESERVE` | Receivables held as a reserve for the creditor. | | `CESSION_PROMISE` | A registered promise to assign the receivables. | Each effect covers one settlement date. A contract that covers several dates appears once per date, with the same `external_contract_id`. When several effects fall on the same date, `effect_priority` gives their place in the settlement order, starting at `0`. ## Division method `division_method` says which field carries the effect's value; the other one is `null`: | `division_method` | Field | Example | | - | - | - | | `FIXED_AMOUNT` | `effect_amount`, in cents | `150000` | | `PERCENTAGE` | `effect_percentage`, from 0 to 100 with two decimals | `12.5` | An `effect_amount` of `150000` is R\$ 1,500.00 of that date's settlement; an `effect_percentage` of `100` is the whole settlement and `12.5` is an eighth of it. Whatever the method, `committed_effect_amount` is the part of the effect already committed against the settlement, in cents. ## Statuses | Status | Meaning | | - | - | | `ACTIVE` | The latest snapshot reported the effect. Settlements on `expected_settlement_date` may be diverted to the beneficiary. | | `CANCELLED` | A later snapshot no longer reported the effect: the contract was cancelled, settled or ended at the registrar. The snapshot does not say which. | An effect moves from `ACTIVE` to `CANCELLED` when a snapshot stops reporting it, and back to `ACTIVE` if a later snapshot reports it again. `cancelled_at` is when Rinne recorded the cancellation, and is `null` while the effect is `ACTIVE`. A past `expected_settlement_date` does not cancel an effect: it stays `ACTIVE` for as long as the snapshots keep reporting it. When an `ACTIVE` effect explains a settlement, the conversation about the contract is with its beneficiary, not with Rinne. A `CANCELLED` effect needs no action; keep it as history when you reconcile a settlement from the period when the effect was active. ## Snapshot freshness Two dates tell you how current the data is: * **`latest_snapshot_date`**, at the top level of every list response: the date of the latest snapshot Rinne received. It is `null` before the first snapshot, and then the list is empty. * **`last_snapshot_date`**, on each effect: the latest snapshot that reported that effect. Read them together: * When `latest_snapshot_date` is older than you expect, every effect in the list is that old too. A contract registered since then is not listed yet; compare `latest_snapshot_date` with today's date before you conclude that no effect exists. * On an `ACTIVE` effect, `last_snapshot_date` is normally the same date as `latest_snapshot_date`. On a `CANCELLED` effect it is earlier: it is the last snapshot that still reported the effect before it was lifted. ## List your own contract effects `GET /v1/receivables/contract-effects` returns the effects on the authenticated company's own document, under its organization: the parent organization for a merchant, the organization itself for an organization. Requires the `receivable.list` permission. The scope comes from your API key and cannot be widened from the query string: the endpoint accepts no `merchant_document` or organization filter. A merchant that belongs to no organization gets `404`. This request asks for one contract's lifted effects: ```bash theme={null} curl "https://api-sandbox.rinne.com.br/core/v1/receivables/contract-effects?status=CANCELLED&external_contract_id=CTR-2026-000390" \ -H "x-api-key: YOUR_API_KEY" ``` ```json theme={null} { "data": [ { "external_contract_id": "CTR-2026-000390", "merchant_document": "11444777000161", "effect_type": "GUARANTEE", "effect_priority": 0, "division_method": "FIXED_AMOUNT", "effect_amount": 45000, "effect_percentage": null, "committed_effect_amount": 45000, "expected_settlement_date": "2026-08-04", "status": "CANCELLED", "beneficiary_document": "60701190000104", "beneficiary_document_type": "CNPJ", "beneficiary_account": { "holder_document": "60701190000104", "ispb": "60701190", "branch_code": "0001", "account_number": "123456", "check_digit": "7", "account_type": "CHECKING" }, "registrar_document": "11222333000181", "last_snapshot_date": "2026-08-03", "cancelled_at": "2026-08-05T09:04:51.000Z", "created_at": "2026-06-30T09:11:20.000Z", "updated_at": "2026-08-05T09:04:51.000Z" } ], "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1, "hasNext": false, "hasPrev": false }, "latest_snapshot_date": "2026-10-14" } ``` The effect was last reported on 2026-08-03 and lifted when the next snapshot left it out, while the list itself is current as of 2026-10-14. ## List your merchants' contract effects `GET /v1/merchants/receivables/contract-effects` returns the effects on the documents of the authenticated organization's merchants, under that organization. Requires the `merchant.receivable.list` permission; organizations only, so a merchant calling it gets `403` and uses [`GET /v1/receivables/contract-effects`](#list-your-own-contract-effects) instead. * **`merchant_document`** narrows the list to one document. A document that is not one of the organization's merchants returns an empty list, never another organization's effects. * **The organization's own document** is left out unless one of its merchants carries it too. List it with [`GET /v1/receivables/contract-effects`](#list-your-own-contract-effects). * **A document under two organizations**: each organization sees only the effects registered under itself, so the same contract on the same document can appear to both, once each. This request lists the effects on one merchant's document for settlements due in July 2026: ```bash theme={null} curl "https://api-sandbox.rinne.com.br/core/v1/merchants/receivables/contract-effects?merchant_document=11444777000161&expected_settlement_date_from=2026-07-01&expected_settlement_date_to=2026-07-31" \ -H "x-api-key: YOUR_API_KEY" ``` ```json theme={null} { "data": [ { "external_contract_id": "CTR-2026-000481", "merchant_document": "11444777000161", "effect_type": "GUARANTEE_FIDUCIARY_ASSIGNMENT", "effect_priority": 0, "division_method": "PERCENTAGE", "effect_amount": null, "effect_percentage": 100, "committed_effect_amount": 82350, "expected_settlement_date": "2026-07-14", "status": "ACTIVE", "beneficiary_document": "60701190000104", "beneficiary_document_type": "CNPJ", "beneficiary_account": { "holder_document": "60701190000104", "ispb": "60701190", "branch_code": "0001", "account_number": "123456", "check_digit": "7", "account_type": "CHECKING" }, "registrar_document": "11222333000181", "last_snapshot_date": "2026-10-14", "cancelled_at": null, "created_at": "2026-07-02T09:12:44.000Z", "updated_at": "2026-10-14T09:05:10.000Z" }, { "external_contract_id": "CTR-2026-000517", "merchant_document": "11444777000161", "effect_type": "OWNERSHIP_TRANSFER", "effect_priority": 0, "division_method": "FIXED_AMOUNT", "effect_amount": 150000, "effect_percentage": null, "committed_effect_amount": 150000, "expected_settlement_date": "2026-07-21", "status": "ACTIVE", "beneficiary_document": "12345678909", "beneficiary_document_type": "CPF", "beneficiary_account": { "holder_document": "12345678909", "ispb": "00000000", "branch_code": null, "account_number": "98765432", "check_digit": null, "account_type": "PAYMENT" }, "registrar_document": null, "last_snapshot_date": "2026-10-14", "cancelled_at": null, "created_at": "2026-07-09T09:10:02.000Z", "updated_at": "2026-10-14T09:05:10.000Z" } ], "pagination": { "page": 1, "limit": 20, "total": 2, "totalPages": 1, "hasNext": false, "hasPrev": false }, "latest_snapshot_date": "2026-10-14" } ``` The first effect diverts the whole settlement of 2026-07-14 to its beneficiary; the second diverts R\$ 1,500.00 of the settlement of 2026-07-21. Both are `ACTIVE` and were reported by the latest snapshot. ## Filters, sorting and pagination | Parameter | Endpoints | Description | | - | - | - | | `merchant_document` | Merchants only | The merchant's CNPJ or CPF; formatting is stripped. | | `external_contract_id` | Both | The contract's key. | | `status` | Both | Comma-separated statuses, `ACTIVE` and `CANCELLED`. Defaults to `ACTIVE`. | | `effect_type` | Both | Comma-separated [effect types](#effect-types). | | `expected_settlement_date_from` | Both | Settlement date from, inclusive, `YYYY-MM-DD`. | | `expected_settlement_date_to` | Both | Settlement date until, inclusive, `YYYY-MM-DD`. | | `sort` | Both | `expected_settlement_date` or `created_at`, `-` prefix for descending. Defaults to `expected_settlement_date` ascending. | | `page` | Both | Page number. Defaults to `1`. | | `limit` | Both | Items per page. Defaults to `20`, at most `100`. | A request that matches nothing returns `200` with an empty `data` array and the usual `pagination` and `latest_snapshot_date`. ## The contract effect object **external\_contract\_id** `string` *required* The contract's key, as reported. Repeats across the dates one contract covers. **merchant\_document** `string` *required* The CNPJ or CPF the contract is registered on, without formatting. It covers every merchant (company) with this document. **effect\_type** `string` *required* One of the [effect types](#effect-types). **effect\_priority** `integer` *required* The effect's place in the settlement order among the effects on the same date, as reported, sequential from `0`. **division\_method** `string` *required* `FIXED_AMOUNT` or `PERCENTAGE`. See [Division method](#division-method). **effect\_amount** `integer | null` *required* The effect's amount in cents for `FIXED_AMOUNT`; `null` for `PERCENTAGE`. **effect\_percentage** `number | null` *required* The effect's share of the settlement for `PERCENTAGE`, from 0 to 100 with two decimals; `null` for `FIXED_AMOUNT`. **committed\_effect\_amount** `integer` *required* The part of the effect already committed against the settlement, in cents. **expected\_settlement\_date** `string` *required* The settlement date the effect applies to, `YYYY-MM-DD`. **status** `string` *required* `ACTIVE` or `CANCELLED`. See [Statuses](#statuses). **beneficiary\_document** `string` *required* The creditor's CNPJ or CPF, as reported. **beneficiary\_document\_type** `string` *required* `CNPJ` or `CPF`. **beneficiary\_account** `object` *required* The account the settlement is diverted to, as reported. **properties** **holder\_document** `string` *required* The account holder's CNPJ or CPF. **ispb** `string` *required* The ISPB code of the account's institution. **branch\_code** `string | null` *required* The branch; `null` when not reported. **account\_number** `string` *required* The account number. **check\_digit** `string | null` *required* The account's check digit; `null` when not reported. **account\_type** `string` *required* `CHECKING`, `DEPOSIT`, `GUARANTEED`, `INVESTMENT`, `PAYMENT` or `SAVINGS`. **registrar\_document** `string | null` *required* The CNPJ of the registrar the contract is registered at; `null` when not reported. **last\_snapshot\_date** `string` *required* The latest snapshot that reported this effect, `YYYY-MM-DD`. See [Snapshot freshness](#snapshot-freshness). **cancelled\_at** `string | null` *required* When Rinne recorded the cancellation; `null` while `ACTIVE`. **created\_at** `string` *required* When Rinne first stored the effect. **updated\_at** `string` *required* When the effect last changed. The list response wraps the effects in `data`, next to `pagination` and the top-level `latest_snapshot_date`. ## Errors and empty results | Status | When | | - | - | | `400` | A filter is invalid: an empty or unknown `status`, an unknown `effect_type` or `sort` field, a date not in `YYYY-MM-DD`, a `limit` above `100`, or, on the merchants endpoint, an invalid `merchant_document`. | | `401` | The API key is missing or invalid. | | `403` | The API key lacks the endpoint's permission, or a merchant called the merchants endpoint. | | `404` | A merchant without an organization called `GET /v1/receivables/contract-effects`. | An empty `data` array is not an error. It means no effect matches the filters as of `latest_snapshot_date`; when `latest_snapshot_date` is `null`, Rinne has not received any snapshot yet. Contract effects have no webhooks: you read them by listing them. ## Next steps > **[Settlement items](/concepts/settlement-items)** > > See what was actually paid and when > **[Organizations and merchants](/concepts/organizations-and-merchants)** > > Understand how merchants and their documents relate to an organization This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.