Alinha Pay - Documentação da API

Antes de começar

Valores sempre em centavos - R$ 129,90 vira 12990. Datas em AAAA-MM-DD.

Dois ambientes, um contrato. A chave alinha_sk_test_... roda em sandbox, sem dinheiro de verdade - dá pra integrar hoje. A alinha_sk_live_... entra quando o credenciamento fechar. Nenhuma linha de código muda entre os dois.

Autenticação

Toda chamada leva a chave no header. Ela nunca pode aparecer no front-end.

Authorization: Bearer alinha_sk_test_xxxxxxxxxxxx

Cobrança - Pix e boleto

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" }
  }'

// 201 Created
{
  "id": "chg_9f2c...",
  "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-09-01 18:40:00"
}

Boleto

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

Cartão não entra aqui. Use /v1/checkouts, na seção seguinte. Dado de cartão não pode passar pelo seu servidor - é o que mantém você fora do escopo PCI-DSS.

Campos

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

Checkout - cartão, Pix e boleto na mesma tela

POST/v1/checkouts

Cria uma página de pagamento pronta e devolve a URL. Redirecione o comprador ou embuta num iframe - ele escolhe o meio ali dentro.

Por que cartão é sempre por aqui. Os campos onde o comprador digita o cartão são servidos pela adquirente dentro da página. O número vai do navegador dele direto pra lá - não passa pelo seu servidor nem pelo da Alinha. Ninguém precisa de certificação PCI, e não existe dado de cartão pra vazar de nenhum dos dois lados.

curl -X POST https://pay.alinha.net/v1/checkouts \
  -H "Authorization: Bearer $ALINHA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "valor": 25000,
    "descricao": "Ingresso - Lote 1",
    "referencia_externa": "pedido_1042",
    "meios": ["cartao", "pix", "boleto"],
    "max_parcelas": 6,
    "pagador": { "nome": "Maria Souza", "documento": "12345678900", "email": "maria@exemplo.com" }
  }'

// 201 Created
{
  "id": "chg_c416...",
  "objeto": "checkout",
  "status": "pendente",
  "valor": 25000,
  "meios": ["cartao", "pix", "boleto"],
  "url_pagamento": "https://pay.alinha.net/pagar/chg_c416..."
}

Campo	Tipo	Obrigatório	Observação
`valor`	inteiro	sim	em centavos
`meios`	lista	não	`cartao`, `pix`, `boleto`, `googlepay`, `applepay`
`max_parcelas`	inteiro	não	padrão 12
`juros`	texto	não	`loja` (padrão) ou `cliente`
`expira_minutos`	inteiro	não	validade do link, padrão 1440
`pix_expira_minutos`	inteiro	não	padrão 30

A página sai com a sua marca - logo, cor e nome. A URL é sempre um domínio da Alinha ou o seu, nunca o de um terceiro.

Consultar, cancelar e status

GET/v1/cobrancas/:id

Se estiver pendente, a Alinha confere na hora antes de responder.

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

Filtra por status e referencia_externa.

POST/v1/cobrancas/:id/cancelar

Status	O que significa
`pendente`	aguardando o pagamento
`pago`	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 em menos de um segundo e processe depois.

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-09-01 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. E trate cada evento como repetível: use o id da cobrança pra não processar duas vezes.

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.