Alinha Pay

Uma integração, três meios de pagamento. Você fala com a Alinha; a liquidação e a conciliação acontecem por baixo. Valores sempre em centavos (R$ 129,90 = 12990).

Ambientes. A chave alinha_sk_test_... roda em sandbox, sem dinheiro de verdade e sem depender de aprovação - dá pra integrar hoje. A alinha_sk_live_... vai pra produção quando o credenciamento estiver concluído. O contrato da API é o mesmo nos dois.

Autenticação

Toda chamada leva a chave no header. Nunca exponha a chave no front-end.

Authorization: Bearer alinha_sk_test_xxxxxxxxxxxx

Criar uma cobrança

POST/v1/cobrancas

Pix

curl -X POST https://pay.alinha.net/v1/cobrancas \
  -H "Authorization: Bearer $ALINHA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "valor": 12990,
    "metodo": "pix",
    "descricao": "Pedido 1042",
    "referencia_externa": "pedido_1042",
    "pagador": { "nome": "Maria Souza", "documento": "12345678900", "email": "maria@exemplo.com" },
    "metadata": { "escola": "apollo" }
  }'

// 201 Created
{
  "id": "chg_9f2c...",
  "objeto": "cobranca",
  "status": "pendente",
  "valor": 12990,
  "metodo": "pix",
  "pix": {
    "copia_cola": "00020126580014BR.GOV.BCB.PIX...",
    "qrcode_url": "https://..."
  },
  "url_pagamento": "https://pay.alinha.net/pagar/chg_9f2c...",
  "expira_em": "2026-08-31 18:40:00"
}

Boleto

{ "valor": 45000, "metodo": "boleto", "vencimento": "2026-09-10",
  "pagador": { "nome": "Colégio Apollo", "documento": "19189011000190" } }

Cartão

{ "valor": 89900, "metodo": "cartao", "parcelas": 3, "cartao_token": "tok_..." }

No sandbox, qualquer valor terminado em 13 centavos volta recusado - serve pra testar o caminho de falha.

Campos

Campo	Tipo	Obrigatório	Observação
`valor`	inteiro	sim	em centavos
`metodo`	texto	sim	`pix`, `boleto` ou `cartao`
`referencia_externa`	texto	não	seu id de pedido - use pra conciliar
`pagador`	objeto	boleto: sim	nome, documento, email
`vencimento`	data	não	boleto, AAAA-MM-DD
`parcelas`	inteiro	não	cartão, padrão 1
`metadata`	objeto	não	volta igual em toda consulta e webhook

Consultar

GET/v1/cobrancas/:id

Se a cobrança ainda estiver pendente, a Alinha checa o status na hora antes de responder.

GET/v1/cobrancas?status=pago&limite=50

Filtra por status e referencia_externa.

Cancelar

POST/v1/cobrancas/:id/cancelar

Status

Status	O que significa
`pendente`	aguardando o pagamento
`pago`	pagamento confirmado - pode liberar o pedido
`falhou`	recusado pelo emissor
`cancelado`	cancelado antes do pagamento
`estornado`	devolvido depois de pago
`expirado`	venceu sem pagamento

Webhooks

A Alinha chama a sua URL a cada mudança de status. Responda 200 rápido; a gente registra e reenvia o que falhar.

POST https://sua-loja.com.br/webhooks/alinha
x-alinha-signature: 3f9a...   // HMAC-SHA256 do corpo, com o seu webhook_secret

{ "evento": "cobranca.paga", "criado_em": "2026-08-31 15:12:03",
  "dados": { "id": "chg_9f2c...", "status": "pago", "valor": 12990,
             "referencia_externa": "pedido_1042" } }

Eventos: cobranca.paga, cobranca.falhou, cobranca.cancelada, cobranca.estornada, cobranca.atualizada.

Confira a assinatura antes de dar o pedido por pago: refaça o HMAC-SHA256 do corpo recebido com o seu webhook_secret e compare com o header.

Erros

{ "erro": { "tipo": "requisicao_invalida", "mensagem": "valor deve ser inteiro em centavos e maior que zero" } }

401 chave inválida · 403 lojista bloqueado · 404 não encontrado · 409 estado inválido · 502 falha no processamento.

Como começar

A Alinha te envia o lojista_id, a chave de teste e o webhook_secret.
Integre contra o sandbox e nos diga a URL do seu webhook.
Na virada pra produção, troca só a chave - nenhuma linha de código muda.