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

# Payments API overview

> The Payments API (V3) creates, confirms, captures and refunds payments through one Payment object.

> [!NOTE]
>
> **Preview.** The Payments API (V3) is live at `https://api.tagada.io/v1`, but it is not open to self-serve integrations yet: merchant secret keys cannot be created from the dashboard. Every merchant processes on [V2](https://docs.tagada.io/payments-api/v2-or-v3.md) today. Contact [api-support@tagadapay.com](mailto:api-support@tagadapay.com) if you plan a new integration.

The Payments API is TagadaPay's new payments interface, also called V3. It replaces the payment calls of the Commerce API (V2) with one resource, the **Payment**, and one way to drive it: create on your server, confirm in the browser, follow `next_action` until the payment reaches a final status.

```text theme={null}
https://api.tagada.io/v1
```

## How it works

1. Your server creates a payment with a secret key. The response carries a `client_secret`.
2. Your page passes the `client_secret` to the browser client, `@tagadapay/core-js/payments-v3`, which holds a publishable key (`tpk_`).
3. The browser confirms the payment. If the bank or the payment method needs the shopper, the payment moves to `requires_action` and carries a [`next_action`](https://docs.tagada.io/payments-api/payment-lifecycle#next_action) (3DS, redirect, wallet confirmation). The browser client performs it.
4. The payment ends in `succeeded`, `requires_capture`, `failed` or `canceled`. Your server reads it to fulfil the order.

## What the API covers

| Area | Resources |
| - | - |
| Payments | `payments` (create, confirm, capture, cancel, retry, timeline), `refunds`, `disputes` (read) |
| Shoppers | `customers`, `payment-methods` |
| Recurring | `renewal-cycles` |
| Routing | `payment-policies`, `processors`, `block-list` |
| Browser | `publishable-keys`, `client-config`, `eligible-methods` |
| Testing | `test-helpers/clocks` |

The full list is in the [API reference](https://docs.tagada.io/payments-api/reference/introduction.md).

## Conventions

| Topic | Rule |
| - | - |
| [Authentication](https://docs.tagada.io/payments-api/authentication.md) | `Authorization: Bearer <key>`. Secret keys on servers, publishable keys in browsers. |
| [Versioning](https://docs.tagada.io/payments-api/versioning.md) | `Payments-Version: 2026-11-01`. Every response returns the version it used. |
| [Idempotency](https://docs.tagada.io/payments-api/idempotency.md) | `Idempotency-Key` is required on every `POST` and `PATCH` that changes state. |
| [Errors](https://docs.tagada.io/payments-api/errors.md) | One error object: `type`, `code`, `message`, `param`, `request_id`. A decline is not an HTTP error. |
| Amounts | Integers in the currency minor unit (`1999` is 19.99 USD). |
| Lists | Cursor pagination: `limit` (1 to 100, default 20) and `cursor` in the query; `has_more` and `next_cursor` in the response. |
| Enums | Response enums are open. Handle values you do not know. |

## Release phases

| Phase | Meaning | Today |
| - | - | - |
| Preview | Live in production, contract versioned, access on request. | Payments API, `@tagadapay/core-js/payments-v3` |
| Coming soon | Designed, not available. | Self-serve secret keys, merchant webhooks, `node-sdk` Payments API methods, `headless-sdk` V3 support |
| Generally available | Open to every merchant. | Commerce API and V2 payments |

## Next steps

> **[V2 or V3?](https://docs.tagada.io/payments-api/v2-or-v3.md)**
>
> Which API to use for a new or existing integration.

> **[Payment lifecycle](https://docs.tagada.io/payments-api/payment-lifecycle.md)**
>
> Statuses, `client_secret` and `next_action`.

> **[Browser client](https://docs.tagada.io/payments-api/browser-client.md)**
>
> Card fields, wallets and confirmation with `core-js/payments-v3`.

> **[Migrate from V2](https://docs.tagada.io/payments-api/migrate-from-v2.md)**
>
> What changes, what stays, and the per-store switch.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.