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

# Referência da API

> 35 endpoints, um formato de erro, uma autenticação. Com playground pra testar aqui mesmo.

**Base URL:** `https://api.purin.cash`

Todos os endpoints ficam sob `/v1` e exigem o header de autenticação:

```
Authorization: Bearer ps_live_sua_chave
```

> [!TIP]
>
> Cada página desta seção tem um playground. Cole uma chave `ps_test_` e dispare a
> requisição direto do navegador, sem sair da documentação.

## Convenções

> [accordion] Dinheiro vai em centavos, inteiro
>
> `valueCents: 4990` é R\$ 49,90. Os campos terminados em `Cents` são sempre inteiros.
>
> Duas exceções, que vale conhecer antes de escrever o parser: cartão e saque usam
> `amount` em reais decimal, e produto da loja usa `price` como **texto** no padrão
> brasileiro (`"49,90"`).

> [accordion] O prefixo do ID diz o que é
>
> | Prefixo | Recurso |
> | - | - |
> | `psa_` | Pagamento de `POST /v1/payments` |
> | `psa_sub_` | Assinatura |
> | `psc_` | Cobrança de `POST /v1/charges` |
> | `psplit_` | Cobrança com split |
> | Sem prefixo | Cartão usa `orderCode`, produto usa ObjectId |

> [accordion] Erro tem sempre a mesma forma
>
> ```json theme={null}
> { "error": "Descrição do que deu errado" }
> ```
>
> Trate pelo código HTTP, não pelo texto. Lista completa em [Erros](https://docs.purin.cash/guias/erros.md).

> [accordion] Listagem pagina com limit e offset
>
> `limit` vai de 1 a 100 (padrão 50) e `offset` pula resultados. A resposta traz `total`,
> `limit` e `offset` junto do array.

> [accordion] metadata é string, não objeto
>
> Mande um JSON já serializado, de até 2 KB. Ele volta exatamente igual na consulta e no
> webhook, sem parse do nosso lado.
>
> ```json theme={null}
> { "metadata": "{\"pedido\":\"1042\"}" }
> ```
>
> A única exceção é cobrança com [split](https://docs.purin.cash/guias/splits.md), que não aceita `metadata`.

> [accordion] Data é sempre ISO 8601 em UTC
>
> `2026-03-18T12:05:00.000Z`. Converta para o fuso do usuário só na exibição.

## O mapa

> [card] Receber
>
> `/v1/payments` para PIX e LTC.
>
> `/v1/charges` para PIX avulso e split.
>
> `/v1/card-payments` para cartão.
>
> `/v1/subscriptions` para recorrência.

> [card] Catálogo
>
> `/v1/products` para produtos de cobrança.
>
> `/v1/store/products` para os da loja do Discord.
>
> `/v1/deliveries` para o conteúdo entregue.

> [card] Dinheiro
>
> `/v1/wallet` para saldo e retenções.
>
> `/v1/subaccounts` para saldo por cliente seu.
>
> `/v1/payouts` para sacar.
>
> `/v1/disputes` para contestações.

> [card] Teste
>
> `/v1/sandbox/*` para simular pagamento e conferir saldo de teste.
>
> Só com chave `ps_test_`.

## Limites que valem lembrar

| O quê | Limite |
| - | - |
| Requisições | 120 por minuto, somando todas as rotas `/v1/*` |
| Saques | 10 por hora, 5 se for turbo |
| Chaves de API ativas | 10 por conta |
| Produtos de cobrança | 500 por conta e por ambiente |
| Subcontas | 1000 por conta e por ambiente |
| Cobrança com split | R\$ 5.000,00 por cobrança |
| Beneficiários no split | 9, além de você |

Detalhes e como lidar com `429` em [Limites de requisição](https://docs.purin.cash/guias/limites.md).

> [card] [Nunca usou a API?](https://docs.purin.cash/guias/primeira-cobranca.md)
>
> O guia de primeira cobrança vai do zero ao webhook recebido, tudo em sandbox.


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