PSE

PSE em COP, com contrato público LeonaPay e confirmação assíncrona.

Limites e disponibilidade

Consulte GET /api/v2/payment-methods antes de exibir o método. Use minAmount, maxAmount, settlement e available retornados para a empresa; os limites comerciais não são fixos na documentação.

Método	PSE
`Moeda`	`COP`
`Mercado`	`Colômbia`
`Tipo de instrução`	`PSE`

Campos obrigatórios

Valide estes campos no seu backend antes de chamar a API. Não envie credenciais LeonaPay ao navegador.

payer.name	Nome completo
`payer.email`	`E-mail válido`
`payer.phone`	`Telefone com DDI`
`payer.taxId`	`Documento`
`payer.documentType`	`CC, NIT, CE ou TI`
`bankCode`	`Código do banco escolhido`

Criar pagamento PSE

Envie POST /api/v2/payments com uma chave idempotency-key UUID exclusiva.

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":"PSE","currency":"COP","amount":125900,"reference":"pedido-pse-123","bankCode":"1007","payer":{"name":"Ana Gómez","email":"ana@exemplo.com","phone":"+573001234567","taxId":"1020304050","documentType":"CC"}}'

Resposta inicial completa

Persista data.id, status, method, currency e todas as instruções retornadas.

{"success":true,"onpayCode":"ONP201","data":{"id":"pay_01J...","status":"PENDING","method":"PSE","currency":"COP","amount":125900}}

Tempo das instruções

A criação retorna PENDING. A URL de checkout chega de forma assíncrona: ao receber payment.updated, consulte a mesma transação e redirecione o pagador para nextAction.redirectUrl.

Estados e webhook

A resposta inicial não comprova liquidação. Valide a assinatura HMAC sobre o corpo bruto, responda 2xx rapidamente e processe cada event.id uma única vez.

Status	Ação
`PENDING`	`Aguardar instrução ou confirmação`
`ACTION_REQUIRED`	`Entregar a ação ao pagador`
`PAID`	`Liberar o pedido uma única vez`
`FAILED`	`Encerrar a tentativa`
`EXPIRED`	`Não reutilizar a instrução`
`REFUNDED`	`Registrar devolução/reversão`

{"id":"evt_01J...","event":"payment.paid","occurredAt":"2026-09-22T18:32:10Z","data":{"id":"pay_01J...","reference":"pedido-123","status":"PAID","method":"PSE","currency":"COP","amount":125.90}}

Conciliação

O retorno do navegador não confirma o pagamento. Libere o pedido somente após payment.paid ou consulta autenticada em PAID.

Erros e retentativas

Corrija respostas ONP400 antes de uma nova tentativa. Em ONP429, ONP502 ou ONP503, use backoff com jitter e repita a mesma requisição com a mesma idempotência. Consulte o pagamento antes de criar outro.

Código	Ação
`ONP400_*`	`Corrigir o campo indicado`
`ONP409_IDEMPOTENCY_CONFLICT`	`Não reutilizar UUID com conteúdo diferente`
`ONP422_PSE_REJECTED`	`Revisar os dados e iniciar nova tentativa`
`ONP503_PSE_TEMPORARILY_UNAVAILABLE`	`Retentar com a mesma idempotência`

Como simular o resultado no Sandbox

Crie o pagamento usando a chave e a Base URL do Sandbox. PIX, boleto, SPEI, MB WAY, transferências bancárias, PSE, Nequi e Bre-B permanecem aguardando até você enviar o resultado desejado ao endpoint de simulação. Use o ID retornado na criação do pagamento.

Troque PAID por FAILED ou EXPIRED para testar os outros cenários. A simulação aceita somente pagamentos da mesma empresa e do ambiente Sandbox.

Status	Resultado simulado
`PAID`	`Pagamento confirmado e webhook payment.paid emitido`
`FAILED`	`Pagamento recusado e webhook payment.failed emitido`
`EXPIRED`	`Cobrança expirada e webhook payment.expired emitido`

curl --request POST \
  --url https://sandbox.api.leonapay.com.br/api/v2/simulations/payments/{paymentId} \
  --header 'x-api-key: {sandbox_api_key}' \
  --header 'Content-Type: application/json' \
  --data '{"status":"PAID"}'