Merchant Data — Functional Documentation

Product: mps-wlb-merchant-data-ms Audience: product owners, business analysts, QA, and integrating teams. Scope: describes what the service does from a business perspective. For technical setup, architecture and code, refer to the project's README file (README.md, at the repository root). For the machine-readable contract, refer to the OpenAPI specification file (openapi/openapi.json, in the repository) or to the Swagger UI, available at the "{basePath}/api-docs" route of the running service.

Purpose

mps-wlb-merchant-data-ms provides a single, consolidated, read-only view of a merchant (a commercial establishment) accredited within the MPS WLB partner program.

It exists so that consuming applications do not need to talk to — or understand — the upstream Getnet Establishment Contracts system directly. The service:

  • Aggregates the merchant's registration data (identity, address, contacts, bank accounts, working hours, economic activity) into one stable response.
  • Standardizes the vocabulary (field names and meanings) so consumers get a predictable contract even if the upstream changes internally.
  • Protects consumers from upstream complexity and failures, returning clear, safe errors.
The service is query-only: it never creates, updates, or deletes merchant data.

Business context

A consumer application calls the Merchant Data service, which aggregates, maps and normalizes registration data on top of the upstream Establishment Contracts API (the system of record).

Consumer app (front-end / BFF client) GET merchant by id mps-wlb-merchant-data-ms aggregation · mapping error normalization (read-only BFF) forward (Bearer token) Establishment Contracts API (upstream) system of record
  • System of record: the upstream Establishment Contracts API owns the data. This service is a read layer on top of it.
  • Authentication to upstream: the service forwards a pre-provisioned access token injected per environment. There is no user login flow inside this service.

Request flow (sequence diagram)

The diagram below shows a single merchant query, including the happy path and the main error branches (invalid identifier, merchant not found, and upstream failure).

Consumer app Platform gateway Merchant Data service Establishment Contracts API GET /merchants/{merchant_id} Authenticate access token Forward request Echo / generate X-Request-Id Validate merchant_id (allowlist) alt [ Invalid merchant_id ] >C 400 --> 400 "Invalid merchant id." [ Valid merchant_id ] GET /{merchant_id} (Bearer token) alt [ Upstream 200 with data ] >S payload --> Merchant payload Map to domain model (cpf/cnpj, drop empty contacts) >C 200 --> 200 Merchant (+ X-Request-Id) [ Upstream 400/404 or empty ] >S --> 404 / empty >C 404 --> 404 "Merchant not found." [ Upstream error or unavailable ] >S --> 5xx / timeout / no response >C 502 --> 502 "Upstream API error/unavailable."
information icon
Note: before validation, the service also enforces a rate limit; a client exceeding the allowed number of requests in the time window receives 429 "Too many requests.".

Consumers and actors

ActorInteractionPurpose
Consumer applicationCalls GET /merchants/{merchant_id}Display or process consolidated merchant data.
Platform gatewayValidates the access token before requests reach the serviceAccess control.
Orchestrator (OpenShift/Kubernetes)Calls the health endpointsKeep the service available and route traffic only when ready.
Integration/QA teamsRead Swagger UI / OpenAPIUnderstand and test the contract.

Functional capabilities

Retrieve consolidated merchant data

Given a merchant identifier (the acquirer merchant code), the service returns the merchant's consolidated registration profile. Every business field is optional and is only present when the upstream provides it.

Service health visibility

Operational endpoints report whether the service is alive and ready to receive traffic, so the platform can manage availability. These are not business endpoints.

Self-describing contract

The service publishes its own interactive documentation (Swagger UI) and a raw contract (OpenAPI), so integrators can explore and generate clients without reading source code.

Merchant identifier

  • The merchant_id is the acquirer merchant code that uniquely identifies the establishment.
  • It must match the allowlist letters, digits, - and _, 1 to 64 characters.
  • Any value outside this pattern is rejected as a bad request before any lookup happens (protects against malformed input and injection attempts).

Data dictionary (business meaning)

The response is the Merchant view. Fields absent in the source are omitted from the response.

Identity and tax id

FieldMeaningBusiness rule
merchant_idUnique establishment code at the acquirer.Echoes the requested identifier.
cpfTax id when the holder is an individual.Present only when the holder type is natural_person.
cnpjTax id when the holder is a legal entity.Present only when the holder type is company.
trade_nameCommercial name (nome fantasia).—
legal_nameRegistered legal name (razão social).—
information icon
Mutual exclusivity: a merchant returns either cpf or cnpj, never both. The choice is driven by the holder type coming from the source (individual vs. legal entity).

Address

FieldMeaning
street, number, suite, district, city, state, country, postal_codeThe establishment's delivery/registered address, flattened into individual fields.

Contacts

contacts is a list of contact entries. Each entry may contain:
FieldMeaning
emailContact email, when available.
addressA postal address associated with the contact, when available.

Business rules:

  • A contact with no email and no postal address carries no useful information and is discarded.
  • If, after discarding, there are no meaningful contacts, the contacts field is omitted entirely from the response (it is never returned as an empty list).

Status

FieldMeaningAllowed values
statusCurrent registration status of the merchant.ok, canceled, active, inactive, pending

Bank accounts (merchant_accounts)

Each item wraps a bank_account with the merchant's banking details:
FieldMeaningNotes
bank.bank_codeBank code.e.g. 655.
bank.bank_nameBank name.—
bank.bank_countryBank country.When provided.
account_typeAccount type.cc = checking, cp = savings.
bank_branch_codeBranch code (without check digit).—
bank_account_numberAccount number with check digit.—
bank_account_currencyAccount currency.ISO 4217 (e.g. BRL).
account_person_typeHolder type of the account.company or natural_person.
statusAccount status.active, inactive, pending.

Working hours (working_hours)

Opening-hours windows for the establishment:

FieldMeaning
start_day, end_dayWindow day range, as 3-letter English day codes (e.g. mon, fri).
start_time, end_timeWindow opening and closing times (HH:MM:SS).

Ownership and activity

FieldMeaning
ownerNames of the establishment's shareholders/partners.
legal_representativeName of the legal representative.
founding_dateEstablishment founding date (YYYY-MM-DD).
merchant_category_codeMerchant Category Code (MCC).
acquirer_merchant_category_codeMCC as classified by the acquirer.
economic_activity_classification_codesEconomic activity classification codes (e.g. CNAE).

Business rules summary

  1. Read-only: the service only answers queries; it never changes merchant data.
  2. Identifier validation: merchant_id must match the allowlist, otherwise the request is rejected as a bad request.
  3. Tax id selection: cpf for individuals, cnpj for legal entities — mutually exclusive.
  4. Meaningful contacts only: empty contacts are dropped; an empty contact list is omitted.
  5. Optional fields: any field missing in the source is omitted from the response.
  6. Safe errors: upstream/internal failures are translated into clear, non-technical messages; internal details are never exposed to the consumer.

Error scenarios (functional view)

SituationOutcomeMessage returned
Identifier does not match the allowlistRejected as bad requestInvalid merchant id.
Merchant does not exist (or source returns nothing)Treated as not foundMerchant not found.
Source system returns an error or is unavailableReported as an upstream failureUpstream merchant API error. / Upstream merchant API unavailable.
Too many requests in a short periodThrottledToo many requests.
Unexpected internal problemGeneric failure (details in logs only)Internal error.

Non-functional aspects (business relevance)

  • Data protection / privacy: sensitive data (tokens, tax documents, credentials) is redacted from internal logs, supporting privacy and compliance expectations.
  • Abuse protection: a rate limit caps how many requests a client can make in a short window, protecting availability.
  • Confidentiality of failures: server-side errors are opaque to consumers — no stack traces, routes, or upstream internals are leaked.
  • Traceability: every request carries a correlation identifier (X-Request-Id) that is echoed back and stamped on logs, so a specific interaction can be traced end to end when investigating incidents or support tickets.
  • Availability signaling: health and readiness endpoints let the platform route traffic to the service only when it can actually serve requests.

Assumptions and limitations

  • The service depends entirely on the upstream system of record; if the upstream lacks a field, the service cannot provide it.
  • The service performs no data enrichment or business calculations — it aggregates and standardizes only.
  • Access control is enforced by the platform gateway; this service assumes requests that reach it are already authenticated.

Glossary

TermDefinition
Merchant / EstablishmentA commercial establishment accredited in the partner program.
BFFBackend for Frontend — a backend tailored to the needs of consuming applications.
UpstreamThe source system this service reads from (Getnet Establishment Contracts API).
MCCMerchant Category Code — classifies the merchant's line of business.
CNAEBrazilian economic activity classification code.
Base pathURL prefix under which business and documentation routes are served (e.g. /merchant-data/v1).

On this page

Merchant Data — Functional Documentation