Fluxo de integração

Do primeiro request à conciliação: a sequência segura para colocar pagamentos em produção.

1. Preparar a conta

Conclua o KYC, habilite métodos, gere credenciais Sandbox e cadastre ao menos um webhook HTTPS.

Item	Critério
`Empresa`	`KYC verificado`
`Credencial`	`Sandbox ativa`
`Webhook`	`URL HTTPS e eventos selecionados`
`Pedido`	`Referência interna persistida`

2. Criar a transação

Persista seu pedido e UUID de idempotência. Depois chame POST /api/v2/payments e salve o ID LeonaPay.

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

3. Entregar as instruções

PIX devolve copia e cola; boleto devolve linha digitável e PDF; SPEI e BANK_TRANSFER em ARS devolvem dados bancários; os quatro métodos colombianos entregam o checkout em payment.updated e nextAction.redirectUrl; MB WAY depende de autorização no aplicativo.

Criação bem-sucedida não significa pagamento confirmado.

4. Confirmar e conciliar

Valide HMAC usando o corpo bruto, responda HTTP 2xx rapidamente e processe o evento de forma idempotente em fila. Use consulta por ID como reconciliação.

5. Liberar o IP para saques

Antes de chamar uma rota de saque, cadastre no painel o único IP público do backend. Outro IP recebe ONP403_IP.

POST /api/v2/withdrawals/pix
x-api-key: {your_api_key}
idempotency-key: {uuid}