Add LLM/AI agent context document (AGENTS.md) for better AI-assisted integrations

[pedro412]

Summary

As AI coding assistants (Claude Code, GitHub Copilot, Cursor, etc.) become standard tools for developers, having a structured context document significantly improves the quality of AI-assisted integrations.

The Problem

When developers use AI agents to integrate Openpay, the agents struggle because:

1. The docs site (documents.openpay.mx) returns 403 for programmatic access — AI tools can't read your documentation
2. The Python SDK README lacks charge/checkout/webhook examples — the most critical flows aren't documented in a machine-readable format
3. No structured context file exists — agents have to piece together information from test files and source code

Proposal

Add an AGENTS.md (or CLAUDE.md / AI_CONTEXT.md) file to this repo and other Openpay SDKs with:

Suggested content

# Openpay Python SDK — Agent Context

## Authentication
- merchant_id: Your merchant identifier
- api_key: Private key (sk_...) for server-side operations  
- public_key: Public key (pk_...) for client-side tokenization
- sandbox: Set `openpay.production = False` for testing

## Checkout (Recommended for e-commerce)
POST /v1/{merchant_id}/checkouts — creates hosted checkout session
- Request: { amount, currency, description, order_id, customer: {name, last_name, email, phone_number}, redirect_url }
- Response: { id, checkout_link, status: "available", ... }
- Redirect user to checkout_link → Openpay hosted payment page
- Supports: cards, OXXO, SPEI in one integration

## Direct Charges
POST /v1/{merchant_id}/charges
- Card: { method: "card", source_id: "<token>", amount, description, order_id, device_session_id, customer }
- Store (OXXO): { method: "store", amount, description } → returns payment_method.reference + barcode_url
- Bank (SPEI): { method: "bank_account", amount, description } → returns payment_method.clabe

## Charge Statuses
- in_progress: Awaiting payment (store/bank)
- completed: Payment confirmed
- failed: Payment failed
- cancelled: Cancelled/expired

## Webhooks
- Register: openpay.Webhook.create(url=..., event_types=[...])
- Auth: HTTP Basic Auth with your API credentials
- Events: charge.succeeded, charge.failed, charge.cancelled, etc.

## Refunds
charge.refund(merchant=True)  # full refund
charge.refund(amount=50.00, merchant=True)  # partial refund

## Error Types
- InvalidRequestError: Bad format or non-existent URL
- AuthenticationError: Missing/invalid private key
- CardError: Declined, expired, insufficient funds
- APIError: All other errors

## Test Cards (Sandbox)
- Approved: 4111111111111111
- Declined: 4000000000000002

Why This Matters

• Claude Code, Cursor, and GitHub Copilot can read repository files but not SPAs
• A single AGENTS.md would make Openpay integrations dramatically faster and more accurate
• Other payment providers are starting to adopt this pattern (Stripe has excellent structured docs that AI tools can parse)
• This is low effort (one file) with high impact for developer experience

References

• Anthropic's CLAUDE.md convention
• The docs site at documents.openpay.mx uses a JS SPA that returns 403 to programmatic requests, making it invisible to AI tools