DocumentaçãoReferência da API

API PurinCash

Integre pagamentos PIX na sua aplicação em minutos. Simples, segura e feita para desenvolvedores.

O que é a PurinCash?

A PurinCash é um gateway de pagamento que simplifica cobranças PIX. Nossa API foi construída com foco em simplicidade: endpoints intuitivos, respostas consistentes e zero burocracia.

Baseada em intenção

Cada endpoint faz exatamente o que o nome diz

Rápida

PIX gerado em milissegundos, callback instantâneo

Consistente

Respostas padronizadas com error/data em toda a API

Início rápido

Crie uma API Key no painel
Chame POST /v1/payments com o valor ou produto
O cliente paga o PIX (brCode retornado)
Receba o callback automático na sua URL

Usando IA para integrar? Acesse a documentação otimizada para LLMs em purincash.com/llms-full.txt — formato plain text estruturado que modelos de linguagem interpretam perfeitamente.

Exemplo rápido

curl -X POST https://api.purincash.com/v1/payments \
  -H "Authorization: Bearer ps_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "665f1a2b3c4d5e6f7a8b9c0d",
    "callbackUrl": "https://seu-site.com/webhook"
  }'

Resposta

{
  "paymentId": "psa_a1b2c3d4e5f6...",
  "status": "pending",
  "amountCents": 2990,
  "pix": {
    "brCode": "00020126580014br.gov.bcb.pix...",
    "qrCodeImage": "https://api.openpix.com.br/..."
  },
  "expiresAt": "2026-03-18T12:30:00.000Z"
}

Comece aquiAutenticação

Autenticação

Todas as requisições exigem uma API Key no header Authorization.

Terminal

Authorization: Bearer ps_live_sua_chave_aqui

Crie e gerencie suas chaves em Dashboard → API. Cada conta pode ter até 10 chaves ativas.

Nunca exponha sua API key no frontend ou em repositórios públicos. Use apenas no backend (server-side).

Comece aquiErros

Erros

A API retorna erros no formato JSON com o campo error:

Terminal

{
  "error": "Product not found or inactive"
}

CódigoSignificado

400

Parâmetro inválido ou ausente

401

API key inválida ou ausente

404

Recurso não encontrado

429

Rate limit excedido (120 req/min)

502

Falha no gateway de pagamento

ProdutosCRUD

Produtos

Criar produto

POST/v1/products

namestringobrigatório

Nome do produto (max 200)

priceCentsnumberobrigatório

Preço em centavos (min 100 = R$ 1,00)

Opcionais

descriptionstringopcional

Descrição (max 500)

currencystringopcional

Moeda (default BRL)

metadatastringopcional

JSON string com dados extras (max 2KB)

curl -X POST https://api.purincash.com/v1/products \
  -H "Authorization: Bearer ps_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Plano Premium",
  "description": "Acesso mensal ao conteúdo premium",
  "priceCents": 4990,
  "currency": "BRL",
  "metadata": "{\"sku\":\"premium-01\"}"
}'

Cria um produto que pode ser referenciado em pagamentos e assinaturas. Limite: 500 produtos por conta/ambiente.

Resposta (201)

{
  "_id": "60f7b2a1c3e4d5f6a7b8c9d0",
  "name": "Plano Premium",
  "description": "Acesso mensal",
  "priceCents": 4990,
  "currency": "BRL",
  "active": true,
  "metadata": "{}",
  "createdAt": "2026-03-18T10:00:00.000Z"
}

Listar produtos

GET/v1/products

includeInactivestringopcional

Defina como "true" para incluir produtos inativos

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

Resposta (200)

{
  "products": [
    {
      "_id": "60f7...",
      "name": "Plano Premium",
      "priceCents": 4990,
      "currency": "BRL",
      "active": true,
      "createdAt": "..."
    }
  ]
}

Obter produto

GET/v1/products/:id

Retorna o produto individual com os mesmos campos da listagem.

Atualizar produto

PUT/v1/products/:id

namestringopcional

Novo nome (max 200)

descriptionstringopcional

Nova descrição (max 500)

priceCentsnumberopcional

Novo preço em centavos (min 100)

activebooleanopcional

Ativar/desativar produto

metadatastringopcional

JSON string (max 2KB)

curl -X PUT https://api.purincash.com/v1/products/:id \
  -H "Authorization: Bearer ps_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Plano Premium v2",
  "priceCents": 5990,
  "active": true
}'

Todos os campos são opcionais. Envie apenas o que deseja alterar.

Deletar produto

DELETE/v1/products/:id

Resposta (200)

{
  "deleted": true
}

Pagamentos PIXReferência

Pagamentos PIX

Criar pagamento

POST/v1/payments

productIdstringopcional

ID do produto (preço vem dele)

valueCentsnumberopcional

Valor em centavos (min 100) — se sem productId

descriptionstringopcional

Descrição do pagamento

callbackUrlstringopcional

URL HTTPS para webhook quando pago

customer.namestringopcional

Nome do cliente

customer.emailstringopcional

Email do cliente

customer.externalIdstringopcional

ID externo no seu sistema

metadatastringopcional

JSON string com dados extras (max 2KB)

curl -X POST https://api.purincash.com/v1/payments \
  -H "Authorization: Bearer ps_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "valueCents": 4990,
  "description": "Pedido #1234",
  "callbackUrl": "https://seusite.com/webhooks/purincash",
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com",
    "externalId": "user_123"
  }
}'

Cria um pagamento PIX. Vincule a um produto (productId) ou envie valor livre (valueCents).

Envie productId OU valueCents. Se ambos forem enviados, o preço do produto prevalece.

Resposta (200)

{
  "paymentId": "psa_a1b2c3d4e5f6...",
  "status": "pending",
  "amountCents": 4990,
  "currency": "BRL",
  "productName": "Produto Premium",
  "pix": {
    "brCode": "00020126580014br.gov.bcb.pix0136...",
    "qrCodeImage": "https://api.openpix.com.br/..."
  },
  "expiresAt": "2026-03-18T12:30:00.000Z"
}

O brCode é o PIX Copia e Cola. O qrCodeImage é a URL da imagem do QR Code. Pagamento expira em 30 minutos.

Consultar pagamento

GET/v1/payments/:paymentId

Consulta o status de um pagamento pelo paymentId.

Resposta

{
  "paymentId": "psa_a1b2c3d4...",
  "status": "paid",
  "amountCents": 4990,
  "paidAt": "2026-03-18T12:05:00.000Z"
}

Status: pending · paid · expired · refunded

Listar pagamentos

GET/v1/payments

limitnumberopcional

Resultados por página (1-100, default 50)

offsetnumberopcional

Pular N resultados

statusstringopcional

Filtrar: pending, paid, expired, refunded

curl -X GET "https://api.purincash.com/v1/payments?limit=50&status=paid" \
  -H "Authorization: Bearer ps_live_..."

Resposta

{
  "payments": [ ... ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

Cobranças PIXReferência

Cobranças PIX avulsas

Criar cobrança

POST/v1/charges

valueCentsnumberobrigatório

Valor em centavos (min 80). Aceita também `amountCents`/`amount` (decimais) quando usar splits.

Opcionais

descriptionstringopcional

Descrição (max 200, default "Pagamento PIX")

callbackUrlstringopcional

URL HTTPS para webhook quando pago

customer.namestringopcional

Nome do cliente (max 100)

customer.emailstringopcional

Email do cliente (max 255)

customer.externalIdstringopcional

ID externo no seu sistema (max 200)

metadatastringopcional

JSON string com dados extras (max 2KB) — não suportado em cobranças com splits

curl -X POST https://api.purincash.com/v1/charges \
  -H "Authorization: Bearer ps_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "valueCents": 1200,
  "description": "Pagamento avulso",
  "callbackUrl": "https://seu-site.com/webhook",
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com",
    "externalId": "user_123"
  }
}'

Cria uma cobrança PIX avulsa com valor customizado, sem necessidade de produto cadastrado. Opcionalmente, envie splits[] para dividir automaticamente o valor recebido entre múltiplas contas purincash (marketplaces, comissionamento, royalties).

Request

curl -X POST https://api.purincash.com/v1/charges \
  -H "Authorization: Bearer ps_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "valueCents": 1200,
    "description": "Pagamento avulso",
    "callbackUrl": "https://seu-site.com/webhook"
  }'

Resposta (201)

{
  "paymentId": "psc_a1b2c3d4e5f6...",
  "status": "pending",
  "amountCents": 1200,
  "currency": "BRL",
  "environment": "live",
  "pix": {
    "brCode": "00020126580014br.gov.bcb.pix0136...",
    "qrCodeImage": "https://api.openpix.com.br/..."
  },
  "expiresAt": "2026-03-18T12:30:00.000Z"
}

O prefixo psc_ indica cobrança avulsa. psa_ indica pagamento vinculado a produto. psplit_ indica cobrança com splits.

Com splits (divisão automática)

Adicione splits[] ao request com apenas os OUTROS beneficiários. Você, dono da API key, é participante implícito: não entra na lista e recebe automaticamente o resto (100 − soma das percentages). Ao pagamento, cada conta recebe na própria carteira purincash. Também aceito em POST /v1/split-charges (alias).

POST/v1/split-charges

amountCentsnumberobrigatório

Valor total em centavos (80–500000). Aceita também `valueCents`/`amount`.

splitsarrayobrigatório

1 a 9 beneficiários ALÉM de você. Você (dono da API key) NÃO entra na lista — recebe o resto (100 − soma das percentages), que precisa ser a maior fatia.

recipientEmailstring

percentagenumber

Opcionais

descriptionstringopcional

Descrição (max 200)

callbackUrlstringopcional

URL HTTPS para webhook quando pago

customer.namestringopcional

Nome do cliente

customer.emailstringopcional

Email do cliente

curl -X POST https://api.purincash.com/v1/split-charges \
  -H "Authorization: Bearer ps_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "amountCents": 10000,
  "description": "Venda compartilhada",
  "customer": {
    "name": "Cliente",
    "email": "cliente@example.com"
  },
  "splits": [
    {
      "recipientEmail": "socio@example.com",
      "percentage": 30
    }
  ]
}'

Validações rigorosas — rejeição imediata com HTTP 400 se quebradas:

splits: 1 a 9 beneficiários (você é o implícito — até 10 no total)
Não liste você mesmo: o dono da API key recebe o resto automaticamente
Cada percentage: entre 0.01 e 99.99
Soma das percentages: < 100.00 — sua fatia é o resto e precisa ser estritamente a maior
recipientEmail único por charge (sem duplicar)
Beneficiário deve ser conta purincash existente (validado por email)
amountCents: integer entre 80 (R$ 0.80) e 500.000 (R$ 5.000)

Request — você fica com 70%, seu sócio com 30%

curl -X POST https://api.purincash.com/v1/charges \
  -H "Authorization: Bearer ps_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 10000,
    "description": "Venda compartilhada",
    "splits": [
      { "recipientEmail": "socio@example.com", "percentage": 30 }
    ],
    "customer": { "name": "Cliente", "email": "cliente@example.com" }
  }'

Resposta (201)

{
  "paymentId": "psplit_a1b2c3d4...",
  "status": "pending",
  "amountCents": 10000,
  "currency": "BRL",
  "environment": "live",
  "pix": {
    "brCode": "00020126360014BR.GOV.BCB.PIX...",
    "qrCodeImage": null
  },
  "splits": [
    {
      "recipientEmail": "vo***@example.com",
      "percentage": 70,
      "isOwner": true
    },
    {
      "recipientEmail": "so***@example.com",
      "percentage": 30,
      "isOwner": false
    }
  ],
  "expiresAt": "2026-05-28T12:30:00.000Z"
}

Fluxo de pagamento:

Você cria a cobrança com splits → recebe brCode (PIX copia-e-cola)
Cliente paga o valor cheio (10000 cents = R$ 100,00)
Os OUTROS beneficiários recebem a percentage cheia sobre o bruto (sócio 30% → R$ 30,00)
A taxa do gateway (ex: 2% + R$ 0,50 = R$ 2,50) sai 100% da SUA parte
Você recebe o resto: 10000 − 3000 − 250 = 6750 cents (R$ 67,50)
Cada um recebe na própria carteira purincash, com evento financeiro auditável

Exemplo de arredondamento: charge R$ 100 (10000 cents), taxa R$ 2,50. Outros com 33.33% e 33.33% (você fica com 33.34%):

A: floor(10000 × 0.3333) = 3333 cents (R$ 33,33)
B: floor(10000 × 0.3333) = 3333 cents (R$ 33,33)
Você: 10000 − 3333 − 3333 − 250 = 3084 cents (R$ 30,84)

A soma creditada + taxa bate exatamente com o bruto. Se a taxa for maior que a sua fatia, você recebe 0 (nunca negativo).

Consultar cobrança

GET/v1/charges/:paymentId

Consulta o status de uma cobrança pelo paymentId. Quando o ID começa com psplit_, a resposta inclui o breakdown de cada split (valor creditado em centavos e timestamp).

Resposta (200) — cobrança avulsa

{
  "paymentId": "psc_a1b2c3d4...",
  "status": "paid",
  "amountCents": 1200,
  "currency": "BRL",
  "description": "Pagamento avulso",
  "customer": {
    "name": "",
    "email": "",
    "externalId": ""
  },
  "metadata": "{}",
  "paidAt": "2026-03-18T12:05:00.000Z",
  "expiresAt": "2026-03-18T12:30:00.000Z",
  "createdAt": "2026-03-18T12:00:00.000Z"
}

Resposta (200) — cobrança com splits

{
  "paymentId": "psplit_a1b2c3d4...",
  "status": "paid",
  "amountCents": 10000,
  "gatewayFeeCents": 250,
  "netAmountCents": 9750,
  "currency": "BRL",
  "environment": "live",
  "pix": {
    "brCode": "..."
  },
  "splits": [
    {
      "recipientEmail": "vo***@example.com",
      "percentage": 70,
      "isOwner": true,
      "amountCents": 6750,
      "creditedAt": "2026-05-28T12:15:00.000Z"
    },
    {
      "recipientEmail": "so***@example.com",
      "percentage": 30,
      "isOwner": false,
      "amountCents": 3000,
      "creditedAt": "2026-05-28T12:15:00.000Z"
    }
  ],
  "paidAt": "2026-05-28T12:15:00.000Z",
  "expiresAt": "2026-05-28T12:30:00.000Z",
  "createdAt": "2026-05-28T12:00:00.000Z"
}

Status values: pending | paid | expired | refunded | cancelled.

Pagamentos CartãoStripe Checkout

Pagamentos por Cartão

Criar pagamento cartão

POST/v1/card-payments

valueCentsnumberobrigatório

Valor em centavos (min 100)

Opcionais

descriptionstringopcional

Descrição (max 200, default "Pagamento Cartao")

callbackUrlstringopcional

URL HTTPS para webhook quando pago

customer.namestringopcional

Nome do cliente (max 100)

customer.emailstringopcional

Email do cliente (max 255)

customer.externalIdstringopcional

ID externo (max 200)

metadatastringopcional

JSON string com dados extras (max 2KB)

successUrlstringopcional

URL de redirecionamento após pagamento

cancelUrlstringopcional

URL de redirecionamento ao cancelar

curl -X POST https://api.purincash.com/v1/card-payments \
  -H "Authorization: Bearer ps_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "valueCents": 4990,
  "description": "Pedido #1234",
  "callbackUrl": "https://seusite.com/webhooks/purincash",
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com",
    "externalId": "user_123"
  },
  "successUrl": "https://seusite.com/sucesso",
  "cancelUrl": "https://seusite.com/cancelado"
}'

Cria um pagamento por cartão de crédito via Stripe Checkout. O cliente é redirecionado para a página de checkout.

Não disponível em modo sandbox. Requer Stripe configurado no servidor.

Resposta (201)

{
  "orderCode": "JUE7Y9MPSX",
  "status": "pending",
  "amountCents": 4990,
  "currency": "BRL",
  "checkoutUrl": "https://checkout.stripe.com/...",
  "expiresAt": "2026-03-18T12:30:00.000Z"
}

Redirecione o cliente para checkoutUrl. Use successUrl e cancelUrl para controlar a experiência pós-pagamento.

Consultar pagamento cartão

GET/v1/card-payments/:orderCode

Consulta o status de um pagamento por cartão pelo orderCode.

Resposta (200)

{
  "orderCode": "JUE7Y9MPSX",
  "status": "paid",
  "amount": 49.9,
  "amountCents": 4990,
  "currency": "BRL",
  "description": "Pagamento Cartao",
  "checkoutUrl": null,
  "paidAt": "2026-03-18T12:05:00.000Z",
  "createdAt": "2026-03-18T12:00:00.000Z"
}

Status: pending · paid · expired · canceled

Listar pagamentos cartão

GET/v1/card-payments

limitnumberopcional

Resultados por página (1-100, default 50)

offsetnumberopcional

Pular N resultados

statusstringopcional

Filtrar: pending, paid, expired, refunded, failed

curl -X GET "https://api.purincash.com/v1/card-payments?limit=50&status=paid" \
  -H "Authorization: Bearer ps_live_..."

Resposta (200)

{
  "payments": [
    {
      "orderCode": "JUE7Y9MPSX",
      "status": "paid",
      "amountCents": 4990,
      "paidAt": "...",
      "createdAt": "..."
    }
  ],
  "total": 10,
  "limit": 50,
  "offset": 0
}

AssinaturasPIX Recorrente

Assinaturas

Criar assinatura

POST/v1/subscriptions

productIdstringobrigatório

ID do produto

customer.namestringobrigatório

Nome do assinante

Opcionais

customer.externalIdstringopcional

ID externo no seu sistema (max 200)

frequencystringopcional

WEEKLY, MONTHLY (default), SEMIANNUALLY ou ANNUALLY

dayGenerateChargenumberopcional

Dia do mês para gerar cobrança (4-28)

callbackUrlstringopcional

URL HTTPS para webhook a cada pagamento

metadatastringopcional

JSON string com dados extras (max 2KB)

curl -X POST https://api.purincash.com/v1/subscriptions \
  -H "Authorization: Bearer ps_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "productId": "60f7b2a1c3e4d5f6a7b8c9d0",
  "customer": {
    "name": "João Silva",
    "externalId": "user_123"
  },
  "frequency": "MONTHLY",
  "dayGenerateCharge": 15,
  "callbackUrl": "https://seusite.com/webhooks/purincash"
}'

Cria uma assinatura PIX recorrente vinculada a um produto. A cobrança é gerada automaticamente de acordo com a frequência escolhida.

Resposta

{
  "paymentId": "psa_sub_a1b2c3d4...",
  "status": "pending",
  "type": "subscription",
  "subscriptionId": "sub_xyz...",
  "amountCents": 4990,
  "currency": "BRL",
  "productName": "Plano Premium",
  "frequency": "MONTHLY",
  "environment": "live",
  "pix": {
    "brCode": "00020126580014br.gov.bcb.pix...",
    "paymentLinkUrl": "https://openpix.com.br/pay/..."
  },
  "dayGenerateCharge": 15
}

Frequências disponíveis: WEEKLY (semanal), MONTHLY (mensal, padrão), SEMIANNUALLY (semestral) e ANNUALLY (anual).

Listar assinaturas

GET/v1/subscriptions

limitnumberopcional

Resultados por página (1-100, default 50)

offsetnumberopcional

Pular N resultados (paginação)

statusstringopcional

Filtrar: pending, paid, expired, refunded

curl -X GET "https://api.purincash.com/v1/subscriptions?limit=50&status=paid" \
  -H "Authorization: Bearer ps_live_..."

Retorna as assinaturas criadas na sua conta com paginação e filtros.

Resposta

{
  "subscriptions": [
    {
      "paymentId": "psa_sub_a1b2c3d4...",
      "subscriptionId": "sub_xyz...",
      "status": "pending",
      "amountCents": 4990,
      "currency": "BRL",
      "productName": "Plano Premium",
      "customer": {
        "name": "João Silva",
        "email": "",
        "externalId": "user_123"
      },
      "metadata": "{}",
      "paidAt": null,
      "createdAt": "2026-03-18T10:00:00.000Z"
    }
  ],
  "total": 5,
  "limit": 20,
  "offset": 0
}

Sandbox

Ambiente de Teste

Use uma API key ps_test_... para operar em sandbox. Nesse modo, pagamentos e cobranças são criados sem gateway real e você pode simular confirmação.

Crie chave sandbox em Dashboard → API & Desenvolvedores.

Simular pagamento realizado

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

Marca um pagamento sandbox como pago e dispara callback payment.paid (se callbackUrl foi configurado).

Request

curl -X POST https://api.purincash.com/v1/sandbox/payments/psa_abc123/simulate-paid \
  -H "Authorization: Bearer ps_test_..."

Para cobranças avulsas, use POST /v1/sandbox/charges/:paymentId/simulate-paid.

Sandbox carteira

GET/v1/sandbox/wallet

Retorna saldo disponível e pendente apenas das transações sandbox.

Resposta

{
  "sandbox": true,
  "availableCents": 12990,
  "pendingCents": 4990,
  "available": 129.9,
  "pending": 49.9
}

Sandbox transações

GET/v1/sandbox/transactions

limitnumberopcional

Resultados por página (1-200, default 50)

offsetnumberopcional

Pular N resultados

curl -X GET "https://api.purincash.com/v1/sandbox/transactions?limit=50" \
  -H "Authorization: Bearer ps_live_..."

Resposta

{
  "sandbox": true,
  "transactions": [
    {
      "paymentId": "psa_abc123",
      "source": "payment",
      "type": "one_time",
      "status": "paid",
      "amountCents": 4990
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

DisputasReferência

Disputas

Listar disputas

GET/v1/disputes

limitnumberopcional

Resultados por página (1-100, default 50)

offsetnumberopcional

Pular N resultados (paginação)

statusstringopcional

Filtrar: aberta, resolvida, perdida

curl -X GET "https://api.purincash.com/v1/disputes?limit=50&status=aberta" \
  -H "Authorization: Bearer ps_live_..."

Retorna as disputas (MEDs) abertas contra sua conta. Use para monitorar contestações e enviar evidências.

Resposta

{
  "disputes": [
    {
      "id": "665f1a2b3c4d5e6f7a8b9c0d",
      "code": "MED-2024-001",
      "wooviDisputeId": "abc123...",
      "endToEndId": "E123456782024...",
      "orderCode": "JUE7Y9MPSX",
      "buyer": "João Silva",
      "product": "Produto Premium",
      "amount": 23.07,
      "reason": "Produto não recebido",
      "status": "aberta",
      "evidences": [],
      "resolvedAt": null,
      "createdAt": "2026-03-18T10:00:00.000Z"
    }
  ],
  "total": 3,
  "limit": 50,
  "offset": 0
}

Status: aberta · resolvida · perdida

Obter disputa

GET/v1/disputes/:id

Retorna detalhes de uma disputa pelo ID. Use o id retornado em listar disputas.

ParâmetroTipoDescrição

idreq

string

ID da disputa (path)

Request

curl -X GET https://api.purincash.com/v1/disputes/665f1a2b3c4d5e6f7a8b9c0d \
  -H "Authorization: Bearer ps_live_..."

Resposta

{
  "id": "665f1a2b3c4d5e6f7a8b9c0d",
  "code": "MED-2024-001",
  "wooviDisputeId": "abc123...",
  "endToEndId": "E123456782024...",
  "orderCode": "JUE7Y9MPSX",
  "buyer": "João Silva",
  "buyerDiscordId": "",
  "product": "Produto Premium",
  "amount": 23.07,
  "reason": "Produto não recebido",
  "status": "aberta",
  "evidences": [
    {
      "url": "https://...",
      "description": "Comprovante",
      "correlationID": "MED-2024-001-EV1"
    }
  ],
  "resolvedAt": null,
  "createdAt": "2026-03-18T10:00:00.000Z"
}

Se a disputa não pertencer à sua conta, a API retorna 404 Dispute not found.

Enviar evidências

POST/v1/disputes/:id/evidence

Envia documentos como evidência para contestar uma disputa aberta. Apenas disputas com status aberta aceitam evidências.

ParâmetroTipoDescrição

idreq

string

ID da disputa (path)

documents

array

Lista de documentos de evidência — até 10 itens

textForPdf

string

Texto convertido em PDF e enviado como evidência (alternativa a documents)

Request

curl -X POST https://api.purincash.com/v1/disputes/665f1a2b3c4d5e6f7a8b9c0d/evidence \
  -H "Authorization: Bearer ps_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "url": "https://seu-site.com/comprovante.pdf",
        "description": "Comprovante de entrega",
        "correlationID": "MED-2024-001-EV1"
      }
    ],
    "textForPdf": "O cliente recebeu o produto em 15/03. Rastreio: BR123456789."
  }'

Resposta (200)

{
  "success": true,
  "uploaded": 2
}

URLs devem apontar diretamente para arquivos (PDF, PNG, JPEG, WebP). Links de páginas HTML (como prnt.sc) serão rejeitados pela operadora.

SaquesSolicitar saque

Pague-se via API

Solicitar saque

Solicita uma transferência do saldo disponível da loja. PIX cai pendente de aprovação admin; LTC envia direto após aprovação.

POST/v1/payouts

Rate limit: 10 requisições por hora por API key.
PIX: a chave PIX deve estar pré-verificada no dashboard.

ParâmetroTipoDescrição

methodreq

string

"pix", "ltc" ou "usd"

amountreq

number

Valor em BRL (min 5.00, max 999999.99)

walletAddressreq

string

Chave PIX (PIX), endereço LTC (LTC) ou USDT BEP20 (USD)

cryptoAmount

number

Quantidade em LTC (obrigatório quando method="ltc")

cURL — Saque PIX

curl -X POST https://api.purincash.com/v1/payouts \
  -H "Authorization: Bearer ps_live_<key>" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "pix",
    "amount": 100.00,
    "walletAddress": "loja@email.com"
  }'

Resposta (201)

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

cURL — Saque LTC

curl -X POST https://api.purincash.com/v1/payouts \
  -H "Authorization: Bearer ps_live_<key>" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "ltc",
    "amount": 100.00,
    "cryptoAmount": 0.5,
    "walletAddress": "ltc1q..."
  }'

Status do saque:

pending — aguardando aprovação admin
completed — pago
denied — negado

Erros comuns:

400 — Saldo insuficiente / valor fora do range / endereço LTC inválido
403 — PIX não verificado (faça verificação no painel primeiro)
429 — Rate limit excedido (10/hr)

Segurança: a resposta NUNCA contém dados sensíveis (CPF, chave PIX completa). O walletAddress é mascarado em logs e respostas (12345***).

SaquesSaque em USD

Cash-out em dólar (USDT)

Saque em USD

Converte o saldo BRL da loja e envia USDT na rede BEP20 na hora — é o mesmo fluxo instantâneo do saque Pix→USDT do painel (conversão + pagamento automático), exposto pela API. Usa o endpoint POST /v1/payouts com method: "usd".

POST/v1/payouts

Só depois do 1º saque: por segurança (anti-fraude), o saque em USD só é liberado depois que a loja fizer o primeiro saque em PIX. Antes disso a API responde 403.

ParâmetroTipoDescrição

methodreq

string

"usd"

amountreq

number

Valor em BRL a converter (dentro dos limites por operação)

walletAddressreq

string

Endereço USDT BEP20 (0x + 40 caracteres hex)

confirmNotCoinbasereq

boolean

Confirmação de que a wallet NÃO é depósito Coinbase (Coinbase não suporta USDT BEP20 e os fundos seriam perdidos). Deve ser true.

cURL — Saque USD (USDT BEP20)

curl -X POST https://api.purincash.com/v1/payouts \
  -H "Authorization: Bearer ps_live_<key>" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "usd",
    "amount": 100.00,
    "walletAddress": "0xAbC1230000000000000000000000000000000000",
    "confirmNotCoinbase": true
  }'

Resposta (201) — PIX enviado, entrega em segundos

{
  "success": true,
  "withdrawal": {
    "id": "665f1a2b3c4d5e6f7a8b9c0d",
    "code": "SAQ-U-1A2B3C4D5E6F7A8B",
    "amountBRL": 100,
    "receiveUSDT": 17.42,
    "rateBRLPerUSDT": 5.74,
    "status": "processando",
    "estimatedTime": "menos de 30 segundos"
  }
}

Status: processando = PIX enviado à processadora, USDT chega na wallet em segundos (confirmação via webhook). Em raros casos de incerteza de rede a resposta vem 202 com requiresReview: true — o valor NÃO é estornado até a reconciliação.

Erros comuns:

400 — Saldo insuficiente / fora dos limites por operação / acima da liquidez / endereço BEP20 inválido / confirmNotCoinbase ausente
403 — Ainda não fez o primeiro saque (faça um saque em PIX antes)
429 — Rate limit (10/hr) ou outro saque cripto em processamento
502 — Processadora rejeitou o pagamento (valor estornado pro saldo)
503 — Saque em cripto temporariamente indisponível

Listar saques

GET/v1/payouts

limitnumberopcional

Resultados (1-100, default 20)

statusstringopcional

Filtrar: pendente, concluido, negado

curl -X GET "https://api.purincash.com/v1/payouts?limit=20&status=pendente" \
  -H "Authorization: Bearer ps_live_..."

Resposta

{
  "payouts": [
    {
      "id": "SAQ-API-A1B2C3D4",
      "code": "SAQ-API-A1B2C3D4",
      "method": "pix",
      "amount": 100,
      "cryptoAmount": null,
      "walletAddress": "12345***",
      "status": "pendente",
      "createdAt": "2026-04-27T12:00:00.000Z"
    }
  ]
}

walletAddress sempre vem mascarado (primeiros 6 chars + ***).

WebhooksSegurança (HMAC)

Webhooks

Segurança & Assinatura HMAC

Todo webhook que a gente envia (pagamento, cartão, pedido de loja, saque) vem assinado com HMAC-SHA256. A assinatura fica no header X-Webhook-Signature e é mandada sempre, sem flag de opt-in.

Sua URL de callback é pública, então qualquer um na internet pode mandar um POST com status "paid". Valide a assinatura antes de tratar o evento como confirmado.

Onde fica meu webhook secret?

Cada loja tem um secret próprio. Você pega (ou regenera) em Dashboard → API & Desenvolvedores → Webhooks, ou via API:

GET webhook secret

GET https://api.purincash.com/api/developer/webhook-secret
Authorization: Bearer <seu_token_dashboard>

→ { "secret": "whk_a1b2c3d4..." }

Guarde no seu backend (variável de ambiente). Não exponha no front. Se vazar, regenere pelo dashboard; o antigo para de funcionar na hora.

Como validar a assinatura

Calcule o HMAC-SHA256 do corpo cru da requisição (a string exata do JSON recebido, antes de qualquer parse) usando seu secret como chave. Compare com o valor do header. Use comparação timing-safe pra evitar timing attacks.

Node.js (Express)

import crypto from "node:crypto";
import express from "express";

const app = express();

// Importante: precisa do body cru. O JSON.parse vem depois da validação.
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.header("X-Webhook-Signature");
  const expected = crypto
    .createHmac("sha256", process.env.PURINCASH_WEBHOOK_SECRET)
    .update(req.body)
    .digest("hex");

  // timing-safe compare
  const valid =
    signature &&
    signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

  if (!valid) return res.status(401).send("invalid signature");

  const event = JSON.parse(req.body.toString());
  // ... processa event.event, event.paymentId, etc.
  res.json({ ok: true });
});

PHP

<?php
$payload = file_get_contents('php://input'); // body cru
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$secret = getenv('PURINCASH_WEBHOOK_SECRET');
$expected = hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $signature)) {
  http_response_code(401);
  exit('invalid signature');
}

$event = json_decode($payload, true);
// ... processa $event['event'], $event['paymentId'], etc.
http_response_code(200);
echo json_encode(['ok' => true]);

Lojas antigas que ainda não regeneraram o secret usam um fallback derivado do userId com uma chave global. Recomendamos chamar o endpoint acima pra gerar o seu próprio.

WebhooksCallback PIX

Callback PIX (payment.paid / charge.paid)

Quando o PIX é confirmado, a gente faz um POST pro callbackUrl que você passou na criação. O nome do evento depende do recurso: payment.paid pros Payment Links (/v1/payments) e charge.paid pras cobranças PIX diretas (/v1/charges).

Payload (payment.paid)

POST https://seu-site.com/webhook
Content-Type: application/json
X-Webhook-Signature: a3f5b8c2e1d4f7a9b6c8d2e5f1a4b7c9d2e5f8a1b4c7d0e3f6a9b2c5d8e1f4a7

{
  "event": "payment.paid",
  "paymentId": "psa_a1b2c3d4...",
  "amountCents": 4990,
  "status": "paid",
  "paidAt": "2026-03-18T12:05:00.000Z",
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com",
    "externalId": "user_123"
  },
  "metadata": "{\"orderId\": \"abc-123\"}"
}

Payload (charge.paid) com campos extras do acquirer

{
  "event": "charge.paid",
  "paymentId": "psa_a1b2c3d4...",
  "amountCents": 4990,
  "status": "paid",
  "paidAt": "2026-03-18T12:05:00.000Z",
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com"
  },
  "metadata": "{\"orderId\": \"abc-123\"}",
  "payer": "João Silva",
  "cpfCensored": "123.***.**1-23",
  "bank": "077 - Banco Inter",
  "endToEndId": "E1818773820260318120500abc12345"
}

O callback vai uma única vez (fire-and-forget, timeout de 5s). Não tem retry. Se sua URL responder com erro, faça GET /v1/payments/:paymentId pra conferir o status. O header X-Webhook-Signature está presente em todo callback; veja Segurança & HMAC pra validar.

ParâmetroTipoDescrição

eventreq

string

"payment.paid" ou "charge.paid"

paymentIdreq

string

ID único do pagamento/cobrança

amountCentsreq

number

Valor em centavos

statusreq

string

"paid"

paidAtreq

string

Data/hora ISO da confirmação

customer

object

Dados do cliente (se informados na criação)

metadata

string

JSON string enviado na criação

payer

string

Nome do pagador (apenas charge.paid)

cpfCensored

string

CPF censurado do pagador (apenas charge.paid)

bank

string

Banco de origem do PIX (apenas charge.paid)

endToEndId

string

End-to-end ID do Bacen (apenas charge.paid)

WebhooksCallback Cartão

Callback Cartão (card_payment.paid)

Quando uma cobrança no cartão é confirmada (via Stripe), a gente faz POST pro callbackUrl da cobrança. Evento card_payment.paid. A shape difere um pouco do PIX: o valor vem em amount (reais, decimal), não em amountCents.

Payload

POST https://seu-site.com/webhook
Content-Type: application/json
X-Webhook-Signature: a3f5b8c2e1d4f7a9b6c8d2e5f1a4b7c9d2e5f8a1b4c7d0e3f6a9b2c5d8e1f4a7

{
  "event": "card_payment.paid",
  "orderCode": "ORD-7K3B9X",
  "amount": 49.90,
  "status": "paid",
  "paidAt": "2026-03-18T12:05:00.000Z",
  "customer": { "name": "João Silva", "email": "joao@email.com" },
  "metadata": "{\"orderId\": \"abc-123\"}"
}

ParâmetroTipoDescrição

eventreq

string

"card_payment.paid"

orderCodereq

string

Código da cobrança no cartão

amountreq

number

Valor em reais (não centavos)

statusreq

string

"paid"

paidAtreq

string

Data/hora ISO da confirmação

customer

object

Dados do cliente (se informados)

metadata

string

JSON string enviado na criação

Mesmas garantias do callback PIX: assinatura HMAC, fire-and-forget, timeout 5s. Detalhes em Segurança & HMAC.

WebhooksWebhook Pedido (Discord)

Webhook Pedido (order.paid)

Específico pra lojas no Discord (bot PurinCash). Quando um pedido feito pelo bot é pago, a gente faz POST pra URL configurada na setting order_webhook_url. Útil pra sincronizar estoque ou CRM externo.

Configure a URL em Dashboard → API & Desenvolvedores → Webhooks. Esse aqui é por loja, não por cobrança como o callback PIX. Vale pra todos os pedidos do bot.

Payload

POST https://seu-site.com/webhook
Content-Type: application/json
X-Webhook-Signature: a3f5b8c2e1d4f7a9b6c8d2e5f1a4b7c9d2e5f8a1b4c7d0e3f6a9b2c5d8e1f4a7

{
  "event": "order.paid",
  "orderId": "665f1a2b3c4d5e6f7a8b9c0d",
  "orderCode": "ORD-7K3B9X",
  "total": 49.90,
  "paidAt": "2026-03-18T12:05:00.000Z",
  "acquirer": "cartwave"
}

ParâmetroTipoDescrição

eventreq

string

"order.paid"

orderIdreq

string

ID interno do pedido (ObjectId)

orderCodereq

string

Código curto do pedido

totalreq

number

Valor total em reais

paidAtreq

string

Data/hora ISO da confirmação

acquirerreq

string

Adquirente que processou (ex: cartwave)

Webhook de Saques

Quando um saque é solicitado, aprovado ou negado, enviamos um POST para a URL configurada na setting withdrawal_webhook_url.

Configure a URL de webhook de saques em Dashboard → API & Desenvolvedores → Webhooks. Todos os eventos de saque serão enviados para a URL configurada.

Saque solicitado

Payload

POST https://seu-site.com/webhook
Content-Type: application/json
X-Webhook-Signature: hmac_sha256_...

{
  "event": "withdrawal.requested",
  "withdrawalId": "665f1a2b3c4d5e6f7a8b9c0d",
  "code": "SAQ-A1B2C3",
  "amount": 150.00,
  "method": "pix",
  "walletAddress": "email@exemplo.com",
  "status": "pendente",
  "requestedAt": "2026-03-18T14:00:00.000Z"
}

Saque aprovado

Payload

{
  "event": "withdrawal.completed",
  "withdrawalId": "665f1a2b3c4d5e6f7a8b9c0d",
  "code": "SAQ-A1B2C3",
  "amount": 150,
  "method": "pix",
  "walletAddress": "email@exemplo.com",
  "status": "concluido",
  "processedAt": "2026-03-18T15:30:00.000Z"
}

Saque negado

Payload

{
  "event": "withdrawal.denied",
  "withdrawalId": "665f1a2b3c4d5e6f7a8b9c0d",
  "code": "SAQ-A1B2C3",
  "amount": 150,
  "method": "pix",
  "walletAddress": "email@exemplo.com",
  "status": "negado",
  "processedAt": "2026-03-18T15:30:00.000Z"
}

ParâmetroTipoDescrição

eventreq

string

"withdrawal.requested", "withdrawal.completed" ou "withdrawal.denied"

withdrawalIdreq

string

ID único do saque

codereq

string

Código do saque (ex: SAQ-A1B2C3)

amountreq

number

Valor em reais

methodreq

string

Método: pix, ltc, etc.

walletAddressreq

string

Chave PIX ou endereço de destino

statusreq

string

pendente, concluido ou negado

requestedAt / processedAtreq

string

Data/hora ISO do evento

Mesma garantia dos outros webhooks: header X-Webhook-Signature com HMAC-SHA256. Veja Segurança & HMAC pra exemplos de validação.

Voltar ao início