Skip to main content
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:
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 shows.

​
How contract effects reach you

  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

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.
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.
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.
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.
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: 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: 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

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:
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 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.
  • 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:
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

A request that matches nothing returns 200 with an empty data array and the usual pagination and latest_snapshot_date.

​
The contract effect object

​
string
required
The contract’s key, as reported. Repeats across the dates one contract covers.
​
string
required
The CNPJ or CPF the contract is registered on, without formatting. It covers every merchant (company) with this document.
​
string
required
One of the effect types.
​
integer
required
The effect’s place in the settlement order among the effects on the same date, as reported, sequential from 0.
​
string
required
FIXED_AMOUNT or PERCENTAGE. See Division method.
​
integer | null
required
The effect’s amount in cents for FIXED_AMOUNT; null for PERCENTAGE.
​
number | null
required
The effect’s share of the settlement for PERCENTAGE, from 0 to 100 with two decimals; null for FIXED_AMOUNT.
​
integer
required
The part of the effect already committed against the settlement, in cents.
​
string
required
The settlement date the effect applies to, YYYY-MM-DD.
​
string
required
ACTIVE or CANCELLED. See Statuses.
​
string
required
The creditor’s CNPJ or CPF, as reported.
​
string
required
CNPJ or CPF.
​
object
required
The account the settlement is diverted to, as reported.
​
string | null
required
The CNPJ of the registrar the contract is registered at; null when not reported.
​
string
required
The latest snapshot that reported this effect, YYYY-MM-DD. See Snapshot freshness.
​
string | null
required
When Rinne recorded the cancellation; null while ACTIVE.
​
string
required
When Rinne first stored the effect.
​
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

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

See what was actually paid and when

Organizations and merchants

Understand how merchants and their documents relate to an organization