VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Financeiro do seller

Saques e repasses

Pedir saque do saldo e consultar os repasses pagos ao seller.

Há duas coisas com nomes parecidos. O pedido de saque é o que o seller faz: "quero retirar R$ X do meu saldo". O repasse é o que a loja gera depois: o lote de pagamento de um período. Esta página cobre as duas rotas que criam o pedido e as duas que listam repasses.

Fluxo

Veja o saldo em Comissões, peça o saque, e acompanhe. Não há rota de seller para consultar o pedido de saque nem cancelá-lo: o status muda pela loja e aparece como reserved_cents no saldo.

Um pedido aberto por vez

Enquanto houver um pedido O, A ou P, um novo recebe 409 open_request_exists. O valor reservado também reduz available_cents, então um segundo pedido nem teria saldo.

Pedir saque

Cria um pedido de saque. Ele fica O (aberto) até a loja aprovar, processar e pagar. O valor pedido fica reservado no saldo (reserved_cents) enquanto o pedido estiver aberto. Só pode existir um pedido aberto por seller.

POST/api/v1/vendor/commissions/payout-requestSeller

Pedir saque do saldo disponível

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Corpo da requisição

amount_centsintegerpadrão: 0
Valor a sacar, em centavos. 0 saca tudo que está disponível.
bank_infoobject

Destino do pagamento. Não é validado pela API; envie certo.

methodstring
pixbank_transfer
Forma de pagamento.
pix_keystring
Chave PIX.
pix_typestring
cpfcnpjemailphonerandom
Tipo da chave PIX.
bank_codestring
Código do banco, em transferência.
agencystring
Agência.
accountstring
Conta.
holder_namestring
Nome do titular.
holder_docstring
CPF ou CNPJ do titular.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/commissions/payout-request" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amount_cents": 125000,
  "bank_info": {
    "method": "pix",
    "pix_key": "12345678909",
    "pix_type": "cpf",
    "holder_name": "Maria Souza",
    "holder_doc": "123.456.789-09"
  }
}'

Resposta

201Pedido criado
json
{
  "id": "7039e362-9ea6-4cdd-9b5e-07b9973cf99c",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "amount_cents": 125000,
  "status": "O",
  "bank_info": {
    "method": "pix",
    "pix_key": "12345678909",
    "pix_type": "cpf",
    "holder_name": "Maria Souza",
    "holder_doc": "123.456.789-09"
  },
  "admin_notes": "",
  "transaction_ref": "",
  "requested_at": "2026-10-11T12:00:00Z"
}

Campos da resposta

iduuid
Id do pedido de saque.
vendor_iduuid
Seller.
amount_centsinteger
Valor pedido, em centavos. Já é o valor resolvido quando você mandou 0.
statusstring
OAPCR
Situação em letra: O aberto, A aprovado, P em processamento, C concluído (pago), R recusado.
bank_infoobject|null
Destino que você enviou. null se não enviou.
admin_notesstring
Observação da loja. Vazio no início.
transaction_refstring
Referência bancária ou do PIX, preenchida quando a loja conclui o pagamento.
requested_atstring
Quando foi pedido, RFC 3339 em UTC.

Erros

StatusQuandoCorpo de exemplo
400amount_cents negativo, JSON inválido ou saldo insuficiente (o texto de detail vem em inglês).{"error":"failed to create payout request","detail":"insufficient balance: available 0, requested 0"}
409Já existe um pedido de saque aberto (O, A ou P). Só um por vez.{"error":"there is already an open payout request","detail":"open_request_exists"}
422A loja exige KYC (verificação de identidade) para sacar e o seller ainda não foi verificado.{"error":"kyc verification required before requesting payouts","detail":"kyc_required"}
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 usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Pedir saque (rota antiga)

Faz exatamente o mesmo que /commissions/payout-request (mesmo serviço, mesma tabela). A diferença é que aqui qualquer valor menor ou igual a zero significa "sacar tudo", inclusive negativo, e saldo zero responde 400 no available balance to withdraw. Em integração nova prefira a outra rota.

POST/api/v1/vendor/payouts/requestSeller

Mesmo pedido de saque, rota alternativa

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Corpo da requisição

amount_centsintegerpadrão: 0
Valor a sacar, em centavos. 0 saca tudo que está disponível.
bank_infoobject

Destino do pagamento. Não é validado pela API; envie certo.

methodstring
pixbank_transfer
Forma de pagamento.
pix_keystring
Chave PIX.
pix_typestring
cpfcnpjemailphonerandom
Tipo da chave PIX.
bank_codestring
Código do banco, em transferência.
agencystring
Agência.
accountstring
Conta.
holder_namestring
Nome do titular.
holder_docstring
CPF ou CNPJ do titular.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/payouts/request" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amount_cents": 125000,
  "bank_info": {
    "method": "pix",
    "pix_key": "12345678909",
    "pix_type": "cpf",
    "holder_name": "Maria Souza",
    "holder_doc": "123.456.789-09"
  }
}'

Resposta

201Pedido criado
json
{
  "id": "7039e362-9ea6-4cdd-9b5e-07b9973cf99c",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "amount_cents": 125000,
  "status": "O",
  "bank_info": {
    "method": "pix",
    "pix_key": "12345678909",
    "pix_type": "cpf",
    "holder_name": "Maria Souza",
    "holder_doc": "123.456.789-09"
  },
  "admin_notes": "",
  "transaction_ref": "",
  "requested_at": "2026-10-11T12:00:00Z"
}

Campos da resposta

iduuid
Id do pedido de saque.
vendor_iduuid
Seller.
amount_centsinteger
Valor pedido, em centavos. Já é o valor resolvido quando você mandou 0.
statusstring
OAPCR
Situação em letra: O aberto, A aprovado, P em processamento, C concluído (pago), R recusado.
bank_infoobject|null
Destino que você enviou. null se não enviou.
admin_notesstring
Observação da loja. Vazio no início.
transaction_refstring
Referência bancária ou do PIX, preenchida quando a loja conclui o pagamento.
requested_atstring
Quando foi pedido, RFC 3339 em UTC.

Erros

StatusQuandoCorpo de exemplo
400Saldo zero, JSON inválido ou saldo insuficiente.{"error":"no available balance to withdraw"}
409Já existe um pedido de saque aberto (O, A ou P). Só um por vez.{"error":"there is already an open payout request","detail":"open_request_exists"}
422A loja exige KYC (verificação de identidade) para sacar e o seller ainda não foi verificado.{"error":"kyc verification required before requesting payouts","detail":"kyc_required"}
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"]}

Listar repasses

Lista os repasses: lotes de pagamento por período que a loja gera para o seller. Não confunda com o pedido de saque (o que o seller pede e que as duas rotas acima criam). Só page e per_page são aceitos e a ordem é sempre a mais recente primeiro.

GET/api/v1/vendor/payoutsSeller

Repasses (pagamentos) gerados para o seller

Cabeçalhos

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

Parâmetros de consulta

pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
Itens por página, de 1 a 100. Fora disso vale 20.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/payouts?page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Repasses
json
{
  "payouts": [
    {
      "id": "e8ac32c6-98f3-423e-90da-cdbadb9f70ab",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "amount": 99816,
      "commission": 0,
      "net_amount": 99816,
      "status": "O",
      "payout_method": "pix",
      "reference": null,
      "period_start": "2026-07-01T00:00:00Z",
      "period_end": "2026-07-31T00:00:00Z",
      "created_at": "2026-07-13T22:34:24Z"
    }
  ],
  "total": 4,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

payoutsobject[]

Repasses da página. Pode vir null quando não há nenhum.

iduuid
Id do repasse.
vendor_iduuid
Seller.
amountinteger
Valor bruto do período, em centavos (líquido mais comissão).
commissioninteger
Comissão deduzida, em centavos.
net_amountinteger
O que o seller recebe, em centavos.
statusstring
Situação em letra: O pendente, P em processamento, C concluído, F falhou.
payout_methodstring
Forma de pagamento: pix ou bank_transfer.
referencestring|null
Referência bancária ou do PIX, quando paga.
period_startstring
Início do período coberto, data/hora em UTC.
period_endstring
Fim do período coberto, data/hora em UTC.
notesstring
Observação da loja. Omitido se vazio.
created_atstring
Criação, RFC 3339 em UTC.
completed_atstring
Quando foi concluído. Omitido antes disso.
totalinteger
Total de registros.
pageinteger
Página devolvida.
per_pageinteger
Tamanho da página aplicado.
total_pagesinteger
Número de páginas.

Erros

StatusQuandoCorpo de exemplo
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 usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Ver um repasse

Devolve um repasse do seller pelo id.

GET/api/v1/vendor/payouts/{id}Seller

Detalhe de um repasse

Cabeçalhos

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

Parâmetros de caminho

iduuidobrigatório
Id do repasse.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/payouts/e8ac32c6-98f3-423e-90da-cdbadb9f70ab" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Repasse
json
{
  "id": "e8ac32c6-98f3-423e-90da-cdbadb9f70ab",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "amount": 99816,
  "commission": 0,
  "net_amount": 99816,
  "status": "O",
  "payout_method": "pix",
  "reference": null,
  "period_start": "2026-07-01T00:00:00Z",
  "period_end": "2026-07-31T00:00:00Z",
  "created_at": "2026-07-13T22:34:24Z"
}

Campos da resposta

iduuid
Id do repasse.
vendor_iduuid
Seller.
amountinteger
Valor bruto do período, em centavos (líquido mais comissão).
commissioninteger
Comissão deduzida, em centavos.
net_amountinteger
O que o seller recebe, em centavos.
statusstring
Situação em letra: O pendente, P em processamento, C concluído, F falhou.
payout_methodstring
Forma de pagamento: pix ou bank_transfer.
referencestring|null
Referência bancária ou do PIX, quando paga.
period_startstring
Início do período coberto, data/hora em UTC.
period_endstring
Fim do período coberto, data/hora em UTC.
notesstring
Observação da loja. Omitido se vazio.
created_atstring
Criação, RFC 3339 em UTC.
completed_atstring
Quando foi concluído. Omitido antes disso.

Erros

StatusQuandoCorpo de exemplo
404Não existe repasse com esse id.{"error":"payout not found"}
403O repasse existe, mas é de outro seller.{"error":"access denied"}
500id não é um UUID válido. Hoje volta 500 em vez de 400; a mensagem está em detail.{"error":"failed to get payout","detail":"o valor \"xyz\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}
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"]}

Veja também

  • Comissões e saldo
  • Antecipação
  • Visão geral
Anterior
Comissões e saldo
Próxima
Antecipação (Antecipa Venddor)
Nesta página
  • Pedir saque
  • Exemplo de requisição
  • Resposta
  • Erros
  • Pedir saque (rota antiga)
  • Exemplo de requisição
  • Resposta
  • Erros
  • Listar repasses
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ver um repasse
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também