Merchants — Functional Documentation

Documentation generated based on Swagger merchants.yaml (version 1.0.0).

---

1. Overview

The service solves the following problems:

• How to register a new acquiring client? — Whether an individual or a company, the service offers a guided data entry flow, which can be done in a single step or in multiple progressive steps.
• How to know if a CPF or CNPJ is already a Getnet client? — A quick query answers whether the document already has an accredited Commercial Establishment (EC).
• How to keep registration data up to date? — The service allows updating any registration information at any time.
• How to validate if the client is eligible to operate? — The qualification process (risk and compliance analysis) checks if the establishment can actually do business with Getnet.

---

2. Context and Use Cases

When to use this service

Use this service whenever you need to:

• Start the onboarding of a new commercial establishment at Getnet.
• Consult registration data of an existing establishment.
• Update registration information (address, income, legal representative, etc.).
• Pre-check if a CPF or CNPJ already has a link with Getnet.
• Trigger the risk and compliance analysis of an establishment before activating it.

Real business scenarios

Scenario 1 — Self-employed wanting to accept cards

João is a self-employed electrician and wants a Getnet POS. The channel collects his CPF, name, date of birth, mobile, email, and mother's name. With this data, João's registration is created. Then, income, address, and working hours are added. Finally, qualification is triggered to check if João can operate.

Scenario 2 — Company onboarding (PJ)

A bakery with a CNPJ wants to accept digital payments. The channel provides the CNPJ and the legal representative's data (CPF, name, mobile, and email). The platform automatically fetches company data from Receita Federal (corporate name, partners, address). The channel adds trade name, annual revenue, and business address, then triggers qualification.

Scenario 3 — Duplicate check before registration

Before starting onboarding, the channel checks if the CPF or CNPJ already has an accredited EC at Getnet. If so, duplication is avoided. If not, registration proceeds as normal.

Scenario 4 — Updating registration data

An already onboarded merchant changes address. The channel fetches the merchant's current data, changes only the address field in the response, and resubmits the full payload for update.

Scenario 5 — Requalification after rejection

A merchant was rejected in qualification due to incorrect data. After correcting the information via update, the channel triggers qualification again for a new analysis.

---

3. Prerequisites

Authentication

• How to obtain: POST /token (Authentication domain)
• How to use: send in the HTTP header Authorization directly, without the Bearer prefix:

The token has an expiration period. Renew it before starting new requests when necessary.

Available environments

Dependencies on other services

Permissions and profiles

• The integrated channel must be properly enabled on the Getnet platform to operate the Merchants domain.
• The credentials used to obtain the token must have read and write permission over this domain's resources.

---

4. Main Flow

The onboarding of a merchant follows a step-by-step flow, from initial verification to final approval. The endpoints relate as follows:

5. Quick Integration Guide

---

Happy Path — Individual (PF)

Step 1 — Check if the CPF is already a client

Before registering, check if the CPF already has an accredited EC:

If accredited: true, the CPF is already linked. Do not create a new registration.

---

Step 2 — Create the individual merchant (minimum data)

Send the essential data to create the registration. Additional data will be sent in the next step.

What to send:

• fiscal_type: always "natural_person" for individuals.
• acquirer_merchant_category_code: use "2119" (Self-employed Professional) when the specific category is unknown.
• opt_ins: required with lgpd and terms_and_conditions, both with accept: true.

What to note in the response:

• Save the merchant_id — it will be needed in all subsequent steps.
• The sub_status_steps field lists the pending steps. DATA_GRID with status: pending indicates that additional data still needs to be sent.
• TERMS_AND_CONDITIONS and PRIVACY_POLICY already appear as finished because the opt-ins were sent in the POST.

---

Step 3 — Complete the data (PUT)

Before any update, check the current state of the merchant:

Based on the response, add/change the additional fields and resend the full payload:

Attention:

• PUT is a full replacement. Always start from the GET response and change only what is necessary.
• Monetary values in cents: 500000 = R$ 5,000.00.
• The ZIP code provided must exist in Getnet's database. Validate with GET /domains/zipcode/{postal_code} before sending.
• commercial_address and residential_address can be the same (common for self-employed).

---

Step 4 — Qualify the individual merchant

With the complete data, trigger the risk analysis:

The request body can be omitted for standard qualification.

• approved: merchant enabled. Proceed to the next steps (offerings, contracts).
• reproved: read detail_description in each item of details to understand the reason. When the reason cannot be disclosed, the message will be generic (as in the example above).

---

Happy Path — Company (PJ)

Step 1 — Check if the CNPJ is already a client

---

Step 2 — Create the company merchant (minimum data)

What to send:

• Company's fiscal_type: always "company".
• Legal representative's fiscal_type: always "natural_person".
• Company data (corporate name, address, partners) is automatically fetched via CNPJ from Receita Federal — no need to provide them.
• opt_ins is required in the POST.

What to note:

• The returned merchant_id should be saved for the next steps.
• The platform has already automatically filled: legal_name, founding_date, tax_regime, federal_registration_status, and the shareholders list (shareholders).
• SOCIAL_CONTRACT and LETTER_OF_ATTORNEY are exclusive steps for companies.

---

Step 3 — Complete the company data (PUT)

Check the current state:

Based on the GET response, add the additional data and resend:

Main fields to complete for companies:

Attention to the shareholders list (shareholders): The shareholders array is automatically filled by the platform. Resend it exactly as returned by the GET — do not omit, change, or reorder the partners.

---

Step 4 — Qualify the company merchant

The response and interpretation are the same as for individuals:

• report.recommended.status: "approved" → merchant enabled.
• report.recommended.status: "reproved" → check report.details[*].detail_description.

---

6. Business Rules

General rules

Required parameter in listing

• legal_document_number — CPF (11 digits) or CNPJ (14 digits), digits only.
• acquirer_merchant_code — EC code at Getnet.

Listing pagination

---

Creation rules — POST /merchants

Required opt-ins

Required fields in POST — Individual (PF)

Required fields in POST — Company (PJ)

---

Update rules — PUT /merchants/{merchant_id}

Full replacement

Never send a partial payload in PUT.

Shareholders (PJ)

---

Address rules

---

Monetary value rules

---

Qualification rules

---

Merchant lifecycle status

---

Onboarding steps (sub_status_steps)

---

7. Error Handling

Standard error structure

All errors follow the structure below:

---

Error codes by endpoint

---

Most common error scenarios

Creation with existing document (409)

---

Missing required field (400)

---

Merchant rejected in qualification (200 with status reproved)

---

Expired token (401)

---

8. Glossary