Construa com a LeonaPay

Uma única API para receber pagamentos imediatos e métodos locais nos mercados onde seus clientes estão.

Como funciona

Crie uma credencial no painel, faça uma requisição autenticada e acompanhe o ciclo da transação por consulta ou webhook. Todas as requisições e respostas usam JSON.

Use sempre o ambiente Sandbox durante o desenvolvimento. Ele não movimenta valores reais.

Seu primeiro pagamento

O endpoint unificado recebe o método, o valor em unidades monetárias e os dados do pagador.

curl --request POST \
+  --url https://api.leonapay.com.br/api/v2/payments \
+  --header 'Accept: application/json' \
+  --header 'Content-Type: application/json' \
+  --header 'x-api-key: {your_api_key}' \
+  --header 'idempotency-key: {unique_uuid_per_payment}' \
+  --data '{
  "method": "PIX",
  "amount": 125.90,
  "currency": "BRL",
  "reference": "pedido-123",
  "payer": { "name": "Ana Souza", "taxId": "12345678909" }
}'

Principais recursos

Pagamentos locais, cartões, idempotência, estornos, conciliação, recibos, webhooks assinados e ambientes isolados por credencial.

Recurso	Disponibilidade
`Pagamentos locais`	`PIX, SPEI, MB WAY, BANK_TRANSFER, PSE, NEQUI e BREB`
`Cartões`	`Crédito e débito`
`Notificações`	`Webhooks em tempo real`
`Ambientes`	`Sandbox e Produção`

Fluxo completo de integração

Crie a empresa e conclua o KYC, gere credenciais separadas para Sandbox e Produção, autentique cada chamada com x-api-key, use uma chave de idempotência única, crie o pagamento, entregue as instruções ao cliente e confirme o resultado somente por consulta autenticada ou webhook assinado.

Etapa	Ação	Resultado
`1`	`Ativar empresa e métodos`	`Empresa apta a transacionar`
`2`	`Gerar credenciais`	`Chaves isoladas por ambiente`
`3`	`Cadastrar webhook`	`webhookId e segredo de assinatura`
`4`	`Criar pagamento`	`ID e instruções do método`
`5`	`Aguardar evento`	`Status final assinado`
`6`	`Conciliar`	`Pedido e saldo atualizados`

Escolha o método de pagamento

Todos usam a mesma autenticação e o mesmo envelope de resposta, mas devolvem instruções próprias para o pagador.

Método	Mercado	Experiência do pagador
`PIX`	`Brasil · BRL`	`QR Code e código copia e cola`
`SPEI`	`México · MXN`	`CLABE, beneficiário e banco`
`MB WAY`	`Portugal · EUR`	`Autorização no aplicativo`
`BANK_TRANSFER`	`Argentina · ARS`	`Dados bancários`
`BANK_TRANSFER`	`Colômbia · COP`	`Checkout recebido por payment.updated`
`PSE`	`Colômbia · COP`	`Redirecionamento bancário`
`NEQUI`	`Colômbia · COP`	`Checkout recebido por payment.updated`
`BREB`	`Colômbia · COP`	`Checkout recebido por payment.updated`
`Crédito e débito`	`Internacional`	`Tokenização e autenticação 3DS`

Boas práticas de produção

Mantenha chaves apenas no servidor, valide moeda e valor, nunca reutilize idempotência entre pedidos, aplique timeout com retentativa exponencial, registre o RequestId e valide a assinatura com o corpo bruto do webhook. Não marque um pedido como pago pelo retorno do navegador.

A URL de webhook deve usar HTTPS, responder rapidamente com HTTP 2xx e delegar o processamento pesado para uma fila.

Integrações assistidas por IA

Assistentes de IA podem gerar clientes HTTP, testes e mapeamentos a partir desta referência. Nunca compartilhe chaves reais, segredos, dados pessoais ou payloads de produção. Revise o código, teste no Sandbox e mantenha validações, idempotência e assinatura no servidor.

Objetivo: integrar PIX da LeonaPay no backend.
Base URL: https://sandbox.api.leonapay.com.br
Autenticação: x-api-key via variável de ambiente.
Requisitos: idempotência UUID, timeout, logs sem dados sensíveis, validação HMAC do webhook e testes automatizados.
Não inclua credenciais reais no código.

Infraestrutura recomendada

Separe frontend, backend e workers assíncronos. O backend protege credenciais e cria operações; uma fila absorve webhooks e retentativas; o banco mantém pedidos e idempotência; a observabilidade correlaciona chamadas pelo RequestId.

Camada	Responsabilidade
`Backend privado`	`Autenticação, validação e chamadas à LeonaPay`
`Banco de dados`	`Pedidos, referências, estados e idempotência`
`Fila / worker`	`Webhooks, retentativas e conciliação`
`Cofre de segredos`	`Chaves de API e segredos de assinatura`
`Logs e métricas`	`RequestId, latência, falhas e alertas`