/Documentação da API

Kyzeno API v1

A Kyzeno API permite que você integre cobranças PIX, consulte saldos e realize saques diretamente em seu sistema ou aplicativo, sem precisar acessar o dashboard.

REST & JSON

Padrão moderno, fácil de integrar

Auth por headers

Client ID + Secret em cada requisição

Webhooks em tempo real

Notificações instantâneas de pagamento

Endpoints disponíveis

POST

/transactions

Criar cobrança PIX

GET

/transactions/:id

Consultar status de uma transação

GET

/balance

Consultar saldo disponível

POST

/withdrawals

Solicitar saque via PIX

POST

/withdrawals/crypto

Saque em cripto (Premium)

GET

/fees

Consultar taxas da sua conta

Autenticação

Todas as requisições devem incluir suas credenciais nos headers HTTP. Gere suas credenciais no dashboard → Credenciais API.

Nunca exponha suas credenciais em código client-side (browser/app). Use sempre pelo backend.

Headers obrigatórios

`x-client-id`*	string	Seu Client ID (UUID)
`x-client-secret`*	string	Seu Client Secret (gerado uma vez, não recuperável)

http

POST /api/v1/transactions HTTP/1.1
Host: kyzeno2.discloud.app
Content-Type: application/json
x-client-id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
x-client-secret: cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{ "amount": 29.90, "description": "Plano mensal" }

Erros de autenticação

json

// 401 — Credenciais ausentes ou inválidas
{ "error": "Credenciais inválidas" }

// 403 — KYC não aprovado
{ "error": "KYC não aprovado" }

Transações PIX

POST/api/v1/transactions

Cria uma nova cobrança PIX. Retorna o código Copia e Cola e o QR Code em base64.

Corpo da requisição

`amount`*	number	Valor em reais. Ex: 29.90
`description`	string	Descrição da cobrança (opcional, máx 100 chars)

javascript

// Criar cobrança PIX
const res = await fetch('https://kyzeno2.discloud.app/api/v1/transactions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-client-id': 'seu-client-id',
    'x-client-secret': 'seu-client-secret',
  },
  body: JSON.stringify({
    amount: 97.00,
    description: 'Produto digital - Acesso vitalício',
  }),
})

const data = await res.json()
console.log(data.pixCode)      // Copia e Cola
console.log(data.qrCodeBase64) // Imagem base64

Resposta (201)

json

{
  "id": "kyz_abc123",
  "pixCode": "00020126330014BR.GOV.BCB.PIX...",
  "qrCodeBase64": "data:image/png;base64,iVBORw0KGgo...",
  "amount": 97.00,
  "fee": 3.41,
  "netAmount": 93.59,
  "status": "pending",
  "expiresAt": "2025-03-26T18:00:00.000Z"
}

GET/api/v1/transactions/:id

Consulta o status de uma transação pelo ID retornado na criação.

javascript

const res = await fetch('https://kyzeno2.discloud.app/api/v1/transactions/kyz_abc123', {
  headers: {
    'x-client-id': 'seu-client-id',
    'x-client-secret': 'seu-client-secret',
  },
})
const data = await res.json()
// data.status: "pending" | "approved" | "expired" | "refunded"

Resposta (200)

json

{
  "id": "kyz_abc123",
  "status": "approved",
  "amount": 97.00,
  "fee": 3.41,
  "netAmount": 93.59,
  "description": "Produto digital - Acesso vitalício",
  "payerName": "João Silva",
  "payerDocument": "***.***.***-00",
  "createdAt": "2025-03-25T17:00:00.000Z",
  "expiresAt": "2025-03-26T18:00:00.000Z"
}

Status possíveis

`pending`	string	Aguardando pagamento
`approved`	string	Pago com sucesso, saldo creditado
`expired`	string	QR Code expirou sem pagamento (24h)
`refunded`	string	Estorno realizado

Saldo

GET/api/v1/balance

Retorna o saldo disponível para saque, saldo bloqueado por disputas (MEDs) e saldo com holdtime pendente.

javascript

const res = await fetch('https://kyzeno2.discloud.app/api/v1/balance', {
  headers: {
    'x-client-id': 'seu-client-id',
    'x-client-secret': 'seu-client-secret',
  },
})
const { available, blocked, pending, niche } = await res.json()

Resposta (200)

json

{
  "available": 342.50,
  "blocked": 0.00,
  "pending": 97.00,
  "niche": "standard"
}

`available`	number	Disponível para saque imediato (R$)
`blocked`	number	Bloqueado por disputa MED ativa (R$)
`pending`	number	Em holdtime, será liberado em breve (R$)
`niche`	string	"standard" ou "premium"

Saques

POST/api/v1/withdrawals

Solicita um saque via PIX. Disponível para planos Standard e Premium.

Corpo da requisição

`amount`*	number	Valor em reais a sacar
`pixKey`*	string	Chave PIX de destino
`pixKeyType`*	string	"cpf" \| "cnpj" \| "email" \| "phone" \| "random"

javascript

const res = await fetch('https://kyzeno2.discloud.app/api/v1/withdrawals', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-client-id': 'seu-client-id',
    'x-client-secret': 'seu-client-secret',
  },
  body: JSON.stringify({
    amount: 200.00,
    pixKey: 'seu@email.com',
    pixKeyType: 'email',
  }),
})

Resposta (201)

json

{
  "id": "saque_xyz789",
  "status": "processing",
  "amount": 200.00,
  "fee": 3.00,
  "netAmount": 197.00,
  "type": "pix",
  "createdAt": "2025-03-25T20:00:00.000Z"
}

POST/api/v1/withdrawals/cryptoPremium

Converte e saca em USDT (TRC-20). Exclusivo para usuários do plano Premium.

Corpo da requisição

`amount`*	number	Valor em reais a converter
`wallet`*	string	Endereço da carteira USDT TRC-20

json

// Resposta (201)
{
  "id": "crypto_abc456",
  "status": "processing",
  "amount": 500.00,
  "fee": 5.00,
  "cryptoAmount": 89.32,
  "cryptoRate": 5.54,
  "type": "crypto",
  "createdAt": "2025-03-25T20:00:00.000Z"
}

Taxas

GET/api/v1/fees

Retorna as taxas atuais da sua conta. Útil para calcular o valor líquido antes de criar cobranças.

json

// Standard (Plano padrão)
{
  "niche": "standard",
  "transactionFeePercent": 3.5,
  "transactionFeeFixed": 0.48,
  "withdrawalFee": 3.00,
  "withdrawalTypes": ["pix"]
}

// Premium
{
  "niche": "premium",
  "transactionFeePercent": 5.0,
  "transactionFeeFixed": 1.50,
  "withdrawalFee": 5.00,
  "cryptoPlatformFeePercent": 1.0,
  "cryptoNetworkFee": 1.00,
  "withdrawalTypes": ["pix", "crypto"]
}

Cálculo do valor líquido

liquido = valor - (valor × feePercent / 100) - feeFixed

Exemplo: R$ 100 com 3.5% + R$ 0,48 → R$ 96,02 líquido

Webhooks

Configure uma URL de webhook no dashboard para receber notificações em tempo real quando um pagamento for confirmado. A Kyzeno faz um POST para sua URL com o payload abaixo.

Evento: pagamento aprovado

json

{
  "event": "payment.approved",
  "transaction": {
    "id": "kyz_abc123",
    "status": "approved",
    "amount": 97.00,
    "fee": 3.41,
    "netAmount": 93.59,
    "description": "Produto digital",
    "payerName": "João Silva",
    "payerDocument": "***.***.***-00",
    "createdAt": "2025-03-25T17:00:00.000Z",
    "paidAt": "2025-03-25T17:03:27.000Z"
  }
}

Boas práticas

Responda com 200 OK rapidamente (máx 5s). Processe de forma assíncrona.

Valide o ID da transação consultando GET /transactions/:id antes de liberar o produto.

Implemente idempotência: o mesmo webhook pode ser reenviado em caso de falha.

Filtre por event para ignorar tipos de eventos que não usa.

Split de Pagamento

Premium

O Split de Pagamento permite dividir automaticamente o valor líquido de uma cobrança entre duas contas Kyzeno no momento do pagamento. É ideal para marketplaces, programas de afiliados, criadores de conteúdo e qualquer modelo que envolva comissão automática.

Split está disponível exclusivamente para contas no Plano Premium. Ambas as contas (quem gera a cobrança e quem recebe o split) devem ser usuários cadastrados na plataforma.

Como funciona

Ao criar uma cobrança com split, você informa o e-mail do usuário que deve receber uma parte do valor e o percentual correspondente. Quando o pagamento for confirmado, o valor é dividido automaticamente entre as duas contas.

Crie a cobrança

Inclua splitEmail e splitPercent na requisição POST /transactions

Cliente paga

O pagamento PIX é processado normalmente pelo sistema

Split automático

O valor líquido é dividido automaticamente entre as contas no momento da confirmação

Parâmetros de split

Campo	Tipo	Descrição
splitEmail	string	E-mail do usuário Kyzeno que receberá a parte do split
splitPercent	number	Percentual (0–100) do valor líquido a ser transferido para splitEmail

Exemplo de requisição

json

// POST https://kyzeno2.discloud.app/api/v1/transactions
// Headers: x-client-id, x-client-secret

{
  "amount": 200.00,
  "description": "Venda com comissão de afiliado",
  "splitEmail": "afiliado@exemplo.com",
  "splitPercent": 20
}

Resposta

json

{
  "id": "KYZ-ABCD1234",
  "pixCode": "00020126...",
  "qrCodeBase64": "data:image/png;base64,...",
  "amount": 200.00,
  "fee": 11.50,
  "netAmount": 188.50,
  "status": "pending",
  "expiresAt": "2026-03-26T15:00:00.000Z"
}

Observações importantes

O splitPercent é aplicado sobre o valor líquido (após deducão das taxas da plataforma)
O usuário em splitEmail deve ter conta ativa e KYC aprovado na plataforma
Ambos os campos são opcionais; omitir cria uma cobrança normal sem split
O split é processado automaticamente ao confirmar o pagamento

Checkouts

Liste os checkouts ativos da sua conta via API. Cada checkout possui uma URL pública que pode ser usada em botões, bots, redirecionamentos e integrações.

GET

/checkouts

Lista todos os checkouts ativos da conta

Resposta

json

{
  "checkouts": [
    {
      "id": "6617abc...",
      "slug": "netflix-premium-a1b2c3d4",
      "title": "Netflix Premium 1 Mês",
      "price": 20.00,
      "sales": 47,
      "url": "https://kyzeno.com/c/netflix-premium-a1b2c3d4",
      "createdAt": "2026-01-10T12:00:00.000Z"
    }
  ]
}

Produtos

Liste os produtos ativos e a disponibilidade de estoque em tempo real. Útil para bots e sistemas externos verificarem se há itens disponíveis antes de oferecer ao cliente.

GET

/products

Lista todos os produtos ativos com estoque disponível

Resposta

json

{
  "products": [
    {
      "id": "6617def...",
      "name": "Conta Netflix Premium",
      "description": "Acesso imediato após pagamento",
      "price": 20.00,
      "stockAvailable": 12,
      "createdAt": "2026-01-10T12:00:00.000Z"
    }
  ]
}

Pronto para integrar?

Crie sua conta gratuitamente e gere suas credenciais em minutos.

Criar conta grátis Já tenho conta