> ## 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.

# Regenerar o PIX de um pagamento

> Regenera o código PIX de um Payment Intent elegível, preserva o ID e retorna um novo next_action, expires_at e latest_charge.

Emite um código PIX fresco para um `payment_intent` cujo código anterior
já expirou — mesma PI, mesmo `client_secret`, novo
`latest_charge`, novo `next_action.pix_display_qr_code`. O código PIX tem
validade curta definida na geração (retornada em
`next_action.pix_display_qr_code.expires_at`); quando ela passa sem
pagamento, o intent volta a `requires_payment_method` — a tentativa acabou, o
intent não — e esta ação inicia a próxima tentativa com um código novo.

No checkout hospedado isso já acontece na tela: o comprador clica em
"Gerar novo código PIX" e continua o pagamento sem recomeçar a compra.

## Restrições

* O `payment_intent` precisa ter `payment_method: "pix"` e estar em
  `status: "requires_payment_method"` — o estado em que um código vencido
  deixa o intent. Um PIX `pending` ou `processing` ainda pode ser pago e não
  pode ser regenerado. Um cancelamento explícito via `/cancel` é terminal.
* 1 reemissão por minuto por Payment Intent. 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>

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

## Resposta

Retorna o `payment_intent` atualizado — `status` volta a `pending` e
`next_action.pix_display_qr_code` traz o QR novo com a nova validade.

<ResponseExample>
  ```json 200 theme={"theme":"css-variables"}
  {
    "id": "pi_Y41orEhbk6jQa1AG",
    "object": "payment_intent",
    "...": "outros campos do DTO",
    "amount": 14990,
    "currency": "brl",
    "latest_charge": "ch_beuLCYqwCGQm3JCG",
    "next_action": {
      "pix_display_qr_code": {
        "expires_at": "2026-05-16T19:35:00Z",
        "qr_code": "00020126360014BR.GOV.BCB.PIX0114+5511...",
        "qr_code_url": null
      },
      "type": "pix_display_qr_code"
    },
    "payment_method_types": [
      "pix"
    ],
    "status": "pending"
  }
  ```

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

  ```json 422 theme={"theme":"css-variables"}
  {
    "error": {
      "code": "invalid_request",
      "message": "regenerate_pix only applies to pix payment intents",
      "type": "invalid_request_error"
    }
  }
  ```

  ```json 429 theme={"theme":"css-variables"}
  {
    "error": {
      "code": "rate_limit",
      "message": "PIX regenerated too recently; try again later",
      "type": "rate_limit_error"
    }
  }
  ```

  ```json 502 theme={"theme":"css-variables"}
  {
    "error": {
      "code": "payment_result_unconfirmed",
      "message": "The payment result is not confirmed yet. Do not submit the operation again.",
      "type": "api_error"
    }
  }
  ```
</ResponseExample>

## Efeitos colaterais

* O código antigo não é cancelado ativamente: a própria validade curta o
  invalida no provedor, e um pagamento feito após a expiração é estornado
  automaticamente — não há risco de pagamento duplo.
* A `charge` antiga permanece `canceled` (quando o código expirou) e uma nova
  `charge` `pending` vira o `latest_charge`.
* Eventos emitidos: `charge.updated` (nova charge) + `payment.intent.updated`.

## Erros comuns

| Status      | `code`                       | Quando ocorre                                                                                                                                          |
| ----------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `409`       | `resource_state_conflict`    | PI ainda está ativo (`pending`, `processing`, `requires_confirmation`), já foi pago ou foi cancelado.                                                  |
| `422`       | `invalid_request`            | PI não é pix, ou a organização não pode receber pagamentos.                                                                                            |
| `429`       | `rate_limit`                 | Chamada feita menos de 1 minuto depois da última reemissão.                                                                                            |
| `400`–`409` | código específico da falha   | A emissão foi recusada de forma definitiva; a resposta usa o código estável correspondente da [tabela de erros](/api-reference/charges/failure-codes). |
| `502`       | `payment_result_unconfirmed` | A solicitação pode ter sido recebida, mas a resposta se perdeu. Não repita a operação; consulte o Payment Intent e aguarde os webhooks.                |
| `503`       | `processing_error`           | O provedor devolveu uma falha ainda não classificada. Ela é registrada e exibida, nunca tratada como sucesso.                                          |

<CardGroup cols={2}>
  <Card title="Objeto Payment Intent" icon="cube" href="/api-reference/payment-intents/object">
    Diferença entre validade do PIX e estado do intent.
  </Card>

  <Card title="Nova tentativa de pagamento" icon="rotate" href="/payments/accept-payments-with-payment-intents">
    Quando regenerar o PIX e quando criar outro Payment Intent.
  </Card>
</CardGroup>