# PurinCash — Documentacao completa da API

> Gateway de pagamentos brasileiro: PIX instantaneo, cartao de credito, criptomoedas (LTC) e integracao Discord.
> Base URL: https://api.purincash.com — prefixo /v1
> Auth: Authorization: Bearer ps_live_<key> (producao) ou ps_test_<key> (sandbox)
> Rate limit: 120 requisicoes/minuto por chave. Erros no formato { "error": "mensagem" }.
> Indice navegavel: https://purincash.com/llms.txt
> Contato: contato@purincash.com

Este arquivo contem a documentacao completa de todos os endpoints da API publica,
gerada a partir do comportamento real da API. Cada secao tambem existe como pagina
individual em https://purincash.com/docs/ (links no llms.txt).


---

# Authentication

> Como autenticar suas requisições na API da PurinCash usando chaves de API (Bearer token).

Todas as requisições à API pública devem ser autenticadas com uma **chave de API** enviada no header `Authorization` usando o esquema **Bearer**.

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

## Obtendo sua chave

1. Acesse o painel em [purincash.com](https://purincash.com).
2. Vá até a seção **API**.
3. Gere uma chave de **produção** (`ps_live_...`) ou de **sandbox** (`ps_test_...`).

A chave completa é exibida **apenas no momento da criação** — guarde-a em local seguro. Se perdê-la, revogue e gere uma nova.

## Formato da chave

| Prefixo | Ambiente | Descrição |
|---|---|---|
| `ps_live_` | Produção | Transações reais, com movimentação financeira |
| `ps_test_` | Sandbox | Ambiente de testes, sem movimentação real |

O **ambiente é derivado automaticamente do prefixo da chave**. Não existe parâmetro de ambiente na URL ou no body: uma chave `ps_test_` opera sempre em sandbox e uma chave `ps_live_` opera sempre em produção, com isolamento total entre os dois ambientes.

## Enviando a chave

Inclua o header em toda requisição:

```
Authorization: Bearer ps_live_SUA_CHAVE_AQUI
```

Exemplo com curl:

```bash
curl https://api.purincash.com/v1/payments \
  -H "Authorization: Bearer ps_live_abc123..." \
  -H "Content-Type: application/json"
```

Em sandbox:

```bash
curl https://api.purincash.com/v1/payments \
  -H "Authorization: Bearer ps_test_abc123..." \
  -H "Content-Type: application/json"
```

## Boas práticas de segurança

- **Nunca** exponha a chave em código frontend (JavaScript no navegador, apps mobile). Use-a apenas em chamadas servidor-a-servidor.
- Não versione a chave em repositórios de código; use variáveis de ambiente ou um gerenciador de segredos.
- Use chaves `ps_test_` durante o desenvolvimento e a integração.
- Revogue imediatamente qualquer chave que possa ter vazado e gere uma nova no painel.
- Rotacione as chaves periodicamente.

## Erros

Falhas de autenticação retornam `401 Unauthorized` com o formato padrão `{ "error": string }`:

| HTTP | Mensagem | Causa |
|---|---|---|
| 401 | `API key required. Use: Authorization: Bearer ps_live_...` | Header `Authorization` ausente ou sem o esquema `Bearer ps_...` |
| 401 | `Invalid API key prefix. Use ps_live_ or ps_test_` | A chave não começa com `ps_live_` nem `ps_test_` |
| 401 | `Invalid or revoked API key` | Chave inexistente, incorreta ou revogada no painel |
| 401 | `API key environment mismatch. Please generate a new key.` | Prefixo da chave não corresponde ao ambiente em que ela foi criada — gere uma nova chave no painel |
| 500 | `Internal error` | Erro interno ao validar a chave — tente novamente |

Exemplo de resposta de erro:

```json
{
  "error": "Invalid or revoked API key"
}
```

---

# Errors

> Formato padrão de erros da API da PurinCash e o significado de cada código HTTP.

A API usa códigos de status HTTP convencionais e retorna **todo erro** como um objeto JSON com um único campo:

```json
{
  "error": "Descrição do que deu errado"
}
```

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

## Formato

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| error | string | Sim | Mensagem legível descrevendo o erro. Use o código HTTP para tratamento programático; a mensagem é para diagnóstico |

## Códigos HTTP

| Código | Significado | Quando ocorre |
|---|---|---|
| 400 | Bad Request | Parâmetros ausentes, inválidos ou fora dos limites (ex.: valor mínimo, formato de ID) |
| 401 | Unauthorized | Chave de API ausente, inválida, revogada ou com prefixo incorreto (veja [Authentication](./authentication.md)) |
| 403 | Forbidden | A chave é válida, mas a operação não é permitida (ex.: endpoint de sandbox com chave `ps_live_`, conta sem verificação aprovada) |
| 404 | Not Found | O recurso solicitado não existe ou não pertence à sua conta |
| 429 | Too Many Requests | Limite de requisições excedido (veja [Rate Limit](./rate-limit.md)) |
| 500 | Internal Server Error | Erro inesperado no servidor — tente novamente; se persistir, contate o suporte |
| 502 | Bad Gateway | Falha temporária ao processar a transação junto ao provedor — tente novamente em instantes |

## Exemplos

Requisição com parâmetro inválido:

```bash
curl -X POST https://api.purincash.com/v1/payments \
  -H "Authorization: Bearer ps_test_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "valueCents": 10 }'
```

Resposta `400`:

```json
{
  "error": "valueCents must be >= 80 (R$ 0.80), or provide productId"
}
```

Recurso inexistente (`404`):

```json
{
  "error": "Charge not found"
}
```

Endpoint de sandbox com chave de produção (`403`):

```json
{
  "error": "Sandbox endpoint requires ps_test_ key"
}
```

Mensagens exatas comuns:

| HTTP | Mensagem |
|---|---|
| 400 | `Invalid product ID format` |
| 400 | `priceCents must be >= 100 (R$ 1.00)` |
| 400 | `callbackUrl must be a valid, public HTTPS URL` |
| 400 | `paymentMethod must be 'pix' or 'ltc'` |
| 403 | `Sandbox endpoint requires ps_test_ key` |
| 404 | `Product not found` |
| 404 | `Charge not found` |
| 429 | `Rate limit exceeded. Max 120 requests/minute.` |
| 500 | `Internal error` |
| 502 | `LTC price unavailable` |

## Boas práticas

- Trate erros pelo **código HTTP**, não pelo texto da mensagem (o texto pode mudar).
- Registre o body `{ "error": ... }` nos seus logs para facilitar o diagnóstico.
- Para `429`, `500` e `502`, implemente retry com backoff exponencial. Para `4xx` restantes, corrija a requisição antes de reenviar.

---

# Rate Limit

> Limites de requisições da API pública da PurinCash e como lidar com respostas 429.

Para garantir estabilidade, a API pública aplica limite de requisições por origem.

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

## Limite

| Escopo | Limite | Janela |
|---|---|---|
| Rotas `/v1/*` | **120 requisições** | 60 segundos (janela fixa) |

O limite se aplica a todas as rotas da API pública (`/v1/...`), somando todos os endpoints.

## Headers de rate limit

A API envia os headers padrão (draft IETF `RateLimit-*`) em toda resposta:

| Header | Descrição |
|---|---|
| RateLimit-Limit | Total de requisições permitidas na janela (120) |
| RateLimit-Remaining | Requisições restantes na janela atual |
| RateLimit-Reset | Segundos até a janela reiniciar |

Monitore `RateLimit-Remaining` para desacelerar antes de atingir o limite.

## Comportamento ao exceder (429)

Ao ultrapassar 120 requisições no minuto, a API responde `429 Too Many Requests` com o body:

```json
{
  "error": "Rate limit exceeded. Max 120 requests/minute."
}
```

Exemplo:

```bash
curl -i https://api.purincash.com/v1/payments \
  -H "Authorization: Bearer ps_live_abc123..."
```

```
HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 42
Content-Type: application/json

{ "error": "Rate limit exceeded. Max 120 requests/minute." }
```

## Boas práticas de retry

- **Nunca faça retry imediato** de um 429 — você continuará bloqueado até a janela reiniciar.
- Use **backoff exponencial com jitter**: espere 1s, 2s, 4s, 8s... adicionando um valor aleatório para evitar rajadas sincronizadas.
- Respeite `RateLimit-Reset`: se disponível, aguarde pelo menos esse número de segundos antes de tentar de novo.
- Limite o número de tentativas (ex.: 5) e registre falhas persistentes.
- Para consultar status de pagamentos, prefira **webhooks** (veja [Webhooks](./webhooks.md)) em vez de polling — isso elimina a maior parte do consumo de requisições.
- Se fizer polling, use intervalos de 5s ou mais e interrompa assim que o status final chegar.

Exemplo de backoff em pseudocódigo:

```js
async function requestWithRetry(fn, maxRetries = 5) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fn();
    if (res.status !== 429) return res;
    const reset = Number(res.headers.get("RateLimit-Reset")) || 2 ** attempt;
    const jitter = Math.random() * 1000;
    await sleep(reset * 1000 + jitter);
  }
  throw new Error("Rate limit: máximo de tentativas excedido");
}
```

## Erros

| HTTP | Mensagem | Causa |
|---|---|---|
| 429 | `Rate limit exceeded. Max 120 requests/minute.` | Mais de 120 requisições em 60 segundos nas rotas `/v1/*` |

---

# Webhooks

> Receba notificações HTTP em tempo real quando um pagamento for confirmado ou um saque mudar de status.

Ao criar um pagamento ou cobrança, informe um `callbackUrl`. Quando o evento ocorrer (ex.: pagamento confirmado), a PurinCash fará um **POST** nessa URL com o payload JSON do evento.

## Exigências do callbackUrl

| Requisito | Detalhe |
|---|---|
| HTTPS | Obrigatório. URLs `http://` são rejeitadas |
| Domínio público | Apenas nomes de domínio. IPs numéricos, IPv6, `localhost` e endereços de rede privada são bloqueados |
| Resposta rápida | Responda com status **2xx em até 5 segundos**. Timeout ou status fora de 2xx contam como falha e disparam reentrega |

URLs inválidas retornam `400` com a mensagem: `callbackUrl must be a valid, public HTTPS URL`.

## Headers enviados

| Header | Descrição |
|---|---|
| Content-Type | Sempre `application/json` |
| X-Webhook-Signature | HMAC-SHA256 (hex) do body bruto, assinado com o seu **webhook secret** (obtido na seção API do painel [purincash.com](https://purincash.com)) |
| X-Webhook-Id | Chave de idempotência estável no formato `evento:id` (ex.: `payment.paid:psa_abc123`). Reentregas do mesmo evento usam o mesmo valor — use-o para deduplicar |

### Verificando a assinatura

```js
const crypto = require("crypto");

function isValid(rawBody, signatureHeader, webhookSecret) {
  const expected = crypto.createHmac("sha256", webhookSecret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}
```

Calcule o HMAC sobre o **body bruto** (antes de fazer parse do JSON). Rejeite requisições com assinatura inválida.

## Reentregas (retry)

Se a entrega falhar (timeout de 5s, erro de rede ou status não-2xx), o evento entra na fila de reentrega com backoff crescente:

| Tentativa | Espera após a falha anterior |
|---|---|
| 1ª | Imediata (no momento do evento) |
| 2ª | ~1 minuto |
| 3ª em diante | 5, 30, 120, 360 e 720 minutos |

São feitas até **7 tentativas no total**. O body reenviado é **idêntico** ao original e o `X-Webhook-Id` não muda — implemente deduplicação por ele.

## Eventos e payloads

### `payment.paid` / `charge.paid` — pagamento PIX confirmado

```json
{
  "event": "payment.paid",
  "paymentId": "psa_abc123",
  "amountCents": 1990,
  "status": "paid",
  "paidAt": "2026-07-11T14:32:10.000Z",
  "customer": { "name": "João Silva", "email": "joao@exemplo.com", "externalId": "user_42" },
  "metadata": "{\"orderId\":\"123\"}",
  "payer": "JOAO DA SILVA",
  "bank": "00000000 - BANCO DO BRASIL S.A.",
  "endToEndId": "E00000000202607111432abcdef123456",
  "txId": "abc123def456",
  "description": "Plano Pro",
  "amountReais": 19.9,
  "deliveredContent": "chave-do-produto-1"
}
```

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| event | string | Sim | `payment.paid` (pagamentos `psa_`) ou `charge.paid` (cobranças `psc_`) |
| paymentId | string | Sim | ID do pagamento/cobrança na PurinCash |
| amountCents | number | Sim | Valor em centavos |
| status | string | Sim | Sempre `paid` neste evento |
| paidAt | string | Sim | Data/hora da confirmação (ISO 8601) |
| customer | object | Não | Dados do cliente informados na criação (`name`, `email`, `externalId`) |
| metadata | string | Não | Metadata informada na criação, devolvida sem alteração |
| payer | string | Não | Nome do pagador no PIX |
| bank | string | Não | Banco do pagador (`código - nome`); apenas em `charge.paid` |
| endToEndId | string | Não | Identificador end-to-end da transação PIX |
| txId | string | Não | txid da transação PIX |
| description | string | Não | Descrição informada na criação |
| amountReais | number | Não | Valor bruto em reais |
| deliveredContent | string | Não | Conteúdo entregue automaticamente (quando há produto com estoque) |
| sandbox | boolean | Não | `true` quando o evento foi gerado pelos endpoints de simulação do sandbox |

Nos endpoints de simulação do sandbox (`simulate-paid`), o `event` enviado é sempre `payment.paid` — inclusive ao simular cobranças `psc_` — e o payload contém apenas `event`, `paymentId`, `amountCents`, `status`, `paidAt`, `customer`, `metadata` e `sandbox: true`.

Campos opcionais são omitidos quando não se aplicam. Dados sensíveis (CPF, telefone, endereço) **nunca** são enviados em webhooks.

### `card_payment.paid` — pagamento com cartão confirmado

```json
{
  "event": "card_payment.paid",
  "orderCode": "ord_abc123",
  "amount": 19.9,
  "status": "paid",
  "paidAt": "2026-07-11T14:32:10.000Z",
  "customer": { "name": "João Silva", "email": "joao@exemplo.com" },
  "metadata": null
}
```

### `withdrawal.requested` / `withdrawal.completed` / `withdrawal.denied` — saques

Enviados à URL de webhook configurada no painel quando um saque é solicitado, concluído ou negado. Em sandbox os eventos são `withdrawal.test.requested` e `withdrawal.test.completed`.

```json
{
  "event": "withdrawal.completed",
  "withdrawalId": "665f1a2b3c4d5e6f7a8b9c0d",
  "code": "WD-1234",
  "amount": 150.0,
  "method": "pix",
  "walletAddress": "chave-pix-ou-carteira",
  "status": "concluido",
  "processedAt": "2026-07-11T15:00:00.000Z"
}
```

Eventos `withdrawal.requested` incluem `requestedAt` e `sandbox` (boolean) em vez de `processedAt`.

## Boas práticas

- Responda `200` **imediatamente** e processe o evento de forma assíncrona.
- Deduplique pelo header `X-Webhook-Id` — reentregas e confirmações duplicadas usam a mesma chave.
- Sempre valide `X-Webhook-Signature` antes de confiar no payload.
- Não dependa da ordem de chegada dos eventos; confirme o estado atual via `GET` na API se necessário.

---

# List Products

> Lista todos os produtos da sua conta, ordenados do mais recente para o mais antigo.

```
GET /v1/products
```

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

## Autenticação

`Authorization: Bearer ps_live_...` (use `ps_test_...` para sandbox)

## Parâmetros

### Query

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| includeInactive | string | Não | Envie `"true"` para incluir produtos inativos. Por padrão, apenas produtos com `active: true` são retornados. |

## Exemplo

```bash
curl -X GET "https://api.purincash.com/v1/products?includeInactive=true" \
  -H "Authorization: Bearer ps_live_SEU_TOKEN"
```

## Resposta

`200 OK`

```json
{
  "products": [
    {
      "_id": "665f1c2ab8e4d21f3c9a7e01",
      "name": "Plano Premium",
      "description": "Acesso mensal ao plano premium",
      "priceCents": 1990,
      "currency": "BRL",
      "active": true,
      "metadata": "{}",
      "createdAt": "2026-07-01T12:00:00.000Z",
      "updatedAt": "2026-07-01T12:00:00.000Z"
    }
  ]
}
```

Campos de cada produto:

| Campo | Tipo | Descrição |
|---|---|---|
| _id | string | Identificador único do produto. |
| name | string | Nome do produto (máx. 200 caracteres). |
| description | string | Descrição exibida na cobrança (máx. 500 caracteres). |
| priceCents | number | Preço em centavos (ex.: `1990` = R$ 19,90). |
| currency | string | Moeda do produto (padrão `BRL`). |
| active | boolean | Indica se o produto está ativo. |
| metadata | string | Metadata livre do integrador (string JSON, máx. 2 KB). |
| createdAt | string | Data de criação (ISO 8601). |
| updatedAt | string | Data da última atualização (ISO 8601). |

## Erros

| HTTP | Erro | Quando |
|---|---|---|
| 401 | `API key required. Use: Authorization: Bearer ps_live_...` | Header `Authorization` ausente. |
| 401 | `Invalid API key prefix. Use ps_live_ or ps_test_` | Chave com prefixo inválido. |
| 401 | `Invalid or revoked API key` | Chave inexistente ou revogada. |
| 500 | `Internal error` | Falha interna do servidor. |

---

# Get Product

> Retorna os detalhes de um produto específico pelo seu ID.

```
GET /v1/products/:id
```

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

## Autenticação

`Authorization: Bearer ps_live_...` (use `ps_test_...` para sandbox)

## Parâmetros

### Path

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| id | string | Sim | ID do produto (retornado na criação ou na listagem). |

## Exemplo

```bash
curl -X GET "https://api.purincash.com/v1/products/665f1c2ab8e4d21f3c9a7e01" \
  -H "Authorization: Bearer ps_live_SEU_TOKEN"
```

## Resposta

`200 OK`

```json
{
  "_id": "665f1c2ab8e4d21f3c9a7e01",
  "name": "Plano Premium",
  "description": "Acesso mensal ao plano premium",
  "priceCents": 1990,
  "currency": "BRL",
  "active": true,
  "metadata": "{}",
  "createdAt": "2026-07-01T12:00:00.000Z",
  "updatedAt": "2026-07-01T12:00:00.000Z"
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| _id | string | Identificador único do produto. |
| name | string | Nome do produto. |
| description | string | Descrição exibida na cobrança. |
| priceCents | number | Preço em centavos (ex.: `1990` = R$ 19,90). |
| currency | string | Moeda do produto (padrão `BRL`). |
| active | boolean | Indica se o produto está ativo. |
| metadata | string | Metadata livre do integrador (string JSON, máx. 2 KB). |
| createdAt | string | Data de criação (ISO 8601). |
| updatedAt | string | Data da última atualização (ISO 8601). |

## Erros

| HTTP | Erro | Quando |
|---|---|---|
| 400 | `Invalid product ID format` | O `id` informado não é um ID válido. |
| 401 | `API key required. Use: Authorization: Bearer ps_live_...` | Header `Authorization` ausente. |
| 401 | `Invalid or revoked API key` | Chave inexistente ou revogada. |
| 404 | `Product not found` | Produto não existe, pertence a outra conta ou a outro ambiente (live/sandbox). |
| 500 | `Internal error` | Falha interna do servidor. |

---

# Create Product

> Cria um novo produto na sua conta, com preço em centavos como fonte de verdade para cobranças.

```
POST /v1/products
```

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

## Autenticação

`Authorization: Bearer ps_live_...` (use `ps_test_...` para sandbox)

## Parâmetros

### Body (JSON)

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| name | string | Sim | Nome do produto. Truncado em 200 caracteres. |
| description | string | Não | Descrição exibida na cobrança. Truncada em 500 caracteres. Padrão: `""`. |
| priceCents | number | Sim | Preço em centavos. Mínimo `100` (R$ 1,00). Valores decimais são arredondados. |
| currency | string | Não | Código da moeda (3 letras, convertido para maiúsculas). Padrão: `BRL`. |
| metadata | string | Não | Metadata livre do integrador (string JSON, máx. 2048 caracteres). Padrão: `"{}"`. |

Limite: máximo de 500 produtos por conta (por ambiente).

## Exemplo

```bash
curl -X POST "https://api.purincash.com/v1/products" \
  -H "Authorization: Bearer ps_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plano Premium",
    "description": "Acesso mensal ao plano premium",
    "priceCents": 1990,
    "currency": "BRL",
    "metadata": "{\"sku\":\"premium-mensal\"}"
  }'
```

## Resposta

`201 Created`

```json
{
  "_id": "665f1c2ab8e4d21f3c9a7e01",
  "name": "Plano Premium",
  "description": "Acesso mensal ao plano premium",
  "priceCents": 1990,
  "currency": "BRL",
  "active": true,
  "metadata": "{\"sku\":\"premium-mensal\"}",
  "createdAt": "2026-07-01T12:00:00.000Z"
}
```

O produto é criado com `active: true` por padrão.

## Erros

| HTTP | Erro | Quando |
|---|---|---|
| 400 | `name is required` | Campo `name` ausente ou vazio. |
| 400 | `priceCents must be >= 100 (R$ 1.00)` | Preço menor que 100 centavos. |
| 400 | `Max 500 products per account` | Limite de 500 produtos atingido. |
| 401 | `API key required. Use: Authorization: Bearer ps_live_...` | Header `Authorization` ausente. |
| 401 | `Invalid or revoked API key` | Chave inexistente ou revogada. |
| 500 | `Internal error` | Falha interna do servidor. |

---

# Update Product

> Atualiza parcialmente um produto existente; apenas os campos enviados são alterados.

```
PUT /v1/products/:id
```

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

## Autenticação

`Authorization: Bearer ps_live_...` (use `ps_test_...` para sandbox)

## Parâmetros

### Path

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| id | string | Sim | ID do produto a atualizar. |

### Body (JSON)

Todos os campos são opcionais — envie apenas o que deseja alterar. Campos omitidos permanecem inalterados.

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| name | string | Não | Novo nome do produto (não pode ser vazio). Truncado em 200 caracteres. |
| description | string | Não | Nova descrição. Truncada em 500 caracteres. |
| priceCents | number | Não | Novo preço em centavos. Mínimo `100`. Valores decimais são arredondados. |
| active | boolean | Não | Ativa (`true`) ou desativa (`false`) o produto. |
| metadata | string | Não | Nova metadata (string JSON, máx. 2048 caracteres). |

O campo `updatedAt` é atualizado automaticamente.

## Exemplo

```bash
curl -X PUT "https://api.purincash.com/v1/products/665f1c2ab8e4d21f3c9a7e01" \
  -H "Authorization: Bearer ps_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "priceCents": 2490,
    "active": false
  }'
```

## Resposta

`200 OK` — retorna o produto já atualizado.

```json
{
  "_id": "665f1c2ab8e4d21f3c9a7e01",
  "name": "Plano Premium",
  "description": "Acesso mensal ao plano premium",
  "priceCents": 2490,
  "currency": "BRL",
  "active": false,
  "metadata": "{}",
  "createdAt": "2026-07-01T12:00:00.000Z",
  "updatedAt": "2026-07-10T09:30:00.000Z"
}
```

## Erros

| HTTP | Erro | Quando |
|---|---|---|
| 400 | `name cannot be empty` | Campo `name` enviado, mas vazio após remoção de espaços. |
| 400 | `priceCents must be >= 100` | Campo `priceCents` enviado com valor menor que 100. |
| 400 | `Invalid product ID format` | O `id` informado não é um ID válido. |
| 401 | `API key required. Use: Authorization: Bearer ps_live_...` | Header `Authorization` ausente. |
| 401 | `Invalid or revoked API key` | Chave inexistente ou revogada. |
| 404 | `Product not found` | Produto não existe, pertence a outra conta ou a outro ambiente (live/sandbox). |
| 500 | `Internal error` | Falha interna do servidor. |

---

# Delete Product

> Remove permanentemente um produto da sua conta.

```
DELETE /v1/products/:id
```

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

## Autenticação

`Authorization: Bearer ps_live_...` (use `ps_test_...` para sandbox)

## Parâmetros

### Path

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| id | string | Sim | ID do produto a excluir. |

A exclusão é permanente e não pode ser desfeita. Se você quiser apenas impedir novas cobranças mantendo o histórico, prefira desativar o produto com `PUT /v1/products/:id` enviando `{ "active": false }`.

## Exemplo

```bash
curl -X DELETE "https://api.purincash.com/v1/products/665f1c2ab8e4d21f3c9a7e01" \
  -H "Authorization: Bearer ps_live_SEU_TOKEN"
```

## Resposta

`200 OK`

```json
{
  "deleted": true
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| deleted | boolean | `true` quando o produto foi excluído com sucesso. |

## Erros

| HTTP | Erro | Quando |
|---|---|---|
| 400 | `Invalid product ID format` | O `id` informado não é um ID válido. |
| 401 | `API key required. Use: Authorization: Bearer ps_live_...` | Header `Authorization` ausente. |
| 401 | `Invalid or revoked API key` | Chave inexistente ou revogada. |
| 404 | `Product not found` | Produto não existe, pertence a outra conta ou a outro ambiente (live/sandbox). |
| 500 | `Internal error` | Falha interna do servidor. |

---

# Create Payment

> Cria um pagamento PIX ou LTC (Litecoin), vinculado a um produto do catálogo ou com valor avulso.

```
POST /v1/payments
```

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

## Autenticação

Envie o header `Authorization: Bearer <sua_chave>` — use `ps_live_...` em produção ou `ps_test_...` em sandbox.

## Parâmetros

Informe **`productId`** (o valor vem do produto) **ou** **`valueCents`** (valor avulso). Se ambos forem enviados, `productId` tem prioridade.

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `productId` | string | condicional | ID de um produto ativo criado via API. O valor e a moeda vêm do produto (moedas diferentes de BRL são convertidas automaticamente para BRL). |
| `valueCents` | integer | condicional | Valor avulso em centavos, quando não usar `productId`. Mínimo: `80` (R$ 0,80). |
| `description` | string | não | Descrição do pagamento avulso (máx. 200 caracteres). Usada como nome do produto na cobrança; padrão `"Pagamento"`. |
| `paymentMethod` | string | não | Método de pagamento: `pix` (padrão) ou `ltc` (Litecoin). LTC não está disponível em sandbox. |
| `callbackUrl` | string | não | URL HTTPS pública que receberá o webhook `payment.paid` (máx. 500 caracteres). |
| `customer.name` | string | não | Nome do cliente (máx. 100 caracteres). |
| `customer.email` | string | não | E-mail do cliente (máx. 255 caracteres). |
| `customer.externalId` | string | não | Identificador do cliente no seu sistema (máx. 200 caracteres). |
| `metadata` | string | não | Dados livres (ex.: JSON serializado), máx. 2048 caracteres. Retornado nas consultas e no webhook. |
| `supplier.productId` | string | não | ID público (`prod_xxx`) de um produto do seu painel vinculado a fornecedor, para entrega automática após o pagamento. |
| `supplier.variationIndex` | integer | não | Índice da variação do produto de fornecedor: `0` (primeira), `1` (segunda), etc. Padrão: `0`. |

Ao usar `supplier`, o valor da venda é validado contra o custo do fornecedor: se for menor que o custo (fixo ou percentual), o pagamento é recusado com erro `400`.

O pagamento PIX expira em **30 minutos**; o pagamento LTC expira em **25 minutos**.

## Exemplo

```bash
curl -X POST https://api.purincash.com/v1/payments \
  -H "Authorization: Bearer ps_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "valueCents": 1990,
    "description": "Plano mensal",
    "paymentMethod": "pix",
    "callbackUrl": "https://minhaloja.com/webhooks/purincash",
    "customer": {
      "name": "Maria Silva",
      "email": "maria@example.com",
      "externalId": "cliente_123"
    },
    "metadata": "{\"orderId\":\"456\"}"
  }'
```

## Resposta

Pagamento PIX:

```json
{
  "paymentId": "psa_9f2c1a7e5b3d4c8a0e6f1b2d3c4e5a6f",
  "status": "pending",
  "type": "one_time",
  "amountCents": 1990,
  "currency": "BRL",
  "productName": "Plano mensal",
  "environment": "live",
  "pix": {
    "brCode": "00020126580014br.gov.bcb.pix...",
    "qrCodeImage": "data:image/png;base64,..."
  },
  "expiresAt": "2026-07-11T15:30:00.000Z"
}
```

`pix.qrCodeImage` pode ser `null` (inclusive sempre em sandbox); nesse caso, gere o QR Code a partir de `pix.brCode`.

Pagamento LTC (`paymentMethod: "ltc"`):

```json
{
  "paymentId": "psa_9f2c1a7e5b3d4c8a0e6f1b2d3c4e5a6f",
  "status": "pending",
  "type": "one_time",
  "paymentMethod": "ltc",
  "amountCents": 1990,
  "currency": "BRL",
  "productName": "Plano mensal",
  "environment": "live",
  "ltc": {
    "address": "ltc1q...",
    "amount": 0.03412345,
    "amountBrl": 19.9,
    "ltcPriceBrl": 583.21
  },
  "expiresAt": "2026-07-11T15:25:00.000Z"
}
```

## Erros

| HTTP | Erro | Quando |
|---|---|---|
| 400 | `valueCents must be >= 80 (R$ 0.80), or provide productId` | Sem `productId` e `valueCents` abaixo de 80. |
| 400 | `callbackUrl must be a valid, public HTTPS URL` | `callbackUrl` inválida, não HTTPS ou não pública. |
| 400 | `paymentMethod must be 'pix' or 'ltc'` | `paymentMethod` com valor diferente de `pix`/`ltc`. |
| 400 | `LTC payments are not available in sandbox mode` | `paymentMethod: "ltc"` com chave `ps_test_`. |
| 400 | `supplier.productId must be a public API ID (prod_xxx). Get it from your product panel.` | `supplier.productId` sem o prefixo `prod_`. |
| 400 | `supplier.variationIndex {n} does not exist. Product has {x} variation(s).` | Índice de variação inexistente no produto. |
| 400 | `Price too low. Supplier cost is R$ {custo} (...), but sale amount is R$ {valor}. Increase valueCents or product price.` | Valor da venda menor que o custo do fornecedor. |
| 400 | `Invalid productId format` | `productId` com formato inválido. |
| 403 | `Antes de receber pagamentos, verifique sua conta: acesse o painel → Carteira → Verificar Chave PIX e preencha seu nome e chave PIX. Isso é obrigatório para novas lojas.` | Loja ainda não verificada. |
| 403 | `No approved supplier access for this variation` | Sem acesso aprovado ao fornecedor da variação. |
| 404 | `Product not found or inactive` | `productId` inexistente ou produto inativo. |
| 404 | `supplier.productId not found` | Produto de fornecedor não encontrado no seu painel. |
| 502 | `Failed to create PIX charge (...): {detalhe}` | Falha ao gerar a cobrança PIX no provedor. |
| 502 | `LTC price unavailable` | Cotação do LTC indisponível no momento. |
| 503 | `LTC wallet not configured for this store` | Loja sem carteira LTC configurada. |
| 500 | `Internal error` | Erro interno inesperado. |

---

# Get Payment

> Consulta os detalhes e o status atual de um pagamento pelo seu `paymentId`.

```
GET /v1/payments/:paymentId
```

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

## Autenticação

Envie o header `Authorization: Bearer <sua_chave>` — use `ps_live_...` em produção ou `ps_test_...` em sandbox.

## Parâmetros

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `paymentId` | string (path) | sim | ID do pagamento retornado na criação (formato `psa_...`). |

A consulta só retorna pagamentos do ambiente da chave utilizada (produção ou sandbox).

## Exemplo

```bash
curl https://api.purincash.com/v1/payments/psa_9f2c1a7e5b3d4c8a0e6f1b2d3c4e5a6f \
  -H "Authorization: Bearer ps_live_sua_chave"
```

## Resposta

```json
{
  "paymentId": "psa_9f2c1a7e5b3d4c8a0e6f1b2d3c4e5a6f",
  "status": "paid",
  "type": "one_time",
  "paymentMethod": "pix",
  "environment": "live",
  "amountCents": 1990,
  "currency": "BRL",
  "productName": "Plano mensal",
  "customer": {
    "name": "Maria Silva",
    "email": "maria@example.com",
    "externalId": "cliente_123"
  },
  "metadata": "{\"orderId\":\"456\"}",
  "paidAt": "2026-07-11T15:02:11.000Z",
  "expiresAt": "2026-07-11T15:30:00.000Z",
  "createdAt": "2026-07-11T15:00:00.000Z"
}
```

Campos de resposta:

| Campo | Tipo | Descrição |
|---|---|---|
| `paymentId` | string | ID único do pagamento. |
| `status` | string | `pending`, `paid`, `expired` ou `refunded`. |
| `type` | string | `one_time` ou `subscription`. |
| `paymentMethod` | string | `pix` ou `ltc`. |
| `environment` | string | `live` ou `sandbox`. |
| `subscriptionId` | string | Presente apenas quando o pagamento pertence a uma assinatura. |
| `amountCents` | integer | Valor em centavos. |
| `currency` | string | Moeda do produto vinculado; `BRL` para pagamentos avulsos. |
| `productName` | string | Nome do produto vinculado; vazio para pagamentos avulsos. |
| `customer` | object | Dados do cliente informados na criação. |
| `metadata` | string | Metadados enviados na criação. |
| `paidAt` | string | Data/hora do pagamento (ausente enquanto pendente). |
| `expiresAt` | string | Data/hora de expiração da cobrança. |
| `createdAt` | string | Data/hora de criação. |

## Erros

| HTTP | Erro | Quando |
|---|---|---|
| 404 | `Payment not found` | Pagamento inexistente, de outra conta ou de outro ambiente. |
| 500 | `Internal error` | Erro interno inesperado. |

---

# List Payments

> Lista os pagamentos da sua conta com paginação e filtros por status e tipo.

```
GET /v1/payments
```

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

## Autenticação

Envie o header `Authorization: Bearer <sua_chave>` — use `ps_live_...` em produção ou `ps_test_...` em sandbox.

## Parâmetros

Todos os parâmetros são enviados via query string.

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `limit` | integer | não | Quantidade de itens por página. Padrão: `50`. Mínimo: `1`. Máximo: `100`. |
| `offset` | integer | não | Quantidade de itens a pular (paginação). Padrão: `0`. |
| `status` | string | não | Filtra por status: `pending`, `paid`, `expired` ou `refunded`. Valores fora dessa lista são ignorados. |
| `type` | string | não | Filtra por tipo: `one_time` ou `subscription`. Valores fora dessa lista são ignorados. |

Os pagamentos são retornados do mais recente para o mais antigo (`createdAt` decrescente) e apenas do ambiente da chave utilizada.

## Exemplo

```bash
curl "https://api.purincash.com/v1/payments?status=paid&type=one_time&limit=20&offset=0" \
  -H "Authorization: Bearer ps_live_sua_chave"
```

## Resposta

```json
{
  "payments": [
    {
      "paymentId": "psa_9f2c1a7e5b3d4c8a0e6f1b2d3c4e5a6f",
      "status": "paid",
      "type": "one_time",
      "environment": "live",
      "amountCents": 1990,
      "currency": "BRL",
      "productName": "Plano mensal",
      "customer": {
        "name": "Maria Silva",
        "email": "maria@example.com",
        "externalId": "cliente_123"
      },
      "paidAt": "2026-07-11T15:02:11.000Z",
      "createdAt": "2026-07-11T15:00:00.000Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}
```

Campos de resposta:

| Campo | Tipo | Descrição |
|---|---|---|
| `payments` | array | Lista de pagamentos da página atual. |
| `payments[].subscriptionId` | string | Presente apenas em pagamentos de assinatura. |
| `total` | integer | Total de pagamentos que atendem ao filtro (independente da página). |
| `limit` | integer | Limite efetivamente aplicado. |
| `offset` | integer | Offset efetivamente aplicado. |

Para obter os detalhes completos de um pagamento (incluindo `metadata`, `paymentMethod` e `expiresAt`), use `GET /v1/payments/:paymentId`.

## Erros

| HTTP | Erro | Quando |
|---|---|---|
| 500 | `Internal error` | Erro interno inesperado. |

---

# Create Charge

> Cria uma cobrança PIX avulsa com valor customizado, sem produto associado e sem divisão de valores.

```
POST /v1/charges
```

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

## Autenticação

Envie sua chave de API no header `Authorization: Bearer ps_live_...` (produção) ou `Bearer ps_test_...` (sandbox).

## Parâmetros

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `valueCents` | integer | Sim | Valor da cobrança em centavos. Mínimo **80** (R$ 0,80). |
| `description` | string | Não | Descrição da cobrança (máx. 200 caracteres). Padrão: `"Pagamento PIX"`. |
| `callbackUrl` | string | Não | URL HTTPS pública para receber o webhook de confirmação (máx. 500 caracteres). |
| `customer` | object | Não | Dados do pagador. |
| `customer.name` | string | Não | Nome do pagador (máx. 100 caracteres). |
| `customer.email` | string | Não | E-mail do pagador (máx. 255 caracteres). |
| `customer.externalId` | string | Não | Identificador do pagador no seu sistema (máx. 200 caracteres). |
| `metadata` | string | Não | String livre (ex.: JSON serializado) para uso próprio (máx. 2048 caracteres). Retornada no `GET /v1/charges/:paymentId`. |
| `supplier` | object | Não | Vincula a cobrança a um produto de fornecedor. |
| `supplier.productId` | string | Não | ID público do produto (`prod_xxx`). Deve pertencer à sua conta. |
| `supplier.variationIndex` | integer | Não | Índice da variação do produto. Padrão: `0`. |

> Para cobranças com divisão de valores entre contas, veja [Create Split Charge](./create-split-charge.md).

## Exemplo

```bash
curl -X POST https://api.purincash.com/v1/charges \
  -H "Authorization: Bearer ps_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "valueCents": 2500,
    "description": "Assinatura mensal",
    "callbackUrl": "https://minhaloja.com/webhooks/purincash",
    "customer": {
      "name": "Maria Souza",
      "email": "maria@example.com",
      "externalId": "cliente-42"
    },
    "metadata": "{\"pedido\":\"9812\"}"
  }'
```

## Resposta

`201 Created`

```json
{
  "paymentId": "psc_9f3a1c2b4d5e6f708192a3b4c5d6e7f8",
  "status": "pending",
  "amountCents": 2500,
  "currency": "BRL",
  "environment": "production",
  "pix": {
    "brCode": "00020126580014br.gov.bcb.pix...",
    "qrCodeImage": "data:image/png;base64,..."
  },
  "expiresAt": "2026-07-11T15:30:00.000Z"
}
```

- `pix.brCode` é o código PIX copia-e-cola; `pix.qrCodeImage` pode ser `null` dependendo da cobrança.
- A cobrança expira em **30 minutos** (`expiresAt`).
- Consulte o status com [Get Charge](./get-charge.md).

## Erros

Formato de erro: `{ "error": "mensagem" }`.

| HTTP | Erro | Quando |
|---|---|---|
| 400 | `valueCents must be >= 80 (R$ 0.80)` | `valueCents` ausente, inválido ou menor que 80. |
| 400 | `callbackUrl must be a valid, public HTTPS URL` | `callbackUrl` informada não é uma URL HTTPS pública válida. |
| 400 | `supplier.productId must be a public API ID (prod_xxx)` | `supplier.productId` não começa com `prod_`. |
| 400 | `supplier.variationIndex {n} not found` | A variação informada não existe no produto. |
| 400 | `Price R$ {x} is below supplier cost R$ {y}` | O valor da cobrança é menor que o custo do fornecedor. |
| 401 | `API key required. Use: Authorization: Bearer ps_live_...` | Header `Authorization` ausente. |
| 401 | `Invalid API key prefix. Use ps_live_ or ps_test_` | Prefixo da chave inválido. |
| 401 | `Invalid or revoked API key` | Chave inexistente ou revogada. |
| 401 | `API key environment mismatch. Please generate a new key.` | Chave não corresponde ao ambiente da requisição. |
| 403 | `Antes de receber pagamentos, verifique sua conta: acesse o painel → Carteira → Verificar Chave PIX e preencha seu nome e chave PIX. Isso é obrigatório para novas lojas.` | Conta ainda não verificada. |
| 403 | `No approved supplier access` | Sem acesso aprovado ao fornecedor do produto. |
| 404 | `supplier.productId not found` | Produto não encontrado na sua conta. |
| 502 | `Failed to create PIX charge (...): ...` | Falha temporária ao gerar a cobrança PIX. Tente novamente. |
| 500 | `Internal error` | Erro interno inesperado. |

---

# Create Split Charge

> Cria uma cobrança PIX cujo valor é dividido automaticamente entre você (dono da chave de API) e até 9 outras contas PurinCash no momento do pagamento.

```
POST /v1/split-charges
```

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

Também funciona como `POST /v1/charges` com o campo `splits[]` no body — os dois endpoints são equivalentes; em `/v1/split-charges` o `splits[]` é obrigatório.

## Autenticação

Envie sua chave de API no header `Authorization: Bearer ps_live_...` (produção) ou `Bearer ps_test_...` (sandbox).

## Como funciona o modelo de split

- **Você (dono da chave de API) é participante implícito e NÃO entra em `splits[]`.** A lista contém apenas os **outros** beneficiários (de 1 a 9; com você, até 10 no total).
- **Você fica com o resto:** sua fatia é `100 − soma(percentages dos outros)`. Por isso a soma deve ser **estritamente menor que 100%**.
- **Sua fatia deve ser estritamente a maior.** Se algum beneficiário tiver percentual maior ou igual ao seu resto, a cobrança é **rejeitada** (a API nunca ajusta os valores sozinha).
- **A taxa do gateway sai 100% da sua parte.** Cada outro beneficiário recebe a porcentagem **cheia sobre o valor bruto**; você recebe `bruto − soma(outros) − taxa`. Se a taxa for maior que a sua fatia, você recebe 0 (a cobrança não é bloqueada).
- Cada percentual dos outros deve estar entre **0.01** e **99.99** (arredondado para 2 casas decimais).
- Beneficiários devem ser contas PurinCash existentes e ativas, identificadas por e-mail, sem duplicatas — e você não pode listar a si mesmo.
- **`metadata` não é suportado em cobranças com splits.**

Exemplo: cobrança de R$ 100,00 (10000 centavos), taxa de R$ 2,50, um beneficiário com 30%: o beneficiário recebe R$ 30,00 e você recebe `10000 − 3000 − 250 = 6750` (R$ 67,50).

## Parâmetros

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `amountCents` | integer | Sim* | Valor bruto em centavos. Entre **80** (R$ 0,80) e **500000** (R$ 5.000,00). |
| `valueCents` | integer | Sim* | Alias de `amountCents`. |
| `amount` | number | Sim* | Alias em reais decimais (ex.: `100.00`). *Envie ao menos um dos três; se mais de um for enviado, prevalece a ordem `amountCents` > `valueCents` > `amount`. |
| `splits` | array | Sim | Lista dos **outros** beneficiários (1 a 9). Você não entra na lista. |
| `splits[].recipientEmail` | string | Sim | E-mail da conta PurinCash do beneficiário (máx. 255 caracteres). |
| `splits[].percentage` | number | Sim | Percentual sobre o valor **bruto**, de 0.01 a 99.99 (2 casas decimais). |
| `description` | string | Não | Descrição da cobrança (máx. 200 caracteres). Padrão: `"Split PIX"`. |
| `callbackUrl` | string | Não | URL HTTPS pública para receber o webhook de confirmação (máx. 500 caracteres). |
| `customer` | object | Não | Dados do pagador: `name` (100), `email` (255), `externalId` (100). |

## Exemplo

Cobrança de R$ 100,00 com um beneficiário recebendo 30% — você fica com 70% (menos a taxa do gateway).

```bash
curl -X POST https://api.purincash.com/v1/split-charges \
  -H "Authorization: Bearer ps_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 10000,
    "description": "Venda com comissão",
    "callbackUrl": "https://minhaloja.com/webhooks/purincash",
    "customer": { "name": "Maria Souza", "email": "maria@example.com" },
    "splits": [
      { "recipientEmail": "socio@example.com", "percentage": 30 }
    ]
  }'
```

## Resposta

`201 Created` — o primeiro item de `splits` é sempre você (`isOwner: true`), com a fatia do resto. E-mails são mascarados.

```json
{
  "paymentId": "psplit_9f3a1c2b4d5e6f708192a3b4c5d6e7f8",
  "status": "pending",
  "amountCents": 10000,
  "currency": "BRL",
  "environment": "production",
  "pix": {
    "brCode": "00020126580014br.gov.bcb.pix...",
    "qrCodeImage": null
  },
  "splits": [
    { "recipientEmail": "vo***@example.com", "percentage": 70, "isOwner": true },
    { "recipientEmail": "so***@example.com", "percentage": 30, "isOwner": false }
  ],
  "expiresAt": "2026-07-11T15:30:00.000Z"
}
```

A cobrança expira em **30 minutos**. Consulte o status e os valores creditados com [Get Charge](./get-charge.md).

## Erros

Formato de erro: `{ "error": "mensagem" }`. `{i}` é o índice do item em `splits[]`.

| HTTP | Erro | Quando |
|---|---|---|
| 400 | `splits[] is required on /v1/split-charges (1 to 9 recipients — you, the API owner, are implicit and keep the remainder). For a simple charge use POST /v1/charges.` | `/v1/split-charges` chamado sem `splits[]`. |
| 400 | `amountCents (integer) or amount (decimal reais) required when using splits` | Nenhum campo de valor válido informado. |
| 400 | `amountCents must be an integer >= 80 (R$ 0.80)` | Valor abaixo de 80 centavos. |
| 400 | `amountCents exceeds R$ 5,000.00 cap for charges with splits` | Valor acima de 500000 centavos. |
| 400 | `callbackUrl must be a valid, public HTTPS URL` | `callbackUrl` inválida. |
| 400 | `splits must be an array` | `splits` não é um array. |
| 400 | `splits must have at least 1 recipient (you, the API owner, keep the remainder and are NOT listed)` | `splits` vazio. |
| 400 | `splits must have at most 9 recipients (you, the API owner, are the 10th and keep the remainder)` | Mais de 9 beneficiários. |
| 400 | `splits[{i}] must be an object` | Item da lista não é um objeto. |
| 400 | `splits[{i}].recipientEmail is invalid` | E-mail em formato inválido. |
| 400 | `splits[{i}].recipientEmail exceeds 255 chars` | E-mail longo demais. |
| 400 | `splits[{i}].recipientEmail is duplicated` | E-mail repetido na lista. |
| 400 | `splits[{i}].percentage must be a finite number` | `percentage` ausente ou não numérico. |
| 400 | `splits[{i}].percentage must be >= 0.01 (got {valor})` | Percentual abaixo de 0.01. |
| 400 | `splits[{i}].percentage must be <= 99.99 (got {valor})` | Percentual acima de 99.99. |
| 400 | `recipients sum to {X}% — must be < 100.00% (you, the API owner, keep the remainder)` | Soma dos percentuais ≥ 100%. |
| 400 | `your share would be {X}% but a recipient has {Y}% — you (the API owner) must keep the strictly largest share. Lower the recipients' percentages.` | Sua fatia (resto) não é estritamente a maior. |
| 400 | `splits[{i}].recipientEmail not found in paysync` | E-mail não corresponde a nenhuma conta. |
| 400 | `splits[{i}].recipientEmail account is deactivated` | Conta do beneficiário desativada. |
| 400 | `splits[{i}].recipientEmail belongs to a sub-bot, not a main account` | E-mail pertence a uma subconta, não a uma conta principal. |
| 400 | `splits[{i}].recipientEmail is your own account — you are the API owner and keep the remainder automatically; don't list yourself` | Você listou seu próprio e-mail. |
| 400 | `splits[{i}].recipientEmail resolves to a duplicate user id` | Dois e-mails apontam para a mesma conta. |
| 401 | `API key required. Use: Authorization: Bearer ps_live_...` | Header `Authorization` ausente. |
| 401 | `Invalid or revoked API key` | Chave inexistente ou revogada. |
| 403 | `Antes de receber pagamentos, verifique sua conta: acesse o painel → Carteira → Verificar Chave PIX e preencha seu nome e chave PIX. Isso é obrigatório para novas lojas.` | Conta ainda não verificada. |
| 502 | `Failed to create PIX charge (...): ...` | Falha temporária ao gerar a cobrança PIX. Tente novamente. |
| 500 | `Internal error` | Erro interno inesperado. |

---

# Get Charge

> Consulta uma cobrança PIX pelo `paymentId` — funciona tanto para cobranças simples (`psc_...`) quanto para cobranças com split (`psplit_...`).

```
GET /v1/charges/:paymentId
```

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

Alias equivalente: `GET /v1/split-charges/:paymentId` (mesmo comportamento; útil para IDs `psplit_...`).

## Autenticação

Envie sua chave de API no header `Authorization: Bearer ps_live_...` (produção) ou `Bearer ps_test_...` (sandbox) — a cobrança só é encontrada no ambiente da chave usada.

## Parâmetros

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `paymentId` | string (path) | Sim | ID retornado na criação: `psc_...` para cobrança simples ou `psplit_...` para cobrança com split. |

## Exemplo

```bash
curl https://api.purincash.com/v1/charges/psc_9f3a1c2b4d5e6f708192a3b4c5d6e7f8 \
  -H "Authorization: Bearer ps_live_sua_chave"
```

```bash
curl https://api.purincash.com/v1/split-charges/psplit_9f3a1c2b4d5e6f708192a3b4c5d6e7f8 \
  -H "Authorization: Bearer ps_live_sua_chave"
```

## Resposta

### Cobrança simples (`psc_...`)

`200 OK`

```json
{
  "paymentId": "psc_9f3a1c2b4d5e6f708192a3b4c5d6e7f8",
  "status": "paid",
  "amountCents": 2500,
  "currency": "BRL",
  "description": "Assinatura mensal",
  "customer": {
    "name": "Maria Souza",
    "email": "maria@example.com",
    "externalId": "cliente-42"
  },
  "metadata": "{\"pedido\":\"9812\"}",
  "paidAt": "2026-07-11T15:12:44.000Z",
  "expiresAt": "2026-07-11T15:30:00.000Z",
  "createdAt": "2026-07-11T15:00:00.000Z"
}
```

### Cobrança com split (`psplit_...`)

`200 OK` — inclui o breakdown por beneficiário. E-mails são mascarados (ex.: `so***@example.com`). Antes do pagamento, `amountCents` de cada split é `0` e `creditedAt` é `null`; após o pagamento, `amountCents` traz os centavos efetivamente creditados e `creditedAt` a data do crédito.

```json
{
  "paymentId": "psplit_9f3a1c2b4d5e6f708192a3b4c5d6e7f8",
  "status": "paid",
  "amountCents": 10000,
  "gatewayFeeCents": 250,
  "netAmountCents": 9750,
  "currency": "BRL",
  "environment": "production",
  "pix": {
    "brCode": "00020126580014br.gov.bcb.pix..."
  },
  "splits": [
    {
      "recipientEmail": "vo***@example.com",
      "percentage": 70,
      "isOwner": true,
      "amountCents": 6750,
      "creditedAt": "2026-07-11T15:12:44.000Z"
    },
    {
      "recipientEmail": "so***@example.com",
      "percentage": 30,
      "isOwner": false,
      "amountCents": 3000,
      "creditedAt": "2026-07-11T15:12:44.000Z"
    }
  ],
  "paidAt": "2026-07-11T15:12:44.000Z",
  "expiresAt": "2026-07-11T15:30:00.000Z",
  "createdAt": "2026-07-11T15:00:00.000Z"
}
```

Campos específicos do split:

| Campo | Tipo | Descrição |
|---|---|---|
| `gatewayFeeCents` | integer | Taxa do gateway em centavos, descontada integralmente da parte do dono. `0` enquanto pendente. |
| `netAmountCents` | integer | Valor líquido creditado no total (`amountCents − gatewayFeeCents`, nunca negativo — mínimo `0`). `0` enquanto pendente. |
| `splits[].isOwner` | boolean | `true` para o dono da chave de API (fatia do resto, paga a taxa). |
| `splits[].amountCents` | integer | Centavos creditados ao beneficiário (os não-donos recebem a % cheia sobre o bruto). |
| `splits[].creditedAt` | string \| null | Data do crédito na carteira do beneficiário. |

## Erros

Formato de erro: `{ "error": "mensagem" }`.

| HTTP | Erro | Quando |
|---|---|---|
| 401 | `API key required. Use: Authorization: Bearer ps_live_...` | Header `Authorization` ausente. |
| 401 | `Invalid API key prefix. Use ps_live_ or ps_test_` | Prefixo da chave inválido. |
| 401 | `Invalid or revoked API key` | Chave inexistente ou revogada. |
| 404 | `Charge not found` | `paymentId` inexistente, de outra conta ou de outro ambiente (live vs. sandbox). |
| 500 | `Internal error` | Erro interno inesperado. |

---

# Create Card Payment

> Cria um pagamento com cartão de crédito e retorna a URL de um checkout hospedado, processado por parceiro de pagamentos com cartão.

```
POST /v1/card-payments
```

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

## Autenticação

Envie sua chave de API no header `Authorization: Bearer ps_live_...` (pagamentos com cartão estão disponíveis apenas em produção).

## Parâmetros

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `valueCents` | integer | Sim | Valor do pagamento em centavos. Mínimo: `80` (R$ 0,80). |
| `description` | string | Não | Descrição exibida no checkout (máx. 200 caracteres). Padrão: `"Pagamento Cartao"`. |
| `callbackUrl` | string | Não | URL HTTPS pública para receber notificações (webhook) sobre o pagamento (máx. 500 caracteres). |
| `successUrl` | string | Não | URL para onde o cliente é redirecionado após o pagamento aprovado (máx. 500 caracteres). |
| `cancelUrl` | string | Não | URL para onde o cliente é redirecionado se cancelar o checkout (máx. 500 caracteres). |
| `customer.name` | string | Não | Nome do cliente (máx. 100 caracteres). |
| `customer.email` | string | Não | E-mail do cliente; se informado, é pré-preenchido no checkout (máx. 255 caracteres). |
| `customer.externalId` | string | Não | Identificador do cliente no seu sistema (máx. 200 caracteres). |
| `metadata` | string | Não | String livre (ex.: JSON serializado) associada ao pagamento (máx. 2048 caracteres). |

> O checkout expira em 30 minutos após a criação. Dependendo das configurações de repasse de taxa da sua loja, o valor cobrado do cliente no checkout pode incluir a taxa de processamento do cartão.

## Exemplo

```bash
curl -X POST "https://api.purincash.com/v1/card-payments" \
  -H "Authorization: Bearer ps_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "valueCents": 4990,
    "description": "Plano Pro - 1 mês",
    "callbackUrl": "https://minhaloja.com/webhooks/purincash",
    "successUrl": "https://minhaloja.com/obrigado",
    "cancelUrl": "https://minhaloja.com/carrinho",
    "customer": {
      "name": "Maria Silva",
      "email": "maria@example.com",
      "externalId": "cliente_123"
    },
    "metadata": "{\"pedido\":\"789\"}"
  }'
```

## Resposta

`201 Created`

```json
{
  "orderCode": "A1B2C3D4E5",
  "status": "pending",
  "amountCents": 4990,
  "currency": "BRL",
  "checkoutUrl": "https://checkout.parceiro.com/pay/cs_xxx",
  "expiresAt": "2026-07-11T15:30:00.000Z"
}
```

Redirecione o cliente para `checkoutUrl` para concluir o pagamento. Use `orderCode` para consultar o status posteriormente via `GET /v1/card-payments/:orderCode`.

## Erros

| HTTP | Erro | Quando |
|---|---|---|
| 400 | `Use sandbox endpoints for test mode` | A chave usada é de sandbox (`ps_test_`); cartão só está disponível em produção. |
| 400 | `valueCents must be >= 80 (R$ 0.80)` | Valor ausente, inválido ou abaixo do mínimo de 80 centavos. |
| 400 | `callbackUrl must be a valid, public HTTPS URL` | `callbackUrl` informada não é uma URL HTTPS pública válida. |
| 401 | `API key required. Use: Authorization: Bearer ps_live_...` | Header `Authorization` ausente ou malformado. |
| 401 | `Invalid or revoked API key` | Chave de API inexistente ou revogada. |
| 403 | `Antes de receber pagamentos, verifique sua conta: acesse o painel → Carteira → Verificar Chave PIX e preencha seu nome e chave PIX. Isso é obrigatório para novas lojas.` | A loja ainda não concluiu a verificação de conta. |
| 503 | `Card payments not configured (Stripe)` | Pagamentos com cartão indisponíveis no momento na plataforma. |
| 500 | `Internal error` | Erro inesperado no servidor. |

---

# Get Card Payment

> Consulta os detalhes e o status atual de um pagamento com cartão pelo seu `orderCode`.

```
GET /v1/card-payments/:orderCode
```

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

## Autenticação

Envie sua chave de API no header `Authorization: Bearer ps_live_...` (pagamentos com cartão estão disponíveis apenas em produção).

## Parâmetros

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `orderCode` | string (path) | Sim | Código do pedido retornado na criação do pagamento (`POST /v1/card-payments`). |

## Exemplo

```bash
curl "https://api.purincash.com/v1/card-payments/A1B2C3D4E5" \
  -H "Authorization: Bearer ps_live_SUA_CHAVE"
```

## Resposta

`200 OK`

```json
{
  "orderCode": "A1B2C3D4E5",
  "status": "paid",
  "amount": 49.9,
  "amountCents": 4990,
  "currency": "BRL",
  "description": "Plano Pro - 1 mês",
  "checkoutUrl": "https://checkout.parceiro.com/pay/cs_xxx",
  "customer": {
    "name": "Maria Silva",
    "email": "maria@example.com",
    "externalId": "cliente_123"
  },
  "metadata": "{\"pedido\":\"789\"}",
  "paidAt": "2026-07-11T15:12:44.000Z",
  "expiresAt": "2026-07-11T15:30:00.000Z",
  "createdAt": "2026-07-11T15:00:00.000Z"
}
```

Campos que podem ser `null`: `checkoutUrl`, `customer`, `metadata` e `paidAt` (este último é `null` enquanto o pagamento não for confirmado).

Valores possíveis de `status`: `pending`, `paid`, `expired`, `canceled`.

## Erros

| HTTP | Erro | Quando |
|---|---|---|
| 401 | `API key required. Use: Authorization: Bearer ps_live_...` | Header `Authorization` ausente ou malformado. |
| 401 | `Invalid or revoked API key` | Chave de API inexistente ou revogada. |
| 404 | `Card payment not found` | `orderCode` inexistente, pertencente a outra loja, ou requisição feita com chave de sandbox (`ps_test_`). |
| 500 | `Internal error` | Erro inesperado no servidor. |

---

# List Card Payments

> Lista os pagamentos com cartão da sua loja, com paginação e filtro opcional por status.

```
GET /v1/card-payments
```

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

## Autenticação

Envie sua chave de API no header `Authorization: Bearer ps_live_...` (pagamentos com cartão estão disponíveis apenas em produção).

## Parâmetros

Todos os parâmetros são enviados via query string.

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `limit` | integer | Não | Quantidade de itens por página. Padrão: `50`. Mínimo: `1`. Máximo: `100`. |
| `offset` | integer | Não | Quantidade de itens a pular (paginação). Padrão: `0`. |
| `status` | string | Não | Filtra por status: `pending`, `paid`, `expired`, `refunded` ou `failed`. Valores inválidos são ignorados. |

Os resultados são ordenados do mais recente para o mais antigo (`createdAt` decrescente).

## Exemplo

```bash
curl "https://api.purincash.com/v1/card-payments?status=paid&limit=20&offset=0" \
  -H "Authorization: Bearer ps_live_SUA_CHAVE"
```

## Resposta

`200 OK`

```json
{
  "payments": [
    {
      "orderCode": "A1B2C3D4E5",
      "status": "paid",
      "amount": 49.9,
      "amountCents": 4990,
      "currency": "BRL",
      "description": "Plano Pro - 1 mês",
      "checkoutUrl": "https://checkout.parceiro.com/pay/cs_xxx",
      "paidAt": "2026-07-11T15:12:44.000Z",
      "createdAt": "2026-07-11T15:00:00.000Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}
```

Em cada item, `checkoutUrl` e `paidAt` podem ser `null`. Os itens retornados podem também ter status `canceled`, que não está disponível como filtro. Para os detalhes completos de um pagamento (cliente, `metadata`, `expiresAt`), use `GET /v1/card-payments/:orderCode`.

Se a requisição for feita com chave de sandbox (`ps_test_`), a resposta é uma lista vazia:

```json
{ "payments": [], "total": 0, "limit": 50, "offset": 0, "sandbox": true }
```

## Erros

| HTTP | Erro | Quando |
|---|---|---|
| 401 | `API key required. Use: Authorization: Bearer ps_live_...` | Header `Authorization` ausente ou malformado. |
| 401 | `Invalid or revoked API key` | Chave de API inexistente ou revogada. |
| 500 | `Internal error` | Erro inesperado no servidor. |

---

# Create Subscription

> Cria uma assinatura com cobrança recorrente via PIX a partir de um produto cadastrado na sua loja.

```
POST /v1/subscriptions
```

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

## Autenticação

Envie sua chave de API no header `Authorization: Bearer ps_live_...` (produção) ou `Bearer ps_test_...` (sandbox).

## Parâmetros

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `productId` | string | Sim | ID do produto ativo cadastrado na sua loja. Define o valor (`priceCents`) e a moeda da assinatura. |
| `customer.name` | string | Sim | Nome do cliente assinante (máx. 100 caracteres). |
| `customer.externalId` | string | Não | Identificador do cliente no seu sistema (máx. 200 caracteres). |
| `frequency` | string | Não | Frequência da cobrança: `WEEKLY`, `MONTHLY`, `SEMIANNUALLY` ou `ANNUALLY`. Padrão: `MONTHLY`. |
| `dayGenerateCharge` | integer | Não | Dia do mês em que a cobrança é gerada. Aceito entre `4` e `28` (valores fora do intervalo são ajustados). Padrão: dia atual. |
| `callbackUrl` | string | Não | URL HTTPS pública para receber notificações (webhook) sobre os pagamentos (máx. 500 caracteres). |
| `metadata` | string | Não | String livre (ex.: JSON serializado) associada à assinatura (máx. 2048 caracteres). |

## Exemplo

```bash
curl -X POST "https://api.purincash.com/v1/subscriptions" \
  -H "Authorization: Bearer ps_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "665f1a2b3c4d5e6f7a8b9c0d",
    "frequency": "MONTHLY",
    "dayGenerateCharge": 10,
    "callbackUrl": "https://minhaloja.com/webhooks/purincash",
    "customer": {
      "name": "Maria Silva",
      "externalId": "cliente_123"
    },
    "metadata": "{\"plano\":\"pro\"}"
  }'
```

## Resposta

`200 OK`

```json
{
  "paymentId": "psa_sub_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c",
  "status": "pending",
  "type": "subscription",
  "subscriptionId": "sub_abc123",
  "amountCents": 4990,
  "currency": "BRL",
  "productName": "Plano Pro",
  "frequency": "MONTHLY",
  "environment": "live",
  "pix": {
    "brCode": "00020126580014br.gov.bcb.pix...",
    "paymentLinkUrl": "https://pagamento.exemplo.com/sub_abc123"
  },
  "dayGenerateCharge": 10
}
```

Apresente o `pix.brCode` (copia e cola / QR Code) ou o `pix.paymentLinkUrl` ao cliente para o pagamento da primeira cobrança. Os campos `pix.brCode` e `pix.paymentLinkUrl` podem ser `null` dependendo da forma de cobrança da sua loja. Use `paymentId` para consultar o status via `GET /v1/payments/:paymentId`.

## Erros

| HTTP | Erro | Quando |
|---|---|---|
| 400 | `productId is required` | Campo `productId` ausente ou vazio. |
| 400 | `customer.name is required for subscriptions` | Campo `customer.name` ausente ou vazio. |
| 400 | `callbackUrl must be a valid, public HTTPS URL` | `callbackUrl` informada não é uma URL HTTPS pública válida. |
| 400 | `Invalid productId format` | `productId` não tem um formato de ID válido. |
| 401 | `API key required. Use: Authorization: Bearer ps_live_...` | Header `Authorization` ausente ou malformado. |
| 401 | `Invalid or revoked API key` | Chave de API inexistente ou revogada. |
| 403 | `Antes de receber pagamentos, verifique sua conta: acesse o painel → Carteira → Verificar Chave PIX e preencha seu nome e chave PIX. Isso é obrigatório para novas lojas.` | A loja ainda não concluiu a verificação de conta. |
| 404 | `Product not found or inactive` | Produto inexistente, inativo, de outra loja ou de outro ambiente (produção/sandbox). |
| 502 | `Failed to create subscription` | Falha ao criar a assinatura junto ao provedor de pagamentos. |
| 502 | `Failed to create charge` | Falha ao gerar a cobrança PIX junto ao provedor de pagamentos. |
| 503 | `Payment gateway not configured` | Provedor de pagamentos indisponível no momento na plataforma. |
| 500 | `Internal error` | Erro inesperado no servidor. |

---

# List Subscriptions

> Lista as assinaturas da sua loja, com paginação e filtro opcional por status.

```
GET /v1/subscriptions
```

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

## Autenticação

Envie sua chave de API no header `Authorization: Bearer ps_live_...` (produção) ou `Bearer ps_test_...` (sandbox).

## Parâmetros

Todos os parâmetros são enviados via query string. Apenas assinaturas do ambiente da chave usada (produção ou sandbox) são retornadas.

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `limit` | integer | Não | Quantidade de itens por página. Padrão: `50`. Mínimo: `1`. Máximo: `100`. |
| `offset` | integer | Não | Quantidade de itens a pular (paginação). Padrão: `0`. |
| `status` | string | Não | Filtra por status: `pending`, `paid`, `expired` ou `refunded`. Valores inválidos são ignorados. |

Os resultados são ordenados do mais recente para o mais antigo (`createdAt` decrescente).

## Exemplo

```bash
curl "https://api.purincash.com/v1/subscriptions?status=paid&limit=20&offset=0" \
  -H "Authorization: Bearer ps_live_SUA_CHAVE"
```

## Resposta

`200 OK`

```json
{
  "subscriptions": [
    {
      "paymentId": "psa_sub_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c",
      "subscriptionId": "sub_abc123",
      "status": "paid",
      "amountCents": 4990,
      "currency": "BRL",
      "productName": "Plano Pro",
      "customer": {
        "name": "Maria Silva",
        "email": "",
        "externalId": "cliente_123"
      },
      "metadata": "{\"plano\":\"pro\"}",
      "paidAt": "2026-07-10T12:00:00.000Z",
      "createdAt": "2026-07-01T09:30:00.000Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}
```

Em cada item, `paidAt` é `null` enquanto a cobrança não for confirmada e `subscriptionId` pode ser uma string vazia. Para os detalhes completos de uma assinatura, use `GET /v1/payments/:paymentId`.

## Erros

| HTTP | Erro | Quando |
|---|---|---|
| 401 | `API key required. Use: Authorization: Bearer ps_live_...` | Header `Authorization` ausente ou malformado. |
| 401 | `Invalid or revoked API key` | Chave de API inexistente ou revogada. |
| 500 | `Internal error` | Erro inesperado no servidor. |

---

# Get Delivery

> Consulta o conteúdo de estoque entregue para um pagamento, junto com status e dados do cliente.

```
GET /v1/deliveries/:paymentId
```

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

## Autenticação

Envie sua chave de API no header: `Authorization: Bearer ps_live_...` (use `ps_test_` para sandbox).

## Parâmetros

Parâmetros de rota:

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `paymentId` | string | Sim | ID do pagamento. Aceita IDs de pagamentos (`psa_...`) e de cobranças (`psc_...`). O pagamento deve pertencer à sua conta. |

## Exemplo

```bash
curl "https://api.purincash.com/v1/deliveries/psa_1a2b3c4d5e6f" \
  -H "Authorization: Bearer ps_live_SUA_CHAVE"
```

## Resposta

`200 OK`

```json
{
  "paymentId": "psa_1a2b3c4d5e6f",
  "status": "paid",
  "amountCents": 14990,
  "paidAt": "2026-07-11T12:34:56.000Z",
  "deliveredContent": "LICENSE-KEY-ABCD-1234",
  "customer": {
    "name": "João da Silva",
    "email": "joao@email.com"
  }
}
```

Campos da resposta:

| Campo | Tipo | Descrição |
|---|---|---|
| `paymentId` | string | ID do pagamento consultado. |
| `status` | string | Status atual do pagamento. |
| `amountCents` | integer | Valor do pagamento, em centavos. |
| `paidAt` | string \| null | Data de confirmação do pagamento (ISO 8601), ou `null` se ainda não pago. |
| `deliveredContent` | string \| null | Conteúdo de estoque entregue ao cliente, ou `null` se nada foi entregue. |
| `customer` | object | Dados do cliente informados na criação do pagamento. |

## Erros

| HTTP | Erro | Quando |
|---|---|---|
| 400 | `paymentId required` | `paymentId` ausente ou vazio. |
| 401 | `API key required. Use: Authorization: Bearer ps_live_...` | Header `Authorization` ausente. |
| 401 | `Invalid API key prefix. Use ps_live_ or ps_test_` | Chave sem o prefixo `ps_live_` ou `ps_test_`. |
| 401 | `Invalid or revoked API key` | Chave inexistente ou revogada. |
| 404 | `Payment not found` | ID sem prefixo `psa_`/`psc_`, pagamento inexistente ou pertencente a outra conta. |
| 500 | `Internal error` | Erro interno inesperado. |

---

# List Disputes

> Lista as disputas (MEDs) da sua conta, com paginação e filtro por status.

```
GET /v1/disputes
```

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

## Autenticação

Envie sua chave de API no header: `Authorization: Bearer ps_live_...` (use `ps_test_` para sandbox).

## Parâmetros

Parâmetros de query string:

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `limit` | integer | Não | Quantidade de disputas por página. Mínimo `1`, máximo `100`. Padrão: `50`. |
| `offset` | integer | Não | Quantidade de registros a pular (paginação). Mínimo `0`. Padrão: `0`. |
| `status` | string | Não | Filtra pelo status da disputa: `aberta`, `resolvida` ou `perdida`. Valores diferentes desses são ignorados. |

> **Sandbox:** chaves `ps_test_` sempre retornam uma lista vazia com o campo extra `"sandbox": true`.

## Exemplo

```bash
curl "https://api.purincash.com/v1/disputes?limit=20&offset=0&status=aberta" \
  -H "Authorization: Bearer ps_live_SUA_CHAVE"
```

## Resposta

`200 OK`

```json
{
  "disputes": [
    {
      "id": "665f1c2ab9e8d40012a4c789",
      "code": "MED-2026-0042",
      "wooviDisputeId": "disp_abc123",
      "endToEndId": "E12345678202607111200abcdef12345",
      "orderCode": "ORD-1234",
      "buyer": "cliente@email.com",
      "buyerDiscordId": "123456789012345678",
      "product": "Produto Exemplo",
      "amount": 149.9,
      "reason": "Compra não reconhecida",
      "status": "aberta",
      "evidences": [
        {
          "url": "https://api.purincash.com/uploads/disputes/665f1c2a.../doc.pdf?sig=...",
          "description": "Comprovante de entrega",
          "correlationID": "MED-2026-0042-EV1",
          "uploadedAt": "2026-07-10T18:30:00.000Z"
        }
      ],
      "resolvedAt": null,
      "createdAt": "2026-07-09T14:00:00.000Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}
```

Campos de cada disputa:

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | string | Identificador único da disputa. |
| `code` | string | Código legível da disputa. |
| `wooviDisputeId` | string | Identificador da disputa no gateway (pode ser vazio). |
| `endToEndId` | string | End-to-end ID da transação Pix contestada (pode ser vazio). |
| `orderCode` | string | Código do pedido relacionado (pode ser vazio). |
| `buyer` | string | Identificação do comprador. |
| `buyerDiscordId` | string | Discord ID do comprador (pode ser vazio). |
| `product` | string | Produto relacionado à disputa. |
| `amount` | number | Valor contestado, em reais. |
| `reason` | string | Motivo da contestação. |
| `status` | string | `aberta`, `resolvida` ou `perdida`. |
| `evidences` | array | Evidências já enviadas (`url`, `description`, `correlationID`, `uploadedAt`). URLs são assinadas e expiram. |
| `resolvedAt` | string \| null | Data de resolução (ISO 8601), quando houver. |
| `createdAt` | string | Data de criação (ISO 8601). |

## Erros

| HTTP | Erro | Quando |
|---|---|---|
| 401 | `API key required. Use: Authorization: Bearer ps_live_...` | Header `Authorization` ausente. |
| 401 | `Invalid API key prefix. Use ps_live_ or ps_test_` | Chave sem o prefixo `ps_live_` ou `ps_test_`. |
| 401 | `Invalid or revoked API key` | Chave inexistente ou revogada. |
| 500 | `Internal error` | Erro interno inesperado. |

---

# Get Dispute

> Consulta os detalhes de uma disputa (MED) específica pelo seu ID.

```
GET /v1/disputes/:id
```

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

## Autenticação

Envie sua chave de API no header: `Authorization: Bearer ps_live_...` (use `ps_test_` para sandbox).

## Parâmetros

Parâmetros de rota:

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `id` | string | Sim | ID da disputa (retornado em `GET /v1/disputes`). Deve pertencer à sua conta. |

> **Sandbox:** chaves `ps_test_` sempre retornam `404` com a mensagem `Dispute not found in sandbox`.

## Exemplo

```bash
curl "https://api.purincash.com/v1/disputes/665f1c2ab9e8d40012a4c789" \
  -H "Authorization: Bearer ps_live_SUA_CHAVE"
```

## Resposta

`200 OK`

```json
{
  "id": "665f1c2ab9e8d40012a4c789",
  "code": "MED-2026-0042",
  "wooviDisputeId": "disp_abc123",
  "endToEndId": "E12345678202607111200abcdef12345",
  "orderCode": "ORD-1234",
  "buyer": "cliente@email.com",
  "buyerDiscordId": "123456789012345678",
  "product": "Produto Exemplo",
  "amount": 149.9,
  "reason": "Compra não reconhecida",
  "status": "aberta",
  "evidences": [
    {
      "url": "https://api.purincash.com/uploads/disputes/665f1c2a.../doc.pdf?sig=...",
      "description": "Comprovante de entrega",
      "correlationID": "MED-2026-0042-EV1",
      "uploadedAt": "2026-07-10T18:30:00.000Z"
    }
  ],
  "resolvedAt": null,
  "createdAt": "2026-07-09T14:00:00.000Z"
}
```

Campos da resposta:

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | string | Identificador único da disputa. |
| `code` | string | Código legível da disputa. |
| `wooviDisputeId` | string | Identificador da disputa no gateway (pode ser vazio). |
| `endToEndId` | string | End-to-end ID da transação Pix contestada (pode ser vazio). |
| `orderCode` | string | Código do pedido relacionado (pode ser vazio). |
| `buyer` | string | Identificação do comprador. |
| `buyerDiscordId` | string | Discord ID do comprador (pode ser vazio). |
| `product` | string | Produto relacionado à disputa. |
| `amount` | number | Valor contestado, em reais. |
| `reason` | string | Motivo da contestação. |
| `status` | string | `aberta`, `resolvida` ou `perdida`. |
| `evidences` | array | Evidências já enviadas (`url`, `description`, `correlationID`, `uploadedAt`). URLs são assinadas e expiram. |
| `resolvedAt` | string \| null | Data de resolução (ISO 8601), quando houver. |
| `createdAt` | string | Data de criação (ISO 8601). |

## Erros

| HTTP | Erro | Quando |
|---|---|---|
| 400 | `Invalid dispute ID format` | O `id` informado não tem um formato válido. |
| 401 | `API key required. Use: Authorization: Bearer ps_live_...` | Header `Authorization` ausente. |
| 401 | `Invalid API key prefix. Use ps_live_ or ps_test_` | Chave sem o prefixo `ps_live_` ou `ps_test_`. |
| 401 | `Invalid or revoked API key` | Chave inexistente ou revogada. |
| 404 | `Dispute not found` | Disputa inexistente ou pertencente a outra conta. |
| 404 | `Dispute not found in sandbox` | Requisição feita com chave de sandbox (`ps_test_`). |
| 500 | `Internal error` | Erro interno inesperado. |

---

# Submit Evidence

> Envia evidências (documentos por URL e/ou texto explicativo) para contestar uma disputa aberta.

```
POST /v1/disputes/:id/evidence
```

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

## Autenticação

Envie sua chave de API no header: `Authorization: Bearer ps_live_...` (endpoint disponível apenas em produção).

## Parâmetros

Parâmetro de rota:

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `id` | string | Sim | ID da disputa. A disputa deve estar com status `aberta`. |

Corpo da requisição (JSON). É obrigatório enviar `documents` e/ou `textForPdf`:

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `documents` | array | Condicional | Lista de documentos de evidência. Máximo de **10 itens** — itens excedentes são descartados. |
| `documents[].url` | string | Sim | URL pública do documento. Deve começar com `http://` ou `https://`. Máximo de 2000 caracteres. Itens sem URL válida são descartados. |
| `documents[].description` | string | Não | Descrição do documento. Máximo de 500 caracteres. Padrão: `"Evidence"`. |
| `documents[].correlationID` | string | Não | Identificador seu para o documento. Máximo de 100 caracteres. Padrão: `{code}-EV{n}` (ex.: `MED-2026-0042-EV1`). |
| `textForPdf` | string | Condicional | Texto explicativo da contestação. É convertido automaticamente em um PDF e anexado como evidência adicional, com a descrição `"Explicação da contestação"`. |

> **Sandbox:** este endpoint não está disponível com chaves `ps_test_` (retorna `400`).

## Exemplo

```bash
curl -X POST "https://api.purincash.com/v1/disputes/665f1c2ab9e8d40012a4c789/evidence" \
  -H "Authorization: Bearer ps_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "url": "https://meusite.com/comprovantes/entrega-1234.png",
        "description": "Comprovante de entrega do produto",
        "correlationID": "pedido-1234-entrega"
      }
    ],
    "textForPdf": "O produto foi entregue ao comprador em 09/07/2026, conforme comprovante anexo."
  }'
```

## Resposta

`200 OK`

```json
{
  "uploaded": 2
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `uploaded` | integer | Quantidade de evidências enviadas com sucesso (documentos válidos + PDF gerado a partir de `textForPdf`, quando informado). |

As evidências enviadas passam a aparecer no campo `evidences` da disputa (`GET /v1/disputes/:id`).

## Erros

| HTTP | Erro | Quando |
|---|---|---|
| 400 | `Evidence upload not available in sandbox` | Requisição feita com chave de sandbox (`ps_test_`). |
| 400 | `Dispute already resolved` | A disputa não está mais com status `aberta`. |
| 400 | `Dispute has no gateway ID — cannot submit evidence` | A disputa ainda não possui identificador no gateway. |
| 400 | `documents array or textForPdf is required` | Corpo sem `documents` e sem `textForPdf`. |
| 400 | `No valid documents provided (url must be http or https)` | Nenhum documento com URL `http`/`https` válida após validação. |
| 400 | `Invalid dispute ID format` | O `id` informado não tem um formato válido. |
| 401 | `API key required. Use: Authorization: Bearer ps_live_...` | Header `Authorization` ausente. |
| 401 | `Invalid API key prefix. Use ps_live_ or ps_test_` | Chave sem o prefixo `ps_live_` ou `ps_test_`. |
| 401 | `Invalid or revoked API key` | Chave inexistente ou revogada. |
| 404 | `Dispute not found` | Disputa inexistente ou pertencente a outra conta. |
| 500 | `Failed to generate PDF from text` | Falha ao gerar o PDF de `textForPdf` sem nenhum outro documento válido. |
| 502 | `Failed to upload evidence to gateway` | O gateway recusou o envio (a mensagem pode variar conforme o retorno do gateway). |
| 503 | `Payment gateway not configured` | Gateway de pagamento indisponível no momento. |
| 500 | `Internal error` | Erro interno inesperado. |

---

# Get Wallet

> Retorna o saldo da carteira: disponivel, retido por disputas (MED), liberacao pendente de cartao e saldo LTC.

```
GET /v1/wallet
```

Funciona com chaves `ps_live_` e `ps_test_` — no sandbox retorna o saldo simulado calculado a partir dos pagamentos de teste (mesma regra de `GET /v1/sandbox/wallet`), com `"sandbox": true`.

## Resposta (200)

```json
{
  "currency": "BRL",
  "balance": 1520.75,
  "balanceCents": 152075,
  "disputeBlocked": 120.00,
  "withdrawable": 1400.75,
  "withdrawableCents": 140075,
  "pendingRelease": 350.00,
  "pendingReleaseCents": 35000,
  "cryptoBalanceLtc": 0.5231
}
```

| Campo            | Descricao                                                              |
|------------------|------------------------------------------------------------------------|
| balance          | Saldo bruto da carteira (BRL)                                          |
| disputeBlocked   | Valor retido por disputas (MED) abertas/perdidas nao perdoadas         |
| withdrawable     | O que `POST /v1/payouts` aceita sacar agora (balance - disputeBlocked) |
| pendingRelease   | Vendas no cartao aguardando liberacao (D+14)                           |
| cryptoBalanceLtc | Saldo LTC (saque via `POST /v1/payouts` com `method: "ltc"`)           |

No sandbox, `disputeBlocked` e `cryptoBalanceLtc` sao sempre 0.

---

# Create Payout

> Solicita um saque (payout) do saldo da sua carteira via PIX ou Litecoin (LTC).

```
POST /v1/payouts
```

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

## Autenticação

Envie sua chave de API no header `Authorization: Bearer <chave>` — use `ps_live_...` em produção e `ps_test_...` no sandbox.

## Parâmetros

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `method` | string | Não | Método do saque: `"pix"` ou `"ltc"`. Padrão: `"pix"`. |
| `amount` | number | Sim | Valor do saque em reais (BRL). Arredondado para 2 casas decimais. Mínimo: `5.00`. Máximo: `999999.99`. |
| `walletAddress` | string | Sim | Destino do saque: chave PIX (para `method: "pix"`) ou endereço Litecoin (para `method: "ltc"`). Valores com mais de 100 caracteres são truncados em 100. |
| `cryptoAmount` | number | Condicional | Quantidade em LTC a sacar. Obrigatório (e maior que zero) quando `method` é `"ltc"` em produção. |

### Observações

- **PIX:** exige que a chave PIX da loja esteja verificada no dashboard. O valor de `amount` é debitado do saldo em reais da carteira e o saque é criado com status `pending`.
- **LTC:** o endereço deve ter formato Litecoin válido (legado iniciado em `L`, `M` ou `3`, ou bech32 iniciado em `ltc1`). O `cryptoAmount` é debitado do saldo LTC da carteira.
- **Sandbox:** com chave `ps_test_`, o saque é simulado — nenhum saldo real é debitado e a resposta retorna `status: "completed"` com `sandbox: true`.

## Rate limit

Máximo de **10 solicitações de payout por hora** por conta. Requisições que falham (erros de validação, saldo insuficiente etc.) não contam para o limite. Ao exceder, a API responde `429` com `{ "error": "Rate limit: max 10 payout requests per hour" }`.

Além disso, vale o limite global da API: **120 requisições por minuto**. Ao exceder, a API responde `429` com `{ "error": "Rate limit exceeded. Max 120 requests/minute." }`.

## Exemplo

```bash
curl -X POST https://api.purincash.com/v1/payouts \
  -H "Authorization: Bearer ps_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "pix",
    "amount": 150.00,
    "walletAddress": "sua-chave-pix@exemplo.com"
  }'
```

## Resposta

`201 Created` — saque PIX (produção):

```json
{
  "id": "SAQ-API-A1B2C3D4",
  "code": "SAQ-API-A1B2C3D4",
  "method": "pix",
  "amount": 150,
  "status": "pending",
  "sandbox": false
}
```

`201 Created` — saque LTC (produção):

```json
{
  "id": "SAQ-API-A1B2C3D4",
  "code": "SAQ-API-A1B2C3D4",
  "method": "ltc",
  "amount": 150,
  "cryptoAmount": 0.5,
  "status": "pending",
  "sandbox": false
}
```

`201 Created` — sandbox:

```json
{
  "id": "SAQ-SBX-A1B2C3D4",
  "code": "SAQ-SBX-A1B2C3D4",
  "method": "pix",
  "amount": 150,
  "walletAddress": "sua-chave-pix@exemplo.com",
  "status": "completed",
  "sandbox": true
}
```

## Erros

Erros seguem o formato `{ "error": "mensagem" }`.

| HTTP | Erro | Quando |
|---|---|---|
| 400 | `Invalid method. Use 'pix' or 'ltc'.` | `method` diferente de `pix` ou `ltc`. |
| 400 | `Amount must be at least R$ 5.00` | `amount` ausente, inválido ou menor que 5.00. |
| 400 | `Amount exceeds maximum (R$ 999,999.99)` | `amount` maior que 999999.99. |
| 400 | `walletAddress is required (PIX key or LTC address)` | `walletAddress` ausente ou vazio. |
| 400 | `Invalid LTC address format` | Endereço Litecoin com formato inválido (`method: "ltc"`). |
| 400 | `Insufficient balance` | Saldo em reais insuficiente para o saque PIX. A resposta inclui o campo `available` com o saldo disponível. |
| 400 | `Insufficient balance (concurrent debit)` | Saldo tornou-se insuficiente durante o processamento (débito concorrente). |
| 400 | `cryptoAmount is required for LTC withdrawals (> 0)` | `cryptoAmount` ausente ou não positivo em saque LTC. |
| 400 | `Insufficient LTC balance` | Saldo LTC insuficiente. A resposta inclui o campo `available` com o saldo LTC disponível. |
| 401 | `API key required. Use: Authorization: Bearer ps_live_...` | Header `Authorization` ausente ou sem o formato `Bearer ps_...`. |
| 401 | `Invalid API key prefix. Use ps_live_ or ps_test_` | Chave sem o prefixo `ps_live_` ou `ps_test_`. |
| 401 | `Invalid or revoked API key` | Chave de API inválida ou revogada. |
| 403 | `PIX not verified. Complete verification in the dashboard first.` | Saque PIX sem chave PIX verificada no dashboard. |
| 429 | `Rate limit: max 10 payout requests per hour` | Limite de 10 solicitações de payout por hora excedido. |
| 429 | `Rate limit exceeded. Max 120 requests/minute.` | Limite global de 120 requisições por minuto excedido. |
| 500 | `Internal error` | Erro interno inesperado. |

---

# List Payouts

> Lista os saques (payouts) da sua conta, do mais recente para o mais antigo.

```
GET /v1/payouts
```

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

## Autenticação

Envie sua chave de API no header `Authorization: Bearer <chave>` — use `ps_live_...` em produção e `ps_test_...` no sandbox.

## Parâmetros

Parâmetros de query string:

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `limit` | integer | Não | Quantidade máxima de saques retornados. Entre 1 e 100. Padrão: 20. |
| `status` | string | Não | Filtra os saques pelo status informado. Valores possíveis: `pendente`, `processing`, `concluido`, `negado`, `falhou`. |

### Observações

- Os resultados são ordenados por data de criação, do mais recente para o mais antigo.
- O campo `walletAddress` é retornado mascarado por segurança (apenas os 6 primeiros caracteres, seguidos de `***`).
- **Sandbox:** com chave `ps_test_`, a resposta é sempre uma lista vazia (`{ "payouts": [] }`) — saques simulados não são persistidos.

## Exemplo

```bash
curl "https://api.purincash.com/v1/payouts?limit=10&status=pendente" \
  -H "Authorization: Bearer ps_live_SUA_CHAVE"
```

## Resposta

`200 OK`:

```json
{
  "payouts": [
    {
      "id": "SAQ-API-A1B2C3D4",
      "code": "SAQ-API-A1B2C3D4",
      "method": "pix",
      "amount": 150,
      "cryptoAmount": null,
      "walletAddress": "sua-ch***",
      "status": "pendente",
      "createdAt": "2026-07-11T14:30:00.000Z"
    },
    {
      "id": "SAQ-API-E5F6G7H8",
      "code": "SAQ-API-E5F6G7H8",
      "method": "ltc",
      "amount": 300,
      "cryptoAmount": "0.5",
      "walletAddress": "ltc1qx***",
      "status": "pendente",
      "createdAt": "2026-07-10T09:12:00.000Z"
    }
  ]
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | string | Código identificador do saque. |
| `code` | string | Mesmo valor de `id`. |
| `method` | string | Método do saque: `pix` ou `ltc`. |
| `amount` | number | Valor do saque em reais (BRL). |
| `cryptoAmount` | string \| null | Quantidade em LTC (apenas saques `ltc`); `null` para saques PIX. |
| `walletAddress` | string \| null | Destino do saque, mascarado (6 primeiros caracteres + `***`). |
| `status` | string | Status atual do saque: `pendente`, `processing`, `concluido`, `negado` ou `falhou`. Um saque recém-criado (retornado como `pending` na criação) aparece aqui como `pendente`. |
| `createdAt` | string | Data de criação do saque (ISO 8601). |

## Erros

Erros seguem o formato `{ "error": "mensagem" }`.

| HTTP | Erro | Quando |
|---|---|---|
| 401 | `API key required. Use: Authorization: Bearer ps_live_...` | Header `Authorization` ausente ou sem o formato `Bearer ps_...`. |
| 401 | `Invalid API key prefix. Use ps_live_ or ps_test_` | Chave sem o prefixo `ps_live_` ou `ps_test_`. |
| 401 | `Invalid or revoked API key` | Chave de API inválida ou revogada. |
| 429 | `Rate limit exceeded. Max 120 requests/minute.` | Limite global de 120 requisições por minuto excedido. |
| 500 | `Internal error` | Erro interno inesperado. |

---

# Simulate Payment Paid

> Simula a confirmação de pagamento de uma cobrança de checkout criada no sandbox, sem movimentar dinheiro real.

```
POST /v1/sandbox/payments/:paymentId/simulate-paid
```

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

## Autenticação

Requer uma chave de **sandbox** (`ps_test_...`) no header `Authorization: Bearer`.

## Como funciona o sandbox

O ambiente de sandbox usa dados totalmente simulados — nenhuma cobrança real é gerada e nenhum valor é movimentado. Pagamentos criados com uma chave `ps_test_` nunca são pagos de verdade; use este endpoint para marcar o pagamento como `paid` e testar sua integração de ponta a ponta.

Se o pagamento tiver um `callbackUrl` configurado, o webhook `payment.paid` é disparado imediatamente na simulação, com o campo `sandbox: true` no corpo — exatamente como aconteceria em produção após um pagamento real.

Chamar o endpoint em um pagamento que já está `paid` não altera o status nem o `paidAt`: a resposta é retornada normalmente. Porém, se houver `callbackUrl`, o webhook `payment.paid` é reenviado a cada chamada — inclusive em chamadas repetidas.

## Parâmetros

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `paymentId` | string (path) | Sim | ID do pagamento retornado na criação (ambiente sandbox). |

Não há corpo de requisição.

## Exemplo

```bash
curl -X POST "https://api.purincash.com/v1/sandbox/payments/pay_abc123/simulate-paid" \
  -H "Authorization: Bearer ps_test_sua_chave"
```

## Resposta

```json
{
  "success": true,
  "paymentId": "pay_abc123",
  "status": "paid",
  "paidAt": "2026-07-11T14:32:10.000Z"
}
```

Payload do webhook enviado ao `callbackUrl` (se configurado):

```json
{
  "event": "payment.paid",
  "paymentId": "pay_abc123",
  "amountCents": 5000,
  "status": "paid",
  "paidAt": "2026-07-11T14:32:10.000Z",
  "customer": { "name": "Cliente Teste", "email": "cliente@exemplo.com" },
  "metadata": {},
  "sandbox": true
}
```

## Erros

| HTTP | Erro | Quando |
|---|---|---|
| 403 | `Sandbox endpoint requires ps_test_ key` | A chave usada não é de sandbox (`ps_test_`). |
| 404 | `Payment not found` | O `paymentId` não existe no seu ambiente sandbox. |
| 500 | `Internal error` | Erro inesperado no servidor. |

---

# Simulate Charge Paid

> Simula a confirmação de pagamento de uma cobrança avulsa (charge) criada no sandbox, sem movimentar dinheiro real.

```
POST /v1/sandbox/charges/:paymentId/simulate-paid
```

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

## Autenticação

Requer uma chave de **sandbox** (`ps_test_...`) no header `Authorization: Bearer`.

## Como funciona o sandbox

Charges criadas com uma chave `ps_test_` são totalmente simuladas — nenhum QR Code real é cobrado e nenhum valor é movimentado. Como no sandbox ninguém paga de verdade, use este endpoint para marcar a charge como `paid` e validar o fluxo completo da sua integração.

Se a charge tiver um `callbackUrl` configurado, o webhook `payment.paid` é disparado imediatamente na simulação, com o campo `sandbox: true` no corpo — igual ao comportamento de produção após um pagamento real.

Chamar o endpoint em uma charge que já está `paid` não altera o status nem o `paidAt`: a resposta é retornada normalmente. Porém, se houver `callbackUrl`, o webhook `payment.paid` é reenviado a cada chamada — inclusive em chamadas repetidas.

## Parâmetros

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `paymentId` | string (path) | Sim | ID da charge retornado na criação (ambiente sandbox). |

Não há corpo de requisição.

## Exemplo

```bash
curl -X POST "https://api.purincash.com/v1/sandbox/charges/pay_xyz789/simulate-paid" \
  -H "Authorization: Bearer ps_test_sua_chave"
```

## Resposta

```json
{
  "success": true,
  "paymentId": "pay_xyz789",
  "status": "paid",
  "paidAt": "2026-07-11T14:32:10.000Z"
}
```

Payload do webhook enviado ao `callbackUrl` (se configurado):

```json
{
  "event": "payment.paid",
  "paymentId": "pay_xyz789",
  "amountCents": 2500,
  "status": "paid",
  "paidAt": "2026-07-11T14:32:10.000Z",
  "customer": { "name": "Cliente Teste", "email": "cliente@exemplo.com" },
  "metadata": {},
  "sandbox": true
}
```

## Erros

| HTTP | Erro | Quando |
|---|---|---|
| 403 | `Sandbox endpoint requires ps_test_ key` | A chave usada não é de sandbox (`ps_test_`). |
| 404 | `Charge not found` | O `paymentId` não corresponde a uma charge no seu ambiente sandbox. |
| 500 | `Internal error` | Erro inesperado no servidor. |

---

# Sandbox Wallet

> Consulta o saldo simulado da sua carteira no ambiente de sandbox, calculado a partir dos pagamentos e charges de teste.

```
GET /v1/sandbox/wallet
```

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

## Autenticação

Requer uma chave de **sandbox** (`ps_test_...`) no header `Authorization: Bearer`.

## Como funciona o sandbox

O saldo retornado é totalmente simulado — nenhum dinheiro real está envolvido. Ele é calculado somando todos os pagamentos e charges do seu ambiente sandbox:

- **Disponível** (`availableCents` / `available`): soma dos itens com status `paid` (inclusive os marcados via endpoints de simulação).
- **Pendente** (`pendingCents` / `pending`): soma dos itens com status `pending`.

Use este endpoint para verificar que suas simulações de pagamento estão refletindo corretamente no saldo antes de ir para produção com uma chave `ps_live_`.

## Parâmetros

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| — | — | — | Este endpoint não recebe parâmetros. |

## Exemplo

```bash
curl "https://api.purincash.com/v1/sandbox/wallet" \
  -H "Authorization: Bearer ps_test_sua_chave"
```

## Resposta

```json
{
  "sandbox": true,
  "availableCents": 7500,
  "pendingCents": 2500,
  "available": 75,
  "pending": 25
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `sandbox` | boolean | Sempre `true` — indica que os valores são simulados. |
| `availableCents` | number | Saldo disponível em centavos (soma dos itens `paid`). |
| `pendingCents` | number | Saldo pendente em centavos (soma dos itens `pending`). |
| `available` | number | Saldo disponível em reais. |
| `pending` | number | Saldo pendente em reais. |

## Erros

| HTTP | Erro | Quando |
|---|---|---|
| 403 | `Sandbox endpoint requires ps_test_ key` | A chave usada não é de sandbox (`ps_test_`). |
| 500 | `Internal error` | Erro inesperado no servidor. |

---

# Sandbox Transactions

> Lista todas as transações simuladas (pagamentos e charges) do seu ambiente de sandbox, com paginação.

```
GET /v1/sandbox/transactions
```

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

## Autenticação

Requer uma chave de **sandbox** (`ps_test_...`) no header `Authorization: Bearer`.

## Como funciona o sandbox

As transações listadas são todas simuladas — criadas com sua chave `ps_test_`, sem qualquer cobrança real. A lista unifica pagamentos de checkout (`source: "payment"`) e charges avulsas (`source: "charge"`), ordenados do mais recente para o mais antigo. Use este endpoint para auditar seus testes e conferir o efeito das simulações de pagamento.

## Parâmetros

Query string:

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `limit` | number | Não | Quantidade de itens por página. Padrão `50`, mínimo `1`, máximo `200`. |
| `offset` | number | Não | Quantidade de itens a pular. Padrão `0`. |

## Exemplo

```bash
curl "https://api.purincash.com/v1/sandbox/transactions?limit=20&offset=0" \
  -H "Authorization: Bearer ps_test_sua_chave"
```

## Resposta

```json
{
  "sandbox": true,
  "transactions": [
    {
      "id": "66b2f0c1e4a1a2b3c4d5e6f7",
      "paymentId": "pay_abc123",
      "type": "one_time",
      "source": "payment",
      "status": "paid",
      "amountCents": 5000,
      "createdAt": "2026-07-11T14:00:00.000Z",
      "paidAt": "2026-07-11T14:32:10.000Z"
    },
    {
      "id": "66b2f0c1e4a1a2b3c4d5e6f8",
      "paymentId": "pay_xyz789",
      "type": "charge",
      "source": "charge",
      "status": "pending",
      "amountCents": 2500,
      "createdAt": "2026-07-11T13:00:00.000Z",
      "paidAt": null
    }
  ],
  "total": 2,
  "limit": 20,
  "offset": 0
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | string | Identificador interno da transação. |
| `paymentId` | string | ID público do pagamento ou charge. |
| `type` | string | `one_time`, `subscription` ou `charge`. |
| `source` | string | Origem: `payment` (checkout) ou `charge` (cobrança avulsa). |
| `status` | string | Status atual (ex.: `pending`, `paid`). |
| `amountCents` | number | Valor em centavos. |
| `createdAt` | string | Data de criação (ISO 8601). |
| `paidAt` | string \| null | Data do pagamento simulado, se houver. |

## Erros

| HTTP | Erro | Quando |
|---|---|---|
| 403 | `Sandbox endpoint requires ps_test_ key` | A chave usada não é de sandbox (`ps_test_`). |
| 500 | `Internal error` | Erro inesperado no servidor. |