> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paymove.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> ## paymove integration rules for AI agents
>
> These rules are verified against the live API. Follow them exactly.
>
> 1. Amounts are INTEGERS in grosze (minor units). `1000` means 10.00 PLN. PLN is the only supported currency and there is no currency field in the API.
> 2. A float `price` (e.g. `12.99`) is SILENTLY TRUNCATED to 12 grosze and still returns HTTP 200. Always send an integer: `Math.round(pln * 100)`.
> 3. Authenticate with the `X-API-KEY` header. Never `Authorization: Bearer`. Sandbox keys start with `sk_test_`, production keys with `sk_live_`.
> 4. Server-side only. A call from a merchant page is rejected. Never put the key in frontend code.
> 5. Unknown request fields are silently ignored and still return HTTP 200 — a wrong body shape looks like success. Match the documented shape exactly.
> 6. A missing `externalId` returns HTTP 500 `Something went wrong`, not 400. A missing `price` or `details.returnUrl` returns HTTP 200 and a usable `redirectUrl` — no error at all. Validate the body yourself before sending it.
> 7. Always verify the `X-Paymove-Signature` header on incoming webhooks before trusting them: https://docs.paymove.io/en/webhook-signature.md
> 8. Errors are `{"status": <int>, "message": "<text>"}`. Branch on the HTTP status only — never on `message`, which is unstable and leaks internal class names.
> 9. There is no rate limiting, no HTTP 429, no HTTP 422, no `Idempotency-Key` header and no API versioning. Do not write code that handles them.
> 10. Re-POSTing an `externalId` that already exists returns HTTP 200 with the ORIGINAL `redirectUrl` and silently discards EVERY field you send — the new price, description and details are all ignored. Use `PATCH /api/pay/product/{productId}/subproduct/{externalId}` to change a price.
> 11. Webhooks fire only on `COMPLETED` by default, and `retries` defaults to `0` (no retries) unless you set it explicitly. Delivery counts as successful when the HTTP status equals `expectedCode` — the response body is never inspected.
> 12. Never fulfil an order on the `returnUrl` redirect. The checkout does not redirect there by itself: the customer has to click "back to shop", and inside the widget modal that redirect never happens. Fulfil only in the webhook handler, after verifying the signature.
> 13. Do not pin a version of `@paymove-io/sdk` — install the latest.
> 14. Full documentation index: https://docs.paymove.io/llms.txt · Copy-paste quickstart: https://docs.paymove.io/en/quickstart.md · Agent skill: https://docs.paymove.io/skill.md

# Start

> Płatności dla agentów i inteligentnych systemów AI

AI Payments to zestaw integracji, dzięki którym agenci AI - zarówno tekstowi (LLM podłączone
przez MCP), jak i głosowi (ElevenLabs) - mogą samodzielnie sprawdzać katalog produktów i
płacić za nie BLIK-iem w imieniu użytkownika. Każda płatność to osobna, świeża transakcja
BLIK, potwierdzana kodem z aplikacji bankowej - obecnie agent nigdy nie płaci automatycznie, bez
udziału człowieka w danej transakcji.

## Jak to działa?

Każdy agent AI jest powiązany z jednym kontem (`agentId` + klucz API) w Agent Panel. Wszystkie
kwoty w API AI Payments wyrażone są w **groszach** (najmniejsza jednostka PLN, liczba
całkowita) - to obowiązuje zarówno w katalogu produktów, jak i w żądaniach płatności.

<Warning>
  Płatność BLIK-iem nie jest pobierana z zasilonego wcześniej salda portfela w
  Agent Panel - to osobna, każdorazowo potwierdzana płatność. Saldo portfela
  dotyczy innego mechanizmu (automatyczne płatności x402 bez potwierdzenia
  BLIK), który na ten moment jest wyłączony - patrz sekcja MCP.
</Warning>

```mermaid theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
sequenceDiagram
    participant U as Użytkownik
    participant A as Agent AI (MCP / ElevenLabs)
    participant P as Agent Panel API
    participant PM as Paymove (BLIK)

    U->>A: "Kup mi bilet do Kopernika"
    A->>P: Sprawdź katalog produktów
    A->>U: Poproś o kod BLIK
    U->>A: Podaje kod BLIK
    A->>P: Zainicjuj płatność (agentId, cena, kod BLIK)
    P->>PM: Utwórz płatność BLIK
    PM->>P: Status płatności
    A->>P: Sprawdzaj status aż do rozstrzygnięcia
    A->>U: Potwierdzenie sukcesu / niepowodzenia
```

## Dwie ścieżki integracji

<CardGroup cols={2}>
  <Card title="MCP" icon="robot" href="/products/ai-payments/mcp">
    Serwer Model Context Protocol dla agentów LLM (Claude i inni klienci MCP) -
    narzędzia do przeglądania katalogu, płatności BLIK i historii transakcji.
  </Card>

  <Card title="ElevenLabs" icon="microphone" href="/products/ai-payments/elevenlabs">
    Agent głosowy osadzony w Agent Panel - klient rozmawia głosowo, agent
    sprawdza katalog i finalizuje płatność BLIK przez narzędzia webhook.
  </Card>
</CardGroup>

<Warning>
  Guardrails (limity kwotowe) skonfigurowane dla agenta w Agent Panel nie są
  dziś egzekwowane przy płatności BLIK - żadna z integracji nie sprawdza ich
  przed zainicjowaniem płatności. Bezpieczeństwo zapewnia w tej chwili wyłącznie
  to, że każdą płatność BLIK musi osobno potwierdzić człowiek w aplikacji
  bankowej.
</Warning>