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`

Cartão que a instituição deixou de compartilhar

No Open Finance, cada cartão é um recurso do consentimento. A instituição pode tirar um cartão já sincronizado do consentimento ou suspendê-lo por um tempo. Quando isso acontece, a Malvo para de buscar o cartão, mantém a conta, as faturas e as transações já recebidas, e não avança o updatedAt dele. O Item termina UPDATED com executionStatus=PARTIAL_SUCCESS, e statusDetail.creditCards traz isUpdated: false com um destes avisos:

`code`	O que aconteceu	O que fazer
`RESOURCE_NO_LONGER_SHARED`	O cartão saiu do consentimento: a instituição não o lista mais, o marcou como indisponível de forma definitiva ou parou de servi-lo.	Peça ao usuário para reconectar o Item e selecionar o cartão na instituição.
`RESOURCE_TEMPORARILY_UNAVAILABLE`	A instituição suspendeu o cartão temporariamente (por exemplo, bloqueio da conta cartão).	Espere. A Malvo retoma a coleta sozinha quando a instituição liberar o cartão.

{
  "creditCards": {
    "isUpdated": false,
    "warnings": [
      {
        "code": "RESOURCE_NO_LONGER_SHARED",
        "message": "A instituição deixou de compartilhar o cartão final 5270 neste consentimento. Para voltar a receber os dados, reconecte a conta selecionando o cartão.",
        "providerMessage": null
      }
    ]
  }
}

A message traz os quatro últimos dígitos do number quando ele existe. Quando o cartão volta a ser compartilhado, o aviso some e a coleta continua de onde parou, sem reimportar os 12 meses de histórico. Nenhum webhook novo é emitido: o aviso chega no item/updated da sincronização. Cartão novo que a instituição já anunciou no consentimento, mas ainda não serve, aparece como RESOURCE_NOT_PUBLISHED. Nesse caso não é preciso reconectar.

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.

Fatura fechada sem transações

Algumas instituições publicam a fatura fechada antes das compras dela. Nesses cartões, a fatura pode aparecer em GET /bills alguns dias antes de GET /transactions?accountId={accountId}&billId={billId} trazer qualquer resultado. Quando surge um billId novo sem transações, a Malvo relê o histórico do cartão sem esperar a cadência semanal, dentro do teto de 4 leituras de histórico por mês. Se as compras ainda não vierem, há uma nova tentativa cerca de 24 h depois. Depois disso, o Item traz o aviso CC_001 em statusDetail.creditCards.warnings:

{
  "creditCards": {
    "isUpdated": true,
    "warnings": [
      {
        "code": "CC_001",
        "message": "Transações da fatura ainda não disponibilizadas pela instituição",
        "providerMessage": null
      }
    ]
  }
}

O aviso sai no sync em que as transações chegam, e elas chegam por transactions/created. Detalhes em Limites do Open Finance Brasil.

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.

Valores em reais

amount, creditCardMetadata.totalAmount e Bill.totalAmount são números decimais em reais, com até duas casas. R$ 173,90 (17.390 centavos) chega no JSON como 173.90, e não como o inteiro 17390. A unidade é a mesma em produção e no sandbox. Um valor que a instituição envia como "184.2700" chega como 184.27.

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).

Realize — billClosingDate igual ao dueDate

A Realize devolve billClosingDate igual ao dueDate e publica as compras da fatura fechada só no histórico do cartão. A Malvo não usa a data de fechamento como gatilho: a releitura parte do billId novo na lista de faturas. Veja Fatura fechada sem transações.

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.

Como testar no sandbox

Nos conectores mockados locais (0–99), o cartão fecha no dia 8 e vence no dia 15, no fuso America/Sao_Paulo. As compras do ciclo aberto chegam como PENDING, sem billId, e a fatura desse ciclo não aparece em /bills. Para ver a transição PENDING → POSTED sem esperar o fechamento, chame POST /items/{id}/sandbox/close-bill com uma aplicação SANDBOX: o ciclo aberto fecha, as mesmas transações recebem o billId e você recebe transactions/updated. Os valores continuam em reais (173.90), como em produção. No sandbox, todo o ciclo aberto aparece como PENDING, e não só a janela de 7 dias de produção. Detalhes, códigos de erro e limites do mock estão na página Sandbox.

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`)

Cartão que a instituição deixou de compartilhar

Faturas (`GET /bills`)

Conferindo o fechamento (settlement check)

Disponibilidade

Fatura fechada sem transações

Parcelamentos via `creditCardMetadata`

Ciclo de vida da parcela

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

Valores em reais

Gotchas por instituição

Como testar no sandbox

Próximos passos

Sincronizar transações

Reconciliação

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

​Cartão que a instituição deixou de compartilhar

​Faturas (GET /bills)

​Conferindo o fechamento (settlement check)

​Disponibilidade

​Fatura fechada sem transações

​Parcelamentos via creditCardMetadata

​Ciclo de vida da parcela

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

​Valores em reais

​Gotchas por instituição

​Como testar no sandbox

​Próximos passos

Sincronizar transações

Reconciliação

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

Cartão que a instituição deixou de compartilhar

Faturas (`GET /bills`)

Conferindo o fechamento (settlement check)

Disponibilidade

Fatura fechada sem transações

Parcelamentos via `creditCardMetadata`

Ciclo de vida da parcela

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

Valores em reais

Gotchas por instituição

Como testar no sandbox

Próximos passos