UNIPAYCriar conta
Integração única

Área do desenvolvedor

Integre pagamentos Pix ao seu sistema com a UNIPAY. A empresa gera a chave no próprio painel, depois do cadastro aprovado, e copia de lá os dois únicos valores necessários.

O que você precisa (só isso)

  • Chave de API — enviada no cabeçalho Authorization: Bearer SUA_CHAVE de todas as chamadas.
  • Segredo do webhook — usado para conferir a assinatura X-Unipay-Signature dos avisos que enviamos.

A URL do seu sistema (que recebe o aviso de pagamento) é cadastrada uma única vez no painel UNIPAY, na aba Integração. Nada de URL da UNIPAY dentro do seu código. A chave só funciona com o cadastro aprovado — nunca a exponha no navegador.

Endpoints

1. Criar uma cobrança Pix

POST https://unipaysolucoes.digital/api/public/gateway/cobrancas
Authorization: Bearer SUA_CHAVE
Content-Type: application/json

{
  "valor": 149.90,
  "descricao": "Pedido 1234",
  "referencia": "1234",
  "pagador": { "nome": "Maria Silva", "documento": "00000000000" }
}

Resposta

{
  "dados": {
    "id": "uuid-da-cobranca",
    "status": "pendente",
    "valor": 149.9,
    "url_checkout": "https://unipaysolucoes.digital/checkout/uuid-da-cobranca",
    "pix": { "copia_e_cola": "000201...", "imagem": "", "expira_em": "..." }
  }
}

2. Criar uma cobrança por boleto

POST https://unipaysolucoes.digital/api/public/gateway/cobrancas
Authorization: Bearer SUA_CHAVE
Content-Type: application/json

{
  "valor": 149.90,
  "descricao": "Pedido 1234",
  "referencia": "1234",
  "metodo": "boleto",
  "vencimento_dias": 3,
  "pagador": {
    "nome": "Maria Silva",
    "documento": "00000000000",
    "cep": "46880000",
    "endereco": "Rua das Flores",
    "numero": "100",
    "bairro": "Centro",
    "cidade": "Itaberaba",
    "uf": "BA"
  }
}

// resposta: "boleto": { "linha_digitavel": "...", "codigo_barras": "...", "vencimento": "2026-09-10", "pdf": "https://unipaysolucoes.digital/api/public/gateway/boleto/{id}" }

3. Consultar o status

GET https://unipaysolucoes.digital/api/public/gateway/cobrancas/{id}
Authorization: Bearer SUA_CHAVE

4. Listar cobranças e saldo

GET https://unipaysolucoes.digital/api/public/gateway/cobrancas
GET https://unipaysolucoes.digital/api/public/gateway/saldo
Authorization: Bearer SUA_CHAVE

Checkout hospedado

O pagamento do cliente final acontece sempre pelo checkout da UNIPAY. Toda cobrança criada devolve o campo url_checkout: basta redirecionar o cliente para esse endereço, que abre uma página de pagamento com QR Code, código copia e cola, contagem de expiração e confirmação automática — sem que você precise montar tela nenhuma.

Melhorias no checkout (novos meios de pagamento, layout, antifraude) entram no ar automaticamente para quem já usa esse link, sem nova integração.

Redirecionar o cliente

https://unipaysolucoes.digital/checkout/{id-da-cobranca}

Aviso automático (webhook)

Enviado quando o cliente paga

POST na URL cadastrada no painel UNIPAY
X-Unipay-Event: cobranca.paga
X-Unipay-Signature: HMAC-SHA256 (hex) do corpo com o segredo do webhook

{ "evento": "cobranca.paga", "dados": { "id": "...", "referencia": "1234", "status": "pago" } }

Conferindo a assinatura (Node.js)

const esperado = crypto
  .createHmac('sha256', SEGREDO_DO_WEBHOOK)
  .update(corpoBruto)
  .digest('hex');

if (esperado !== req.headers['x-unipay-signature']) return res.status(401).end();
res.status(200).json({ ok: true });

Use o corpo bruto da requisição no cálculo e responda 200. Se o seu sistema não responder, reenviamos o aviso automaticamente.

Erros comuns

Respostas de erro

401 { "erro": "Chave de API inválida" }
403 { "erro": "Cadastro em análise ou bloqueado" }
422 { "erro": "Falha ao criar a cobrança" }

Atualizações automáticas

A API não tem versões separadas: os endereços acima são fixos e definitivos. Toda melhoria que fazemos (novos meios de pagamento, checkout, segurança, desempenho) entra no ar na mesma hora para quem já está integrado, sem precisar refazer a integração, atualizar biblioteca ou trocar a chave.

Só adicionamos campos novos nas respostas — nunca removemos nem renomeamos os existentes. Por isso, ignore campos desconhecidos no seu código e a integração continua funcionando para sempre.

Pronto para integrar?

Crie a conta da sua empresa, envie os documentos e gere sua chave de API no painel.

Criar conta