Reciprocity

How the Cumbuca Gateway API fulfils the Open Finance reciprocity duty, answering other participants' lookups about your account holders, in its two operating modes: without delegation, where Cumbuca stores the records and answers for you, and with delegation, where every lookup is proxied live, over mTLS, to a service you run yourself.

What is Reciprocity

Participating in Open Finance Brasil as a data receiver comes with a reciprocity duty: other participants can ask whether a given document belongs to one of your account holders, and read that customer's identification records. Cumbuca fulfils this duty in one of two ways, decided by a single instance-wide setting, namely delegation.

With and without delegation

Without delegation (delegation off), the default. Cumbuca stores the customer records it knows about (through the automatic registration that follows an authorised consent, or through the PUT /personal/identifications/register and PUT /business/identifications/register writes) and answers ecosystem lookups itself, from its own store. Your service is not called.

With delegation (delegation on). Cumbuca stores nothing. Every reciprocity lookup is proxied live, over mTLS, to a service that you implement and operate. It becomes the source of truth.

Comparison

Automatic Registration (without delegation)

When the instance does not delegate, Cumbuca itself needs to know your account holders in order to answer reciprocity lookups. It populates that store automatically, with no partner action, from the data-sharing consents your instance creates:

1. When a data-sharing consent is created, Cumbuca starts tracking it.
2. Open Finance does not push status changes, so Cumbuca polls the consent until it reaches AUTHORISED (or expires, when the ecosystem auto-rejects unauthorised consents after ~1 h).
3. Once authorised, Cumbuca reads the customer's identifications through the consent (a billable read) and stores each record, with x-data-source: internal. A personal consent feeds /personal/identifications; a business consent (one carrying a businessEntity) feeds /business/identifications.

The two are independent: a consent that grants both permissions registers both, and a failure on one side never blocks the other.

Registration is idempotent, so re-runs are harmless. For personal records, data you write yourself (via PUT /personal/identifications/register, source tenant) takes precedence over the internal automatic registration and is never overwritten by it.

Mandatory permissions

Automatic registration is only possible if the consent carries the permission that authorises Cumbuca to read the customer's identification data. That is why, when the instance does not delegate, Cumbuca adds the matching permission automatically at consent creation, ensuring the reciprocity store can be populated:

Only the identifications permission is added. Qualification and financial-relations records are derived from the same identifications payload, so they need no separate read.

With Delegation: Your Service's Contract

When your instance delegates, you hand Cumbuca a base URL at onboarding. HTTPS is mandatory in production and homologation. Under that base URL, your service must implement the JSON POST endpoints below; the paths are relative to that base URL. The business (PJ) endpoints are only required if your institution serves legal-entity customers.

• Every request Cumbuca sends is a JSON POST with content-type: application/json. Documents travel only in the body, never in the query string.
• Every request carries an x-nexus-request-id header (UUIDv7). Log it: it is also echoed as a response header on every Cumbuca gateway response, making it the cross-service correlation key for support.
• Responses must be HTTP 200 with exactly the JSON shapes documented below. Wrong shapes are not tolerated anywhere in the chain; they fail the lookup (see error mapping).

{
  "cpf": "12345678901",
  "cnpj": "12345678000199" // optional
}

{
  "data": { "isAccountHolder": true }
}

{
  "cpf": "12345678901"
}

{
  "data": [
    { /* Open Finance Brasil personal-identifications record */ }
  ]
}

{
  "cnpj": "12345678000199"
}

{
  "data": [
    { /* Open Finance Brasil business-identifications record */ }
  ]
}

{
  "cpf": "12345678901"    // "cnpj" on the business paths
}

{
  "data": { /* Open Finance Brasil qualification / financial-relations object */ }
}

mTLS on the Delegated Leg

Every call from Cumbuca to your service rides on mutual TLS. There is no bearer token and no API key on this hop: the gateway's client certificate is the only authentication.

• What Cumbuca presents: a gateway client certificate on every delegated call. Your service must require a client certificate and validate / allowlist Cumbuca's; connections without it must be rejected. The certificate is exchanged during onboarding.
• What you must serve: a TLS server certificate that chains to a public CA. If yours doesn't, provide your CA chain to Cumbuca at onboarding so it can be added to the gateway's trust store.
• No plaintext fallback: in production and homologation, if the gateway's client certificate is unavailable Cumbuca refuses the call (502 DELEGATED_UNAVAILABLE) rather than calling without mTLS, and a delegated instance will not even boot without the certificate configured.

Timeout Budget

• The gateway waits up to 30 seconds for your response: its configured receive timeout, which defaults to 30 s and may differ per deployment (the internal hop that precedes it has a fixed 30-second budget). Answer comfortably under that, ideally in well under a second, since these lookups sit on another institution's request path.
• Single attempt, no retry. A slow or failed answer immediately fails the lookup; the gateway will not try again.

Failure Semantics

• No fallback answer. When your service is down, times out, or answers a wrong shape, the reciprocity lookup fails: the requesting institution gets an error, never a default "not an account holder".
• Your error bodies are withheld. When your service answers a non-200 status, Cumbuca passes the status through with a generic DELEGATED_ERROR envelope and discards your response body (PII protection). Don't rely on error details propagating; use x-nexus-request-id and your own logs instead.
• Error envelope. Gateway errors follow the Open Finance format {"errors":[{"code","title","detail"}]} and carry the response headers x-nexus-request-id and x-nexus-error-source (client | upstream | gateway).

Error mapping

What each behaviour of your service produces downstream:

What Changes When You Delegate

Registration returns 422

On a delegated instance, both partner-facing registration writes, PUT /personal/identifications/register and PUT /business/identifications/register, are always refused: every authenticated, well-formed request gets 422 and nothing is ever stored (malformed bodies still get the generic 400/415, and missing auth gets 401):

HTTP/1.1 422
x-nexus-error-source: client
x-nexus-request-id: <uuidv7>

{
  "errors": [
    {
      "code": "UNKNOWN",
      "title": "Unknown Error",
      "detail": "Registration not supported for a delegated client"
    }
  ],
  "meta": { "requestDateTime": "2026-07-15T12:00:00Z" }
}

Don't call registration on a delegated instance; treat this 422 as the expected, permanent answer.

Automatic registration is skipped

The automatic registration that populates Cumbuca's store does not apply when you delegate. After a data-sharing consent reaches AUTHORISED, Cumbuca still attempts the internal write, for personal and business alike, but it is refused with the same 422 (nothing is stored at Cumbuca) and the step is silently skipped. Your service is the only place reciprocity data comes from. Cumbuca also skips adding the identifications permission to consents on a delegated instance, since it never needs to perform that read.

LGPD - nothing stored at Cumbuca

With delegation enabled, no customer identification data for reciprocity is retained at Cumbuca: registration writes are refused before validation, and every read is answered live from your service. Personal data handled for reciprocity stays inside your infrastructure.

Cumbuca Gateway API - Reciprocity.