SopagueDocs
v3

Listar Faturas do Cliente

GET/v2/payment-customers/{customerId}/billings

Consulta paginada do histórico financeiro de faturas geradas para o cliente em todas as suas assinaturas.

O parâmetro customerId é o identificador obtido no cadastro do pagador em Criar Cliente. As faturas são geradas e processadas automaticamente pelo motor de recorrência a cada ciclo das assinaturas ativas criadas via Criar Assinatura ou via Pagar Sessão de Checkout.

Cabeçalhos (Headers)

CabeçalhoValorObrigatórioDescrição
AuthorizationBearer <token>SimToken JWT Bearer autenticado

Parâmetros

Exemplo de requisição
curl --request GET \
  --url 'https://api.sopague.com.br/gateway/v2/payment-customers/{customerId}/billings' \
  --header 'Authorization: Bearer {token}'

Resposta (200 OK)

Exemplo de resposta
{
  "items": [
    {
      "id": "3c2b1a0f-5e6d-4c3b-2a1f-0e9d8c7b6a5e",
      "subscriptionId": "e1f2a3b4-5c6d-7e8f-9a01-234567890abc",
      "plan": {
        "id": "f5e4d3c2-1b0a-9f8e-7d6c-5b4a3f2e1d0c",
        "name": "Plano Premium Mensal",
        "intervalUnit": "MONTH",
        "intervalCount": 1
      },
      "amount": 49.9,
      "currency": "BRL",
      "status": "PAID",
      "periodStartsOn": "2026-09-09T10:00:00Z",
      "periodEndsOn": "2026-10-09T10:00:00Z",
      "dueOn": "2026-09-09T10:00:00Z",
      "attemptCount": 1,
      "paidOn": "2026-09-09T10:00:05Z",
      "lastPayment": {
        "paymentId": "9a8b7c6d-5e4f-3a2b-1c0d-ef9a8b7c6d5e",
        "amount": 49.9,
        "gatewayPaymentId": "123456789012",
        "authorizationCode": "098765",
        "returnCode": "0"
      }
    }
  ],
  "page": 1,
  "pageSize": 20,
  "totalCount": 1,
  "totalPages": 1
}

Erros

As respostas de erro conhecidas estão abaixo. Os retornos observados em homologação estão identificados separadamente dos exemplos documentados; as respostas podem variar conforme o ambiente e a configuração.

Ver validações observadas em homologação

Requisição com corpo JSON vazio ou identificador sintético. O retorno abaixo mostra a validação realizada em homologação.

[
  {
    "tag": "CustomerId",
    "description": "O identificador do cliente é obrigatório."
  }
]

Campos da resposta de erro

A tabela reúne os campos presentes nos exemplos acima. Uma resposta HTTP sem corpo não inclui esses campos.