Pendencies API — Functional Documentation

This document describes the functional behavior of the Pendencies API from the perspective of a partner integrating with it. It explains what the API does, the onboarding flow it supports, the pendencies a merchant may have, and the business rules that govern each operation.

Overview
Actors and context
Supported pendencies
End-to-end onboarding flow
Operations
data_grid attribute catalog
Business rules and constraints
Error meanings

Overview

The Pendencies API lets partners query and resolve the onboarding pendencies of a Getnet merchant. A pendency is an outstanding requirement (missing data, a document, or an acceptance) that the merchant must satisfy before affiliation can proceed.

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.

All requests and responses use JSON in snake_case, dates are ISO-8601 UTC, and the content type is application/json.

Actors and context

Every operation runs in the context of a partner acting on behalf of a merchant.

Field	Description
`partnerId`	Unique identifier of the partner application.
`merchantId`	Identifier of the merchant whose onboarding is being managed.

Both identifiers appear in the path of every endpoint:

text

/api/v1/partner/{partnerId}/merchant/{merchantId}/pendencies

text

/api/v1/partner/{partnerId}/merchant/{merchantId}/pendencies

A person type is derived from the merchant's legal document and returned as person_type:

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.

Pendency	Meaning	Resolved via
`cell_phone_validation`	Cell phone ownership must be verified	token request + validation
`email_validation`	Email ownership must be verified	token request + validation
`data_grid`	Registration attributes must be provided/updated	`PUT /data-grid`
`selfie_upload`	Selfie must be uploaded	`POST /upload-document`
`identification_document_upload`	Identification document must be uploaded	`POST /upload-document`
`social_contract_upload`	Social contract must be uploaded	`POST /upload-document`
`letter_of_attorney_upload`	Power of attorney must be uploaded	`POST /upload-document`
`order_summary`	Order summary must be accepted	`PUT /acceptance-document`
`terms_and_conditions`	Terms and conditions must be accepted	`PUT /acceptance-document`
`privacy_policy`	Privacy policy must be accepted	`PUT /acceptance-document`

A merchant with no open pendencies returns an empty list (pendencies: []).

When a data_grid pendency is returned, its grid_info field lists exactly which registration attributes must be submitted.

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.

text

Query pendencies
      │
      ▼
1. Contact validation (first)
      ├─ Submit email / cell_phone via data_grid   → 600;">PUT  .../data-grid
      │  (the value must exist before a code can be sent to it)
      └─ Request and validate the code             → 600;">POST .../token-request
                                                    → 600;">POST .../token-validation
      │
      ▼
2. Resolve remaining registration data (data_grid) → 600;">PUT  .../data-grid
      │
      ▼
3. Documents                                       → 600;">POST .../upload-document
      ├─ Selfie, then identification document (only after the selfie, when required)
      └─ Social contract or power of attorney (per the merchant&#039;s case)
      │
      ▼
4. Accept documents and terms                      → 600;">PUT  .../acceptance-document
      │
      ▼
Onboarding completed

text

Query pendencies
      │
      ▼
1. Contact validation (first)
      ├─ Submit email / cell_phone via data_grid   → 600;">PUT  .../data-grid
      │  (the value must exist before a code can be sent to it)
      └─ Request and validate the code             → 600;">POST .../token-request
                                                    → 600;">POST .../token-validation
      │
      ▼
2. Resolve remaining registration data (data_grid) → 600;">PUT  .../data-grid
      │
      ▼
3. Documents                                       → 600;">POST .../upload-document
      ├─ Selfie, then identification document (only after the selfie, when required)
      └─ Social contract or power of attorney (per the merchant&#039;s case)
      │
      ▼
4. Accept documents and terms                      → 600;">PUT  .../acceptance-document
      │
      ▼
Onboarding completed

Ordering rules:

Contact validation comes first. A verification code can only be requested after the matching email / cell_phone value already exists in the registration. Submit those data_grid attributes before requesting/validating a token for that channel.
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

Base path: /api/v1/partner/{partnerId}/merchant/{merchantId}/pendencies

Interactive docs are available at /swagger-ui.html; the OpenAPI spec at /api-docs.

1. Query pendencies

GET (base path)

Returns the merchant's pendencies with their current status and last-update timestamp, plus the merchant's person_type and overall situations. When a pendency is of type data_grid, grid_info tells the partner which attributes must be resolved.

Merchant not found / not accessible → 404.
No applicable pendencies → 200 with an empty list.

Success: 200

2. Request validation code

POST /token-request

Requests a one-time verification code to be sent to the merchant through a contact channel.

Field	Required	Description
`type`	yes	Contact channel: `cell_phone`, `email` (WhatsApp also supported as a channel).
`value`	yes	The channel value (e.g. `email@email.com` or a phone number).

The code is dispatched asynchronously to the merchant.

Success: 202 (accepted / dispatched)

3. Validate code

POST /token-validation

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

Field	Required	Description
`token`	yes	The one-time code received by the merchant.
`type`	no	Contact channel the code was sent to.
`value`	no	The channel value.
`device_fingerprint`	no	Device fingerprint for fraud prevention.

Success: 200 (channel ownership confirmed)

4. Resolve data_grid

PUT /data-grid

Submits registration attributes to resolve the data_grid pendency. The body carries a pendencies envelope; only data_grid is accepted, and each grid_info item is discriminated by its attribute:

json

{
  "pendencies": [
    {
      "name": "data_grid",
      "grid_info": [
        { "attribute": "email", "email": "teste@email.com" },
        { "attribute": "cell_phone", "cell_phone": "51992547923" }
      ]
    }
  ]
}

json

{
  "pendencies": [
    {
      "name": "data_grid",
      "grid_info": [
        { "attribute": "email", "email": "teste@email.com" },
        { "attribute": "cell_phone", "cell_phone": "51992547923" }
      ]
    }
  ]
}

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.

Success: 204 (no content)

5. Upload document

POST /upload-document

Uploads a required document as Base64 content. Returns the current situation (status and last-update date) of the uploaded document.

Field	Required	Description
`document_type`	yes	e.g. `social_contract`, `identification_document`, `selfie`.
`side`	yes	Image side, e.g. `front`, `back`.
`file_type`	yes	File format, e.g. `pdf`, `jpg`, `png`.
`file_base64`	yes	Base64-encoded file content (must be valid Base64).
`device_fingerprint`	no	Device fingerprint.

Unknown fields are rejected with 400.

Success: 200

6. Accept document

PUT /acceptance-document

Accepts a document or terms. The body carries a pendencies envelope; the response returns the name and current situation of the accepted pendency.

json

{
  "pendencies": [
    {
      "name": "privacy_policy",
      "device_fingerprint": "abc123",
      "situation": { "status": "..." }
    }
  ]
}

json

{
  "pendencies": [
    {
      "name": "privacy_policy",
      "device_fingerprint": "abc123",
      "situation": { "status": "..." }
    }
  ]
}

Success: 200

7. Download document

GET /download-document/{documentType}

Downloads a generated document as a Base64 string. documentType must be one of terms_and_conditions or order_summary; any other value → 400.

Success: 200 (returns the document_type and its Base64 content)

data_grid attribute catalog

When a data_grid pendency is returned, grid_info lists the attributes that must be submitted. The applicable set depends on the merchant's person type.

Natural Person (PF)

country_of_birth, cell_phone, email, gross_monthly_income, net_worth, residential_address, merchant_category_code, commercial_address, business_address

Company (PJ)

Company-level attributes merchant_category_code and business_address, plus the legal representative's data:

legal_representative.email, legal_representative.cell_phone, legal_representative.country_of_birth, legal_representative.residential_address, legal_representative.gross_monthly_income, legal_representative.net_worth

Value rules per attribute

Attribute	Value shape	Rule
`email` / `legal_representative.email`	`email`	Valid email address, not blank.
`cell_phone` / `legal_representative.cell_phone`	`cell_phone`	10 to 13 digits.
`country_of_birth` / `legal_representative.country_of_birth`	`country`	ISO 3166-1 alpha-2 (e.g. `BR`).
`residential_address`, `business_address`, `commercial_address` (and `legal_representative.residential_address`)	`address`	See address fields below.
`merchant_category_code`	`merchant_category_code` + `economic_activity_classification_code`, or `acquirer_merchant_category_code`	Provide the MCC pair (MCC = 4 digits, CNAE = 1–7 digits) or the acquirer MCC.
`gross_monthly_income` / `legal_representative.gross_monthly_income`	`gross_monthly_income`	Whole integer amount in BRL (reais, not cents).
`net_worth` / `legal_representative.net_worth`	`net_worth`	Whole integer amount in BRL (reais, not cents).

Address fields: street (required), number (blank is treated as "0"), district (required), city, state, postal_code (required, digits only), country (required, ISO alpha-2).

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.
Strict input. Partner request bodies reject unknown fields (400), and empty bodies ({} / []) are rejected.
Documents must contain valid Base64 content.
Contact validation ordering. A verification code can only be sent to an email / cell_phone value that already exists in the registration.
Person type is derived from the merchant's legal document: CPF → natural_person, CNPJ → company.
No open pendencies returns an empty list.
Sensitive data must be transmitted over HTTPS, and all requests require authentication.

Error meanings

HTTP	Meaning
`200`	Success
`202`	Accepted (validation code dispatched)
`204`	Success, no content returned
`400`	Invalid request (malformed body, unknown field, invalid value, unsupported channel/document type)
`401`	Missing or invalid authentication
`403`	Authenticated caller not allowed to access the resource
`404`	Merchant not found or not accessible by the partner
`422`	Business rule violation (e.g. no active `data_grid` pendency to resolve)
`500`	Unexpected error
`504`	Request timed out

Error responses share a common shape:

json

{ "status_code": 422, "message": "No active data_grid pendency to resolve for this merchant.", "details": [] }

json

{ "status_code": 422, "message": "No active data_grid pendency to resolve for this merchant.", "details": [] }

En esta página

Pendencies API — Functional Documentation

Pendencies API — Functional Documentation

Table of contents

Overview

Actors and context

Supported pendencies

End-to-end onboarding flow

Operations

1. Query pendencies

2. Request validation code

3. Validate code

4. Resolve data_grid

5. Upload document

6. Accept document

7. Download document

data_grid attribute catalog

Natural Person (PF)

Company (PJ)

Value rules per attribute

Business rules and constraints

Error meanings