Data dictionary

Detailed description of entities, fields, and enumerations in the API

Overview

This dictionary documents the entities returned by the API, their fields, types, and allowed values. Use it as a reference when building your integration.

Entities

Card, CardTransaction, Category, CostCenter, Attachment

Enumerations

Card type, status, operation, transaction type

Main entities

CardTransaction

Represents a credit card purchase or related operation.

Field	Type	Required	Description
`id`	string	Yes	Unique transaction id
`operation`	enum	Yes	Operation type (see values)
`transactionDate`	string	Yes	Transaction time (ISO 8601)
`status`	enum	Yes	Status (see values)
`type`	enum	Yes	Transaction type (see values)
`merchant`	string	Yes	Merchant name
`amountBrl`	number	Yes	Amount in Brazilian Reais (BRL)
`exchangeRateUsd`	number	Yes	USD rate (for international)
`isCanceled`	boolean	Yes	Canceled or not
`isConciled`	boolean	Yes	Reconciled or not
`installment`	number	Yes	Installment number (1 = paid in full)
`card`	Card	Yes	Card used for the purchase
`category`	Category	Yes	Expense category
`costCenter`	CostCenter	Yes	Cost center
`attachments`	array[Attachment]	Yes	Linked receipts and documents

Example

{
  "id": "txn_abc123",
  "operation": "CASH_OUT",
  "transactionDate": "2025-01-15T14:30:00.000Z",
  "status": "PROCESSED",
  "type": "PURCHASE",
  "merchant": "UBER *TRIP",
  "amountBrl": 45.90,
  "exchangeRateUsd": 0,
  "isCanceled": false,
  "isConciled": true,
  "installment": 1,
  "card": {
    "id": "card_xyz789",
    "maskedNumber": "**** **** **** 1234",
    "responsibleName": "John Smith",
    "responsibleEmail": "john@company.com",
    "type": "VIRTUAL"
  },
  "category": {
    "id": "cat_001",
    "name": "Transport"
  },
  "costCenter": {
    "id": "cc_001",
    "name": "Sales"
  },
  "attachments": []
}

Card

A physical or virtual credit card.

Field	Type	Required	Description
`id`	string	Yes	Card id
`maskedNumber`	string	Yes	Masked PAN (e.g. `** ** 1234`)
`responsibleName`	string	Yes	Person responsible for the card
`responsibleEmail`	string	Yes	That person’s email
`type`	enum	Yes	Card type

Example

{
  "id": "card_xyz789",
  "maskedNumber": "**** **** **** 1234",
  "responsibleName": "Jane Doe",
  "responsibleEmail": "jane@company.com",
  "type": "PHYSICAL"
}

Field	Type	Required	Description
`id`	string	Yes	Category id
`name`	string	Yes	Category name

CostCenter

Cost center for expense allocation.

Field	Type	Required	Description
`id`	string	Yes	Cost center id
`name`	string	Yes	Cost center name

Example

{
  "id": "cc_001",
  "name": "Marketing"
}

Attachment

A file linked to a transaction (receipt, invoice, etc.).

Field	Type	Required	Description
`id`	string	Yes	Attachment id
`name`	string	Yes	File name
`_links`	object	No	HATEOAS links to the content

Example

{
  "id": "att_001",
  "name": "receipt.pdf",
  "_links": {
    "content": {
      "href": "/attachments/v1/content/att_001",
      "rel": "GET"
    }
  }
}

Download binary content with GET /attachments/v1/content/{attachmentId} in the API Reference.

Enumerations

operation

Direction of the financial movement.

Value	Description
`CASH_IN`	Money in (credit, refund)
`CASH_OUT`	Money out (purchase, cash advance)

status

Processing state.

Value	Description
`PENDING`	Pending
`PROCESSED`	Settled or processed
`CANCELED`	Canceled

type

Detailed transaction classification.

Value	Description
`PURCHASE`	Domestic purchase
`PURCHASE_INTERNATIONAL`	International purchase
`PURCHASE_BNPL`	Installment / BNPL purchase
`WITHDRAW`	Domestic cash advance
`WITHDRAW_INTERNATIONAL`	International cash advance
`WITHDRAW_FUNDS`	Funds withdrawal
`BALANCE_INQUIRY`	Balance inquiry
`PAYMENT_PLAN_INQUIRY`	Installment plan inquiry
`REFUND`	Domestic refund
`REFUND_INTERNATIONAL`	International refund
`REFUND_CREDIT_ADJUSTMENT`	Credit adjustment (refund)
`REVERSAL_CREDIT_ADJUSTMENT`	Reversal of credit adjustment
`REFUND_IOF`	IOF refund
`REFUND_PURCHASE_BNPL`	BNPL refund
`IOF`	IOF tax
`LIMIT`	Limit change (debit)
`LIMIT_CREDIT`	Limit change (credit)
`SUMMARY`	Summary or consolidation
`BILL_TARIFF`	Statement fee
`REFUND_BILL_TARIFF`	Statement fee refund
`INVOICE_PAYMENT`	Invoice payment

card.type

Value	Description
`VIRTUAL`	Virtual card (online)
`PHYSICAL`	Physical (plastic) card

Request objects

CardsTransactionRequest

Parameters to query the card statement.

Field	Type	Required	Description
`startDate`	string	Yes	Start of range (`YYYY-MM-DD`)
`endDate`	string	Yes	End of range (`YYYY-MM-DD`)
`limit`	integer	Yes	Page size (5–100)
`nextPageStartKey`	string	No	Pagination cursor

The queried range (endDate minus startDate) cannot exceed 62 days.

Example

{
  "startDate": "2025-01-01",
  "endDate": "2025-01-31",
  "limit": 50
}

Response objects

CardsTransactionResponse

Response for the card statement: list of transactions and optional next page.

Field	Type	Description
`transactions`	array[CardTransaction]	Transactions
`nextPageStartKey`	string	Next page token if more data exists

Example

{
  "transactions": [
    {
      "id": "txn_001",
      "operation": "CASH_OUT",
      "transactionDate": "2025-01-15T14:30:00.000Z",
      "status": "PROCESSED",
      "type": "PURCHASE",
      "merchant": "RESTAURANT XYZ",
      "amountBrl": 89.90
    }
  ],
  "nextPageStartKey": "eyJsYXN0SWQiOiJ0eG5fMDAxIn0="
}