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.

​
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, detecta a jornada e lê o payload da recorrência no PSP recebedor por HTTPS.
  3. Na jornada 3, envie immediatePayment.result como SETTLED. 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. 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. O PSP recebedor não responde a uma rejeição.

​
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.

​
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.

​
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 liquidados e cancelados.
  2. Chame Cancelar pagamento agendado com esse identificador.
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.
Para as convenções de requisição do Pix Lerian, consulte Integrar com o Pix Lerian.