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

Divisão do pagamento

Como o valor de um pedido de vários sellers é dividido entre cada seller e a loja, e o acompanhamento de cada fatia.

Em um marketplace, um único pagamento do cliente cobre itens de sellers diferentes. A divisão (split) registra quanto de cada pagamento pertence a cada seller e quanto fica com a loja de comissão. As rotas abaixo servem para o financeiro conferir e dar baixa nas fatias.

Listar divisões

Quando um pedido tem itens de sellers diferentes, o pagamento é dividido: uma fatia por seller e uma para a loja. Esta rota lista essas fatias, uma linha por destinatário.

GET/api/v1/admin/payment-splitsAdmin

Lista as divisões do pagamento entre seller e loja

Autenticação: Authorization: Bearer <token> de um administrador com view_vendors ou manage_vendors (a escrita exige manage_vendors). Requer o módulo direct-payments ativo.

Parâmetros de consulta

statusstring
pendingprocessingcompletedfailedrefunded
pending, processing, completed, failed ou refunded. processing e pending retornam as mesmas linhas.
vendor_iduuid
Só as fatias de um seller (UUID completo).
order_iduuid
Só as fatias de um pedido.
searchstring
Trecho do número do pedido.
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
De 1 a 100. Fora disso vale 20.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/payment-splits?status=pending&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Divisões devolvidas
json
{
  "splits": [
    {
      "id": "e596dfec-f18d-4946-9950-9199b26e5516",
      "order_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Seller Teste",
      "order_number": "PEDIDO-20261010-0004",
      "recipient_type": "vendor",
      "amount": 27300,
      "commission_amount": 2700,
      "status": "pending",
      "payment_method": "pix",
      "created_at": "2026-10-11T02:56:38.077512Z",
      "updated_at": "2026-10-11T02:56:38.077512Z"
    }
  ],
  "total": 75296,
  "page": 1,
  "per_page": 20,
  "total_pages": 3765
}

Campos da resposta

splitsarray
Fatias da página.
splits[].iduuid
Identificador da divisão.
splits[].order_iduuid
Pedido dividido.
splits[].vendor_iduuid
Seller que recebe. Omitido na fatia da própria loja.
splits[].vendor_namestring
Nome do seller. Omitido na fatia da loja.
splits[].order_numberstring
Número do pedido, o mesmo que o cliente vê.
splits[].recipient_typestring
vendormarketplace
vendor (fatia de um seller) ou marketplace (fatia da loja).
splits[].amountinteger
Valor da fatia antes da comissão, em centavos.
splits[].commission_amountinteger
Comissão da loja descontada dessa fatia, em centavos.
splits[].statusstring
pendingcompletedfailedrefunded
pending, completed, failed ou refunded. Na leitura nunca aparece processing: ele é gravado junto com pending.
splits[].payment_methodstring
Forma de pagamento do pedido.
splits[].payment_refstring
Comprovante do repasse dessa fatia, quando informado.
splits[].error_messagestring
Motivo da falha, quando informado.
splits[].processed_atstring
Quando foi concluída. Só nas concluídas.
splits[].created_atstring
Criação, RFC 3339 em UTC.
splits[].updated_atstring
Última alteração.
totalinteger
Total com o filtro.
pageinteger
Página devolvida.
per_pageinteger
Tamanho de página usado.
total_pagesinteger
Total de páginas.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"direct-payments"} / {"error":"insufficient privileges","required":"manage_vendors"}
500vendor_id/order_id que não é UUID, ou falha na consulta{"error":"failed to list payment splits","detail":"..."}

Estatísticas das divisões

Totais agregados das fatias, da loja inteira ou de um seller.

GET/api/v1/admin/payment-splits/statsAdmin

Totais das divisões de pagamento

Autenticação: Authorization: Bearer <token> de um administrador com view_vendors ou manage_vendors (a escrita exige manage_vendors). Requer o módulo direct-payments ativo.

Parâmetros de consulta

vendor_iduuid
Restringe a um seller. Omitido, soma tudo.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/payment-splits/stats?vendor_id=94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Totais devolvidos
json
{
  "total_splits": 75296,
  "pending_splits": 0,
  "completed_splits": 0,
  "failed_splits": 0,
  "total_amount": 4822665587,
  "total_commission": 253823873
}

Campos da resposta

total_splitsinteger
Quantidade de fatias.
pending_splitsinteger
Pretendia contar as pendentes. Hoje fica em 0 (veja o aviso).
completed_splitsinteger
Pretendia contar as concluídas. Hoje fica em 0.
failed_splitsinteger
Pretendia contar as que falharam. Hoje fica em 0.
total_amountinteger
Soma das fatias, em centavos.
total_commissioninteger
Soma das comissões, em centavos.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"direct-payments"} / {"error":"insufficient privileges","required":"manage_vendors"}
500vendor_id que não é UUID ou falha na consulta{"error":"failed to get split stats","detail":"..."}
Contadores por estado não funcionam

pending_splits, completed_splits e failed_splits voltam 0 mesmo quando há fatias nesses estados (a contagem compara a letra gravada com a palavra). Use total_splits, total_amount e total_commission, e conte por estado com a lista filtrada por status e lendo total.

Alterar o estado de uma divisão

Registra o andamento do repasse de uma fatia: concluída (com o comprovante) ou falha (com o motivo). Só atualiza o registro; não movimenta dinheiro. Não há validação de transição: qualquer estado válido pode ir para qualquer outro.

PATCH/api/v1/admin/payment-splits/{id}/statusAdmin

Altera o estado de uma divisão de pagamento

Autenticação: Authorization: Bearer <token> de um administrador com view_vendors ou manage_vendors (a escrita exige manage_vendors). Requer o módulo direct-payments ativo.

Parâmetros de caminho

iduuidobrigatório
Identificador da divisão.

Corpo da requisição

statusstringobrigatório
pendingprocessingcompletedfailedrefunded
Novo estado.
payment_refstring
Comprovante da transferência. Opcional.
error_messagestring
Motivo da falha. Opcional.

Exemplo de requisição

bash
curl -X PATCH "$BASE_URL/api/v1/admin/payment-splits/d5ccd9e1-dd21-458c-90a5-4a7f3c2b9e10/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "payment_ref": "E00038166202610111200abc123"
  }'

Resposta

200Estado alterado
json
{
  "message": "split status updated",
  "split_id": "e596dfec-f18d-4946-9950-9199b26e5516",
  "status": "completed"
}

Campos da resposta

messagestring
Texto fixo de confirmação.
split_iduuid
Divisão alterada.
statusstring
O estado enviado.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"direct-payments"} / {"error":"insufficient privileges","required":"manage_vendors"}
400Corpo inválido ou status ausente{"error":"status is required"}
500status fora da lista, divisão inexistente ou id que não é UUID{"error":"failed to update split status","detail":"invalid split status: \"done\""}
`pending` e `processing` são o mesmo estado gravado

Os dois guardam a mesma letra. Depois de gravar processing, a leitura devolve pending.

Veja também

  • Transações e estornos
  • Comissões
Anterior
Transações e estornos
Próxima
Taxas de gateway
Nesta página
  • Listar divisões
  • Exemplo de requisição
  • Resposta
  • Erros
  • Estatísticas das divisões
  • Exemplo de requisição
  • Resposta
  • Erros
  • Alterar o estado de uma divisão
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também