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

# Examples Overview

> Runnable, testable, cross-language examples of the Pagou v2 core flows, linked to the matching guide and API reference.

The [**PagouAi/examples**](https://github.com/PagouAi/examples) repository is a practical, runnable
companion to these docs. Every core v2 flow is implemented in seven languages using an idiomatic HTTP
client with as few dependencies as possible — it is **not** an SDK and **not** framework-specific, so
the same patterns translate across stacks.

Each guide here links to the exact example directory and file that implements it, and every example
links back to its guide and API reference operation. Use the docs to understand a flow, then jump to
working code you can clone and run against the sandbox.

## Browse by flow

<CardGroup cols={2}>
  <Card title="Payments" icon="wallet" href="/examples/payments">
    Pix + QR, vouchers, card via Payment Element, 3DS, full and partial refunds, cursor pagination.
  </Card>

  <Card title="Checkout Links" icon="link" href="/examples/checkout-links">
    Create a checkout link and store the returned public URL identifier.
  </Card>

  <Card title="Customers & Subscriptions" icon="repeat" href="/examples/subscriptions">
    Create or reuse a customer, then create, retrieve and cancel a subscription.
  </Card>

  <Card title="Transfers (Pix Out)" icon="arrow-left-right" href="/examples/transfers">
    Create, retrieve and reconcile a transfer; cancel when the status allows.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/examples/webhooks">
    Real handlers for the transaction, subscription and transfer event families.
  </Card>
</CardGroup>

## Languages

Every flow above is implemented in each of these languages. Open a language directory for its
`README.md`, `.env.example` and per-flow subdirectories.

| Language          | Runtime (min / current) | Directory                                                                 |
| ----------------- | ----------------------- | ------------------------------------------------------------------------- |
| TypeScript / Node | 18.18 / 20.x            | [`typescript/`](https://github.com/PagouAi/examples/tree/main/typescript) |
| Python            | 3.10 / 3.14             | [`python/`](https://github.com/PagouAi/examples/tree/main/python)         |
| PHP               | 8.1 / 8.4               | [`php/`](https://github.com/PagouAi/examples/tree/main/php)               |
| Java              | 17 / 21                 | [`java/`](https://github.com/PagouAi/examples/tree/main/java)             |
| C# / .NET         | 8.0 / 8.0               | [`dotnet/`](https://github.com/PagouAi/examples/tree/main/dotnet)         |
| Go                | 1.21 / 1.26             | [`go/`](https://github.com/PagouAi/examples/tree/main/go)                 |
| Ruby              | 3.2 / 3.3               | [`ruby/`](https://github.com/PagouAi/examples/tree/main/ruby)             |

The TypeScript reference additionally ships an `@pagouai/api-sdk` variant alongside the raw-HTTP one.

## How to run

<Steps>
  <Step title="Get a sandbox token">
    Sign in to your dashboard and create a **sandbox** API token. Sandbox and production tokens are
    separate — keep them that way.
  </Step>

  <Step title="Pick a language and flow">
    Open a language directory and read its `README.md`, then open the flow subdirectory (for example
    `typescript/payments/`).
  </Step>

  <Step title="Configure the environment">
    Copy `.env.example` to `.env` in that language directory and set your sandbox token. The base URL
    defaults to `https://api.sandbox.pagou.ai`.
  </Step>

  <Step title="Run a flow">
    Each flow README documents a single run command, the input payload, the relevant response, and the
    expected error and recovery path.
  </Step>
</Steps>

## Coverage and security

* The [coverage matrix](https://github.com/PagouAi/examples/blob/main/docs/coverage-matrix.md) is the
  single source of truth for what each language implements.
* No example ever accepts a PAN or CVV at the backend — card data flows only through the
  [Payment Element](/frontend/payment-element/overview) to a `pgct_*` token. API keys are server-side
  only, fixtures are synthetic, and logs redact secrets.

<Note>
  The repository is in **beta** while the docs Examples area rolls out and owner teams are assigned.
  The flows themselves are complete, tested and runnable today.
</Note>