AI Интеграция

You are integrating with Trustly Pay — an API-first payment gateway.

BASE URL: https://api.trustlypay.io
API VERSION: v1
AUTH: Authorization: Bearer <API_KEY> or X-API-Key: <API_KEY>
KEY FORMAT: op_test_xxxxxxxx (test) or op_live_xxxxxxxx (live)

ENDPOINTS:
POST   /v1/payments                  — Create payment
GET    /v1/payments/:id              — Get payment
GET    /v1/payments                  — List payments
POST   /v1/payments/:id              — Cancel payment
POST   /v1/payments/:id/capture      — Capture payment
POST   /v1/payments/:id/authorize    — Authorize payment
POST   /v1/checkout/sessions         — Create checkout session
GET    /v1/checkout/sessions/:id     — Get checkout session
POST   /v1/customers                 — Create customer
GET    /v1/customers/:id             — Get customer
GET    /v1/customers                 — List customers
PATCH  /v1/customers/:id             — Update customer
DELETE /v1/customers/:id             — Delete customer
POST   /v1/refunds                   — Create refund
GET    /v1/refunds/:id               — Get refund
GET    /v1/refunds                   — List refunds
POST   /v1/payouts                   — Create payout
GET    /v1/payouts/:id               — Get payout
GET    /v1/payouts                   — List payouts
GET    /v1/balance                   — Get balance
GET    /v1/balance/transactions      — List balance transactions
POST   /v1/webhooks/endpoints        — Create webhook endpoint
GET    /v1/webhooks/endpoints/:id    — Get webhook endpoint
GET    /v1/webhooks/endpoints        — List webhook endpoints
PATCH  /v1/webhooks/endpoints/:id    — Update webhook endpoint
DELETE /v1/webhooks/endpoints/:id    — Delete webhook endpoint
POST   /v1/webhooks/endpoints/:id/test — Test webhook endpoint
GET    /v1/payment-methods           — List payment methods
GET    /v1/payment-methods/:id       — Get payment method
POST   /v1/currencies                — Create currency
GET    /v1/currencies/:id            — Get currency
GET    /v1/currencies                — List currencies

RULES:
- Use only documented endpoints from OpenAPI
- Use test mode (op_test_*) during development
- Use Idempotency-Key header for payment creation
- Verify webhook signatures with HMAC-SHA256
- Handle all payment states: created, pending, succeeded, failed, canceled, expired, refunded, partially_refunded
- Never expose API keys in code or logs
- Amounts are in kopecks (smallest currency unit)
- Currency is 3 uppercase letters (RUB, USD, EUR)

OPENAPI: https://api.trustlypay.io/api/v1/openapi
FULL DOCS: https://trustlypay.io/docs/

# Trustly Pay — AI Agent Rules

## Never invent endpoints
Always reference the OpenAPI spec before writing code.
If unsure, ask or check the documentation.

## Always check OpenAPI spec first
The OpenAPI JSON: https://api.trustlypay.io/api/v1/openapi
Fetch and parse it to understand request/response schemas.

## Use test mode first
Always use op_test_* keys during development.
Never use op_live_* keys in code examples or logs.

## Implement webhook verification
Verify all webhook signatures using HMAC-SHA256.
Never trust unverified webhook payloads.

## Handle payment state machine
Payment flow: created → pending → succeeded/failed/canceled/expired
Refund flow: pending → succeeded/failed
Respect state transitions — do not skip states.

## Use idempotency for mutations
Always include Idempotency-Key header for POST /v1/payments.
Generate unique keys for each payment attempt.

## Handle retries and errors
Implement exponential backoff for retries.
Handle rate limiting (429 responses) gracefully.
Log all errors for debugging.

## Never expose secrets
Never log API keys, webhook secrets, or tokens.
Never include secrets in client-side code.
Use environment variables for all credentials.