Consultar cobrança

Quick Reference

WhatRecuperar uma cobrança pelo UUID

WhyVerificar status do pagamento, conferir valores e conciliar transações em tempo real

Reading Time5 min

DifficultyBeginner

PrerequisitesAuthentication → Create charge

GET/api/v1/bank/wallet/charge/Bearer TokenRecuperar detalhes da cobrança

Por que consultar o status da cobrança

Sem Consultar Cobrança	Com Consultar Cobrança
Você não tem visibilidade após criar uma cobrança	Você vê o status exato a qualquer momento
Conciliação depende de verificações manuais	Conciliação automatizada vincula seus registros à A55
Suporte ao cliente não consegue responder "cadê meu pagamento?"	Consulta instantânea pelo UUID da cobrança para agentes de suporte
Webhooks perdidos deixam você no escuro	Polling preenche lacunas quando webhooks falham ou chegam atrasados
Sem trilha de auditoria para transições de estado	`updated_at` rastreia cada timestamp de mudança de status

Padrão de polling

Autenticação

Requer token Bearer. Veja Autenticação.

Parâmetros de consulta

Ambos os parâmetros são obrigatórios na query string:

Campo	Tipo	Obrigatório	Descrição
`charge_uuid`	string (UUID)	Sim	Identificador único da cobrança a recuperar
`wallet_uuid`	string (UUID)	Sim	Carteira proprietária da cobrança

Sem corpo na requisição

Este é um endpoint GET. Passe ambos os UUIDs como parâmetros de consulta, não no corpo.

Exemplos de código

cURL
Python
JavaScript

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

import requests
import os

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

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

charge = response.json()
print(f"Status: {charge['status']} | Amount: {charge['currency']} {charge['local_currency']}")

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

const params = new URLSearchParams({
  charge_uuid: "51dcca6e-7310-4b73-a94c-90835408f2ff",
  wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
});

const charge = await fetch(`${base}/api/v1/bank/wallet/charge/?${params}`, {
  headers: { Authorization: `Bearer ${token}` },
}).then((r) => r.json());

console.log(`Status: ${charge.status} | Amount: ${charge.currency} ${charge.local_currency}`);

Polling prático com backoff exponencial

Python
JavaScript

import requests, os, time

token = os.environ["A55_API_TOKEN"]
base = os.environ.get("A55_API_BASE_URL", "https://core-manager.a55.tech")
TERMINAL = {"paid", "confirmed", "error", "canceled", "refunded"}

def poll_charge(charge_uuid, wallet_uuid, max_attempts=10):
    delay = 2
    for attempt in range(max_attempts):
        resp = requests.get(
            f"{base}/api/v1/bank/wallet/charge/",
            params={"charge_uuid": charge_uuid, "wallet_uuid": wallet_uuid},
            headers={"Authorization": f"Bearer {token}"},
        )
        charge = resp.json()
        status = charge["status"]
        print(f"[{attempt+1}/{max_attempts}] Status: {status}")

        if status in TERMINAL:
            return charge

        time.sleep(delay)
        delay = min(delay * 2, 60)

    raise TimeoutError("Charge did not reach terminal status")

const TERMINAL = new Set(["paid", "confirmed", "error", "canceled", "refunded"]);

async function pollCharge(chargeUuid, walletUuid, maxAttempts = 10) {
  let delay = 2000;
  for (let i = 0; i < maxAttempts; i++) {
    const params = new URLSearchParams({ charge_uuid: chargeUuid, wallet_uuid: walletUuid });
    const charge = await fetch(`${base}/api/v1/bank/wallet/charge/?${params}`, {
      headers: { Authorization: `Bearer ${token}` },
    }).then((r) => r.json());

    console.log(`[${i + 1}/${maxAttempts}] Status: ${charge.status}`);
    if (TERMINAL.has(charge.status)) return charge;

    await new Promise((r) => setTimeout(r, delay));
    delay = Math.min(delay * 2, 60000);
  }
  throw new Error("Charge did not reach terminal status");
}

Campos da resposta

Campo	Tipo	Descrição
`charge_uuid`	string	Identificador único da cobrança
`wallet_uuid`	string	Carteira proprietária desta cobrança
`status`	string	Status atual da cobrança (veja tabela abaixo)
`type_charge`	string	Método de pagamento: `credit_card`, `debit_card`, `pix`, `boleto`, `spei`, `oxxo`, `applepay`, `googlepay`, `e_wallet`
`amount`	number	Valor total da cobrança na moeda original
`local_currency`	number	Valor na moeda de liquidação da carteira
`currency`	string	Código de moeda ISO 4217
`usd_currency`	number	Valor equivalente em USD
`eur_currency`	number	Valor equivalente em EUR
`installment_count`	integer	Número de parcelas
`installments`	array	Detalhamento por parcela (veja abaixo)
`created_at`	string	Timestamp de criação ISO 8601
`updated_at`	string	Timestamp da última atualização ISO 8601

Status da cobrança

Status	Terminal?	Descrição
`issued`	Não	Cobrança criada, aguardando ação do pagador (QR PIX, Boleto, checkout)
`pending`	Não	Processando — aguardando resposta do adquirente ou 3DS
`confirmed`	Sim	Pagamento autorizado e capturado com sucesso
`paid`	Sim	Fundos recebidos e confirmados
`error`	Sim	Pagamento falhou — veja o array `message` para detalhes
`canceled`	Sim	Cobrança cancelada antes da conclusão
`refunded`	Sim	Cobrança reembolsada (total ou parcial)

Objeto de parcela

Campo	Tipo	Descrição
`installment_number`	integer	Sequência da parcela (iniciando em 1)
`local_currency`	number	Valor da parcela na moeda de liquidação
`currency`	string	Código de moeda ISO 4217
`usd_currency`	number	Valor da parcela em USD
`eur_currency`	number	Valor da parcela em EUR
`due_date`	string	Data de vencimento da parcela
`status`	string	Status no nível da parcela

Exemplo completo de resposta

{
  "charge_uuid": "51dcca6e-7310-4b73-a94c-90835408f2ff",
  "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "confirmed",
  "type_charge": "credit_card",
  "amount": 450.00,
  "local_currency": 450.00,
  "currency": "BRL",
  "usd_currency": 80.73,
  "eur_currency": 70.78,
  "installment_count": 3,
  "installments": [
    {
      "installment_number": 1,
      "local_currency": 150.00,
      "currency": "BRL",
      "usd_currency": 26.91,
      "eur_currency": 23.59,
      "due_date": "2026-03-20",
      "status": "confirmed"
    },
    {
      "installment_number": 2,
      "local_currency": 150.00,
      "currency": "BRL",
      "usd_currency": 26.91,
      "eur_currency": 23.59,
      "due_date": "2026-04-20",
      "status": "confirmed"
    },
    {
      "installment_number": 3,
      "local_currency": 150.00,
      "currency": "BRL",
      "usd_currency": 26.91,
      "eur_currency": 23.60,
      "due_date": "2026-05-20",
      "status": "confirmed"
    }
  ],
  "created_at": "2026-03-20T14:30:00-03:00",
  "updated_at": "2026-03-20T14:30:05-03:00"
}

Respostas de erro

Status	Código	Descrição	Resolução
400	`validation_error`	`charge_uuid` ou `wallet_uuid` ausente	Ambos os parâmetros de consulta são obrigatórios
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
429	`rate_limit_exceeded`	Muitas requisições	Aguarde e tente novamente após o valor do header `Retry-After`

Não faça polling excessivo

Fazer polling mais de uma vez por segundo aciona limitação de taxa. Para necessidades em tempo real, use webhooks e reserve o polling para conciliação e consultas de suporte.

Ambos os UUIDs são obrigatórios

Passar apenas charge_uuid sem wallet_uuid retorna um erro 400. A API exige escopo por carteira para segurança — você só pode recuperar cobranças pertencentes à sua carteira.

Capturar cobrança →Capturar um pagamento previamente autorizado.Reembolsar cobrança →Reembolsar uma cobrança capturada — total ou parcial.Webhooks →Receber atualizações de status em tempo real em vez de polling.

Quick Reference

Por que consultar o status da cobrança​

Padrão de polling​

Autenticação​

Parâmetros de consulta​

Exemplos de código​

Polling prático com backoff exponencial​

Campos da resposta​

Status da cobrança​

Objeto de parcela​

Exemplo completo de resposta​

Respostas de erro​