Pagos P2P para apps
y agentes de IA

Quick start

Tres pasos para enviar tu primer pago.

# POST /api/v1/auth/login
curl -X POST https://api.payg0.io/api/v1/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/api/v1/users/developer-mode \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{"enabled": true}'

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

# Enviar $100 MXN a un usuario
curl -X POST https://api.payg0.io/api/v1/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 /api/v1/keys.

X-API-Key: pyg0_test_a1b2c3d4e5f6g7h8

JWT Bearer

Para sesiones de usuario. Token de 24 horas obtenido en POST /api/v1/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 · acepta X-API-Key o Bearer)

Uso y métricas (requiere modo dev)

Webhooks

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

Paso 1 — Registrar el webhook

Acepta X-API-Key o Bearer — los agentes de IA pueden registrar y gestionar sus webhooks directamente con su API key, sin necesidad de login.

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

# Response — guarda el secret ahora, no se vuelve a mostrar
{
  "id": "uuid...",
  "url": "https://tu-app.com/webhooks/payg0",
  "events": ["payment.received", "payment.completed"],
  "secret": "a3f8c2d1e9b4...",
  "is_active": true
}

Paso 2 — Verificar la firma en cada entrega

Cada request incluye el header X-Payg0-Signature: sha256={hmac}. Verifica con el secret recibido al registrar.

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)

Paso 3 — Actualizar eventos sin borrar el webhook

Puedes cambiar la URL o los eventos suscritos en cualquier momento. El secret y el ID permanecen igual.

# Suscribirse solo a pagos recibidos (quitar payment.completed)
curl -X PATCH https://api.payg0.io/api/v1/webhooks/{id} \
  -H 'X-API-Key: pyg0_test_xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"events": ["payment.received"]}'

# También puedes actualizar solo la URL
curl -X PATCH https://api.payg0.io/api/v1/webhooks/{id} \
  -H 'X-API-Key: pyg0_test_xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://nueva-url.com/webhook"}'

Paso 4 — Si pierdes el secret, rótalo

No es necesario borrar y volver a registrar el webhook. Usa este endpoint — el secret anterior queda inválido de inmediato.

curl -X POST https://api.payg0.io/api/v1/webhooks/{id}/rotate-secret \
  -H 'X-API-Key: pyg0_test_xxxx'

# Response — nuevo secret, devuelto una única vez
{
  "id": "uuid...",
  "secret": "b7e1a4f2c9d8..."
}

Estructura del payload

Cada entrega es un POST con Content-Type: application/json y este cuerpo:

{
  "event": "payment.received",
  "data": {
    "id": "bc1b2680-d870-41fd-8063-d79bd749d724",
    "sender_id":       "808e5be1-12d7-4a58-ad56-f3d6a2a8fd38",
    "sender_nickname":  "nando",
    "receiver_id":      "ff793bad-7d97-4e5e-baba-6ecc70c12260",
    "receiver_nickname": "diegotco",
    "receiver_email":   null,
    "amount":          "2.97",
    "currency":        "MXN",
    "status":          "COMPLETED",
    "reason":          "transferred",
    "description":     "Es otra prueba",
    "created_at":      "2026-05-26T17:35:00+00:00",
    "updated_at":      "2026-05-26T17:35:00+00:00"
  }
}

Eventos disponibles

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("/api/v1/wallet/balance").json()
print(f"Disponible: ${balance['available_balance']} MXN")

# Enviar pago
response = client.post("/api/v1/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}/api/v1/wallet/balance`, { headers: HEADERS })
  .then(r => r.json());
console.log(`Disponible: $${balance.available_balance} MXN`);

// Enviar pago
const tx = await fetch(`${BASE}/api/v1/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/api/v1/wallet/balance \
  -H "X-API-Key: pyg0_test_xxxxxxxxxxxxx"

# Enviar pago
curl -X POST https://api.payg0.io/api/v1/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/api/v1/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.