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

# Referência da API

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

**Base URL:** `https://api.purincash.com`

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.
</Tip>

## Convenções

<AccordionGroup>
  <Accordion title="Dinheiro vai em centavos, inteiro" icon="coins" defaultOpen>
    `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>

  <Accordion title="O prefixo do ID diz o que é" icon="fingerprint">
    | 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>

  <Accordion title="Erro tem sempre a mesma forma" icon="triangle-exclamation">
    ```json theme={null}
    { "error": "Descrição do que deu errado" }
    ```

    Trate pelo código HTTP, não pelo texto. Lista completa em [Erros](/guias/erros).
  </Accordion>

  <Accordion title="Listagem pagina com limit e offset" icon="list">
    `limit` vai de 1 a 100 (padrão 50) e `offset` pula resultados. A resposta traz `total`,
    `limit` e `offset` junto do array.
  </Accordion>

  <Accordion title="metadata é string, não objeto" icon="tag">
    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](/guias/splits), que não aceita `metadata`.
  </Accordion>

  <Accordion title="Data é sempre ISO 8601 em UTC" icon="clock">
    `2026-03-18T12:05:00.000Z`. Converta para o fuso do usuário só na exibição.
  </Accordion>
</AccordionGroup>

## O mapa

<CardGroup cols={2}>
  <Card title="Receber" icon="arrow-down-to-bracket">
    `/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>

  <Card title="Catálogo" icon="box">
    `/v1/products` para produtos de cobrança.

    `/v1/store/products` para os da loja do Discord.

    `/v1/deliveries` para o conteúdo entregue.
  </Card>

  <Card title="Dinheiro" icon="wallet">
    `/v1/wallet` para saldo e retenções.

    `/v1/payouts` para sacar.

    `/v1/disputes` para contestações.
  </Card>

  <Card title="Teste" icon="flask">
    `/v1/sandbox/*` para simular pagamento e conferir saldo de teste.

    Só com chave `ps_test_`.
  </Card>
</CardGroup>

## 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                   |
| 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](/guias/limites).

<Card title="Nunca usou a API?" icon="rocket" href="/guias/primeira-cobranca" horizontal>
  O guia de primeira cobrança vai do zero ao webhook recebido, tudo em sandbox.
</Card>