Webhook de Cobrança

A A55 envia um POST para sua webhook_url sempre que o status de uma cobrança muda. O payload do webhook contém apenas os campos essenciais — use o UUID da cobrança para buscar os detalhes completos na API.

Campos do payload

Campo	Tipo	Descrição
`charge_uuid`	UUID	Identificador único da cobrança
`status`	string	Novo status da cobrança (veja tabela abaixo)
`transaction_reference`	string	ID enviado pelo cliente / referência da transação do adquirente
`subscription_uuid`	UUID ou null	Identificador da assinatura — presente apenas se a cobrança pertencer a uma assinatura
`payment_link_uuid`	UUID ou null	Identificador do link de pagamento — presente apenas se a cobrança foi criada via link de pagamento

Exemplo de payload

{
  "charge_uuid": "fe5e2c1e-b3fb-4cc4-bb28-004da37d5804",
  "status": "confirmed",
  "transaction_reference": "txn-abc-123",
  "subscription_uuid": null,
  "payment_link_uuid": null
}

Todos os status possíveis

Status	Descrição
`confirmed`	Transação aprovada
`pending`	Aguardando desafio 3DS
`issued`	Cobrança emitida, aguardando processamento (ex: SDK Apple Pay)
`canceled`	Cancelada após emissão ou desafio 3DS não concluído
`paid`	Cobrança liquidada
`error`	Transação com erro ou recusada
`refunded`	Estorno concluído
`refund_error`	Erro durante o estorno
`chargeback_refunded`	Chargeback estornado
`chargeback_requested`	Chargeback solicitado
`chargeback_reversed`	Chargeback revertido
`pre_chargeback_resolution`	Pré-resolução de chargeback em andamento

Buscando os detalhes completos da cobrança

O payload do webhook é intencionalmente mínimo. Após recebê-lo, chame a API com seu Bearer token para obter o objeto completo da cobrança:

curl https://api.a55.tech/api/v1/bank/wallet/charge/{charge_uuid}/ \
  -H "Authorization: Bearer $ACCESS_TOKEN"

A resposta é o objeto completo da cobrança com todos os campos, incluindo local_currency, currency, installments, action_url, applepay_payload e outros.

O webhook é o gatilho, a API é a fonte da verdade

Use o webhook para saber quando algo mudou, depois chame GET /api/v1/bank/wallet/charge/{uuid}/ para obter os detalhes completos. Nunca confie apenas na URL de redirecionamento — ela pode ser adulterada.

Exemplos de handler

Python (Flask)
JavaScript (Express)

from flask import Flask, request, jsonify
import requests

app = Flask(__name__)
processed = set()
ACCESS_TOKEN = "seu_bearer_token"

@app.route("/webhook", methods=["POST"])
def charge_webhook():
    data = request.get_json()
    charge_uuid = data.get("charge_uuid")
    status = data.get("status")

    # Deduplicar
    if charge_uuid in processed:
        return jsonify(status="duplicate"), 200
    processed.add(charge_uuid)

    # Buscar detalhes completos da cobrança na API
    charge = requests.get(
        f"https://api.a55.tech/api/v1/bank/wallet/charge/{charge_uuid}/",
        headers={"Authorization": f"Bearer {ACCESS_TOKEN}"},
    ).json()

    # Rotear por status
    if status == "confirmed":
        fulfil_order(charge)
    elif status == "error":
        notify_customer(charge)
    elif status == "refunded":
        credit_customer(charge)
    elif status in ("chargeback_requested", "chargeback_refunded"):
        flag_for_review(charge)

    return jsonify(status="accepted"), 200

const express = require("express");
const fetch = require("node-fetch");

const app = express();
app.use(express.json());

const processed = new Set();
const ACCESS_TOKEN = "seu_bearer_token";

app.post("/webhook", async (req, res) => {
  const { charge_uuid, status } = req.body;

  // Responder imediatamente
  res.sendStatus(200);

  // Deduplicar
  if (processed.has(charge_uuid)) return;
  processed.add(charge_uuid);

  // Buscar detalhes completos da cobrança na API
  const response = await fetch(
    `https://api.a55.tech/api/v1/bank/wallet/charge/${charge_uuid}/`,
    { headers: { Authorization: `Bearer ${ACCESS_TOKEN}` } }
  );
  const charge = await response.json();

  // Rotear por status
  const actions = {
    confirmed: fulfilOrder,
    error: notifyCustomer,
    refunded: creditCustomer,
    chargeback_requested: flagForReview,
    chargeback_refunded: flagForReview,
  };

  if (actions[status]) actions[status](charge);
});

Boas práticas

Prática	Por quê
Retorne `200` imediatamente	Evita timeouts e entregas duplicadas
Processe em background	Mantém o tempo de resposta abaixo de 30 s
Deduplique por `charge_uuid`	Trata webhooks retentados com segurança
Busque os detalhes completos via API	O payload do webhook é mínimo por design
Registre os payloads brutos	Facilita depuração sem reenvio

Campos do payload​

Exemplo de payload​

Todos os status possíveis​

Buscando os detalhes completos da cobrança​

Exemplos de handler​

Boas práticas​