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

# Regenerate a Boleto

> Regenera um boleto pendente.

Cancela o boleto anexado a um `payment_intent` no estado `pending` e emite
um boleto fresco — mesma PI, mesmo `client_secret`, novo `latest_charge`,
novo `next_action.boleto_display_details`. Útil quando o comprador perdeu
o documento original ou o vencimento está próximo.

## Restrições

* O `payment_intent` precisa estar em `status: "pending"` e
  `payment_method: "boleto"`.
* 1 reemissão por hora por PaymentIntent. Chamadas mais frequentes retornam
  `429`.
* Sem limite total de reemissões — pode chamar quantas vezes precisar,
  respeitando o limite de frequência.

## Parâmetros de caminho

<ParamField path="id" type="string" required>
  ID do payment intent (`pi_*`).
</ParamField>

## Attributes

<ParamField body="boleto_due_date" type="string">
  Nova data de vencimento no formato `YYYY-MM-DD`. Default: hoje + 3 dias.
</ParamField>

<RequestExample>
  ```bash cURL theme={}
  curl -X POST "https://api.chargefy.io/v1/payment-intents/pi_boleto_456/regenerate_boleto" \
    -H "Authorization: Bearer {{API_KEY}}"
  ```
</RequestExample>

## Resposta

Retorna o `payment_intent` atualizado com o novo `next_action`. O campo
`regenerated_at` é atualizado para o momento da chamada.

<ResponseExample>
  ```json 200 theme={}
  {
    "id": "pi_boleto_456",
    "object": "payment_intent",
    "...": "outros campos do DTO",
    "amount": 14990,
    "currency": "brl",
    "latest_charge": "ch_boleto_789",
    "next_action": {
      "boleto_display_details": {
        "barcode": "23791966600000149903381286008296100211202300",
        "expires_at": "2026-06-01",
        "hosted_voucher_url": "https://provider.example.com/boletos/new.pdf",
        "number": "23793.38128 60082.961002 11202.300008 1 96660000014990",
        "pdf": "https://provider.example.com/boletos/new.pdf"
      },
      "type": "boleto_display_details"
    },
    "payment_method_types": [
      "boleto"
    ],
    "status": "pending"
  }
  ```

  ```json 409 theme={}
  {
    "error": {
      "code": "resource_state_conflict",
      "message": "Cannot regenerate a boleto in status succeeded",
      "type": "invalid_request_error"
    }
  }
  ```

  ```json 422 theme={}
  {
    "error": {
      "code": "invalid_request",
      "message": "regenerate_boleto only applies to boleto payment intents",
      "type": "invalid_request_error"
    }
  }
  ```

  ```json 429 theme={}
  {
    "error": {
      "code": "rate_limit",
      "message": "Boleto regenerated too recently; try again later",
      "type": "rate_limit_error"
    }
  }
  ```
</ResponseExample>

## Efeitos colaterais

* O boleto antigo é cancelado no provedor (best-effort; cancelamento final
  fica a cargo do banco emissor, processo de 1 dia útil).
* A `charge` antiga vai para `status: "canceled"` com
  `payment_error.message: "Superseded by regenerated boleto"`.
* O job agendado de expiração automática do boleto antigo é cancelado e um
  novo é agendado para o novo `expires_at`.
* Eventos emitidos: `charge.updated` (nova charge) + `payment.intent.updated`.

## Erros comuns

| Status | `code`                    | Quando ocorre                                                            |
| ------ | ------------------------- | ------------------------------------------------------------------------ |
| `409`  | `resource_state_conflict` | PI não está em `pending` (já pago, cancelado, ou ainda em `requires_*`). |
| `422`  | `invalid_request`         | PI não é boleto, ou customer/buyer ausente.                              |
| `429`  | `rate_limit`              | Chamada feita menos de 1h depois da última reemissão.                    |
| `502`  | `api_error`               | Provedor falhou ao emitir o novo boleto.                                 |