PicPay MCP

Início

API Reference

Documentação das Tools

Referência técnica das tools disponíveis para consulta de saldo, boletos, cartões, investimentos, cofrinhos e Pix. Cada tool documenta seus parâmetros de entrada e o formato de retorno.

Endpoint https://mcp.svc.picpay.com/v2/mcp

Client ID [Coloque o client ID da loja]

balance_account_get

Consulta o saldo disponível e bloqueado da conta.

Parâmetros de entrada

Nenhum parâmetro necessário.

Retorno

Campo	Tipo	Descrição
withdrawable.available	float	Saldo disponível para saque
withdrawable.hold	float	Saldo em retenção
withdrawable.pending	float	Saldo pendente
blocked_value	float	Valor bloqueado por operações em andamento

bills_slips_list

Lista boletos registrados na conta, filtráveis por status.

Parâmetros de entrada

Parâmetro	Tipo	Obrigatório	Descrição
status	enum	Não	Filtro: PENDING, ACTIVE, PAID, CANCELED, PROCESSING, IGNORED, NOT_PAYABLE, MOVED, ALREADY_PAID, WAITING_BENEFICIARY_UPDATE. Padrão: PENDING e ACTIVE

Retorno

Campo	Tipo	Descrição
boletos[].assignor	string	Nome do cedente
boletos[].amount	string	Valor em reais
boletos[].due_date	string	Data de vencimento
boletos[].paid_date	string	Data de pagamento (se pago)
boletos[].status	string	Status atual do boleto
boletos[].barcode	string	Código de barras
total	int	Total de boletos retornados

cards_invoices_list

Lista faturas do cartão de crédito (aberta, fechada, futura).

Parâmetros de entrada

Nenhum parâmetro necessário.

Retorno

Campo	Tipo	Descrição
data[].status	string	Status: OPEN, CLOSED, FUTURE
data[].total_amount	string	Valor total da fatura
data[].due_date	string	Data de vencimento
data[].minimum_payment	string	Valor mínimo de pagamento

cards_invoice_summary_get

Consultar resumo da fatura. Consulta o resumo agregado de uma fatura específica, com totais por categoria. Use para obter uma visão geral da fatura; para lançamentos individuais, use cards_invoice_transactions_list; para listar faturas, use cards_invoices_list.

Parâmetros de entrada

Parâmetro	Tipo	Obrigatório	Descrição
invoice_id	string	Sim	Identificador da fatura

Retorno

Campo	Tipo	Descrição
categories[].total_amount	string	Valor total gasto na categoria
categories[].transaction_count	int	Quantidade de transações na categoria
categories[].percentage	float	Percentual da categoria no total da fatura

cards_invoice_transactions_list

Listar transações da fatura. Lista os lançamentos individuais de uma fatura específica, ordenados por data decrescente. Para o resumo por categoria, use cards_invoice_summary_get; para o extrato da conta, use statements_list.

Parâmetros de entrada

Parâmetro	Tipo	Obrigatório	Descrição
invoice_id	string	Sim	Identificador da fatura

Retorno

Campo	Tipo	Descrição
transactions[].description	string	Descrição da transação
transactions[].amount	string	Valor da transação
transactions[].date	string	Data da transação
transactions[].installment_info	string	Informações de parcelamento, quando aplicável
transactions[].category	string	Categoria da transação

cards_invoice_get

Consultar detalhes da fatura. Consulta as informações completas de uma fatura específica. Para listar faturas, use cards_invoices_list; para ver lançamentos individuais, use cards_invoice_transactions_list.

Parâmetros de entrada

Parâmetro	Tipo	Obrigatório	Descrição
invoice_id	string	Sim	Identificador da fatura

Retorno

Campo	Tipo	Descrição
total_value	string	Valor total da fatura
closing_date	string	Data de fechamento
due_date	string	Data de vencimento
paid_date	string	Data de pagamento, quando aplicável
status	string	Status atual da fatura

cards_list

Lista cartões de crédito ativos do usuário.

Parâmetros de entrada

Nenhum parâmetro necessário.

Retorno

Campo	Tipo	Descrição
cards[].last_four_digits	string	Últimos 4 dígitos
cards[].brand	string	Bandeira (ex: Visa, Mastercard)
cards[].status	string	Status do cartão
cards[].card_name	string	Nome impresso no cartão

investments_list

Consulta a carteira de investimentos consolidada do usuário.

Parâmetros de entrada

Nenhum parâmetro necessário.

Retorno

Campo	Tipo	Descrição
total_investido	string	Soma total investida
rentabilidade_12m.valor	string	Rentabilidade dos últimos 12 meses
investimentos[].nome	string	Nome do produto (ex: Cofrinhos, Renda Fixa)
investimentos[].valor	string	Valor investido no produto
investimentos[].percentual	string	Participação na carteira
investimentos[].rentabilidade	string	Rentabilidade do produto

piggy_list

Lista todos os cofrinhos do usuário com saldo e taxa de rendimento.

Parâmetros de entrada

Nenhum parâmetro necessário.

Retorno

Campo	Tipo	Descrição
saldo_total	string	Soma dos saldos de todos os cofrinhos
rendimento_total	string	Rendimento total acumulado
cofrinhos[].title	string	Nome do cofrinho
cofrinhos[].balance	string	Saldo atual
cofrinhos[].yield_description	string	Rendimento acumulado (ex: "+R$ 12,30")
cofrinhos[].description.text	string	Taxa de rendimento (ex: "102% do CDI")
cofrinhos[].wallet_name	string	Identificador para uso em outras operações
limite_atingido	boolean	Se o limite de 10 cofrinhos foi atingido

pix_contacts_list

Lista contatos e favoritos Pix, com filtro opcional.

Parâmetros de entrada

Parâmetro	Tipo	Obrigatório	Descrição
search	string	Não	Filtro por nome, chave Pix, banco ou CPF/CNPJ

Retorno

Campo	Tipo	Descrição
favorites[].name	string	Nome do contato favorito
favorites[].key	string	Chave Pix
favorites[].key_type	string	Tipo: CPF, EMAIL, PHONE_NUMBER, RANDOM
histories[].name	string	Nome do contato histórico
histories[].key	string	Chave Pix
histories[].key_type	string	Tipo da chave

pix_keys_list

Lista todas as chaves Pix registradas pelo usuário.

Parâmetros de entrada

Nenhum parâmetro necessário.

Retorno

Campo	Tipo	Descrição
data[].type	string	Status do registro da chave
data[].attributes.keyType	string	Tipo da chave: cpf, phone, email, random

pix_limits_get

Consulta os limites Pix diurno e noturno configurados para o usuário.

Parâmetros de entrada

Nenhum parâmetro necessário.

Retorno

Campo	Tipo	Descrição
diurno_limite	string	Limite diário total
diurno_disponivel	string	Disponível no período diurno
diurno_usado	string	Valor já utilizado hoje
diurno_maximo_por_transacao	string	Teto por transação diurna
noturno_limite	string	Limite noturno total
noturno_disponivel	string	Disponível no período noturno
noturno_usado	string	Valor já utilizado no período noturno
noturno_maximo_por_transacao	string	Teto por transação noturna
agendado_limite_diario	string	Limite diário para Pix agendado
horario_inicio_noturno	string	Horário de início do período noturno

statements_list

Consulta o extrato de movimentações da conta. Período padrão: últimos 7 dias. Máximo: 90 dias.

Parâmetros de entrada

Parâmetro	Tipo	Obrigatório	Descrição
data_inicio	string	Não	Data de início YYYY-MM-DD
data_fim	string	Não	Data de fim YYYY-MM-DD
limite	int	Não	Máximo de registros. Padrão: 15
tipo	enum	Não	RECENTE (padrão) ou FUTURO

Retorno

Campo	Tipo	Descrição
dias[].date	string	Data do agrupamento
dias[].transacoes[].type	string	Tipo da transação
dias[].transacoes[].description	string	Descrição legível
dias[].transacoes[].amount	string	Valor da transação
periodo.inicio	string	Início do período consultado
periodo.fim	string	Fim do período consultado