P2P payments for apps
and AI agents

Quick start

Three steps to send your first payment.

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

# Turn on developer mode first
curl -X PATCH https://api.payg0.io/api/v1/users/developer-mode \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{"enabled": true}'

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

# Prepare $100 MXN for @carlos: no money moves yet
curl -X POST https://api.payg0.io/api/v1/payments/intents \
  -H 'X-API-Key: pyg0_test_xxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"recipient": "@carlos", "amount": "100.00"}'

# Response: the user opens confirm_url and confirms with their PIN on payg0.io
{
  "id": "uuid...",
  "status": "AWAITING_CONFIRMATION",
  "confirm_url": "https://payg0.io/confirm-payment/uuid..."
}

# Then check it: CONFIRMED, DECLINED, EXPIRED or FAILED
curl https://api.payg0.io/api/v1/payments/intents/{id} \
  -H 'X-API-Key: pyg0_test_xxxxxxxxxxxxx'

Authentication

Two methods, depending on the context.

API Key X-API-Key

Best for server-to-server integrations and AI agents. Create your keys with POST /api/v1/keys.

X-API-Key: pyg0_test_a1b2c3d4e5f6g7h8

JWT Bearer

For user sessions. A 24-hour token from POST /api/v1/auth/login.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Endpoints

Every endpoint, generated from the code. Base URL https://api.payg0.io; full schemas in openapi.json.

Accounts cannot be created through the API. People sign up at payg0.io/register (email verification included); the API works on accounts that already exist.

Auth

Wallet

Payment intents

Payments

Users

API keys, webhooks and usage

Automatic payments

For agents and apps that must pay without a person present.

• → The key's owner turns them on at payg0.io → My profile → API & Dev, with their PIN, and sets two caps: per payment and per day (defaults $500 and $1,500 MXN, never above the tier limits).
• → The key can then call POST /api/v1/payments/send without a PIN. The API never accepts a PIN.
• → The permission lasts 30 days; renewing it needs the PIN again. The owner gets an email for every automatic payment.
• → Errors: 403 AUTOPAY_OFF / AUTOPAY_EXPIRED / PAYMENTS_ON_HOLD; 422 AUTOPAY_LIMIT_PAYMENT / AUTOPAY_LIMIT_DAILY, plus the tier limit errors.

Webhooks

Get real-time notifications when a payment event happens.

Step 1: Register the webhook

Accepts X-API-Key or Bearer: AI agents can register and manage their webhooks directly with their API key, without logging in.

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://your-app.com/webhooks/payg0",
    "events": ["payment.received", "payment.completed"]
  }'

# Response: store the secret now, it is never shown again
{
  "id": "uuid...",
  "url": "https://your-app.com/webhooks/payg0",
  "events": ["payment.received", "payment.completed"],
  "secret": "a3f8c2d1e9b4...",
  "is_active": true
}

Step 2: Verify the signature on every delivery

Every request includes the header X-Payg0-Signature: sha256={hmac}. Verify it with the secret you got when registering.

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)

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

Step 3: Update events without deleting the webhook

You can change the URL or the subscribed events at any time. The secret and the ID stay the same.

# Subscribe only to received payments (drop 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"]}'

# You can also update only the 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://new-url.com/webhook"}'

Step 4: If you lose the secret, rotate it

No need to delete and register the webhook again. Use this endpoint; the old secret stops working immediately.

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

# Response: the new secret, returned only once
{
  "id": "uuid...",
  "secret": "b7e1a4f2c9d8..."
}

Payload structure

Each delivery is a POST with Content-Type: application/json and this body:

{
  "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":     "Another test",
    "created_at":      "2026-05-26T17:35:00+00:00",
    "updated_at":      "2026-05-26T17:35:00+00:00"
  }
}

Available events

Code examples

Sending a payment in several languages.

import httpx

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

# Check the balance
balance = client.get("/api/v1/wallet/balance").json()
print(f"Available: ${balance['available_balance']} MXN")

# Prepare a payment; the user confirms it with their PIN on payg0.io
intent = client.post("/api/v1/payments/intents", json={
    "recipient": "@carlos",
    "amount": "150.00",
    "description": "Payment for services",
}).json()
print(f"Confirm here: {intent['confirm_url']}")

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

// Check the balance
const balance = await fetch(`${BASE}/api/v1/wallet/balance`, { headers: HEADERS })
  .then(r => r.json());
console.log(`Available: $${balance.available_balance} MXN`);

// Prepare a payment; the user confirms it with their PIN on payg0.io
const intent = await fetch(`${BASE}/api/v1/payments/intents`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({ recipient: "@carlos", amount: "150.00" }),
}).then(r => r.json());
console.log(`Confirm here: ${intent.confirm_url}`);

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

# Prepare a payment (the user confirms it with their PIN on payg0.io)
curl -X POST https://api.payg0.io/api/v1/payments/intents \
  -H "X-API-Key: pyg0_test_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"recipient":"@carlos","amount":"150.00","description":"Payment"}'

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

Rate limits

Each endpoint's limit is in the tables above. Limits apply per API key, JWT session or IP.

Above the limit you get 429 Too Many Requests. Limits are per minute: wait about a minute before retrying.

Error codes

Every error returns JSON with a detail field.