Pagos P2P para apps
y agentes de IA

Quick start

Tres pasos para enviar tu primer pago.

# POST /auth/login
curl -X POST https://api.payg0.io/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"tu@email.com","password":"tu-password"}'

# Activa modo dev primero
curl -X PATCH https://api.payg0.io/users/developer-mode \
  -H 'Authorization: Bearer {token}' \
  -d '{"enabled": true}'

# Genera tu API key
curl -X POST https://api.payg0.io/keys \
  -H 'Authorization: Bearer {token}' \
  -d '{"name": "Mi app"}'

# Enviar $100 MXN a un usuario
curl -X POST https://api.payg0.io/payments/send \
  -H 'X-API-Key: pyg0_test_xxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"recipient": "@carlos", "amount": 100.00}'

# Response
{
  "id": "uuid...",
  "status": "COMPLETED",
  "reason": "transferred",
  "amount": "100.00"
}

Autenticación

Dos métodos según el contexto.

API Key X-API-Key

Ideal para integraciones server-to-server y agentes de IA. Genera tus keys en POST /keys.

X-API-Key: pyg0_test_a1b2c3d4e5f6g7h8

JWT Bearer

Para sesiones de usuario. Token de 24 horas obtenido en POST /auth/login.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Endpoints

Todos los endpoints disponibles en la API.

Auth

Wallet

Pagos

Usuarios

API Keys (requiere modo dev)

Webhooks (requiere modo dev)

Webhooks

Recibe notificaciones en tiempo real cuando ocurre un evento de pago.

Eventos disponibles

• payment.completed
• payment.pending
• payment.failed
• payment.cancelled
• payment.expired

Registrar un webhook

curl -X POST https://api.payg0.io/webhooks \
  -H 'X-API-Key: pyg0_test_xxxx' \
  -d '{
    "url": "https://tu-app.com/webhooks/payg0",
    "events": ["payment.completed", "payment.failed"]
  }'

Verificar la firma

Cada request incluye el header X-Payg0-Signature: sha256={hmac}. Verifica con el secret que recibiste al crear el webhook.

import hmac, hashlib

def verify_signature(payload: bytes, secret: str, signature: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# En tu handler:
body = await request.body()
sig = request.headers["X-Payg0-Signature"]
if not verify_signature(body, WEBHOOK_SECRET, sig):
    raise HTTPException(401)

Ejemplos de código

Enviar un pago en distintos lenguajes.

import httpx

client = httpx.Client(
    base_url="https://api.payg0.io",
    headers={"X-API-Key": "pyg0_test_xxxxxxxxxxxxx"},
)

# Consultar saldo
balance = client.get("/wallet/balance").json()
print(f"Disponible: ${balance['available_balance']} MXN")

# Enviar pago
response = client.post("/payments/send", json={
    "recipient": "@carlos",
    "amount": 150.00,
    "description": "Pago por servicio",
})
tx = response.json()
print(f"Transacción {tx['id']}: {tx['status']}")

const BASE = "https://api.payg0.io";
const HEADERS = {
  "X-API-Key": "pyg0_test_xxxxxxxxxxxxx",
  "Content-Type": "application/json",
};

// Consultar saldo
const balance = await fetch(`${BASE}/wallet/balance`, { headers: HEADERS })
  .then(r => r.json());
console.log(`Disponible: $${balance.available_balance} MXN`);

// Enviar pago
const tx = await fetch(`${BASE}/payments/send`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({ recipient: "@carlos", amount: 150 }),
}).then(r => r.json());
console.log(`Transacción ${tx.id}: ${tx.status}`);

# Saldo
curl https://api.payg0.io/wallet/balance \
  -H "X-API-Key: pyg0_test_xxxxxxxxxxxxx"

# Enviar pago
curl -X POST https://api.payg0.io/payments/send \
  -H "X-API-Key: pyg0_test_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"recipient":"@carlos","amount":150,"description":"Pago"}'

# Historial
curl "https://api.payg0.io/payments/history?status=COMPLETED&limit=10" \
  -H "X-API-Key: pyg0_test_xxxxxxxxxxxxx"

Rate limits

Los límites se aplican por API key, sesión JWT o IP.

Al superar el límite recibirás 429 Too Many Requests. El header Retry-After indica cuándo reintentar.

Códigos de error

Todos los errores retornan JSON con el campo detail.