Capturar uma transação

Captura confirma a cobrança de uma transação de cartão que foi pré-autorizada (o valor ficou reservado no cartão do cliente, mas ainda não foi efetivamente debitado). Use a captura quando seu fluxo de negócio exige reservar fundos primeiro e cobrar depois — por exemplo, ao confirmar a entrega de um pedido ou após apurar o valor final de um serviço. Você pode capturar o valor total ou apenas uma parte do valor autorizado.

POST /v1/transactions/{transactionId}/capture

Como funciona

Um pagamento com cartão pode ser feito em duas etapas (chamado de auth & capture):

1. Autorização (pré-autorização): ao criar a transação, o emissor do cartão reserva o valor e devolve a transação com status: "pre-authorized". Nesse momento nada foi debitado — o limite do cliente apenas fica bloqueado. (Veja Criar transação para como gerar uma pré-autorização.)
2. Captura: você chama este endpoint para confirmar a cobrança. O servidor envia a captura à adquirente, debita o cartão e move a transação para status: "approved". Só a partir daí o valor entra no seu fluxo de recebíveis.

Capturar é uma operação síncrona: a resposta 200 já traz a transação no novo estado. A liquidação financeira (quando o dinheiro fica disponível no seu saldo), porém, segue o cronograma dos recebíveis (receivables[]), com expectedOn indicando a data prevista de cada parcela.

Captura total vs. parcial

• Captura total: envie amount igual ao valor autorizado.
• Captura parcial: envie um amount menor que o autorizado. O servidor captura apenas esse valor e libera o restante da reserva no cartão do cliente. Útil quando o valor final ficou abaixo do estimado (ex.: o cliente consumiu menos do que a caução).

O amount nunca pode exceder o valor autorizado, nem ficar abaixo do mínimo aceito. Tarifas (fees) também são consideradas: se o valor solicitado, somado às tarifas, ultrapassar o autorizado, a captura é recusada (veja a tabela de erros).

Quando usar

Use a captura quando precisar separar a reserva de fundos da cobrança efetiva:

• Reservas e cauções (hotéis, aluguel de veículos): autorize no check-in/retirada e capture só o valor realmente devido.
• Serviços sob demanda: autorize um valor estimado e capture o valor real após a conclusão.
• Verificação de fundos antes de separar o pedido: garanta que o cliente tem saldo/limite antes de despachar.

Quando NÃO usar:

• Para uma cobrança imediata (autorizar e capturar de uma vez), crie a transação já capturada — não há etapa manual de captura. Veja Criar transação.
• Para estornar um valor já capturado, use o Reembolso — captura não é reversível.
• Métodos como Pix e boleto não usam captura manual; tentar capturá-los retorna transactionMethodCaptureNotAllowed.

Requisição

Headers

Parâmetros de caminho

Corpo

Exemplo — captura total

curl -X POST "https://api.selectwin.io/v1/transactions/tra_01hqzvabc/capture" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: cap-tra_01hqzvabc-001" \
  -d '{
    "amount": 10000
  }'

Exemplo — captura parcial

Autorizou R$ 100,00, mas só vai cobrar R$ 60,00 (o restante é liberado no cartão):

{
  "amount": 6000
}

Resposta

200 OK — a resposta é o objeto completo da transação já atualizado: status passa a "approved", amount reflete o valor capturado e os receivables[] são gerados/atualizados com o cronograma de liquidação.

{
  "id": "tra_01hqzvabc",
  "customId": "PEDIDO-1042",
  "amount": 10000,
  "originalAmount": 10000,
  "status": "approved",
  "method": "credit",
  "currency": "BRL",
  "payment": {
    "provider": "selectwin",
    "version": "1.1",
    "refused": null,
    "reusable": false,
    "acquirerTransactionNumber": "A1B2C3D4E5",
    "cardFirstDigits": "411111",
    "cardLastDigits": "1111",
    "cardBrand": "visa",
    "cardRegistered": false,
    "installments": 3,
    "expirationDate": null,
    "paidAt": "2026-04-12T17:56:33.000Z",
    "allowRenewPayment": false,
    "invoiceLink": "https://selectwin.io/invoices/tra_01hqzvabc"
  },
  "discount": null,
  "customer": {
    "id": "cus_01hqzvabc",
    "firstName": "João",
    "lastName": "Silva",
    "email": "[email protected]",
    "document": { "type": "cpf", "number": "12345678901" }
  },
  "billing": {
    "address": {
      "id": "addr_01hqzvabc",
      "street": "Av. Paulista",
      "number": "1000",
      "city": "São Paulo",
      "state": "SP",
      "postcode": "01310-100",
      "country": "BR"
    }
  },
  "shipping": null,
  "externalReference": "order-9981",
  "shippable": false,
  "spplited": false,
  "items": [
    {
      "id": "item_01hqzvabc",
      "name": "Premium Plan",
      "unitPrice": 10000,
      "quantity": 1,
      "currency": "BRL"
    }
  ],
  "receivables": [
    {
      "id": "rec_01hqzvabc",
      "recipient": "bus_1234567890",
      "status": "paid",
      "amount": 9610,
      "grossAmount": 10000,
      "anticipationFee": 0,
      "installmentNumber": 1,
      "currency": "BRL",
      "authorizationCode": "654321",
      "paidAt": "2026-04-12T17:56:33.000Z",
      "expectedOn": "2026-05-12",
      "liable": true,
      "chargeProcessingFee": true,
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "splits": null,
  "refunds": null
}

Campos-chave da resposta

Os IDs e datas dos exemplos são ilustrativos. Confie sempre no campo id e nos timestamps reais da resposta. Veja Convenções.

Erros

Em caso de falha, a resposta segue o envelope de erro padrão com um error.code estável. Trate sempre pelo code, nunca pela message.

Erros transversais também se aplicam: 401 unauthorized (SelectKey ausente/inválida), 429 tooManyRequests (respeite error.retryAfterMinutes) e 500 serverError. Veja o Catálogo de Códigos de Erro.

Boas práticas

• Confirme o estado antes de capturar. Faça um Read e verifique status: "pre-authorized" para evitar transactionCaptureNotProcessable.
• Capture dentro da validade da pré-autorização. A reserva expira em poucos dias; defina um prazo interno e capture assim que a regra de negócio permitir.
• Use captura parcial quando o valor final for menor que o autorizado — isso libera o saldo restante no cartão do cliente, melhorando a experiência dele.
• Envie X-Idempotency-Key para que um retry após timeout não gere captura duplicada. Veja Idempotência.
• Trate 503 (traCaptureFailed) com backoff exponencial — é uma falha transitória da adquirente, não um erro do seu pedido.
• Não fique fazendo polling para saber se capturou. Assine o webhook transaction.approved para reagir à confirmação. Veja Proibição de Polling.
• Guarde o id da transação retornado na criação — ele é a única chave para capturar depois.

Veja também

• Visão geral de Transações — o objeto, estados e todas as operações.
• Criar transação — como gerar uma pré-autorização para capturar depois.
• Reembolsar — devolver um valor já capturado.
• Consultar transação — verificar o estado antes/depois da captura.
• Listar transações · Disputas
• Convenções · Códigos de Erro