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, BankingTransaction, Category, CostCenter, Attachment, Vcn (coming soon)

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 (ULID, e.g. `01JB4M8WQ2YX5KN7RT9HF3DE6C`)
`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": "01JB4M8WQ2YX5KN7RT9HF3DE6C",
  "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": []
}

BankingTransaction

Represents an entry on the banking statement — Pix, TED, transfers between Conta Simples accounts, bill payments, and other account operations. Returned by Banking statement and updated by Update Banking Transaction.

Field	Type	Required	Description
`id`	integer	Yes	Transaction id. Use it in Update Banking Transaction and Banking Transaction Receipt
`transactionType`	object	Yes	Operation type: `{ id, description, icon, subType }`
`companyId`	string	Yes	Company id
`status`	integer	Yes	Numeric status: `1` canceled, `2` processed, `3` pending
`statusDescription`	string	Yes	Status label
`accountId`	integer	Yes	Bank account id
`finalCardNumber`	string	No	Last card digits, if any
`bearerName`	string	No	Cardholder name, if any
`transactionDate`	string	Yes	Transaction time (ISO 8601)
`brlAmount`	number	Yes	Amount in Brazilian Reais (BRL)
`usdAmount`	number	Yes	Amount in USD
`usdExchangeRate`	number	Yes	USD/BRL rate used
`usdExchangeRateDate`	string	No	When the rate was set
`totalTransactionAmount`	number	Yes	Total amount, fees included
`iofAmount`	number	Yes	IOF amount
`feeServiceAmount`	number	Yes	Service fee amount
`mccCode`	integer	No	Merchant MCC code
`mccGroup`	integer	No	Merchant MCC group
`idPurchaseEvent`	integer	No	Linked purchase event id
`mccDescription`	string	No	Merchant MCC description
`sourceDestinationName`	string	No	Source or destination name
`placeEstablishment`	string	No	Merchant location
`attachments`	array[Attachment]	Yes	Documents attached to the transaction (invoices, receipts). Distinct from `showReceipt`
`conciliation`	object	No	Reconciliation state: `{ description, conciled }` — `conciled: true` once the transaction has been reviewed
`showReceipt`	boolean	Yes	Whether the operation generated a bank receipt on the platform. Check this field before calling Banking Transaction Receipt; it is not an attachment — for documents, use `attachments`
`description`	string	No	Transaction description
`notes`	string	No	Transaction note (editable, up to 1000 characters)
`category`	object	No	Transaction category: `{ id, description }`
`costCenter`	object	No	Cost center: `{ id, description }`
`user`	object	No	User responsible: `{ id, email }`
`requesterUser`	object	No	Requesting user: `{ id, email }`
`customCategory`	object	No	Custom category: `{ id, name }`

Reconciliation reads and writes use different fields. On the statement, the state comes in conciliation.conciled. To reconcile, send isConciled at the root of the Update Banking Transaction body — the field accepts true only, and reconciliation is irreversible through the API.

Example

{
  "id": 987654,
  "transactionType": {
    "id": 12,
    "description": "PIX SENT",
    "icon": "pix",
    "subType": "PIX_OUT"
  },
  "companyId": "01JB4M8WQ2YX5KN7RT9HF3DE6C",
  "status": 2,
  "statusDescription": "PROCESSED",
  "accountId": 4321,
  "transactionDate": "2025-01-15T13:05:22.000Z",
  "brlAmount": 1250.00,
  "usdAmount": 0,
  "usdExchangeRate": 0,
  "totalTransactionAmount": 1250.00,
  "iofAmount": 0,
  "feeServiceAmount": 0,
  "sourceDestinationName": "Example Supplier LTDA",
  "attachments": [],
  "conciliation": {
    "description": "Reviewed",
    "conciled": true
  },
  "showReceipt": true,
  "description": "Supplier payment",
  "notes": "Ref. order 4471",
  "category": {
    "id": "cat_014",
    "description": "Suppliers"
  },
  "costCenter": {
    "id": "cc_002",
    "description": "Operations"
  },
  "user": {
    "id": "usr_001",
    "email": "finance@company.example"
  },
  "customCategory": {
    "id": 7,
    "name": "Supplies"
  }
}

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.

Vcn

🚧 Coming soon — the VCN endpoints are not yet available in Sandbox or Production. The terms below are already published so you can prepare your integration.

Restricted-use virtual card (VCN, Virtual Card Number) issued to pay for a travel booking — lodging (HOTEL) or air (AERIAL) — or a use you define (CUSTOM, e.g. one top-up-able card per supplier). Returned by Create VCN and updated by Update VCN.

Field	Type	Required	Description
`vcnId`	string	Yes	VCN identifier (ULID). Addresses Update VCN and Reveal VCN card data
`type`	enum	Yes	What the card is tied to: `HOTEL`, `AERIAL` or `CUSTOM`
`partner`	string	Yes	Integrator platform, resolved from the credential and echoed in the response — the partner does not send it
`hotelBooking.reservationId`	string	Conditional	Booking id in the OBT — idempotency key for `HOTEL`
`flightBooking.recordLocator`	string	Conditional	Booking locator (PNR, Passenger Name Record) — idempotency key for `AERIAL`
`reference.id`	string	Conditional	Opaque identifier you define — idempotency key for `CUSTOM`
`status`	enum	Yes	`ACTIVE`, `BLOCKED` or `CANCELLED`
`startDate` / `endDate`	string	Yes	Card usage window, as pure dates (`YYYY-MM-DD`) — what you sent in the request or, when absent, the issuance day and the type default. Same names in both directions; not the physical card expiration (`card.expirationDate`)
`limit`	object	Yes	Current spending ceiling `{value, currency}` (decimal, 2 places): sent for `CUSTOM`, derived from `amount` for booking types
`card`	object	Yes	`pan`, `cvv` and `expirationDate` in clear text — do not log or cache

Full request and response examples in the endpoint 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": "01JB4M9XR3ZY6LN8SU0IG4EF7D",
      "operation": "CASH_OUT",
      "transactionDate": "2025-01-15T14:30:00.000Z",
      "status": "PROCESSED",
      "type": "PURCHASE",
      "merchant": "RESTAURANT XYZ",
      "amountBrl": 89.90
    }
  ],
  "nextPageStartKey": "eyJsYXN0SWQiOiJ0eG5fMDAxIn0="
}

Global rules

Dates and ranges

Input format: YYYY-MM-DD (e.g. 2025-01-15)
Output format: full ISO 8601 in UTC (e.g. 2025-01-15T14:30:00.000Z)
Maximum range: 62 days per request
Timezone: UTC

Pagination

Minimum page size: 5
Maximum page size: 100
Cursor: nextPageStartKey is opaque — do not parse or change it

Attachments and links

Attachments can include HATEOAS _links for the download URL
Use GET /attachments/v1/content/{attachmentId} to download the file
Supported: image/png, image/jpeg, application/pdf

Next steps

Best practices

Pagination, retry, and attachment downloads.

Integration flow

Sandbox to Production, step by step.

API Reference

Technical endpoint reference.

Common errors

Troubleshoot errors.

Was this page helpful?