Capturar uma transação

Captura uma transação previamente pré-autorizada (criada com payment.capture: false). A captura confirma a cobrança no cartão do cliente. É possível capturar o valor total ou um valor parcial (menor q

Visão Geral

Captura uma transação previamente pré-autorizada (criada com payment.capture: false). A captura confirma a cobrança no cartão do cliente. É possível capturar o valor total ou um valor parcial (menor que o autorizado).

A captura é assíncrona: o endpoint aceita a solicitação (HTTP 202) e o processamento ocorre em background. Acompanhe o resultado pelos webhooks (transaction.approved) ou consultando a transação.

Precauções

Só pode ser usado em transações no status pre-authorized.
O valor da captura não pode exceder o valor autorizado.
Uma vez capturada, a transação não pode ser revertida — apenas reembolsada.
O ID da transação é sensível a maiúsculas e minúsculas (tra_... ou trx_...).

Casos de uso

Reservas hoteleiras: autorizar no check-in e capturar após verificar consumos.
Aluguel de veículos: pré-autorizar caução e capturar apenas se houver danos.
Serviços sob demanda: autorizar valor estimado e capturar o valor real.
Verificação de fundos: garantir saldo antes de processar.

Requisição

POST /v1/transactions/{transactionId}/capture

Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição
`transactionId`	string	Sim	Identificador da transação a capturar

Parâmetros do Corpo da Requisição

Parâmetro	Tipo	Obrigatório	Descrição
`amount`	integer	Não	Valor a capturar em centavos. Se omitido, captura o valor total autorizado. Para captura parcial, informe um valor menor (`> 0` e `≤` autorizado)

Exemplo de Requisição

Captura total (corpo vazio ou sem amount):

{}

Captura parcial:

{ "amount": 8000 }

Resposta

Aceito (HTTP 202 Accepted)

A captura foi aceita para processamento assíncrono.

{
  "transactionId": "tra_987654321",
  "status": "pre-authorized",
  "accepted": true
}

Atributo	Tipo	Descrição
`transactionId`	string	Identificador da transação
`status`	string	Status no momento do aceite (a confirmação da captura chega por webhook)
`accepted`	boolean	Sempre `true`

Erros

`error.code`	HTTP	Quando
`transactionNotCapturable`	422	A transação não está aguardando captura (não está em `pre-authorized`)
`captureAmountInvalid`	422	O valor de captura é zero/negativo ou excede o autorizado
`transactionNotFound`	404	Transação inexistente

Melhores Práticas

Verifique o status (pre-authorized) antes de capturar.
Reaja ao webhook transaction.approved para confirmar a captura.
Considere captura parcial quando o valor final for menor que o autorizado.
Lembre-se do prazo de validade das pré-autorizações (normalmente alguns dias).

Capturar uma transação

On this page