Cartões de crédito e faturas

Um cartão de crédito é uma conta com type=CREDIT e subtype=CREDIT_CARD. Os limites, o status e as datas de fechamento/vencimento vivem em creditData; as faturas vivem no recurso Bill; e as compras (inclusive parcelamentos) chegam como transações com creditCardMetadata.

Todos os endpoints exigem o header X-API-KEY e respondem em https://api.malvo.io. As transações de cartão são normalizadas: a convenção de sinal de amount é diferente da de contas bancárias — veja Convenção de sinal.

A conta de cartão (`type=CREDIT`)

Liste as contas do Item e filtre por type=CREDIT para encontrar os cartões.

curl "https://api.malvo.io/accounts?itemId=a0922d6f-2007-4169-a181-b961500608db&type=CREDIT" \
  -H "X-API-KEY: $MALVO_API_KEY"

const res = await fetch(
  `https://api.malvo.io/accounts?itemId=${itemId}&type=CREDIT`,
  { headers: { "X-API-KEY": apiKey } },
);
const { results: cards } = await res.json();

Cada cartão traz o objeto creditData:

Account (type=CREDIT)

{
  "id": "a658c848-e475-457b-8565-d1fffba127c4",
  "type": "CREDIT",
  "subtype": "CREDIT_CARD",
  "number": "xxxx8670",
  "name": "Mastercard Black",
  "marketingName": "MALVO UNICLASS MASTERCARD BLACK",
  "balance": 120950,
  "itemId": "a0922d6f-2007-4169-a181-b961500608db",
  "taxNumber": "416.799.495-00",
  "owner": "Maria Oliveira",
  "currencyCode": "BRL",
  "creditData": {
    "level": "BLACK",
    "brand": "MASTERCARD",
    "balanceCloseDate": "2026-07-03",
    "balanceDueDate": "2026-07-10",
    "availableCreditLimit": 200000,
    "balanceForeignCurrency": 0,
    "minimumPayment": 16190,
    "creditLimit": 300000,
    "status": "ACTIVE",
    "holderType": "MAIN"
  }
}

Em cartão, balance é o valor da fatura atualmente aberta (não é dinheiro disponível). A posição total de crédito é creditLimit = availableCreditLimit + balance + dívida não paga anterior. O number vem mascarado nos últimos 4 dígitos (ex.: "xxxx8670").

Campos relevantes de creditData:

Campo	Tipo	Descrição
`level`	string	Nível do cartão (ex.: `"BLACK"`, `"Signature"`)
`brand`	string	Bandeira (`"MASTERCARD"`, `"Visa"`, `"Elo"`)
`balanceCloseDate`	date-time	Data em que a fatura atual fechou
`balanceDueDate`	date-time	Vencimento da fatura
`availableCreditLimit`	number	Limite disponível para gastar
`minimumPayment`	number	Pagamento mínimo
`creditLimit`	number	Limite máximo do cartão
`status`	enum	`ACTIVE` \| `BLOCKED` \| `CANCELLED`
`holderType`	enum	`MAIN` \| `ADDITIONAL`

Faturas (`GET /bills`)

Liste as faturas de um cartão passando o accountId (obrigatório, e precisa ser uma conta CREDIT_CARD):

curl "https://api.malvo.io/bills?accountId=a658c848-e475-457b-8565-d1fffba127c4" \
  -H "X-API-KEY: $MALVO_API_KEY"

const res = await fetch(
  `https://api.malvo.io/bills?accountId=${accountId}`,
  { headers: { "X-API-KEY": apiKey } },
);
const { results: bills } = await res.json();

Bill

{
  "id": "05c693bf-c196-47ea-a28c-8251d6bb8a06",
  "dueDate": "2026-07-20T00:00:00",
  "totalAmount": 50000,
  "totalAmountCurrencyCode": "BRL",
  "minimumPaymentAmount": 50000,
  "allowsInstallments": true,
  "financeCharges": [
    {
      "id": "123456bf-c196-47ea-a28c-8251d6bb8777",
      "type": "IOF",
      "amount": 20.51,
      "currencyCode": "BRL",
      "additionalInfo": "NA"
    }
  ]
}

Campo	Tipo	Descrição
`dueDate`	date-time	Vencimento mostrado ao cliente
`totalAmount`	number	Valor total da fatura
`minimumPaymentAmount`	number	Pagamento mínimo
`allowsInstallments`	boolean	Se a fatura pode ser parcelada
`financeCharges`	array	Encargos: `LATE_PAYMENT_REMUNERATIVE_INTEREST` \| `LATE_PAYMENT_FEE` \| `LATE_PAYMENT_INTEREST` \| `IOF` \| `OTHER`
`payments`	array	Pagamentos: `valueType` (`INSTALLMENT_PAYMENT`/`FULL_PAYMENT`/`OTHER_PAYMENT`), `paymentMode` (`DEBIT_ACCOUNT`/`BANK_SLIP`/`PAYROLL_DEDUCTION`/`PIX`)

No additionalInfo dos encargos: o campo é livre, mas obrigatório quando type = OTHER. Em GET /bills/{id} (retrieve), o objeto também traz accountId e cada encargo carrega o creditCardBillId da fatura-pai.

Conferindo o fechamento (settlement check)

Uma fatura N está quitada quando os encargos e pagamentos da fatura seguinte (N+1) fecham a conta:

totalAmount(Fatura N) + soma(financeCharges(Fatura N+1)) === soma(payments(Fatura N+1))

Em pseudo-código:

function isSettled(billN: Bill, billNext: Bill): boolean {
  const charges = sum(billNext.financeCharges.map((c) => c.amount));
  const payments = sum(billNext.payments.map((p) => p.amount));
  return billN.totalAmount + charges === payments;
}

Disponibilidade

Em produção (Open Finance), faturas estão disponíveis para todas as instituições reguladas.

Parcelamentos via `creditCardMetadata`

O Open Finance não fornece um id único agrupando todas as parcelas de uma mesma compra. Cada parcela aparece como uma transação com o objeto creditCardMetadata, que carrega o número da parcela, o total de parcelas, o valor cheio e — quando a fatura fecha — o billId.

Transação parcelada

{
  "id": "ff9ed929-edc4-408c-a959-d51f79ab1814",
  "description": "MERCADOLIVRE*2PRODUTOS",
  "currencyCode": "BRL",
  "amount": 159.2,
  "date": "2026-06-14T00:00:00.000Z",
  "accountId": "562b795d-1653-429f-be86-74ead9502813",
  "status": "POSTED",
  "type": "DEBIT",
  "creditCardMetadata": {
    "totalAmount": 320,
    "totalInstallments": 2,
    "installmentNumber": 2,
    "purchaseDate": "2026-05-14T00:00:00.000Z",
    "payeeMCC": 1234,
    "cardNumber": "0597",
    "billId": "abced929-edc4-408c-a959-d51f79ab1123"
  }
}

Ciclo de vida da parcela

PENDING — sem billId

A compra aparece nas transações correntes (últimos 7 dias) com status=PENDING e sem creditCardMetadata.billId — a fatura ainda está aberta.

POSTED — billId definido

Quando o extrato fecha, a transação vira status=POSTED e creditCardMetadata.billId é preenchido. Essa transição dispara o webhook transactions/updated.

Leitura por fatura

As transações de uma fatura fechada específica são lidas pelo filtro legado GET /transactions?accountId={accountId}&billId={billId}.

curl "https://api.malvo.io/transactions?accountId=562b795d-1653-429f-be86-74ead9502813&billId=abced929-edc4-408c-a959-d51f79ab1123" \
  -H "X-API-KEY: $MALVO_API_KEY"

const url = new URL("https://api.malvo.io/transactions");
url.searchParams.set("accountId", accountId);
url.searchParams.set("billId", billId);
const res = await fetch(url, { headers: { "X-API-KEY": apiKey } });
const { results } = await res.json();

Como não há id de agrupamento, junte as parcelas de uma mesma compra heuristicamente por (merchantName, totalAmount, totalInstallments, purchaseDate). E assine transactions/created e transactions/updated para capturar parcelas que caem fora da janela corrente de 7 dias.

Convenção de sinal do `amount` no cartão

Em contas de cartão (type=CREDIT) o sinal de amount é invertido em relação a contas bancárias, mas o campo type continua normalizado para a perspectiva do titular:

Movimento	`amount`	`type`
Compra / gasto	positivo	`DEBIT`
Pagamento / estorno no cartão	negativo	`CREDIT`

Em contas bancárias (type=BANK) é o oposto: débitos são negativos e créditos positivos, e o sinal sempre concorda com type. Trate cada tipo de conta separadamente ao somar gastos.

Gotchas por instituição

Algumas instituições expõem parcelamentos de formas diferentes. Trate estes casos explicitamente ao consolidar gastos:

BTG (connectorId 614) — parcelas futuras como PENDING

O BTG traz todas as parcelas futuras já como transações PENDING. Se você somar tudo sem filtrar por status, vai contar gastos que ainda não ocorreram. Para o gasto do mês, use apenas as parcelas POSTED (ou o installmentNumber corrente).

XP (connectorId 602) — valor total da compra

A XP traz o valor total da compra (não o valor da parcela individual). Antes de somar, cheque creditCardMetadata.totalInstallments/installmentNumber e divida pelo total de parcelas para não inflar o gasto.

Próximos passos

Sincronizar transações

Paginação por cursor e atualização incremental com createdAtFrom.

Reconciliação

Webhooks + job noturno para nunca perder uma transição PENDING→POSTED.

Comece aqui

Conceitos

Connect Widget

Webhooks

Guias

Conta & Dashboard

Sandbox & Suporte

Cartões de crédito e faturas

A conta de cartão (`type=CREDIT`)

Faturas (`GET /bills`)

Conferindo o fechamento (settlement check)

Disponibilidade

Parcelamentos via `creditCardMetadata`

Ciclo de vida da parcela

Convenção de sinal do `amount` no cartão

Gotchas por instituição

Próximos passos

Sincronizar transações

Reconciliação

​A conta de cartão (type=CREDIT)

​Faturas (GET /bills)

​Conferindo o fechamento (settlement check)

​Disponibilidade

​Parcelamentos via creditCardMetadata

​Ciclo de vida da parcela

​Convenção de sinal do amount no cartão

​Gotchas por instituição

​Próximos passos

Sincronizar transações

Reconciliação

A conta de cartão (`type=CREDIT`)

Faturas (`GET /bills`)

Conferindo o fechamento (settlement check)

Disponibilidade

Parcelamentos via `creditCardMetadata`

Ciclo de vida da parcela

Convenção de sinal do `amount` no cartão

Gotchas por instituição

Próximos passos