# PurinCash

> Documentação da API PurinCash. Cobranças PIX, cartão, assinaturas, splits, saques e webhooks, com sandbox gratuito.

- [Documentação PurinCash](https://docs.purin.cash/index.md): Como integrar pagamentos PIX, cartão, cripto e assinatura na PurinCash: referência da API, webhooks e um sandbox pra testar o fluxo inteiro sem mover dinheiro.
- [Sua primeira cobrança](https://docs.purin.cash/guias/primeira-cobranca.md): Do zero ao PIX pago em sandbox, sem mover dinheiro de verdade.
- [Autenticação](https://docs.purin.cash/guias/autenticacao.md): Uma chave, um header. Como pegar, como guardar e o que fazer quando vaza.
- [Ambientes e sandbox](https://docs.purin.cash/guias/ambientes.md): Como testar o fluxo inteiro, inclusive webhook, sem mover um centavo.
- [Receber por PIX](https://docs.purin.cash/guias/pix.md): Os dois endpoints de PIX, quando usar cada um e como reconciliar sem passar vergonha.
- [Receber por cartão](https://docs.purin.cash/guias/cartao.md): Checkout hospedado: você redireciona, a gente cobra e devolve o resultado.
- [Assinaturas](https://docs.purin.cash/guias/assinaturas.md): Pix Automático: o cliente paga uma vez, autoriza no banco, e a renovação é cobrada sozinha.
- [Receber em Litecoin](https://docs.purin.cash/guias/cripto.md): Mesmo endpoint do PIX, um campo a mais. E três diferenças que mudam o seu fluxo.
- [Dividir o valor (split)](https://docs.purin.cash/guias/splits.md): Marketplace, comissão e sociedade resolvidos no instante em que o dinheiro entra.
- [Produtos](https://docs.purin.cash/guias/produtos.md): Existem dois tipos de produto com o mesmo nome. Aqui está qual é qual.
- [Entrega automática](https://docs.purin.cash/guias/entrega.md): Como buscar a chave, a conta ou o link que o comprador recebeu.
- [Carteira](https://docs.purin.cash/guias/carteira.md): Saldo bruto, retido, a liberar e sacável. Quatro números que não são a mesma coisa.
- [Subcontas](https://docs.purin.cash/guias/subcontas.md): Um saldo separado para cada cliente seu, sem você manter essa contabilidade na mão.
- [Saques](https://docs.purin.cash/guias/saques.md): Tirar o saldo por PIX, LTC ou USDT sem sair do código. O PIX pode sair na hora, e aí não tem volta.
- [Disputas](https://docs.purin.cash/guias/disputas.md): O cliente contestou o PIX. Como acompanhar, responder com provas e saber o resultado, tudo pela API.
- [Erros](https://docs.purin.cash/guias/erros.md): Um formato só, sete códigos, e quais deles vale reenviar.
- [Limites de requisição](https://docs.purin.cash/guias/limites.md): 120 por minuto no geral, 10 por hora em saque. E como não bater neles.
- [Antes de ir pra produção](https://docs.purin.cash/guias/producao.md): A lista curta do que costuma quebrar no primeiro dia com dinheiro de verdade.
- [Como funcionam os webhooks](https://docs.purin.cash/webhooks/visao-geral.md): Quem avisa quem, o que a sua URL precisa ter e o que acontece quando ela cai.
- [Validando a assinatura](https://docs.purin.cash/webhooks/assinatura.md): Sem isso, qualquer pessoa na internet consegue dizer que pagou.
- [payment.paid e charge.paid](https://docs.purin.cash/webhooks/pagamentos.md): O evento que confirma que o PIX caiu, com os dados que só o banco tem.
- [card_payment.paid](https://docs.purin.cash/webhooks/cartao.md): Mesma ideia do PIX, dois campos com nome diferente. É onde o handler genérico quebra.
- [subscription.*](https://docs.purin.cash/webhooks/assinaturas.md): Autorizou, renovou, falhou, cancelou. Quatro eventos, uma chave estável: o subscriptionId.
- [order.paid](https://docs.purin.cash/webhooks/pedidos.md): Para quem vende pelo bot no Discord e quer sincronizar estoque ou CRM.
- [withdrawal.*](https://docs.purin.cash/webhooks/saques.md): Solicitado, pago, negado ou falhou. Os momentos em que o seu saldo muda de lado.
- [subaccount.*](https://docs.purin.cash/webhooks/subcontas.md): Transferência, saque e estorno: todo movimento do ledger que não nasce de uma cobrança.
- [Referência da API](https://docs.purin.cash/api-reference/introducao.md): 35 endpoints, um formato de erro, uma autenticação. Com playground pra testar aqui mesmo.
- [Create Payment](https://docs.purin.cash/api-reference/pagamentos/create-payment.md): Cria um pagamento e retorna os dados para o cliente pagar. Suporta PIX (padrão) e LTC (Litecoin) via `paymentMethod`. Envie `productId` (o preço vem do produto) ou `valueCents` (valor avulso em centavos); se ambos forem enviados, o preço do produto prevalece. Pagamentos LTC não estão disponíveis no…
- [List Payments](https://docs.purin.cash/api-reference/pagamentos/list-payments.md): Retorna a lista de pagamentos com paginação e filtros por status e tipo, ordenada da mais recente para a mais antiga. Os filtros são estritos: valor fora do vocabulário (status/type desconhecido, limit/offset inválido) devolve 400 em vez de cair no padrão em silêncio, e subaccountId malformado devol…
- [Get Payment](https://docs.purin.cash/api-reference/pagamentos/get-payment.md): Consulta os detalhes de um pagamento pelo paymentId, incluindo status, método de pagamento, cliente, metadata e datas. Use para confirmar o pagamento (polling) como alternativa ao webhook do callbackUrl.
- [Create Charge](https://docs.purin.cash/api-reference/cobrancas/create-charge.md): Cria uma cobrança PIX avulsa com valor customizado, sem produto vinculado. Retorna o BR Code (copia-e-cola) e a imagem do QR code para pagamento. Se `callbackUrl` for informado, um webhook `charge.paid` assinado com HMAC-SHA256 (header `X-Webhook-Signature`) é enviado quando o pagamento for confirma…
- [List Charges](https://docs.purin.cash/api-reference/cobrancas/list-charges.md): Lista as cobranças (psc_ e psplit_) da mais recente para a mais antiga, com os mesmos filtros estritos da lista de pagamentos: valor fora do vocabulário devolve 400, e ?subaccountId= malformado devolve 400 (inexistente, 404). Fecha a reconciliação por lista das vendas atribuídas via cobrança: antes,…
- [Get Charge](https://docs.purin.cash/api-reference/cobrancas/get-charge.md): Consulta os detalhes de uma cobrança avulsa pelo paymentId, incluindo status, cliente, metadata e datas. Use para confirmar o pagamento (polling) como alternativa ao webhook do callbackUrl. Cobranças com split (prefixo psplit_) retornam o formato descrito em GET /v1/split-charges/{paymentId}.
- [Create Split Charge](https://docs.purin.cash/api-reference/splits/create-split-charge.md): Cria uma cobrança PIX que, ao ser paga, é dividida automaticamente entre VOCÊ (dono da chave de API) e 1 a 9 beneficiários (contas PurinCash já cadastradas). Em `splits` você lista SOMENTE os outros beneficiários. Você não se inclui: fica com o resto (100% menos a soma) e deve obrigatoriamente ter a…
- [Get Split Charge](https://docs.purin.cash/api-reference/splits/get-split-charge.md): Consulta o status de uma cobrança com split pelo paymentId (prefixo psplit_). Após o pagamento, retorna a taxa do gateway, o valor líquido e o quanto cada beneficiário recebeu (amountCents) com a data do crédito (creditedAt). Emails dos beneficiários são mascarados (LGPD).
- [Create Card Payment](https://docs.purin.cash/api-reference/cartao/create-card-payment.md): Cria um pagamento no cartão de crédito via Stripe Checkout e retorna a checkoutUrl para redirecionar o cliente. A sessão de checkout expira em 30 minutos. Não disponível no modo sandbox (chaves ps_test_).
- [List Card Payments](https://docs.purin.cash/api-reference/cartao/list-card-payments.md): Retorna a lista de pagamentos no cartão, ordenados do mais recente para o mais antigo, com paginação por limit/offset e filtro opcional por status. No modo sandbox (chaves ps_test_) a lista retorna vazia.
- [Get Card Payment](https://docs.purin.cash/api-reference/cartao/get-card-payment.md): Consulta os detalhes de um pagamento no cartão pelo orderCode retornado na criação. Não disponível no modo sandbox (chaves ps_test_).
- [Create Subscription](https://docs.purin.cash/api-reference/assinaturas/create-subscription.md): Cria uma assinatura por Pix Automático (o padrão de recorrência do Banco Central) vinculada a um produto ativo. O brCode devolvido é um QR composto: o cliente paga o primeiro ciclo e, no mesmo ato, autoriza os próximos no app do banco. A partir daí cada renovação é cobrada sozinha, um período depois…
- [List Subscriptions](https://docs.purin.cash/api-reference/assinaturas/list-subscriptions.md): Retorna a lista de assinaturas do ambiente da chave utilizada, ordenadas da mais recente para a mais antiga, com paginação por limit/offset e filtro opcional por status. É uma linha por assinatura; cada renovação paga aparece em GET /v1/payments como um pagamento próprio.
- [Get Subscription](https://docs.purin.cash/api-reference/assinaturas/get-subscription.md): Devolve a assinatura com o estado da autorização, o próximo débito e cada cobrança recorrente já enviada ao banco, com as tentativas de liquidação. O id pode ser o paymentId (psa_sub_…) ou o subscriptionId.
- [Cancel Subscription](https://docs.purin.cash/api-reference/assinaturas/cancel-subscription.md): Cancela a autorização no banco e as cobranças recorrentes ainda não liquidadas. O que já foi pago não muda. Dispara o webhook subscription.cancelled com reason "merchant". Idempotente: cancelar de novo devolve o mesmo resultado.
- [Create Product](https://docs.purin.cash/api-reference/produtos/create-product.md): Cria um produto para ser referenciado em pagamentos e assinaturas. Limite de 500 produtos por conta por ambiente.
- [List Products](https://docs.purin.cash/api-reference/produtos/list-products.md): Retorna a lista de produtos criados, ordenada da mais recente para a mais antiga. Por padrão, apenas produtos ativos são retornados.
- [Get Product](https://docs.purin.cash/api-reference/produtos/get-product.md): Obtém os detalhes de um único produto pelo seu ID.
- [Update Product](https://docs.purin.cash/api-reference/produtos/update-product.md): Atualiza um produto existente. Todos os campos são opcionais, e apenas os campos enviados são alterados.
- [Delete Product](https://docs.purin.cash/api-reference/produtos/delete-product.md): Exclui permanentemente um produto pelo seu ID.
- [List Store Products](https://docs.purin.cash/api-reference/loja/list-store-products.md): Lista os produtos da loja do Discord, com categoria, variações e estoque. É uma rota de leitura: para criar ou editar produtos da loja, use o painel.
- [Get Delivery](https://docs.purin.cash/api-reference/entregas/get-delivery.md): Consulta o status de entrega de um pagamento e retorna o conteúdo entregue, se disponível. Aceita IDs de pagamento (prefixo psa_) e de cobrança (prefixo psc_). O campo deliveredContent é null se o pagamento estiver pendente ou se o produto tiver entrega manual.
- [Create Subaccount](https://docs.purin.cash/api-reference/subcontas/create-subaccount.md): Cria uma subconta: um ledger de saldo próprio para um cliente seu, dentro da sua conta. Cobranças criadas com `subaccountId` creditam o saldo da subconta quando o pagamento confirma, e você consulta quanto pertence a cada cliente sem manter essa contabilidade do seu lado.
- [List Subaccounts](https://docs.purin.cash/api-reference/subcontas/list-subaccounts.md): Lista as subcontas da conta, mais recentes primeiro. Cada item já vem com medBlockedCents e availableCents, iguais aos do GET individual: uma tela de repasse em lote não precisa de uma chamada por subconta.
- [Get Subaccount](https://docs.purin.cash/api-reference/subcontas/get-subaccount.md): Detalhes de uma subconta, incluindo saldo atual e total recebido.
- [Update Subaccount](https://docs.purin.cash/api-reference/subcontas/update-subaccount.md): Atualiza nome, e-mail, metadata ou situação. Envie só o que quer mudar. `externalId` é imutável: enviar no PUT é `400`. `active` precisa ser boolean de verdade (`"false"` entre aspas é `400`), `metadata` precisa ser string de até 2048, e nada é truncado em silêncio: fora do limite é `400`. Desativar…
- [List Subaccount Transactions](https://docs.purin.cash/api-reference/subcontas/list-subaccount-transactions.md): Extrato da subconta: vendas creditadas e transferências, mais recentes primeiro. `amountCents` vem com sinal: crédito positivo, débito negativo. Somar a coluna reproduz o `balanceCents`.
- [Transfer Subaccount Balance](https://docs.purin.cash/api-reference/subcontas/transfer-subaccount-balance.md): Move saldo entre a subconta e a conta principal, nos dois sentidos. É uma operação contábil: nenhum PIX é enviado e o dinheiro real não sai da carteira da sua conta. Muda apenas a quem o valor está atribuído.
- [Payout From Subaccount](https://docs.purin.cash/api-reference/subcontas/payout-from-subaccount.md): Envia PIX para fora debitando ESTA subconta. O dinheiro sai da carteira da conta principal (é ela que tem lastro), mas a atribuição é da subconta: o saldo dela é debitado antes, e se o banco recusar depois, o valor volta para ela, não para o caixa geral.
- [Get Subaccount Payout](https://docs.purin.cash/api-reference/subcontas/get-subaccount-payout.md): Consulta um saque desta subconta: se o PIX saiu, se ainda está em processamento, ou se falhou e o valor voltou para a subconta.
- [Get Wallet](https://docs.purin.cash/api-reference/carteira/get-wallet.md): Retorna o saldo da carteira da loja. O campo withdrawable é o saldo sacável agora (balance - disputeBlocked - comprometido com subcontas): o valor retido por disputas (MED) e a soma dos saldos das subcontas são descontados do saldo bruto, e é esse o limite máximo aceito pelo POST /v1/payouts. Dinhei…
- [Create Payout](https://docs.purin.cash/api-reference/saques/create-payout.md): Solicita um saque PIX ou LTC do saldo disponível. O débito do saldo é atômico. O valor máximo sacável é o campo withdrawable do GET /v1/wallet (balance - disputeBlocked - comprometido com subcontas): o saldo retido por disputas (MED) abertas ou perdidas não perdoadas não é sacável, e o valor já atri…
- [Decode PIX Code](https://docs.purin.cash/api-reference/saques/decode-pix-code.md): Lê um código copia e cola (BR Code) e devolve o que há dentro dele SEM mover dinheiro: destino, valor, se o valor é fixo e a taxa que será somada. É o passo recomendado antes de POST /v1/payouts com method "pix_code": o pagamento é imediato e não tem cancelamento, então descobrir destino e valor pel…
- [List Payouts](https://docs.purin.cash/api-reference/saques/list-payouts.md): Lista os saques solicitados pela loja, do mais recente para o mais antigo. O campo walletAddress é sempre mascarado (6 primeiros caracteres + ***). No sandbox lista os saques simulados, com "sandbox": true em cada item. Os status vêm crus, em português: pendente, concluido, negado, processing (turbo…
- [List Disputes](https://docs.purin.cash/api-reference/disputas/list-disputes.md): Lista as disputas (MED, o Mecanismo Especial de Devolução) da conta, das mais recentes para as mais antigas. Enquanto uma disputa está aberta ou foi perdida, o valor contestado fica retido do saldo sacável (campo disputeBlocked do GET /v1/wallet). Precisa da permissão disputas.gerenciar. No sandbox…
- [Get Dispute](https://docs.purin.cash/api-reference/disputas/get-dispute.md): Uma disputa pelo ID, com as provas enviadas, a situação da defesa e a linha do tempo dos status (os mesmos eventos enviados por webhook). Precisa da permissão disputas.gerenciar. No sandbox retorna 404.
- [Submit Evidence](https://docs.purin.cash/api-reference/disputas/submit-evidence.md): Responde uma disputa aberta (canRespond: true) com arquivos, links e um texto, que vira PDF. A resposta é entregue ao banco do pagador; a mesma do painel. Prefira arquivos: vários bancos recebem a defesa só como arquivo, e links em documents vão citados no texto. Pode ser chamado mais de uma vez enq…
- [Simulate Payment Paid](https://docs.purin.cash/api-reference/sandbox/simulate-payment-paid.md): Simula a confirmação de um pagamento no ambiente de teste. Requer chave ps_test_ (retorna 403 com chave ps_live_). Marca o pagamento como "paid" e, se o pagamento tiver callbackUrl, dispara o webhook payment.paid com "sandbox": true. Pagamentos já pagos apenas retornam o estado atual.
- [Simulate Charge Paid](https://docs.purin.cash/api-reference/sandbox/simulate-charge-paid.md): Simula a confirmação de uma cobrança avulsa no ambiente de teste. Requer chave ps_test_ (retorna 403 com chave ps_live_). Marca a cobrança como "paid" e dispara o webhook charge.paid com "sandbox": true, IGUAL ao evento da cobrança em produção (na callbackUrl da cobrança, ou na URL geral da conta).…
- [Sandbox Wallet](https://docs.purin.cash/api-reference/sandbox/sandbox-wallet.md): Retorna o saldo simulado do ambiente de teste, calculado a partir dos pagamentos e cobranças de teste. Os pagos somam em available e os pendentes em pending. Requer chave ps_test_ (retorna 403 com chave ps_live_).
- [Sandbox Transactions](https://docs.purin.cash/api-reference/sandbox/sandbox-transactions.md): Lista as transações do ambiente de teste (pagamentos e cobranças avulsas), das mais recentes para as mais antigas. Requer chave ps_test_ (retorna 403 com chave ps_live_).

## OpenAPI Specs

- [openapi](/api-reference/openapi.yaml)

## Optional

- [Dashboard](https://purin.cash/dashboard/api)
- [Suporte no Discord](https://discord.gg/8eyQQFZZxY)
- [llms.txt](https://docs.purin.cash/llms-full.txt)


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