Capturar cobrança

Quick Reference

WhatCapturar uma cobrança previamente autorizada

WhyReserve os fundos primeiro, cobre o valor final depois — essencial para hotéis, locadoras de veículos e marketplaces

Reading Time5 min

DifficultyIntermediate

PrerequisitesAuthentication → Create charge (with capture: false)

POST/api/v1/bank/wallet/charge/capture/Bearer TokenCapturar uma cobrança autorizada

Por que separar autorização e captura

Sem autorização + captura	Com autorização + captura
Hotel cobra R$ 500 mesmo que o hóspede gaste R$ 320	Hotel autoriza R$ 500 no check-in, captura R$ 320 no checkout
Locadora não consegue reter depósito de danos	Locadora autoriza R$ 2.000 de depósito, captura apenas as despesas reais
Marketplace cobra o comprador antes do vendedor confirmar estoque	Marketplace retém os fundos até o vendedor enviar o item
Cobranças a mais levam a reembolsos, disputas e churn	Captura parcial cobra apenas o valor devido — sem necessidade de reembolso
Restaurantes não conseguem adicionar gorjetas após autorização	Restaurante autoriza a conta, captura conta + gorjeta depois

Fluxo de autorização e captura

Autenticação

Requer token Bearer. Veja Autenticação.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`charge_uuid`	string (UUID)	Sim	Cobrança autorizada a capturar
`wallet_uuid`	string (UUID)	Sim	Carteira proprietária da cobrança
`amount`	number	Não	Valor da captura. Omita para captura total. Passe um valor menor para captura parcial

Captura parcial

Quando amount é menor que o valor original autorizado, a A55 captura apenas o valor especificado e libera a reserva restante. Nem todos os adquirentes suportam captura parcial — consulte Capacidades dos provedores para detalhes.

Exemplos de código

Captura total

cURL
Python
JavaScript

curl -s -X POST https://core-manager.a55.tech/api/v1/bank/wallet/charge/capture/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "charge_uuid": "51dcca6e-7310-4b73-a94c-90835408f2ff",
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }'

import requests
import os

token = os.environ["A55_API_TOKEN"]
base = os.environ.get("A55_API_BASE_URL", "https://core-manager.a55.tech")

capture = requests.post(
    f"{base}/api/v1/bank/wallet/charge/capture/",
    json={
        "charge_uuid": "51dcca6e-7310-4b73-a94c-90835408f2ff",
        "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    },
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
).json()

print(f"Captured: {capture['charge_uuid']} — Status: {capture['status']}")
print(f"Amount: {capture['currency']} {capture['local_currency']}")

const token = process.env.A55_API_TOKEN;
const base = process.env.A55_API_BASE_URL || "https://core-manager.a55.tech";

const capture = await fetch(`${base}/api/v1/bank/wallet/charge/capture/`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    charge_uuid: "51dcca6e-7310-4b73-a94c-90835408f2ff",
    wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  }),
}).then((r) => r.json());

console.log(`Captured: ${capture.charge_uuid} — Status: ${capture.status}`);

Captura parcial (exemplo de checkout de hotel)

cURL
Python
JavaScript

curl -s -X POST https://core-manager.a55.tech/api/v1/bank/wallet/charge/capture/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "charge_uuid": "51dcca6e-7310-4b73-a94c-90835408f2ff",
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "amount": 320.00
  }'

partial = requests.post(
    f"{base}/api/v1/bank/wallet/charge/capture/",
    json={
        "charge_uuid": "51dcca6e-7310-4b73-a94c-90835408f2ff",
        "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "amount": 320.00,
    },
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
).json()

print(f"Partial capture: {partial['currency']} {partial['local_currency']} of original hold")

const partial = await fetch(`${base}/api/v1/bank/wallet/charge/capture/`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    charge_uuid: "51dcca6e-7310-4b73-a94c-90835408f2ff",
    wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    amount: 320.0,
  }),
}).then((r) => r.json());

console.log(`Partial capture: ${partial.currency} ${partial.local_currency}`);

Campos da resposta

A resposta segue a mesma estrutura de Criar cobrança com o status atualizado para confirmed:

Campo	Tipo	Descrição
`charge_uuid`	string	Identificador único da cobrança
`status`	string	`confirmed` após captura bem-sucedida
`local_currency`	number	Valor capturado na moeda de liquidação
`currency`	string	Código de moeda ISO 4217
`usd_currency`	number	Valor capturado em USD
`eur_currency`	number	Valor capturado em EUR
`type`	string	Método de pagamento (`credit_card`, `debit_card`)
`date`	string	Data de criação original da cobrança
`description`	string	Descrição da cobrança
`due_date`	string	Data de vencimento do pagamento
`message`	array/null	`null` em sucesso, detalhes do erro em falha
`installment_count`	integer	Número de parcelas
`installments`	array	Detalhamento por parcela com valores atualizados

Exemplo completo de resposta

{
  "status": "confirmed",
  "charge_uuid": "51dcca6e-7310-4b73-a94c-90835408f2ff",
  "local_currency": 320.00,
  "currency": "BRL",
  "usd_currency": 57.41,
  "eur_currency": 50.33,
  "type": "credit_card",
  "date": "2026-03-15",
  "description": "Hotel reservation — Grand Suite",
  "due_date": "2026-03-20",
  "message": null,
  "installment_count": 1,
  "installments": [
    {
      "local_currency": 320.00,
      "currency": "BRL",
      "usd_currency": 57.41,
      "eur_currency": 50.33,
      "due_date": "2026-03-20",
      "status": "confirmed",
      "installment_number": 1
    }
  ]
}

Respostas de erro

Status	Código	Descrição	Resolução
400	`errors.wallet.charge_capture_not_available`	Cobrança não está em estado capturável	Verifique se o status da cobrança é `authorized`. Cobranças já capturadas, expiradas ou falhadas não podem ser capturadas
401	`unauthorized`	Token Bearer inválido ou expirado	Renove seu token de acesso via Cognito
404	`errors.wallet.not_found`	UUID da carteira não existe	Verifique se o `wallet_uuid` está correto
404	`CHARGE_NOT_FOUND`	Cobrança não encontrada para esta carteira	Verifique se ambos os UUIDs correspondem à cobrança original
422	`amount_exceeds_authorization`	Valor da captura excede o valor autorizado	O valor da captura deve ser ≤ ao valor originalmente autorizado

Capture em até 7 dias

Reservas de autorização expiram após 7 dias na maioria das bandeiras de cartão. Capture antes da reserva expirar, ou a autorização será anulada automaticamente e você precisará criar uma nova cobrança.

Este endpoint usa POST, não PUT

Apesar de ser uma operação de atualização, a spec OpenAPI define captura como POST /charge/capture/. Use POST na sua integração.

Configurando cobranças somente autorização

Para usar a captura, você deve primeiro criar uma cobrança com capture: false na requisição de Criar cobrança. Se capture for true (padrão), a cobrança é autorizada e capturada em uma única etapa — não há nada para capturar separadamente.

Criar cobrança →Criar uma cobrança somente autorização com capture: false.Reembolsar cobrança →Reembolsar uma cobrança capturada — total ou parcial.Consultar cobrança →Verificar o status da captura após a chamada.

Quick Reference

Por que separar autorização e captura​

Fluxo de autorização e captura​

Autenticação​

Corpo da requisição​

Exemplos de código​

Captura total​

Captura parcial (exemplo de checkout de hotel)​

Campos da resposta​

Exemplo completo de resposta​

Respostas de erro​