API de pagamentos Pix

Crie cobranças Pix, mande o cliente para o checkout pronto e receba um aviso assinado quando o pagamento cair. Pagamentos processados pela ALFA2 DXX LTDA.

Criar conta · Entrar no painel

1. Autenticação

Crie a conta em /cadastro. Depois que a ALFA2 DXX aprovar o cadastro, gere a chave de API no painel, em Integração: ela aparece uma única vez. Guarde-a só no seu servidor, nunca no navegador ou no app.

Authorization: Bearer a2d_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Base: https://pay.sunshinex.net. Valores sempre em centavos (R$ 25,90 = 2590).

2. Criar cobrança

POST /v1/cobrancas
Content-Type: application/json
Idempotency-Key: pedido-1234        (opcional: repetir a chamada devolve a mesma cobrança)

{
  "valor": 2590,
  "descricao": "Pedido 1234",
  "referencia": "1234",
  "expiracao": 3600,
  "retorno_url": "https://sualoja.com/obrigado",
  "pagador": { "nome": "Maria Silva", "documento": "12345678909" }
}

Campo	Obrigatório	Descrição
`valor`	sim	Inteiro em centavos, mínimo 100.
`descricao`	não	Até 80 caracteres; aparece no app do banco e no checkout.
`referencia`	não	Seu id do pedido (até 64), devolvido em tudo.
`expiracao`	não	Segundos, de 300 a 86400. Padrão 3600.
`retorno_url`	não	https; o checkout manda o cliente para cá depois de pagar.
`pagador`	não	`nome` + `documento` (CPF ou CNPJ).

Resposta 201:

{
  "id": "cob_9f2c…",
  "status": "pendente",
  "valor": 2590, "taxa": 90, "liquido": 2500,
  "descricao": "Pedido 1234", "referencia": "1234",
  "criado": "2026-10-24T19:00:00.000Z", "expira_em": "2026-10-24T20:00:00.000Z", "pago_em": null,
  "pix": { "copia_e_cola": "00020101021226…", "qr_code": "data:image/png;base64,…", "end_to_end_id": null },
  "checkout_url": "https://pay.sunshinex.net/c/cob_9f2c…"
}

Duas formas de cobrar: checkout pronto (redirecione o cliente para checkout_url) ou dentro do seu site (mostre pix.qr_code e pix.copia_e_cola).

3. Consultar cobrança

GET /v1/cobrancas/{id}

status	Significado
`pendente`	Aguardando pagamento
`paga`	Pago e confirmado no banco. Pode entregar o pedido.
`expirada`	Passou do prazo sem pagamento
`cancelada`	Cancelada antes do pagamento

4. Saldo

GET /v1/saldo
→ { "recebido": 250000, "repassado": 200000, "disponivel": 50000 }

recebido soma o líquido das cobranças pagas; repassado é o que a ALFA2 DXX já transferiu para você.

5. Webhooks

Configure a URL https e gere o segredo no painel, em Integração → Webhook (o botão Enviar teste manda um evento teste). Enviamos um POST a cada mudança de status: cobranca.paga, cobranca.expirada, cobranca.cancelada. Responda com qualquer 2xx em até 10 segundos; sem isso tentamos de novo em 1 min, 5 min, 30 min, 2 h, 6 h e 24 h.

X-Alfa2dx-Evento: cobranca.paga
X-Alfa2dx-Id: evt_…                      (use para ignorar duplicados)
X-Alfa2dx-Assinatura: t=1792872000,v1=5f3a…

{ "evento": "cobranca.paga", "criado": "…", "dados": { …mesma estrutura da cobrança… } }

Verificar a assinatura

v1 = HMAC-SHA256, com o seu segredo do webhook, de t + "." + corpo_bruto. Recuse se não bater ou se t tiver mais de 5 minutos.

// Node.js (use o corpo bruto, antes de qualquer JSON.parse)
const crypto = require('crypto');
function valido(corpo, cabecalho, segredo) {
  const { t, v1 } = Object.fromEntries(cabecalho.split(',').map(p => p.split('=')));
  if (Math.abs(Date.now() / 1000 - +t) > 300) return false;
  const esperado = crypto.createHmac('sha256', segredo).update(`${t}.${corpo}`).digest('hex');
  const a = Buffer.from(esperado), b = Buffer.from(v1 || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// PHP
$corpo = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_ALFA2DX_ASSINATURA']), $a);
$ok = abs(time() - (int)$a['t']) <= 300
   && hash_equals(hash_hmac('sha256', $a['t'] . '.' . $corpo, $SEGREDO), $a['v1']);

O webhook é um aviso: antes de liberar algo valioso, você pode confirmar com GET /v1/cobrancas/{id}.

6. Erros

{ "erro": { "codigo": "valor_invalido", "mensagem": "…" } }

HTTP	Quando
401	Chave ausente ou inválida
403	Conta suspensa
422	Campo inválido (veja `codigo`)
429	Mais de 120 cobranças por minuto
502	Banco indisponível no momento: tente de novo com a mesma `Idempotency-Key`

7. Exemplo completo

curl -X POST https://pay.sunshinex.net/v1/cobrancas \
  -H "Authorization: Bearer $ALFA2DX_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1234" \
  -d '{"valor": 2590, "descricao": "Pedido 1234", "referencia": "1234", "retorno_url": "https://sualoja.com/obrigado"}'

Repasses dos valores recebidos são feitos pela ALFA2 DXX LTDA para a chave Pix cadastrada, conforme o contrato com cada lojista.