Skip to main content
A API do Pix Automático atende o lado do pagador dos pagamentos Pix recorrentes. Com ela, o pagador aceita ou rejeita uma solicitação de autorização, gerencia a autorização e cancela débitos agendados. A Lerian configura um limite diário para pagadores pessoa física com CPF mediante solicitação pelo Lerian Clients. Se nenhum limite estiver configurado, não há limite diário.

​
Chamar a API a partir do seu backend

Quem chama é o backend do seu PSP, autenticado com um token de aplicação. O token identifica a sua aplicação, não um dos seus clientes. O seu backend autentica o pagador e autoriza o pagador para a conta antes de chamar a API.
  • Envie a conta do pagador em X-Account-Id nas operações com escopo de conta. Criar solicitação de autorização a partir de QR code recebe a conta no campo payerAccountId do corpo.
  • Um recurso que pertence a uma conta diferente da que você envia retorna 404.
  • Envie X-Idempotency em cada escrita. Reutilize o valor apenas para repetir a mesma requisição.

​
Iniciar uma autorização a partir de um QR code

  1. Chame Criar solicitação de autorização a partir de QR code. Envie o conteúdo bruto do QR code em qrCodePayload e a conta do pagador em payerAccountId.
  2. A API decodifica o QR code e detecta a jornada. Depois, ela resolve a conta do pagador no CRM e lê o payload da recorrência no PSP recebedor por HTTPS.
  3. Na jornada 3, envie immediatePayment.result como SETTLED. Envie também immediatePayment.settlementConfirmedAt, o momento em que a sua instituição recebeu a confirmação da liquidação. Sem ele, a API não envia uma autorização aceita ao BACEN. Na jornada 4, um resultado FAILED interrompe a jornada.
  4. Guarde o authorizationRequestId da resposta. A solicitação aguarda a decisão do pagador até expiresAt.
Se a API não conseguir ler o payload da recorrência, a jornada para com um erro e a API não cria nenhuma solicitação. Se o CRM não tiver a conta do pagador, a API responde 422 (PIX-0813). Se a API não conseguir acessar o CRM ou não tiver o endereço do CRM, a API responde 503 (PIX-0814). Na jornada 1, a solicitação vem do PSP recebedor. Ela também aparece na lista de solicitações pendentes.

​
Decidir uma solicitação pendente

  1. Chame Listar solicitações de autorização para obter as solicitações que aguardam a decisão do pagador. Uma solicitação sai dessa lista quando o pagador a aceita ou rejeita, quando o PSP recebedor a cancela ou quando ela expira.
  2. Chame Decidir solicitação de autorização com decision definido como ACCEPT ou REJECT. Use exatamente o authorizationRequestId que a API retornou.
  3. Para aceitar, você também pode enviar os parâmetros do pagador. Um parâmetro que você não envia assume o padrão: notificações ativadas, linha de crédito ativada e nenhum valor máximo.
  4. Para rejeitar, envie rejectionReason como NotRecognizedByDebtor ou RejectedByDebtor.
  5. Chame Obter solicitação de autorização para ler o resultado. Essa operação retorna a solicitação em qualquer estado.
A decisão é um único comando. Não há uma segunda etapa de confirmação. A API envia a decisão ao PSP recebedor de forma assíncrona. Na jornada 1, o PSP recebedor não responde a uma rejeição. Nas jornadas 2, 3 e 4, a API registra uma rejeição e não a envia.

​
Gerenciar autorizações

  • Listar autorizações retorna as autorizações que não terminaram: APPROVED e AWAITING_CONCLUSION. Envie include_terminated=true para obter também as autorizações REJECTED, EXPIRED e CANCELLED.
  • Uma autorização AWAITING_CONCLUSION não está ativa no BACEN até que o PSP recebedor conclua o processo. Filtre por status=APPROVED para obter apenas as autorizações em vigor.
  • Obter autorização retorna uma autorização em qualquer estado.
  • Listar histórico da autorização retorna a auditoria das transições de estado. Cada entrada tem o estado anterior, o novo estado, o instante e o ator.

​
Alterar os parâmetros do pagador

Atualizar parâmetros da autorização aplica um JSON merge patch (RFC 7386) aos três parâmetros do pagador: maximumAmount, schedulingNotificationsEnabled e creditLineEnabled. Envie o corpo como application/merge-patch+json.
  • Omita um parâmetro para manter o valor dele.
  • Defina um parâmetro como null para restaurar o padrão. As duas opções têm o padrão ativado, então uma restauração não as desativa.
  • Uma alteração se aplica aos débitos agendados depois dela. Um débito que já está agendado mantém o valor máximo que estava em vigor quando ele foi agendado.
  • Em uma autorização criada pelo Open Finance, a API recusa uma alteração de maximumAmount com 409 (PIX-0812). Os outros dois parâmetros continuam editáveis.

​
Cancelar uma autorização

Cancelar autorização encerra a autorização a pedido do pagador. O cancelamento é imediato. Ele também cancela os débitos agendados sob a autorização, incluindo as novas tentativas após o vencimento. Os débitos com liquidação prevista para o dia do cancelamento continuam agendados e são liquidados nesse dia. A resposta informa cancelledScheduledPayments e preservedScheduledPayments. Uma contagem de preservados acima de zero é o comportamento correto, não uma falha parcial. O campo reason é uma nota em texto livre para a trilha de auditoria do pagador. O PSP recebedor recebe o código SLDB, que a resposta retorna em counterpartyReason. Quando o PSP recebedor cancela a recorrência, a API também cancela os débitos agendados sob ela. Ela mantém os débitos com vencimento no dia em que o cancelamento chega, e os do dia seguinte quando ele chega às 22:00 ou depois, no fuso horário America/Sao_Paulo. Ela também mantém um débito com uma tentativa de liquidação em qualquer status diferente de REJECTED.

​
Cancelar um débito agendado

  1. Chame Listar pagamentos agendados para obter o identificador do débito. Essa lista também mantém os débitos cancelados. Um débito liquidado mantém o status SCHEDULED, e o bloco settlement dele traz o resultado do pagamento. Restrinja a lista com status, authorization_id, start_date e end_date.
  2. Chame Cancelar pagamento agendado com esse identificador.
Obter pagamento agendado lê um débito de novo pelo identificador. Ele lê o banco primário, então um cancelamento ou um resultado de liquidação recém-registrado aparece na chamada seguinte. Cancelar um débito não altera a autorização. A autorização continua em vigor, e os próximos débitos continuam agendados. Para encerrar a autorização, cancele a autorização. A API recusa o cancelamento com 409 nestes casos:
  • A requisição chega às 00:00 da data de liquidação ou depois, no fuso horário America/Sao_Paulo (PIX-0825).
  • O débito vem de uma nova tentativa após o vencimento, com finalidade NTAG (PIX-0826).
  • O débito não está mais SCHEDULED.

​
Liberar um débito agendado travado

Use Desbloquear pagamento agendado para liberar um débito agendado cuja tentativa de liquidação saiu e nunca recebeu um resultado. O Pix Lerian libera o débito somente com uma de duas provas, e a resposta informa em evidence qual valeu: NOTHING_SENT (nenhuma tentativa de liquidação foi registrada) ou NOT_ON_RAIL (uma tentativa foi registrada e o SPI não tem transferência para ela). Qualquer outra resposta, inclusive a falta de resposta, recusa a liberação com 409 (PIX-0827). Uma ordem que o SPI rejeitou também é recusada: a conciliação da liquidação encerra essa cobrança. A tentativa precisa ter pelo menos 15 minutos. A partir das 21:00 da data de liquidação nada envia a ordem de novo, então uma liberação NOT_ON_RAIL a partir daí também envia ao pagador o aviso definitivo do fechamento do dia. Quem chama precisa da permissão scheduled-payment-recovery com a ação post, que a permissão de cancelamento não concede. Para as convenções de requisição do Pix Lerian, consulte Integrar com o Pix Lerian.