Pendencies API — Functional Documentation

Table of contents

• Overview
• Actors and context
• Supported pendencies
• End-to-end onboarding flow
• Operations
• data_grid attribute catalog
• Business rules and constraints
• Data protection (masking)
• Error meanings

Overview

Using this API, a partner can:

• Query a merchant's open pendencies and their current status.
• Submit or update registration data.
• Request and validate contact-channel verification codes (SMS / email / WhatsApp).
• Upload required documents (as Base64 content).
• Accept documents and terms.
• Download generated documents when available.

Actors and context

Both identifiers appear in the path of every endpoint:

• natural_person — the merchant's legal document is a CPF (individual).
• company — the merchant's legal document is a CNPJ (legal entity).

The person type determines which registration attributes apply (see data_grid attribute catalog).

Supported pendencies

Only the pendencies below are exposed to partners. Any other pendency the platform tracks internally is never returned.

End-to-end onboarding flow

A partner first queries the merchant's pendencies, then resolves each one respecting the ordering rules below. Only pendencies that are actually open for that merchant need to be resolved.

• Contact validation comes first. The partner never sends the contact value to the token endpoints: the API reads it from the merchant's email_validation / cell_phone_validation pendency. Therefore the matching email / cell_phone value must already exist in the registration (submitted via data_grid); otherwise the token request is rejected with 422.
• Identification document after the selfie, when the selfie is required.
• Social contract before power of attorney. The merchant provides the social contract or the power of attorney depending on their situation.

Operations

1. Query pendencies

Response fields:

Notes:

• The merchant's legal document number is not returned.
• Omitted (null) fields are not serialized.
• Merchant not found / not accessible → 404.
• No applicable pendencies → 200 with an empty list.

2. Request validation code

3. Validate code

Submits the code the merchant received to confirm ownership of the contact channel.

Body:

4. Resolve data_grid

• pendencies and grid_info must not be empty; name must be exactly data_grid.
• The merchant must have an active data_grid pendency (status pending); otherwise the request is rejected with 422.
• Only attributes in the attribute catalog are accepted; any other attribute, an unknown field, an empty body, or a malformed value → 400.

5. Upload document

Uploads a required document as Base64 content.

Response:

6. Accept document

Accepts a document or terms. The body carries a pendencies envelope:

The response flattens the first accepted pendency:

7. Download document

data_grid attribute catalog

Natural Person (PF)

Company (PJ)

Value rules per attribute

Example of an address item:

Business rules and constraints

• Only open pendencies can be resolved. Resolving data_grid requires an active (pending) data_grid pendency; otherwise 422.
• Selective exposure. Only the supported pendencies are returned; internal pendency types are never exposed.
• grid_info is only returned while the pendency is pending. Attributes outside the catalog are discarded; if a pending data_grid carries only unknown attributes, the API returns 500.
• Strict input. Partner request bodies reject unknown fields (400) — the only exception is the token-validation body, which ignores them. Empty bodies ({} / []) are rejected, and a JSON object sent where an array is expected is also rejected.
• Documents must contain valid Base64 content.
• Contact validation ordering. The verification code is always sent to the value already stored in the registration for that channel; the partner cannot override it.
• Person type is derived from the merchant's legal document: CPF → natural_person, CNPJ → company.
• No open pendencies returns an empty list.
• Anti-enumeration. An unknown or inaccessible merchant always results in 404, regardless of how the platform reports it internally.
• Sensitive data must be transmitted over HTTPS, and all requests require authentication.

Data protection (masking)

Raw contact data is never returned to the partner:

Masking rules: e-mail keeps the first character of the local part and the whole domain; phone keeps the area code and the last four digits. Values that cannot be masked (malformed) are omitted.

Error meanings

Error responses share a common shape:

Two variations exist for document flows:

• upload-document, acceptance-document and download-document errors omit the empty details array, returning only status_code and message.
• When the platform reports a field-level problem while accepting a document, the response is { "status_code": ..., "item": ..., "description": ... }.

Messages returned to the partner are always sanitized: internal identifiers, class names and downstream messages in Portuguese are never relayed.