Domain Tables — Support API

1. Overview

Without this service, an integrator could send a country code, an economic activity category, or a zip code that the platform does not recognize — and the registration would be reproved. The service solves this problem by providing, in advance, the exact sets of accepted values.

2. Context and Use Cases

Real-world use cases

Business example: A channel onboarding a self-employed doctor first queries GET /domains/acquirer-merchant-categories?natural_person to obtain the list of natural person categories, presents it to the merchant, and then uses the code of the selected category in the registration payload. Likewise, the channel queries the office's zip code via GET /domains/zipcode/{postal_code} to pre-fill the address form and ensure the zip code exists in the Getnet base.

3. Main Flow

The diagram below illustrates how the domain tables fit into a merchant's registration journey:

Relationship between the endpoints

4. Prerequisites

Authentication

Dependencies

Permissions

You must have a profile with access permission to the Getnet platform's onboarding API. Consult the Getnet integration team to verify the permissions of your credential.

5. Quick Integration Guide

Scenario: Validate a zip code before registering the address

Scenario: Get economic activity categories for Natural Person

Scenario: Get list of countries

6. Business Rules

Zip code lookup (GET /domains/zipcode/{postal_code})

• The zip code must be provided with digits only, without a hyphen, with exactly 8 characters (e.g.: 92410670).
• A zip code that returns 404 (not found) cannot be used in the address registration — the merchant will be reproved in qualification if an invalid zip code is submitted.
• Zip codes of municipal scope (small cities) are returned without the street and district fields. In these cases, request this data manually from the merchant.
• The number (property number) and suite (complement) fields are never returned by this endpoint — they must be collected from the merchant and added to the address before submitting in PUT /merchants/{merchant_id}.
• The number field is required when the property has a number. The suite field is required when the property does not have a number.

Economic activity categories (GET /domains/acquirer-merchant-categories)

• The natural_person parameter is a valueless flag — it must be sent only as ?natural_person in the query string to filter categories applicable to Natural Person.
• The code "2119" (PROFISSIONAL AUTONOMO) is the default value for natural person when the merchant's specific category is not known.
• The value submitted in the registration's acquirer_merchant_category_code field must necessarily exist in the list returned by this endpoint. Codes outside the table result in a validation error.

Country list (GET /domains/countries)

• The codes follow the ISO 3166-1 alpha-2 standard (two uppercase letters, e.g.: BR, US, PT).
• The values submitted in the registration's country_of_birth and nationality fields must necessarily exist in the list returned by this endpoint.

7. Error Handling

Standard error body

All errors return the following format:

Attention to the 404 error on the zip code: This is the only error with a direct impact on the merchant registration. A zip code that returns 404 cannot be used in PUT /merchants/{merchant_id} — the merchant will be reproved in qualification. Handle this case by displaying a clear message to the user so they correct the zip code before proceeding.

8. Glossary