Logo SOAR

Listar Pagamentos

Descrição

Lista pagamentos do sistema com paginação, busca e filtros. Usuários comuns visualizam apenas seus próprios pagamentos, enquanto Admin e Super Admin visualizam todos os pagamentos do sistema. Suporta busca por código do pedido (payment_intent) ou email, e filtro por status do Stripe.

Verbo

GET

URL Base

https://api.soargi.com

Endpoint

/payment/list?page=1&limit=12&search=&stripe_status=

Cabeçalhos

Parâmetro Valor
Authorization Bearer Token

Parâmetros de Consulta

Parâmetro Tipo Obrigatório Descrição
page integer Não Número da página. Padrão: 1.
limit integer Não Quantidade de registros por página. Padrão: 12.
search string Não Busca por código do pedido (payment_intent) ou email do usuário. Suporta busca parcial.
stripe_status string Não Filtro por status do pagamento no Stripe. Valores comuns: "succeeded", "pending", "failed", "canceled", "complete".

Sucesso - 200

{
  "status": "success",
  "message": "Payments retrieved successfully.",
  "page": 1,
  "limit": 12,
  "total": 25,
  "data": [
    {
      "payment_id": "1",
      "user_id": "123",
      "email": "user@example.com",
      "amount": 100.00,
      "quantity": 1,
      "payment_intent": "pi_1234567890abcdef",
      "paid_at": "2025-10-09 14:30:00",
      "payment_method": "card",
      "payment_status": "paid",
      "stripe_status": "succeeded",
      "created_at": "2025-10-09 14:25:00"
    },
    {
      "payment_id": "2",
      "user_id": "123",
      "email": "user@example.com",
      "amount": 200.00,
      "quantity": 2,
      "payment_intent": "pi_0987654321fedcba",
      "paid_at": "2025-10-08 10:15:00",
      "payment_method": "card",
      "payment_status": "paid",
      "stripe_status": "succeeded",
      "created_at": "2025-10-08 10:10:00"
    }
  ]
}

Erro - 401 (Token inválido)

{
  "status": 401,
  "error": "Invalid or expired token."
}

Códigos de Resposta

  • 200 - Lista de pagamentos retornada com sucesso
  • 401 - Token inválido ou expirado

Controle de Acesso por Role

  • Usuários Comuns: Visualizam apenas seus próprios pagamentos
  • Admin/Super Admin: Visualizam todos os pagamentos do sistema

Exemplos de Uso

Buscar por email:

GET /payment/list?search=usuario@email.com

Buscar por código do pedido:

GET /payment/list?search=pi_1234567890

Filtrar por status:

GET /payment/list?stripe_status=succeeded

Combinar filtros com paginação:

GET /payment/list?page=2&limit=20&search=user@email.com&stripe_status=succeeded

Observações

  • É necessário estar autenticado para acessar este endpoint.
  • Os dados são filtrados automaticamente baseado no role do usuário.
  • Os pagamentos são ordenados por data de criação (mais recentes primeiro).
  • A paginação padrão retorna 12 registros por página.
  • O parâmetro search busca em ambos os campos: payment_intent e email.
  • Todos os filtros (search, stripe_status) podem ser combinados.
  • O campo payment_intent é o código único do pedido no Stripe.
  • Valores comuns de stripe_status: "succeeded" (pago), "pending" (pendente), "failed" (falhou), "canceled" (cancelado), "complete" (completo).