VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Pagar.me, chargebacks e disputas

Pagar.me: saldo e recebíveis

Consulta o painel financeiro do seller no Pagar.me: resumo, recebíveis, liquidações e agenda.

Quando a loja usa o Pagar.me como gateway com divisão automática (split), cada seller tem um recebedor (recipient) lá, e o dinheiro das vendas cai direto na conta dele, sem passar pelo saldo da loja. Estas quatro rotas são só leitura e devolvem o que o Pagar.me diz. Exigem o módulo pagarme e o privilégio financeiro.

Valores do Pagar.me

Todos os valores são inteiros em centavos, exatamente como o Pagar.me os envia. O estado (status) é o do Pagar.me, não uma letra da plataforma.

Recebedor primeiro

Sem recebedor vinculado ao seller, todas respondem 409 pagarme_recipient_missing. O vínculo é feito pela loja (administrador), não pelo seller.

Resumo financeiro

Mostra o painel financeiro do seller no Pagar.me: quanto já está disponível, quanto ainda aguarda liberação, quanto já foi transferido, o que cai nos próximos 7 dias e os 10 recebíveis mais recentes. Cada chamada consulta o Pagar.me ao vivo (três consultas), então pode ser lenta.

GET/api/v1/vendor/pagarme/summarySeller

Saldo e próximos recebimentos no Pagar.me

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/pagarme/summary" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Resumo
json
{
  "recipient_id": "rp_Xy9ZaBcDeFgHiJk3",
  "available_amount": 125000,
  "waiting_funds_amount": 54200,
  "transferred_amount": 980000,
  "upcoming_7days": 26890,
  "recent_payables": [
    {
      "id": 4587129,
      "status": "waiting_funds",
      "type": "credit",
      "amount": 27300,
      "fee": 410,
      "anticipation_fee": 0,
      "payment_date": "2026-10-20T00:00:00Z",
      "charge_id": "ch_Ab1CdEfGhIjKlMn2",
      "transaction_id": 90213344,
      "recipient_id": "rp_Xy9ZaBcDeFgHiJk3",
      "split_id": "sp_Lm4NoPqRsTuVwXy5"
    }
  ]
}

Campos da resposta

recipient_idstring
Id do recebedor no Pagar.me.
available_amountinteger
Disponível para transferir, em centavos.
waiting_funds_amountinteger
A receber (ainda não liberado), em centavos.
transferred_amountinteger
Já transferido para a conta do seller, em centavos.
upcoming_7daysinteger
Líquido (valor menos taxa) dos recebíveis waiting_funds com pagamento nos próximos 7 dias, em centavos.
recent_payablesobject[]

Os 10 recebíveis mais recentes.

idinteger
Id do recebível no Pagar.me.
statusstring
Situação no Pagar.me. Esta seção usa waiting_funds (a receber) e paid (pago).
typestring
Natureza: credit (venda) ou refund, chargeback, chargeback_refund (valores que saem).
amountinteger
Valor bruto, em centavos.
feeinteger
Taxa descontada, em centavos.
anticipation_feeinteger
Taxa de antecipação, em centavos.
payment_datestring
Data prevista ou efetiva do pagamento, RFC 3339.
charge_idstring
Cobrança (charge) de origem no Pagar.me.
transaction_idinteger
Transação de origem.
recipient_idstring
Recebedor (o seller).
split_idstring
Divisão do pagamento a que pertence.

Erros

StatusQuandoCorpo de exemplo
409O seller ainda não tem recebedor (recipient) cadastrado no Pagar.me.{"error":"pagarme_recipient_missing","detail":"pagarme: vendor has no recipient"}
503A loja não configurou a chave de API do Pagar.me.{"error":"pagarme_api_key_missing","detail":"pagarme: api key not configured"}
502O Pagar.me recusou ou falhou. O trecho da resposta dele vai em detail.{"error":"pagarme_upstream","detail":"pagarme: /payables returned 401: ..."}
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403Sub-conta do seller sem nenhum dos privilégios financeiro (a lista completa vem em privilege_required_any; o exemplo está cortado). O dono da loja passa sempre.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_financial","vendor_view_financial"]}
403O módulo pagarme está desligado nesta loja.{"error":"module_disabled","module":"pagarme"}

Recebíveis

Um recebível (payable) é uma parcela de dinheiro que o Pagar.me vai pagar ao seller por uma venda, já separada a taxa. Lista os recebíveis do seller com filtros e a paginação do próprio Pagar.me.

GET/api/v1/vendor/pagarme/payablesSeller

Recebíveis (payables) do seller no Pagar.me

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Parâmetros de consulta

statusstring
Filtra pelo status do Pagar.me, por exemplo waiting_funds ou paid.
typestring
Filtra pelo tipo do Pagar.me, por exemplo credit.
pageintegerpadrão: 1
Página, a partir de 1.
sizeintegerpadrão: 25
Itens por página, repassado ao Pagar.me.
date_fromstring
Data de pagamento inicial, YYYY-MM-DD (vira T00:00:00).
date_untilstring
Data de pagamento final, inclusive, YYYY-MM-DD (vira T23:59:59).

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/pagarme/payables?status=waiting_funds&page=1&size=25" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Recebíveis
json
{
  "data": [
    {
      "id": 4587129,
      "status": "waiting_funds",
      "type": "credit",
      "amount": 27300,
      "fee": 410,
      "anticipation_fee": 0,
      "payment_date": "2026-10-20T00:00:00Z",
      "charge_id": "ch_Ab1CdEfGhIjKlMn2",
      "transaction_id": 90213344,
      "recipient_id": "rp_Xy9ZaBcDeFgHiJk3",
      "split_id": "sp_Lm4NoPqRsTuVwXy5"
    }
  ],
  "paging": {
    "total": 1
  }
}

Campos da resposta

dataobject[]

Recebíveis da página.

idinteger
Id do recebível no Pagar.me.
statusstring
Situação no Pagar.me. Esta seção usa waiting_funds (a receber) e paid (pago).
typestring
Natureza: credit (venda) ou refund, chargeback, chargeback_refund (valores que saem).
amountinteger
Valor bruto, em centavos.
feeinteger
Taxa descontada, em centavos.
anticipation_feeinteger
Taxa de antecipação, em centavos.
payment_datestring
Data prevista ou efetiva do pagamento, RFC 3339.
charge_idstring
Cobrança (charge) de origem no Pagar.me.
transaction_idinteger
Transação de origem.
recipient_idstring
Recebedor (o seller).
split_idstring
Divisão do pagamento a que pertence.
pagingobject
total com a quantidade total e, quando há, previous e next (links do Pagar.me).

Erros

StatusQuandoCorpo de exemplo
409O seller ainda não tem recebedor (recipient) cadastrado no Pagar.me.{"error":"pagarme_recipient_missing","detail":"pagarme: vendor has no recipient"}
503A loja não configurou a chave de API do Pagar.me.{"error":"pagarme_api_key_missing","detail":"pagarme: api key not configured"}
502O Pagar.me recusou ou falhou. O trecho da resposta dele vai em detail.{"error":"pagarme_upstream","detail":"pagarme: /payables returned 401: ..."}
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403Sub-conta do seller sem nenhum dos privilégios financeiro (a lista completa vem em privilege_required_any; o exemplo está cortado). O dono da loja passa sempre.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_financial","vendor_view_financial"]}
403O módulo pagarme está desligado nesta loja.{"error":"module_disabled","module":"pagarme"}

Liquidações

Pega os recebíveis já pagos e os agrupa pelo dia do pagamento, com total, taxas e líquido de cada dia. Reembolsos e estornos entram com sinal negativo. O filtro status é sempre forçado para paid. Só a primeira página do Pagar.me é lida; use page/size para as próximas.

GET/api/v1/vendor/pagarme/settlementsSeller

Recebíveis pagos, agrupados por dia

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Parâmetros de consulta

typestring
Tipo do recebível no Pagar.me.
pageintegerpadrão: 1
Página, a partir de 1.
sizeintegerpadrão: 25
Itens por página.
date_fromstring
Data de pagamento inicial, YYYY-MM-DD (vira T00:00:00).
date_untilstring
Data de pagamento final, inclusive, YYYY-MM-DD (vira T23:59:59).

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/pagarme/settlements?date_from=2026-10-01&date_until=2026-10-11" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Liquidações
json
{
  "settlements": [
    {
      "date": "2026-10-09",
      "total": 27300,
      "fee_total": 410,
      "net_total": 26890,
      "count": 1,
      "payables": [
        {
          "id": 4587129,
          "status": "paid",
          "type": "credit",
          "amount": 27300,
          "fee": 410,
          "anticipation_fee": 0,
          "payment_date": "2026-10-20T00:00:00Z",
          "charge_id": "ch_Ab1CdEfGhIjKlMn2",
          "transaction_id": 90213344,
          "recipient_id": "rp_Xy9ZaBcDeFgHiJk3",
          "split_id": "sp_Lm4NoPqRsTuVwXy5"
        }
      ]
    }
  ]
}

Campos da resposta

settlementsobject[]

Um item por dia de pagamento.

datestring
Dia do pagamento, YYYY-MM-DD (ou unknown se o Pagar.me não informou).
totalinteger
Soma bruta do dia, em centavos, com reembolsos e estornos negativos.
fee_totalinteger
Soma das taxas do dia.
net_totalinteger
Líquido do dia: total menos fee_total.
countinteger
Quantidade de recebíveis no dia.
payablesobject[]
Os recebíveis do dia.

Erros

StatusQuandoCorpo de exemplo
409O seller ainda não tem recebedor (recipient) cadastrado no Pagar.me.{"error":"pagarme_recipient_missing","detail":"pagarme: vendor has no recipient"}
503A loja não configurou a chave de API do Pagar.me.{"error":"pagarme_api_key_missing","detail":"pagarme: api key not configured"}
502O Pagar.me recusou ou falhou. O trecho da resposta dele vai em detail.{"error":"pagarme_upstream","detail":"pagarme: /payables returned 401: ..."}
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403Sub-conta do seller sem nenhum dos privilégios financeiro (a lista completa vem em privilege_required_any; o exemplo está cortado). O dono da loja passa sempre.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_financial","vendor_view_financial"]}
403O módulo pagarme está desligado nesta loja.{"error":"module_disabled","module":"pagarme"}

Agenda de recebimento

Soma o líquido dos recebíveis waiting_funds que vencem entre hoje e daqui a 7 ou 30 dias (até 100 recebíveis considerados).

GET/api/v1/vendor/pagarme/scheduleSeller

O que o seller vai receber nos próximos 7 ou 30 dias

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Parâmetros de consulta

daysintegerpadrão: 7
730
Janela em dias. Qualquer valor diferente de 30 vale 7.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/pagarme/schedule?days=30" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Agenda
json
{
  "days": 30,
  "net_cents": 26890,
  "payables": [
    {
      "id": 4587129,
      "status": "waiting_funds",
      "type": "credit",
      "amount": 27300,
      "fee": 410,
      "anticipation_fee": 0,
      "payment_date": "2026-10-20T00:00:00Z",
      "charge_id": "ch_Ab1CdEfGhIjKlMn2",
      "transaction_id": 90213344,
      "recipient_id": "rp_Xy9ZaBcDeFgHiJk3",
      "split_id": "sp_Lm4NoPqRsTuVwXy5"
    }
  ]
}

Campos da resposta

daysinteger
Janela aplicada.
net_centsinteger
Líquido a receber na janela, em centavos.
payablesobject[]

Recebíveis considerados.

idinteger
Id do recebível no Pagar.me.
statusstring
Situação no Pagar.me. Esta seção usa waiting_funds (a receber) e paid (pago).
typestring
Natureza: credit (venda) ou refund, chargeback, chargeback_refund (valores que saem).
amountinteger
Valor bruto, em centavos.
feeinteger
Taxa descontada, em centavos.
anticipation_feeinteger
Taxa de antecipação, em centavos.
payment_datestring
Data prevista ou efetiva do pagamento, RFC 3339.
charge_idstring
Cobrança (charge) de origem no Pagar.me.
transaction_idinteger
Transação de origem.
recipient_idstring
Recebedor (o seller).
split_idstring
Divisão do pagamento a que pertence.

Erros

StatusQuandoCorpo de exemplo
409O seller ainda não tem recebedor (recipient) cadastrado no Pagar.me.{"error":"pagarme_recipient_missing","detail":"pagarme: vendor has no recipient"}
503A loja não configurou a chave de API do Pagar.me.{"error":"pagarme_api_key_missing","detail":"pagarme: api key not configured"}
502O Pagar.me recusou ou falhou. O trecho da resposta dele vai em detail.{"error":"pagarme_upstream","detail":"pagarme: /payables returned 401: ..."}
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403Sub-conta do seller sem nenhum dos privilégios financeiro (a lista completa vem em privilege_required_any; o exemplo está cortado). O dono da loja passa sempre.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_financial","vendor_view_financial"]}
403O módulo pagarme está desligado nesta loja.{"error":"module_disabled","module":"pagarme"}

Veja também

  • Transferências automáticas
  • Chargebacks
  • Visão geral
Anterior
Pagar.me, chargebacks e disputas
Próxima
Pagar.me: transferência automática
Nesta página
  • Resumo financeiro
  • Exemplo de requisição
  • Resposta
  • Erros
  • Recebíveis
  • Exemplo de requisição
  • Resposta
  • Erros
  • Liquidações
  • Exemplo de requisição
  • Resposta
  • Erros
  • Agenda de recebimento
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também