# Trustly Pay API

> API-first payment gateway for Russia. Accept payments via SBP, bank cards, payment links, and crypto.

## Documentation
- API Reference: https://api.trustlypay.io/docs
- OpenAPI Spec: https://api.trustlypay.io/api/v1/openapi
- Full Documentation: https://trustlypay.io/docs/
- Full API Reference (for AI): llms-full.txt

## Quick Start
Base URL: https://api.trustlypay.io
Auth: Bearer token (op_test_xxx or op_live_xxx)
API Version: v1

## Core Endpoints
- POST /api/v1/payments — Create payment
- GET /api/v1/payments — List payments
- GET /api/v1/payments/{id} — Get payment
- POST /api/v1/payments/{id} — Cancel payment
- POST /api/v1/checkout/sessions — Create checkout session
- GET /api/v1/checkout/sessions — List checkout sessions
- GET /api/v1/checkout/{token} — Public checkout page
- POST /api/v1/refunds — Create refund
- GET /api/v1/refunds — List refunds
- GET /api/v1/refunds/{id} — Get refund
- POST /api/v1/customers — Create customer
- GET /api/v1/customers — List customers
- GET /api/v1/customers/{id} — Get customer
- PATCH /api/v1/customers/{id} — Update customer
- DELETE /api/v1/customers/{id} — Delete customer
- GET /api/v1/customers/{id}/payments — List customer payments
- POST /api/v1/payouts — Create payout
- GET /api/v1/payouts — List payouts
- GET /api/v1/balance — Account balance
- GET /api/v1/balance/transactions — Balance transaction history
- POST /api/v1/webhooks/endpoints — Register webhook
- GET /api/v1/webhooks/endpoints — List webhooks
- GET /api/v1/webhooks/endpoints/{id} — Get webhook
- PATCH /api/v1/webhooks/endpoints/{id} — Update webhook
- DELETE /api/v1/webhooks/endpoints/{id} — Delete webhook
- GET /api/v1/webhooks/endpoints/{id}/deliveries — Webhook delivery history
- POST /api/v1/webhooks/endpoints/{id}/deliveries/{delivery_id}/retry — Retry delivery
- GET /api/v1/projects — List projects
- GET /api/v1/payment-methods — List payment methods
- GET /api/v1/limits — Payment limits
- GET /api/v1/health — Health check
- GET /api/v1/openapi — OpenAPI spec

## Key Concepts
- Payment States: created → pending → succeeded/failed/canceled/expired → refunded/partially_refunded
- Idempotency: Use Idempotency-Key header on POST requests
- Webhooks: HMAC-SHA256 signature verification required
- Pagination: Cursor-based (starting_after, limit)
- Amounts: Always in smallest currency unit (kopecks for RUB)
- Currency: Always 3 uppercase letters (e.g., RUB)

## AI Rules
- Never invent endpoints — use only documented ones
- Use test mode (op_test_*) during development
- Always use idempotency for payment creation
- Verify webhook signatures with HMAC-SHA256
- Handle all payment states including failed/expired/canceled
- Never expose API keys in code or logs
- Use /api/v1/openapi for the canonical API contract