Transactions Data API (WLB)

Service: mps-wlb-transactions-data-ms

Functional documentation for the API. It describes what the API delivers to its consumer (the White Label (WLB) front-end), its business rules and the meaning of the data, without going into implementation details.

Overview

This API is a BFF (Backend for Frontend) that powers the sales query and reconciliation journey of the White Label product. It consumes the Auttar acquiring platform (reconciliation API) and delivers to the front-end the data already treated, aggregated and standardized.

Functional capabilities offered:

Reconciled sales listing for a merchant (paginated list).
Aggregated totals of a merchant's sales over a period.
Reconciliation timeline of a specific transaction.
Sales statement export (asynchronous): scheduling, status consultation and file download.

The API does not store data: each request orchestrates acquirer calls in real time, shaping the response for direct consumption by the interface.

General conventions

Addressing

All business endpoints live under the prefix /transactions-data/v1 (configurable per environment). Examples in this document use the environment base URL https://{environment-host}/wlb/transactions-data/v1.

Authentication

Business endpoints require an OAuth2 Bearer (JWT) token issued by the corporate gateway, in the Authorization: Bearer <token> header.
Health probes (liveness/readiness) and /metrics are public.

Time zone

The date/time reference for the entire API is America/Sao_Paulo (Brasília, UTC-03:00). Functional consequences:

Dates and times exposed in responses are in Brasília time.
The query window (begin_date/end_date) is interpreted as full days in Brasília time (00:00:00 to 23:59:59 at offset -03:00).

Formats

Date: YYYY-MM-DD (e.g. 2026-03-30).
Time: HH:mm:ss (e.g. 08:40:26).
ISO date/time: with Brasília offset (e.g. 2026-08-20T16:06:21-03:00).

Response format

Business endpoints: return the domain payload directly (object or array), with no envelope.
Health endpoints: use a { success, data, meta } envelope.
Errors: flat { code, message } body. On validation errors, the body carries one message per invalid field.

Traceability

Each request receives/propagates an x-correlation-id (returned in the response and included in the error body) and a traceparent (W3C), useful for support and auditing.

Functional capabilities

Reconciled sales listing

Lists a merchant's reconciled sales over a period, paginated.

text

GET /transactions-data/v1/merchant/{merchant_id}/transactions/sales

text

GET /transactions-data/v1/merchant/{merchant_id}/transactions/sales

Query parameters

Parameter	Required	Rule	Description
`begin_date`	Yes	`YYYY-MM-DD`	Start of the window (full day, Brasília).
`end_date`	Yes	`YYYY-MM-DD`	End of the window. Must be later than `begin_date` and the interval must not exceed 3 months.
`size`	Yes	integer 1-200	Page size. Required — non-paginated queries are rejected.
`page`	No	integer >= 0 (default `0`)	Requested page (zero-based).
`status`	No	enum	Filters by transaction status (see Transaction status filter).

Response: JSON array of sales. Pagination metadata is sent in headers:

X-Page, X-Page-Size, X-Total-Elements, X-Total-Pages, X-Has-Next, X-Has-Previous, X-Next-Page, X-Previous-Page.

X-Next-Page/X-Previous-Page are omitted when there is no next/previous page.

Field dictionary of each sale

Field	Type	Description
`transaction_id`	number	Transaction identifier.
`date`	date	Transaction date in Brasília (`YYYY-MM-DD`).
`time`	time	Transaction time in Brasília (`HH:mm:ss`).
`amount`	number	Gross sale amount.
`paid_fee`	text	Paid fee, as a formatted percentage (e.g. `0.75%`). Computed over the gross amount.
`net_amount`	number	Net amount (gross minus paid fee), with 2 decimals.
`store_status`	text	Sale reconciliation status (see Reconciliation status).
`acquirer_nsu`	text	Acquirer NSU.
`authorization_code`	text	Authorization code. Omitted when not applicable to the payment method (e.g. Pix).
`merchant_id`	text	Merchant code.
`store_name`	text	Merchant name.
`nro_card`	text	Masked account identifier — card number or Pix key (see Sensitive data masking). Never in clear text.
`terminal_num`	text	Terminal number. Omitted when not applicable (e.g. Pix).
`modality`	object	Payment modality: `{ id, name, code, payment_type }` (e.g. Debit).
`capture_type`	object	Capture type: `{ id, description }` (e.g. `TEF`, `POS`, `INT`).
`brand`	object	Card brand/scheme: `{ id, name, code }` (e.g. Maestro).
`number_installments`	number	Number of installments (default `1`).

Relevant business rules

Resilience to partial data: descriptive fields missing at the acquirer are filled with safe defaults (empty strings, "zeroed" objects, number_installments = 1), so that a single anomalous record never breaks the page.
Omission by payment method: authorization_code and terminal_num are returned only when they carry applicable content.

Example:

bash

curl "https://{environment-host}/wlb/transactions-data/v1/merchant/15859682/transactions/sales?begin_date=2026-03-01&end_date=2026-03-30&page=0&size=20" \
  -H "Authorization: Bearer <token>"

bash

curl "https://{environment-host}/wlb/transactions-data/v1/merchant/15859682/transactions/sales?begin_date=2026-03-01&end_date=2026-03-30&page=0&size=20" \
  -H "Authorization: Bearer <token>"

Aggregated totals

Returns the consolidated totals of a merchant's sales in the period.

text

GET /transactions-data/v1/merchant/{merchant_id}/transactions/totals

text

GET /transactions-data/v1/merchant/{merchant_id}/transactions/totals

Query parameters

Parameter	Required	Rule	Description
`begin_date`	Yes	`YYYY-MM-DD`	Start of the window.
`end_date`	Yes	`YYYY-MM-DD`	End of the window. Must be later than `begin_date`; maximum interval of 3 months.
`mv_status`	No	enum (repeatable)	One or more movement statuses to filter by (see Reconciliation status).

Response

Field	Type	Description
`total_transactions`	number	Number of transactions in the period/filter.
`total_amount`	number	Sum of the amounts.
`total_average_ticket`	number	Average ticket.

Example:

bash

curl "https://{environment-host}/wlb/transactions-data/v1/merchant/15859682/transactions/totals?begin_date=2026-03-01&end_date=2026-03-30&mv_status=CONCILIATED" \
  -H "Authorization: Bearer <token>"

bash

curl "https://{environment-host}/wlb/transactions-data/v1/merchant/15859682/transactions/totals?begin_date=2026-03-01&end_date=2026-03-30&mv_status=CONCILIATED" \
  -H "Authorization: Bearer <token>"

Reconciliation timeline

Returns the reconciliation event history of one transaction, grouped by date.

text

GET /transactions-data/v1/merchant/{merchant_id}/transactions/{transaction_id}/timeline

text

GET /transactions-data/v1/merchant/{merchant_id}/transactions/{transaction_id}/timeline

Response: array of date groups: [{ date, items[] }].

Fields of each event (items[])

Field	Type	Description
`type`	text	Event type: `TRANSACTION` or `SETTLEMENT`.
`time`	time	Event time (`HH:mm:ss`). Absent when the acquirer omits it (e.g. `SETTLEMENT` events).
`status`	text	Textual status of the event.
`mv_status`	text	Reconciliation status of the event (see Reconciliation status).
`main_msg`	text	Main message of the event.
`secondary_msg`	text	Secondary/complementary message.

Example:

bash

curl "https://{environment-host}/wlb/transactions-data/v1/merchant/15859682/transactions/999303023738/timeline" \
  -H "Authorization: Bearer <token>"

bash

curl "https://{environment-host}/wlb/transactions-data/v1/merchant/15859682/transactions/999303023738/timeline" \
  -H "Authorization: Bearer <token>"

Sales statement export

Allows exporting a merchant's sales statement as a ZIP file. The flow is asynchronous and made up of three operations.

Functional flow

Schedule the export (POST) → receives export_id and status SCHEDULED.
Consult the status (GET) until it becomes COMPLETED.
Download the ZIP file (GET .../file).

Email alternative: if delivery_email is provided at scheduling time, the file is sent by email after processing (as arquivosExportadosAuttar.zip), dispensing with the manual download.

Schedule an export

text

POST /transactions-data/v1/merchant/{merchant_id}/transactions/sales/statement-exports

text

POST /transactions-data/v1/merchant/{merchant_id}/transactions/sales/statement-exports

Request body

Field	Required	Rule	Description
`begin_date`	Yes	`YYYY-MM-DD`	Start of the statement period.
`end_date`	Yes	`YYYY-MM-DD`	End of the period. Must not be earlier than `begin_date`; maximum interval of 31 days.
`movement_type`	Yes	enum	Movement type. Currently only `C` is supported.
`delivery_email`	No	valid email	If provided, the file is sent to this address.

The body is strict: unknown fields are rejected with 400.

Response: 202 Accepted

json

{ "export_id": "export-123", "status": "SCHEDULED" }

json

{ "export_id": "export-123", "status": "SCHEDULED" }

The Location header points to the consultation resource, e.g. Location: /transactions-data/v1/merchant/1719245/transactions/sales/statement-exports/export-123.

bash

curl -X POST "https://{environment-host}/wlb/transactions-data/v1/merchant/1719245/transactions/sales/statement-exports" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"begin_date":"2026-03-30","end_date":"2026-03-31","movement_type":"C","delivery_email":"merchant@example.com"}'

bash

curl -X POST "https://{environment-host}/wlb/transactions-data/v1/merchant/1719245/transactions/sales/statement-exports" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"begin_date":"2026-03-30","end_date":"2026-03-31","movement_type":"C","delivery_email":"merchant@example.com"}'

Consult an export status

text

GET /transactions-data/v1/merchant/{merchant_id}/transactions/sales/statement-exports/{export_id}

text

GET /transactions-data/v1/merchant/{merchant_id}/transactions/sales/statement-exports/{export_id}

Response

Field	Type	Description
`export_id`	text	Export identifier.
`status`	text	`PROCESSING`, `COMPLETED` or `FAILED` (see Statement export status).
`begin_date`	date	Start of the exported period.
`end_date`	date	End of the exported period.
`created_at`	date/time	Creation date/time (ISO, Brasília).
`delivery_email`	text	Delivery email. Omitted when not provided.
`files`	array	Generated files (`[{ file_name }]`). Empty while the status is not `COMPLETED`.

This operation never returns SCHEDULED: the initial state appears here as PROCESSING.

Download the export file

text

GET /transactions-data/v1/merchant/{merchant_id}/transactions/sales/statement-exports/{export_id}/file

text

GET /transactions-data/v1/merchant/{merchant_id}/transactions/sales/statement-exports/{export_id}/file

Returns 200 with a binary application/zip response, a Content-Disposition: attachment header and Content-Length (size in bytes). The default file name is arquivosExportacao.zip; if the upstream name is invalid/absent, the fallback statement-export-<export_id>.zip is used.

bash

curl -sS "https://{environment-host}/wlb/transactions-data/v1/merchant/1719245/transactions/sales/statement-exports/export-123/file" \
  -H "Authorization: Bearer <token>" \
  -o statement.zip

bash

curl -sS "https://{environment-host}/wlb/transactions-data/v1/merchant/1719245/transactions/sales/statement-exports/export-123/file" \
  -H "Authorization: Bearer <token>" \
  -o statement.zip

Status and enum dictionary

Transaction status filter

Values accepted by the sales status filter: IN_PROGRESS, APPROVED, UNDONE_CTF, REVERSAL, INVALID_STATUS, ADQ_DENIED, PENDING, REJECTED, DENIED, CANCELED, CANCELED_AQD.

Reconciliation status

Values of mv_status / store_status: PARTIALLY_CONCILIATED, MANUALLY_CONCILIATED, DIVERGENCE, MANUALLY_DELETED, NOT_CONCILIATED, CONCILIATED.

In sales responses (store_status) and timeline responses (mv_status), the value may come empty ("") when the acquirer does not report the status.

Timeline event type

Values of type: TRANSACTION and SETTLEMENT. SETTLEMENT events typically do not carry time.

Statement export status

On scheduling: SCHEDULED.
On consultation: PROCESSING, COMPLETED or FAILED.

Mapping from the source: not_processed → PROCESSING, success → COMPLETED, error → FAILED.

Capture type

capture_type.id is an open domain (not a closed enum). Values observed so far: TEF, POS, INT.

Cross-cutting business rules

Date window

Operation	Interval rule
Sales and Totals	`end_date` strictly later than `begin_date`; interval <= 3 months.
Statement export	`begin_date` not later than `end_date`; interval <= 31 days.

Format/required violations and "end date earlier than start date" result in 400. For the export, exceeding 31 days results in 422.

Sensitive data masking

To protect sensitive data (Pix key, CPF, CNPJ, phone, email, card number), the nro_card field is never exposed in clear text:

Only the last 4 characters stay visible; the rest becomes *, preserving the original length.
Values already masked at the source (containing *, such as 550209******5693) are kept as-is.
Values with 4 characters or fewer are fully masked.

Response reliability

Contract validation: acquirer responses are validated; corrupt/incompatible data becomes 502 instead of propagating to the consumer.
Resilience: each acquirer call has a timeout, retries for transient failures and a per-client circuit breaker.
Rate limiting: when the configured limit is exceeded, the API responds 429.

Error handling

Standard body: { "code": "...", "message": "..." } (with one message per invalid field on validation errors).

HTTP	`code`	When it occurs
`400`	`BAD_REQUEST`	Invalid parameter/body (format, required, unknown field) or `begin_date` later than `end_date`.
`404`	`NOT_FOUND`	Merchant, export or file not found.
`422`	`BUSINESS_RULE_VIOLATION`	Business rule violated (e.g. export with interval > 31 days).
`429`	`TOO_MANY_REQUESTS`	Request limit exceeded.
`500`	`INTERNAL_ERROR`	Unexpected failure. No internal detail leaked.
`502`	`UPSTREAM_ERROR`	Unexpected/invalid response from the acquirer.
`503`	`SERVICE_UNAVAILABLE`	Acquirer unavailable or circuit breaker open.

On 5xx responses, no internal or upstream detail is exposed.

Health and observability

Endpoint	Access	Description
`GET /health/liveness`	Public	Indicates the process is alive.
`GET /health/readiness`	Public	Checks dependencies (acquirer SSO). `200` when everything is `UP`; `503` if anything is `DOWN`.
`GET /metrics`	Public	Prometheus metrics (process + HTTP requests).

Glossary

BFF (Backend for Frontend): a back-end layer dedicated to serving a specific front-end, shaping and aggregating data from source systems.
Acquirer (Auttar): the acquiring platform that processes and reconciles the transactions; the source of this API's data.
Reconciliation: the process of matching the recorded sale with what was actually settled by the acquirer.
Settlement (SETTLEMENT): the sale payout/payment event.
NSU: unique sequential number identifying the transaction at the acquirer.
Average ticket: total amount divided by the number of transactions.
WLB (White Label): the white-label product that consumes this API.

En esta página

Transactions Data API (WLB)