Capturando uma transação
Sobre captura tardia#
Por padrão, uma cobrança criada com auto_capture: true é autorizada e capturada de forma automática. Quando a cobrança é criada com auto_capture: false, o valor é apenas reservado na carteira do cliente (autorização sem captura) e precisa ser capturado em uma segunda chamada.
Use esse fluxo quando precisar confirmar o valor exato da compra após a autorização — por exemplo, em casos de entrega com frete variável.
Atenção
Transações no estado authorized (aguardando captura) devem ser capturadas dentro do prazo de 6 dias. Após esse prazo, a transação passa automaticamente para EXPIRED e a reserva é liberada.
Endpoint#
Exemplo de requisição#
Parâmetros do body#
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
transaction_id | string | Sim* | Identificador da transação gerado pelo PicPay no momento da cobrança |
reference_id | string | Sim* | Identificador único da transação gerado pelo parceiro |
value | number | Sim | Valor em reais a ser capturado. Pode ser menor ou igual ao valor autorizado |
*Ao menos um dos identificadores (transaction_id ou reference_id) deve ser informado.
Resposta de sucesso#
HTTP 204 No Content indica que a captura foi realizada com sucesso. O body de resposta é vazio. A transação passa de AUTHORIZED para PAID.
Erros possíveis#
business_code | HTTP | Descrição |
|---|---|---|
TRANSACTION_CANT_BE_CAPTURED | 409 | Status não permite captura (já capturada, cancelada ou expirada) |
CAPTURED_INVALID_VALUE | 422 | Valor inválido (ex: maior que o autorizado) |
TRANSACTION_NOT_FOUND | 404 | Transação não encontrada |