Curso Engenharia de Agentes

Integração Completa de Gateways de Criptomoedas com FastAPI (MoonPay, Transak e Ramp)

Published on: 2025-10-04
Post image
pt cripto gateway api fastapi pydantic moonpay transak ramp

Este conteúdo apresenta uma API de Gateways de Cripto construída com FastAPI e Pydantic para iniciar fluxos de compra em MoonPay, Transak e Ramp. O termo “widget hospedado” descreve a interface de compra exibida pelo provedor, onde ocorre o pagamento e a verificação de identidade, também chamada de KYC (Know Your Customer). O backend apenas gera URLs ou sessões, redireciona para o provedor e processa webhooks, que são notificações HTTP enviadas automaticamente com o status do pedido. O objetivo é padronizar esse fluxo entre os três provedores, com rotas claras para criação de links e verificação de assinaturas em webhooks.

O material inclui um arquivo de configuração de ambiente, dependências, passos de execução e um main.py funcional. A API fornece URL assinada para MoonPay, criação de sessão e URL do widget para Transak, e montagem do hosted URL para Ramp com verificação de webhooks via ECDSA. Também estão presentes exemplos de cURL para iniciar compras e simular webhooks, facilitando testes locais. O resultado final é um ponto de partida didático e completo para integrar pagamentos cripto via widgets hospedados.

Conceitos essenciais e fluxo de ponta a ponta

Um gateway de cripto permite comprar ativos digitais com moeda fiduciária dentro de uma interface dedicada do provedor, chamada aqui de widget. Nesta abordagem, o pagamento não passa pelo servidor da aplicação, porque o provedor assume a cobrança, o KYC e os meios de pagamento. O backend gera a URL ou a sessão de compra, entrega ao aplicativo cliente e aguarda um webhook com o resultado da transação. Webhook é uma chamada HTTP enviada pelo provedor para uma rota da aplicação, contendo eventos como sucesso, erro ou pendência de verificação. Para garantir integridade, cada provedor assina essas mensagens, e a API implementa verificações de assinatura apropriadas.

Arquitetura geral da API (FastAPI + Pydantic)

A aplicação usa FastAPI, um framework web em Python voltado a desempenho e tipagem, para expor rotas HTTP. Os modelos de entrada e saída são definidos com Pydantic, que valida dados e gera esquemas de forma simples. As variáveis sensíveis ficam em arquivo .env, carregadas por uma biblioteca de utilidade, isolando credenciais do código-fonte. O middleware de CORS (Cross-Origin Resource Sharing) habilita ou restringe origens que podem consumir a API. Funções auxiliares lidam com assinaturas, chamadas a provedores e montagem de URLs, mantendo as rotas concisas e organizadas.

Arquivos do projeto e responsabilidades

A estrutura de arquivos é enxuta e foca somente no que é necessário para a API e testes básicos. Cada item a seguir representa um componente com papel definido no fluxo de compra e notificação. A organização facilita configuração em ambientes distintos e evolução incremental do código. A lista descreve o propósito de cada arquivo para orientar o entendimento do conjunto.

  • .env: variáveis de ambiente, como chaves, hosts e segredos de webhook.
  • requirements.txt: dependências Python pinadas por versão para reprodutibilidade.
  • main.py: aplicação FastAPI com rotas de geração de URL/sessão e webhooks.

Dependências e variáveis de ambiente

As dependências reúnem o servidor ASGI, a validação de dados e bibliotecas de criptografia, além de cliente HTTP assíncrono. Um arquivo requirements.txt garante que todas as máquinas usem as mesmas versões, evitando diferenças inesperadas. O bloco a seguir lista as dependências necessárias para executar a API e realizar verificações criptográficas. Esse conteúdo deve ser instalado no ambiente virtual antes de iniciar o servidor.

fastapi==0.115.0
uvicorn[standard]==0.30.6
python-dotenv==1.0.1
pydantic==2.9.2
httpx==0.27.2
pycryptodome==3.21.0
cryptography==43.0.1

As variáveis de ambiente controlam chaves públicas/secretas, hosts e tokens utilizados por cada provedor. Esse mecanismo evita expor credenciais no código e facilita alternar entre sandbox e produção. O exemplo abaixo apresenta um modelo de .env com valores fictícios e comentários de apoio. Os nomes devem refletir o ambiente real, mantendo segredos fora de sistemas de versionamento.

# app
APP_ENV=dev
APP_HOST=127.0.0.1
APP_PORT=8000
CORS_ORIGINS=*

# MoonPay
MOONPAY_PUBLISHABLE_KEY=pk_test_xxxxxxxxxxxxxxxxxxxxxxxxx
MOONPAY_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxxxxxx
MOONPAY_ENV_HOST=buy-sandbox.moonpay.com
MOONPAY_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxxxxxx

# Transak
TRANSAK_BASE_URL=https://api-gateway-stg.transak.com
TRANSAK_API_KEY=trnsak_api_key_xxxxxxxxxxxxxxxxx
TRANSAK_REFERRER_DOMAIN=dominio-exemplo.com
TRANSAK_ACCESS_TOKEN=at_xxxxxxxxxxxxxxxxx

# Ramp
# Host do widget hospedado (pode variar por ambiente).
RAMP_BASE_HOST=app.ramp.network
RAMP_APP_NAME=AppExemplo
# Verificação de webhook por chave pública (ECDSA).
RAMP_PUBLIC_KEY_PEM="-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0B...==\n-----END PUBLIC KEY-----\n"
# Opcional: JWKS se aplicável.
# RAMP_JWKS_URL=https://exemplo/.well-known/jwks.json

Ambiente virtual e execução local

Um ambiente virtual isola as dependências do projeto e evita conflitos com outras instalações do sistema. A sequência de comandos a seguir cria um venv, instala dependências e inicia o servidor com recarregamento automático. O endereço e a porta respeitam as variáveis do .env para facilitar ajustes por ambiente. A execução local permite testar rotas HTTP e interagir com a API usando cURL ou qualquer cliente.

python3 -m venv .venv
source .venv/bin/activate
# Windows: .\.venv\Scripts\Activate.ps1

pip install --upgrade pip
pip install -r requirements.txt

uvicorn main:app --reload --host ${APP_HOST:-127.0.0.1} --port ${APP_PORT:-8000}

Implementação da API (main.py)

O arquivo principal reúne configuração de CORS, modelos Pydantic, helpers criptográficos e rotas HTTP. A rota de MoonPay cria uma URL assinada; a de Transak solicita a criação de sessão no backend do provedor; e a de Ramp monta o hosted URL. As rotas de webhook validam a origem dos eventos: MoonPay via HMAC, Ramp com ECDSA, e Transak com tentativa de descriptografia compatível. O código completo abaixo demonstra cada parte de forma coesa para uso imediato.

import os
import hmac
import base64
import hashlib
import json
from typing import Optional, Dict, Any

from fastapi import FastAPI, Request, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel, Field
from dotenv import load_dotenv
from urllib.parse import urlencode, quote_plus
import httpx

from Crypto.Cipher import AES
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import ec
from cryptography.hazmat.primitives.serialization import load_pem_public_key
from cryptography.exceptions import InvalidSignature

load_dotenv()

APP_ENV = os.getenv("APP_ENV", "dev")
CORS_ORIGINS = os.getenv("CORS_ORIGINS", "*")

# moonpay
MOONPAY_PUBLISHABLE_KEY = os.getenv("MOONPAY_PUBLISHABLE_KEY", "")
MOONPAY_SECRET_KEY = os.getenv("MOONPAY_SECRET_KEY", "")
MOONPAY_ENV_HOST = os.getenv("MOONPAY_ENV_HOST", "buy-sandbox.moonpay.com")
MOONPAY_WEBHOOK_SECRET = os.getenv("MOONPAY_WEBHOOK_SECRET", "")

# transak
TRANSAK_BASE_URL = os.getenv("TRANSAK_BASE_URL", "https://api-gateway-stg.transak.com")
TRANSAK_API_KEY = os.getenv("TRANSAK_API_KEY", "")
TRANSAK_REFERRER_DOMAIN = os.getenv("TRANSAK_REFERRER_DOMAIN", "")
TRANSAK_ACCESS_TOKEN = os.getenv("TRANSAK_ACCESS_TOKEN", "")

# ramp
RAMP_BASE_HOST = os.getenv("RAMP_BASE_HOST", "app.ramp.network")
RAMP_APP_NAME = os.getenv("RAMP_APP_NAME", "MyApp")
RAMP_PUBLIC_KEY_PEM = os.getenv("RAMP_PUBLIC_KEY_PEM", "")
RAMP_JWKS_URL = os.getenv("RAMP_JWKS_URL", "")

app = FastAPI(title="Crypto Gateways API (MoonPay/Transak/Ramp)")

# CORS
if CORS_ORIGINS == "*":
    app.add_middleware(
        CORSMiddleware,
        allow_origins=["*"],
        allow_methods=["*"],
        allow_headers=["*"],
        allow_credentials=True,
    )
else:
    origins = [o.strip() for o in CORS_ORIGINS.split(",") if o.strip()]
    app.add_middleware(
        CORSMiddleware,
        allow_origins=origins,
        allow_methods=["*"],
        allow_headers=["*"],
        allow_credentials=True,
    )

# -----------------------------
# models
# -----------------------------
class MoonPayURLIn(BaseModel):
    currencyCode: str = Field(default="btc")
    walletAddress: Optional[str] = Field(default=None)
    redirectURL: Optional[str] = Field(default=None)
    baseFiatCurrency: Optional[str] = Field(default="USD")
    baseCurrencyAmount: Optional[float] = Field(default=None)

class MoonPayURLOut(BaseModel):
    url: str

class TransakSessionIn(BaseModel):
    network: Optional[str] = Field(default="ethereum")
    cryptoCurrencyCode: Optional[str] = Field(default="ETH")
    fiatCurrency: Optional[str] = Field(default="USD")
    walletAddress: Optional[str] = Field(default=None)
    redirectURL: Optional[str] = Field(default=None)
    email: Optional[str] = Field(default=None)

class TransakSessionOut(BaseModel):
    widgetUrl: str

class RampURLIn(BaseModel):
    cryptoAssetSymbol: Optional[str] = Field(default="ETH")
    fiatCurrency: Optional[str] = Field(default="USD")
    fiatValue: Optional[float] = Field(default=None)
    userAddress: Optional[str] = Field(default=None)
    redirectUrl: Optional[str] = Field(default=None)

class RampURLOut(BaseModel):
    url: str

# -----------------------------
# helpers
# -----------------------------
def moonpay_signed_url(params: Dict[str, Any]) -> str:
    if not MOONPAY_PUBLISHABLE_KEY or not MOONPAY_SECRET_KEY:
        raise RuntimeError("MoonPay keys ausentes (.env)")
    p = {k: v for k, v in params.items() if v not in (None, "")}
    p["apiKey"] = MOONPAY_PUBLISHABLE_KEY
    qs = urlencode(p, doseq=True)
    sig = hmac.new(MOONPAY_SECRET_KEY.encode(), qs.encode(), hashlib.sha256).digest()
    signature_b64 = base64.b64encode(sig).decode()
    return f"https://{MOONPAY_ENV_HOST}/?{qs}&signature={quote_plus(signature_b64)}"

async def transak_create_session(payload: Dict[str, Any]) -> str:
    if not TRANSAK_API_KEY or not TRANSAK_REFERRER_DOMAIN:
        raise RuntimeError("Transak API key/referrer ausentes (.env)")
    url = f"{TRANSAK_BASE_URL}/api/v2/auth/session"
    body = {"widgetParams": {"apiKey": TRANSAK_API_KEY, "referrerDomain": TRANSAK_REFERRER_DOMAIN, **{k: v for k, v in payload.items() if v not in (None, '')}}}
    async with httpx.AsyncClient(timeout=30) as client:
        r = await client.post(url, json=body)
        if r.status_code >= 400:
            raise HTTPException(status_code=r.status_code, detail=f"Transak error: {r.text}")
        data = r.json()
        widget = data.get("widgetUrl") or data.get("data", {}).get("widgetUrl")
        if not widget:
            raise HTTPException(status_code=500, detail=f"Transak: 'widgetUrl' ausente: {data}")
        return widget

def ramp_hosted_url(params: Dict[str, Any]) -> str:
    p = {k: v for k, v in params.items() if v not in (None, "")}
    p.setdefault("appName", RAMP_APP_NAME)
    qs = urlencode(p, doseq=True)
    return f"https://{RAMP_BASE_HOST}/?{qs}"

def transak_decrypt_webhook_maybe(payload: Dict[str, Any]) -> Dict[str, Any]:
    try:
        iv_b64 = payload.get("iv")
        tag_b64 = payload.get("tag")
        ciphertext_b64 = payload.get("ciphertext")
        if not (iv_b64 and tag_b64 and ciphertext_b64):
            return {"raw": payload, "note": "payload não parece criptografado com {iv,tag,ciphertext}"}
        iv = base64.b64decode(iv_b64); tag = base64.b64decode(tag_b64); ciphertext = base64.b64decode(ciphertext_b64)
        key_a = (TRANSAK_ACCESS_TOKEN.encode() + b"\x00"*32)[:32]
        cipher = AES.new(key_a, AES.MODE_GCM, nonce=iv)
        plain_a = cipher.decrypt_and_verify(ciphertext, tag)
        return {"decrypted": json.loads(plain_a.decode()), "mode": "token-as-key"}
    except Exception:
        try:
            import hashlib as _hl
            key_b = _hl.sha256(TRANSAK_ACCESS_TOKEN.encode()).digest()
            iv = base64.b64decode(payload.get("iv")); tag = base64.b64decode(payload.get("tag")); ciphertext = base64.b64decode(payload.get("ciphertext"))
            cipher = AES.new(key_b, AES.MODE_GCM, nonce=iv)
            plain_b = cipher.decrypt_and_verify(ciphertext, tag)
            return {"decrypted": json.loads(plain_b.decode()), "mode": "sha256(token)"}
        except Exception as e2:
            return {"raw": payload, "note": f"falha decrypt: {type(e2).__name__}: {e2}"}

def verify_moonpay_signature_v2(raw: bytes, header_value: Optional[str]) -> bool:
    if not MOONPAY_WEBHOOK_SECRET:
        return True
    if not header_value:
        return False
    sig_prov = header_value
    if "s=" in header_value:
        try:
            parts = header_value.split(",")
            kv = dict([p.split("=", 1) for p in parts])
            sig_prov = kv.get("s", sig_prov)
        except Exception:
            pass
    mac = hmac.new(MOONPAY_WEBHOOK_SECRET.encode(), raw, hashlib.sha256).digest()
    sig_local = base64.b64encode(mac).decode()
    return hmac.compare_digest(sig_prov.encode(), sig_local.encode())

def verify_ramp_ecdsa(raw: bytes, header_value: Optional[str]) -> bool:
    if not header_value:
        return False
    try:
        signature = base64.b64decode(header_value.strip())
    except Exception:
        return False
    if not RAMP_PUBLIC_KEY_PEM:
        return True  # dev only
    try:
        public_key = load_pem_public_key(RAMP_PUBLIC_KEY_PEM.encode())
        public_key.verify(signature, raw, ec.ECDSA(hashes.SHA256()))
        return True
    except InvalidSignature:
        return False
    except Exception:
        return False

# -----------------------------
# rotas
# -----------------------------
@app.get("/healthz")
async def healthz():
    return {"ok": True, "env": APP_ENV}

@app.get("/moonpay/url", response_model=MoonPayURLOut)
async def get_moonpay_url(
    currencyCode: str = "btc",
    walletAddress: Optional[str] = None,
    redirectURL: Optional[str] = None,
    baseFiatCurrency: Optional[str] = "USD",
    baseCurrencyAmount: Optional[float] = None,
):
    params = {
        "currencyCode": currencyCode,
        "walletAddress": walletAddress,
        "redirectURL": redirectURL,
        "baseFiatCurrency": baseFiatCurrency,
        "baseCurrencyAmount": baseCurrencyAmount,
    }
    url = moonpay_signed_url(params)
    return {"url": url}

@app.post("/transak/session", response_model=TransakSessionOut)
async def post_transak_session(body: TransakSessionIn):
    widget = await transak_create_session(body.model_dump())
    return {"widgetUrl": widget}

@app.get("/ramp/url", response_model=RampURLOut)
async def get_ramp_url(
    cryptoAssetSymbol: Optional[str] = "ETH",
    fiatCurrency: Optional[str] = "USD",
    fiatValue: Optional[float] = None,
    userAddress: Optional[str] = None,
    redirectUrl: Optional[str] = None,
):
    params = {
        "cryptoAssetSymbol": cryptoAssetSymbol,
        "fiatCurrency": fiatCurrency,
        "fiatValue": fiatValue,
        "userAddress": userAddress,
        "redirectUrl": redirectUrl,
    }
    url = ramp_hosted_url(params)
    return {"url": url}

@app.post("/webhooks/moonpay")
async def webhook_moonpay(request: Request):
    raw = await request.body()
    hdr = request.headers.get("Moonpay-Signature-V2") or request.headers.get("X-Moonpay-Signature")
    if not verify_moonpay_signature_v2(raw, hdr):
        raise HTTPException(status_code=400, detail="assinatura MoonPay inválida")
    try:
        data = await request.json()
    except Exception:
        data = {"raw": raw.decode("utf-8", errors="replace")}
    return {"ok": True, "provider": "moonpay", "received": data}

@app.post("/webhooks/transak")
async def webhook_transak(request: Request):
    raw = await request.body()
    try:
        payload = await request.json()
    except Exception:
        payload = {"raw": raw.decode("utf-8", errors="replace")}
    dec = transak_decrypt_webhook_maybe(payload if isinstance(payload, dict) else {})
    return {"ok": True, "provider": "transak", "parsed": dec}

@app.post("/webhooks/ramp")
async def webhook_ramp(request: Request):
    raw = await request.body()
    sig = request.headers.get("X-Body-Signature") or request.headers.get("X-Ramp-Webhook-Signature")
    if not verify_ramp_ecdsa(raw, sig):
        raise HTTPException(status_code=400, detail="assinatura Ramp inválida")
    try:
        data = await request.json()
    except Exception:
        data = {"raw": raw.decode("utf-8", errors="replace")}
    return {"ok": True, "provider": "ramp", "received": data}

MoonPay: URL assinada e webhook

Para iniciar o fluxo na MoonPay, a aplicação gera uma URL contendo parâmetros de compra e uma assinatura HMAC. HMAC é um mecanismo de autenticação de mensagem que usa uma chave secreta compartilhada para garantir integridade dos dados. A assinatura é calculada no query string e adicionada ao link, assegurando que parâmetros não foram alterados. No webhook, a API valida o cabeçalho de assinatura da MoonPay comparando com um HMAC local da carga bruta. Esse processo confirma a origem da notificação e evita processamento de eventos forjados.

Transak: criação de sessão e descriptografia opcional

Na Transak, o backend solicita a criação de sessão ao endpoint do provedor e recebe um widget URL pronto para uso. O corpo enviado reúne apiKey, domínio de referência e preferências como rede, moeda e endereço de carteira. O webhook pode chegar em texto simples ou cifrado, dependendo da configuração do provedor e do ambiente. A API tenta decifrar conteúdos no formato AES-GCM usando o token de acesso, caindo para saída bruta quando a descriptografia não se aplica. Esse comportamento permite compatibilidade com variações de payload e facilita diagnóstico.

Ramp: hosted widget e verificação ECDSA

Na Ramp, o fluxo usa um hosted URL montado com parâmetros de ativo, moeda, valor e endereço, além do nome da aplicação. A verificação de webhooks utiliza ECDSA, um algoritmo de assinatura digital baseado em curvas elípticas. A API carrega uma chave pública em formato PEM e valida a assinatura recebida no cabeçalho contra o corpo original do pedido. Caso a chave não esteja configurada em ambiente de desenvolvimento, a verificação pode ser relaxada para permitir testes locais. Em produção, a checagem deve ser obrigatória para garantir integridade e autenticidade.

Rotas expostas

As rotas a seguir organizam a criação de URLs/sessões e o recebimento de eventos dos provedores. Cada item apresenta caminho, método e propósito no fluxo. Essa visão facilita o mapeamento entre chamadas do cliente e integrações com os gateways. A lista resume o que o main.py disponibiliza de forma padronizada.

  • GET /healthz: verificação simples de saúde do serviço.
  • GET /moonpay/url: gera URL assinada para iniciar o widget da MoonPay.
  • POST /transak/session: cria sessão e retorna widgetUrl da Transak.
  • GET /ramp/url: monta o hosted URL do widget da Ramp.
  • POST /webhooks/moonpay: recebe e valida eventos de MoonPay com HMAC.
  • POST /webhooks/transak: recebe eventos e tenta descriptografar payloads da Transak.
  • POST /webhooks/ramp: recebe e valida eventos da Ramp com ECDSA.

Testes com cURL — iniciar a compra

Para MoonPay, um pedido de compra começa com a geração de um link único contendo moeda, valor, endereço e retorno. Esse link é assinado no backend e pode ser aberto em navegador ou webview do aplicativo. O comando de exemplo demonstra parâmetros comuns como currencyCode, walletAddress e baseCurrencyAmount. O retorno é um JSON com o campo url pronto para uso no fluxo hospedado.

curl -s "http://127.0.0.1:8000/moonpay/url?currencyCode=btc&walletAddress=bc1qEXEMPLO...&redirectURL=https%3A%2F%2Fapp.exemplo%2Fretorno&baseFiatCurrency=USD&baseCurrencyAmount=25"

Na Transak, a criação de sessão ocorre via POST com parâmetros de rede, cripto, fiduciária, endereço e e-mail. O provedor retorna um widgetUrl já vinculado à sessão gerada no backend. Esse fluxo reduz exposição de chaves no cliente e centraliza opções de configuração. O comando abaixo mostra um corpo típico e devolve um link direto para a experiência hospedada.

curl -s -X POST "http://127.0.0.1:8000/transak/session" \
  -H "Content-Type: application/json" \
  -d '{
        "network":"ethereum",
        "cryptoCurrencyCode":"ETH",
        "fiatCurrency":"USD",
        "walletAddress":"0x1234...",
        "redirectURL":"https://app.exemplo/retorno",
        "email":"usuario@exemplo.com"
      }'

Na Ramp, a URL é montada no backend com parâmetros como ativo, moeda, valor e endereço do usuário. Essa abordagem habilita abrir a experiência hosted sem expor lógica de montagem no cliente. A parametrização inclui o nome da aplicação e campos de redirecionamento após o término. O exemplo a seguir retorna um JSON com a url final do widget.

curl -s "http://127.0.0.1:8000/ramp/url?cryptoAssetSymbol=ETH&fiatCurrency=USD&fiatValue=50&userAddress=0x1234...&redirectUrl=https%3A%2F%2Fapp.exemplo%2Fretorno"

Testes com cURL — simulação de webhooks

A simulação de webhooks permite exercitar os validadores de assinatura e observar o processamento de eventos. O primeiro exemplo envia uma notificação da MoonPay com assinatura em cabeçalho compatível com HMAC. O segundo representa um payload da Transak com campos de criptografia, útil para verificar a rotina de descriptografia. O terceiro demonstra um evento da Ramp com assinatura ECDSA no cabeçalho, validada contra o corpo recebido. Esses testes ajudam a confirmar o comportamento esperado antes de qualquer implementação em produção.

# MoonPay (substituir assinatura por valor do ambiente real)
curl -s -X POST "http://127.0.0.1:8000/webhooks/moonpay" \
  -H "Content-Type: application/json" \
  -H "Moonpay-Signature-V2: s=BASE64_ASSINATURA" \
  -d '{"type":"payment_status","data":{"status":"completed","id":"evt_123"}}'

# Transak (payload criptografado de exemplo)
curl -s -X POST "http://127.0.0.1:8000/webhooks/transak" \
  -H "Content-Type: application/json" \
  -d '{"iv":"BASE64_IV","tag":"BASE64_TAG","ciphertext":"BASE64_CIPHERTEXT"}'

# Ramp (ECDSA no cabeçalho)
curl -s -X POST "http://127.0.0.1:8000/webhooks/ramp" \
  -H "Content-Type: application/json" \
  -H "X-Body-Signature: BASE64_ASSINATURA" \
  -d '{"purchase":{"id":"p_123","status":"SUCCESS"}}'

Cuidados de produção

A operação em produção requer mecanismos adicionais de robustez e segurança para garantir consistência de pedidos. A validação de duplicidade de eventos, o armazenamento confiável e o processamento assíncrono reduzem falhas e melhoram escalabilidade. Mecanismos contra replay verificam tempo ou nonce, mitigando repetição indevida de chamadas. O gerenciamento de segredos deve evitar arquivos simples e priorizar cofres gerenciados. A lista abaixo resume pontos críticos frequentemente adotados em sistemas de pagamento.

  • Idempotência em webhooks, usando chaves de evento para evitar processamento duplicado.
  • Persistência de pedidos e eventos em banco de dados, com filas para pós-processamento.
  • Proteção contra replay com timestamp, nonce e janelas de aceitação estritas.
  • Segredos fora de arquivos .env, preferindo serviços de segredos gerenciados.
  • Validação em ambientes sandbox antes de liberar em produção.

Encerramento

A combinação de URLs assinadas, sessões no provedor e validação de webhooks entrega um fluxo completo de compra de cripto sem custodiar pagamentos. O uso de FastAPI e Pydantic organiza modelos, validações e rotas de forma clara para manutenção diária. MoonPay, Transak e Ramp são integrados com padrões equivalentes, reduzindo variação entre provedores. A verificação de assinaturas com HMAC e ECDSA reforça integridade e autenticidade dos eventos recebidos. Com esse conjunto, a API inicia compras e captura resultados de maneira padronizada e confiável.

← Back to blog