Pagamentos nativos para agentes: construindo fluxos de checkout idempotentes com AgentPay

Problema: agentes de IA precisam coletar dinheiro sem segurá-lo

Quando Claude ou outro agente LLM precisa coletar um pagamento—digamos, para desbloquear recursos premium ou liquidar uma taxa de serviço—na maioria das soluções é necessário:

1. Integrações complexas (APIs do Stripe, PayPal com gerenciamento de credenciais)
2. Compromissos de confiança (dinheiro parado em custódia ou em uma conta de terceiros)
3. Dores de cabeça com gerenciamento de estado (rastrear o status do pagamento entre execuções do agente)

O ecossistema VietQR do Vietnã é perfeito para isso: códigos QR apontam diretamente para contas bancárias de comerciantes. Mas não havia um SDK nativo para agentes até agora.

Como o AgentPay resolve isso

AgentPay VN é um SDK Python de código aberto (MIT) + servidor MCP que:

• Nunca toca no dinheiro — códigos QR apontam diretamente para sua conta bancária
• Confirma a liquidação lendo seu feed bancário SePay (uma chave de API)
• Suporta idempotência — seguro para tentar novamente sem cobrar em duplicidade
• Envia webhooks — seu agente pode aguardar o pagamento sem polling

O fluxo é 3 linhas:

from agentpay import PaymentClient

client = PaymentClient(api_key="your_key")

# Cria um pedido de pagamento
request = client.create_payment_request(
    amount=100000,  # VND
    description="Desbloqueio de recurso premium",
    idempotency_key="user_123_2024_01_15"
)

print(f"Checkout: {{request.checkout_url}}")

# Aguardar liquidação (bloqueia até ser pago ou timeout)
receipt = client.await_settlement(
    request_id=request.id,
    timeout=300  # 5 minutos
)

if receipt:
    print(f"Pago! Transação: {{receipt.transaction_id}}")
else:
    print("Pagamento não recebido")

Integrando ao Claude via MCP

Instale o servidor MCP:

pip install agentpay-vn

Adicione ao claude_desktop_config.json:

{
  "mcpServers": {
    "agentpay": {
      "command": "agentpay-mcp",
      "env": {
        "AGENTPAY_API_KEY": "your_api_key",
        "AGENTPAY_ACCOUNT_ID": "your_account_id"
      }
    }
  }
}

Agora no Claude:

Usuário: "Bloqueie meu recurso de exportação atrás de um pagamento de $5."

Claude: Chama agentpay_create_payment → envia URL de checkout VietQR → chama agentpay_await_settlement → confirma e desbloqueia o recurso.

Idempotência + webhooks são importantes

Pedidos idempotentes evitam cobranças acidentais em duplicidade se seu agente tentar novamente:

# Mesmo idempotency_key = mesmo pedido, sem cobrança duplicada
request = client.create_payment_request(
    amount=50000,
    idempotency_key="order_abc_retry_1"
)

Webhooks permitem que você pule o polling:

# Em vez de await_settlement (bloqueando),
# configure um webhook no painel
# e trate o POST em seu endpoint

Limitações honestas

• VietQR apenas — pagamentos domésticos no Vietnã. Não global.
• Dependência do feed bancário SePay — precisa que seu banco exponha dados de transação (suporte confirmado do Techcombank, VCB, BIDV).
• Atraso na liquidação — tipicamente 1-2 horas via API SePay.
• Sem resolução de disputas — você é responsável por reembolsos (é um código QR, não um processador de pagamentos).

Links

• GitHub: https://github.com/phuocdu/agentpay-vn
• Docs + Swagger: https://agentpay.servicesai.vn/v1/docs
• Instalação: pip install agentpay-vn

Ideal para: agentes de IA coletando taxas de desbloqueio de SaaS, taxa de serviço