> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cakto.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Listar Tentativas de Cobrança

> Analise as tentativas de cobrança de um ciclo específico. Entenda por que um pagamento falhou e quando cada tentativa ocorreu.

#### Escopo

```bash theme={null}
    read subscriptions
```

## Quando usar

* Para entender por que uma cobrança específica falhou
* Para verificar se o gateway está tentando cobrar novamente
* Para decidir se é hora de entrar em contato com o cliente

## Como interpretar as tentativas

As tentativas são retornadas ordenadas pelo número da tentativa:

| Campo                         | Descrição              | Como usar                                               |
| ----------------------------- | ---------------------- | ------------------------------------------------------- |
| `attempt_number`              | Sequência da tentativa | Veja quantas vezes o sistema já tentou cobrar           |
| `result`                      | `success` ou `failure` | Identifique se alguma tentativa foi bem-sucedida        |
| `failure_reason`              | Motivo da recusa       | Use para entender o problema (ex: fundos insuficientes) |
| `scheduled_for`               | Data agendada          | Veja quando a próxima tentativa estava prevista         |
| `started_at` / `completed_at` | Início e fim           | Meça o tempo de processamento de cada tentativa         |

<Tip>
  Múltiplas falhas seguidas com o mesmo `failure_reason` indicam um problema persistente no método de pagamento. Considere notificar o cliente antes do cancelamento automático.
</Tip>

<Info>
  Cada tentativa representa uma chamada real ao gateway de pagamento. Use este endpoint para auditar a integridade do processo de cobrança recorrente.
</Info>


## OpenAPI

````yaml GET /public_api/subscriptions/{id}/billing-cycles/{cycle_id}/attempts/
openapi: 3.0.3
info:
  title: Cakto API
  version: 1.0.0
  description: Documentação da API pública do Cakto.
servers:
  - url: https://api.cakto.com.br
    description: Cakto API
security: []
paths:
  /public_api/subscriptions/{id}/billing-cycles/{cycle_id}/attempts/:
    get:
      tags:
        - subscriptions
      description: Public API to list attempts for a specific billing cycle.
      operationId: subscriptions_billing_cycle_attempts_list
      parameters:
        - in: path
          name: cycle_id
          schema:
            type: string
            format: uuid
          required: true
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedAttemptList'
              examples:
                Successo:
                  value:
                    count: 2
                    next: null
                    previous: null
                    results:
                      - id: d9abeb29-6c7d-46fa-938a-4fbce40be05d
                        attempt_number: 1
                        amount: '100.00'
                        result: failure
                        failure_reason: Insufficient funds
                        scheduled_for: '2026-05-18T19:14:17.677041Z'
                        started_at: '2026-05-18T19:14:18.123456Z'
                        completed_at: '2026-05-18T19:14:20.789012Z'
                        created_at: '2026-05-18T19:14:17.677041Z'
                      - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                        attempt_number: 2
                        amount: '100.00'
                        result: success
                        failure_reason: null
                        scheduled_for: '2026-05-19T19:14:17.677041Z'
                        started_at: '2026-05-19T19:14:18.000000Z'
                        completed_at: '2026-05-19T19:14:22.000000Z'
                        created_at: '2026-05-18T19:14:17.677041Z'
          description: Corpo da resposta status 200
        '401':
          description: Request não autenticado devido à ausência ou invalidez do token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedError'
              examples:
                Token ausente ou inválido:
                  $ref: '#/components/examples/UnauthenticatedErrorExample'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedError'
              examples:
                NaoEncontrado:
                  value:
                    detail: Não encontrado.
          description: Assinatura ou ciclo de cobrança não encontrado.
      security:
        - OAuth Token: []
components:
  schemas:
    PaginatedAttemptList:
      type: object
      properties:
        count:
          type: integer
          description: Total de resultados
        next:
          type: string
          format: uri
          nullable: true
          description: URL da próxima página
        previous:
          type: string
          format: uri
          nullable: true
          description: URL da página anterior
        results:
          type: array
          items:
            $ref: '#/components/schemas/Attempt'
          description: Lista de tentativas de cobrança
      required:
        - count
        - results
    UnauthenticatedError:
      type: object
      properties:
        detail:
          type: string
    Attempt:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID da tentativa
        attempt_number:
          type: integer
          description: Número da tentativa
        amount:
          type: string
          description: Valor tentado
        result:
          type: string
          description: Resultado (success ou failure)
        failure_reason:
          type: string
          nullable: true
          description: Motivo da falha, se houver
        scheduled_for:
          type: string
          format: date-time
          description: Data agendada
        started_at:
          type: string
          format: date-time
          nullable: true
          description: Data de início
        completed_at:
          type: string
          format: date-time
          nullable: true
          description: Data de conclusão
        created_at:
          type: string
          format: date-time
          description: Data de criação
      required:
        - amount
        - attempt_number
        - completed_at
        - created_at
        - id
        - result
        - scheduled_for
        - started_at
  examples:
    UnauthenticatedErrorExample:
      summary: Token ausente ou inválido
      description: Token ausente ou inválido
      value:
        detail: As credenciais de autenticação não foram fornecidas.
  securitySchemes:
    OAuth Token:
      type: http
      scheme: bearer
      in: header
      name: Authorization
      description: >-
        Token de autenticação do tipo `Bearer {access_token}`, onde
        `{access_token}` é o token obtido no fluxo de
        [autenticação](/authentication).

````